You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/Compatibility.md
+17-22Lines changed: 17 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,26 +6,29 @@ Pluto aims to be source- and bytecode-compatible with existing Lua code such tha
6
6
7
7
## New Keywords
8
8
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
+
localclass="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
19
19
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).
21
23
22
-
### Mitigations
24
+
### Compatibility Mode
23
25
26
+
Some users may wish for Pluto keywords to be off by default, for which we provide the following options:
24
27
-**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.
26
29
-**For Users:** Pass the `-c` flag to `pluto` or `plutoc`.
27
30
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.
29
32
30
33
### Compile-time Configuration (pluto_use)
31
34
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:
74
77
-`pluto_try`
75
78
-`pluto_catch`
76
79
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.
85
80
## Default Table Metatable
86
81
87
82
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:
0 commit comments