Skip to content

Commit c4a0c5e

Browse files
committed
Update compatibility page to frame new keywords as not much of an issue
1 parent b1d6fc1 commit c4a0c5e

File tree

3 files changed

+19
-23
lines changed

3 files changed

+19
-23
lines changed

docs/Compatibility.md

Lines changed: 17 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -6,26 +6,29 @@ Pluto aims to be source- and bytecode-compatible with existing Lua code such tha
66

77
## New Keywords
88

9-
Pluto adds the following reserved tokens:
10-
- `switch`
11-
- `continue`
12-
- `enum`
13-
- `new`
14-
- `class`
15-
- `parent`
16-
- `export`
17-
- `try`
18-
- `catch`
9+
While Pluto does add a handful of new keywords (`switch`, `continue`, `enum`, `new`, `class`, `parent`, `export`, `try`, `catch`), it can automatically infer when these are used as identifiers to preserve compatibility with Lua:
10+
```lua
11+
local class = "supercar"
12+
print("it's a "..class) --> it's a supercar
13+
```
14+
However, if a script does actually end up using a feature, its respective keyword can no longer be used as an identifier:
15+
```pluto
16+
class Vehicle
17+
-- ...
18+
end
1919
20-
Which means you can't use them as identifiers. They can still be used with short-hand table indexes and goto labels because Pluto [allows reserved keywords to be used in those contexts](QoL%20Improvements/Reserved%20Identifiers).
20+
local class = "supercar" -- Error: expected a class name, found '='
21+
```
22+
The only exception to this is short-hand table syntax and goto labels because Pluto [allows reserved keywords to be used in those contexts](QoL%20Improvements/Reserved%20Identifiers).
2123

22-
### Mitigations
24+
### Compatibility Mode
2325

26+
Some users may wish for Pluto keywords to be off by default, for which we provide the following options:
2427
- **For Integrators:** Check your `luaconf.h` file to find the relevant macros under the "Compatibility" heading.
25-
- **For Scripters:** Use `pluto_use` in the source files. `-- @pluto_use * = false` to simply disable all incompatible keywords.
28+
- **For Scripters:** Put `-- @pluto_use * = false` at the top of your script.
2629
- **For Users:** Pass the `-c` flag to `pluto` or `plutoc`.
2730

28-
The following sections will go more in-depth on source-level mitigations (for scripters).
31+
Note that when keywords have been disabled like this, Pluto will not infer that a script requires them automatically, instead requiring explicit opt-in via pluto_use.
2932

3033
### Compile-time Configuration (pluto_use)
3134
You can change the meaning of Pluto's reserved tokens at any point in your scripts using the `--@pluto_use` comment or `pluto_use` statement.
@@ -74,14 +77,6 @@ These are what they look like:
7477
- `pluto_try`
7578
- `pluto_catch`
7679

77-
### Automatic Compatibility Inference
78-
When Pluto encounters its keywords being used as identifiers in source code, it handles this automatically:
79-
80-
By default, using a Pluto keyword as an identifier would cause a parsing error. But if Pluto detects this situation, and:
81-
- No `pluto_use` statement is present for the afflicting keyword.
82-
- No compatibility settings are configured for the afflicting keyword.
83-
84-
Then Pluto will automatically disable that specific keyword (note, still accessible through `pluto_*`) and prevent an error from occurring.
8580
## Default Table Metatable
8681

8782
This is [a feature in Pluto](Runtime%20Environment/Global%20&%20Base#default-metatables) that, by itself, is a benign QoL improvement for developers. However, in combination with our added standard library functions like [table.min](Runtime%20Environment/Table#tablemin), it can be an unexpected semantic change:

docusaurus.config.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ const config = {
4949
langs: [
5050
'c',
5151
'cpp',
52+
'lua',
5253
{
5354
id: 'pluto',
5455
name: 'pluto',

static/custom.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ function patchCodeblocks() {
1212
div.className = "copy-button";
1313
code.appendChild(div);
1414

15-
if (code.querySelector(".language-id")?.textContent === "pluto" && !code.hasAttribute("norun")) {
15+
if (["pluto", "lua"].indexOf(code.querySelector(".language-id")?.textContent) != -1 && !code.hasAttribute("norun")) {
1616
const button = document.createElement("button");
1717
button.textContent = "Try It";
1818
button.onclick = () => {

0 commit comments

Comments
 (0)