Skip to content

Commit 8c05716

Browse files
committed
Improve compatibility page, document '-c' flag
1 parent 95f163f commit 8c05716

File tree

2 files changed

+18
-12
lines changed

2 files changed

+18
-12
lines changed

docs/Compatibility.md

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ sidebar_position: 10
33
---
44

55
## How compatible with Lua is Pluto?
6-
Pluto is 99.9% compatible with most Lua source code. However, it's imperfect. Due to that, Pluto implements several compatibility macros.
6+
Pluto is compatible with most Lua source code. However, it's imperfect. Due to that, Pluto has several compatibility options.
77
### Where are the incompatibilities?
88
Pluto adds the following reserved tokens:
99
- `switch`
@@ -18,13 +18,17 @@ Pluto adds the following reserved tokens:
1818

1919
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).
2020

21-
However, we have a simple solution for this: Compatibility Mode. This allows integrators to disable Pluto's reserved tokens. Integrators: Check your `luaconf.h` file to find the relevant macros under the "Compatibility" heading.
21+
### How to fix it?
22+
All of these incompatible keywords can be disabled:
23+
- **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)
25+
- **For Users:** Pass the `-c` flag to `pluto` or `plutoc`.
2226

23-
## Writing Scripts Under Compatibility Mode
24-
Obviously, you want to use Pluto's features, so how can you do it if the Pluto environment has all of its tokens disabled? The secret is that each reserved token mentioned above has a portable variant with a `pluto_` prefix. For example, `switch` has a twin called `pluto_switch` that is always valid.
27+
## 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.
2529

2630
### Compile-time Configuration
27-
You can also change the meaning of Pluto's reserved tokens at any point in your scripts using the `@pluto_use` annotation or `pluto_use` statement.
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.
2832

2933
For example, to disable all non-compatible keywords except for `switch`:
3034
```pluto
@@ -37,12 +41,14 @@ It is also possible to specify a version number, which is a shorthand for the ke
3741
- `"0.6.0"` corresponds to `* = false, switch, continue, enum, new, class, parent, export`
3842
- `"0.8.0"` corresponds to `* = false, switch, continue, enum, new, class, parent, export, try, catch`
3943

40-
## Portability & proactive compatibility
41-
We recommend scripters use the `@pluto_use` annotation at the beginning of their scripts for two reasons:
44+
So, writing a portable script that makes use of Pluto 0.8.0's features simply requires this at the beginning:
45+
```pluto
46+
pluto_use "0.8.0"
47+
```
48+
49+
We recommend you always place a `pluto_use` configuration at the beginning of your scripts for two reasons:
4250
- **Portability.** This will override the compatibility mode settings compiled into Pluto so your script will be parsed identically in all Pluto environments.
4351
- **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.
4452

45-
Plus, it's as simple as this:
46-
```pluto
47-
-- @pluto_use "0.8.0"
48-
```
53+
### 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`.

src/theme/pluto.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
Prism.languages.pluto = {
22
'comment': /^#!.+|--(?:\[(=*)\[[\s\S]*?\]\1\]|.*)/m,
33
'attr-name': /(?<=(function|class|extends)\s)[\w:]+/,
4+
'keyword': /\$|\b(?:and|as|class|pluto_class|enum|begin|break|do|else|elseif|end|for|function|goto|if|in|local|new|not|or|repeat|return|static|then|until|while|continue|switch|case|default|pluto_switch|pluto_continue|extends|export|pluto_export|pluto_use|public|private|try|catch|pluto_try|pluto_catch)\b/,
45
'function': [
56
/\b(?!in\s)(?!\d)(?!return)(?!case)(?!function)(?!local)(?!new)\w+(?=\s*(?:\??\())/, // func()
67
/\b(?!in\s)(?!\d)(?!return)(?!case)(?!function)(?!local)(?!not)\w+(?=\s*(?:\??[{"]))/, // func "", func {}
@@ -17,7 +18,6 @@ Prism.languages.pluto = {
1718
},
1819
'boolean': /\b(?:true|false)\b/,
1920
'number': /\b([\d][\d_]+|(0x[a-f\d]+)|(0b[01]+))(?:\.[a-f\d]*)?(?:p[+-]?\d+)?\b|\b\d+(?:\.\B|(?:\.\d*)?(?:e[+-]?\d+)?\b)|\B\.\d+(?:e[+-]?\d+)?\b/i,
20-
'keyword': /\$|\b(?:and|as|class|pluto_class|enum|begin|break|do|else|elseif|end|for|function|goto|if|in|local|new|not|or|repeat|return|static|then|until|while|continue|switch|case|default|pluto_switch|pluto_continue|extends|export|pluto_export|pluto_use|public|private|try|catch|pluto_try|pluto_catch)\b/,
2121
'variable': /\b(?:self|parent|pluto_parent)\b/,
2222
'operator': [
2323
/[-+*%^&|#]|\/\/?|<[<=]?|>[>=]?|[=~]=?|\:=|\?|(?<!\w)\:|\?\.|instanceof/,

0 commit comments

Comments
 (0)