Skip to content

Commit 44d6bc6

Browse files
well-in-that-caseSainan
authored andcommitted
Improve Compatibility documentation
1 parent 6110121 commit 44d6bc6

File tree

1 file changed

+29
-8
lines changed

1 file changed

+29
-8
lines changed

docs/Compatibility.md

Lines changed: 29 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,19 +16,19 @@ Pluto adds the following reserved tokens:
1616
- `try`
1717
- `catch`
1818

19-
Which means you can't use them as variable names or for function calls. They can still be used with short-hand table indexes and goto labels though, because Pluto [removes the restriction from them](QoL%20Improvements/Reserved%20Identifiers).
19+
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).
2020

2121
### How to fix it?
2222
All of these incompatible keywords can be disabled:
2323
- **For Integrators:** Check your `luaconf.h` file to find the relevant macros under the "Compatibility" heading.
24-
- **For Scripters:** Place `-- @pluto_use * = false` at the top of the source file. [Read more...](#compile-time-configuration)
24+
- **For Scripters:** Usage of `pluto_use` in the source files.
2525
- **For Users:** Pass the `-c` flag to `pluto` or `plutoc`.
2626

2727
## For Scripters
28-
Because the Pluto environment your script is running in may have disabled some keywords for compatibility's sake, let's go over the portability and compatibility options given to you by Pluto.
28+
Scripters are given final say in how Compatibility Mode works within their scripts.
2929

30-
### Compile-time Configuration
31-
You can change the meaning of Pluto's reserved tokens at any point in your scripts using the `@pluto_use` annotation or `pluto_use` statement.
30+
### Compile-time Configuration (pluto_use)
31+
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.
3232

3333
For example, to disable all non-compatible keywords except for `switch`:
3434
```pluto
@@ -41,14 +41,35 @@ It is also possible to specify a version number, which is a shorthand for the ke
4141
- `"0.6.0"` corresponds to `* = false, switch, continue, enum, new, class, parent, export`
4242
- `"0.8.0"` corresponds to `* = false, switch, continue, enum, new, class, parent, export, try, catch`
4343

44-
So, writing a portable script that makes use of Pluto 0.8.0's features simply requires this at the beginning:
44+
So, writing a portable script that only makes use of Pluto 0.8.0's features requires this at the beginning:
4545
```pluto
4646
pluto_use "0.8.0"
4747
```
4848

49-
We recommend you always place a `pluto_use` configuration at the beginning of your scripts for two reasons:
49+
This feature also supports quick encompassing of optional features. So, instead of:
50+
```pluto
51+
pluto_use "0.8.0", global
52+
```
53+
You can use a '+' after the version number to also enable all of the optional features. As of 0.9.0, the only optional feature is [explicit globals](New%20Features/Explicit%20Globals) (`global`).
54+
```pluto
55+
pluto_use "0.9.0+"
56+
-- The same as pluto_use "0.9.0", global
57+
```
58+
59+
For module developers and scripts which may be used in future versions of Pluto, we recommend you use `pluto_use` for two reasons:
5060
- **Portability.** This will override the compatibility mode settings compiled into Pluto so your script will be parsed identically in all Pluto environments.
5161
- **Proactive compatibility.** Any keywords added by future versions of Pluto will also be put in compatibility mode by these statements, so in the off-chance your script uses a future reserved keyword as a variable name, it would still parse as you intended when you wrote it.
5262

5363
### Compatible Keywords
54-
Another way of using Pluto's features regardless of compatibility mode is by prefixing the keyword with `pluto_`. For example, `switch` becomes `pluto_switch`.
64+
Another way of using Pluto's features regardless of compatibility mode is by prefixing the keyword with `pluto_`. For example, `switch` becomes `pluto_switch`. These Compatibility Mode variants will always be valid, even when Compatibility Mode is disabled.
65+
66+
These are what they look like:
67+
- `pluto_switch`
68+
- `pluto_continue`
69+
- `pluto_enum`
70+
- `pluto_new`
71+
- `pluto_class`
72+
- `pluto_parent`
73+
- `pluto_export`
74+
- `pluto_try`
75+
- `pluto_catch`

0 commit comments

Comments
 (0)