Compatibility
Pluto aims to be source- and bytecode-compatible with existing Lua code such that it can simply be used as a drop-in replacement for Lua, and Lua modules can simply be used in Pluto codebases. In the vast majority of cases, we do succeed, but there are a few things to be aware of.
New Keywords
Pluto adds the following reserved tokens:
switch
continue
enum
new
class
parent
export
try
catch
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.
Mitigations
- For Integrators: Check your
luaconf.h
file to find the relevant macros under the "Compatibility" heading. - For Scripters: Use
pluto_use
in the source files.-- @pluto_use * = false
to simply disable all incompatible keywords. - For Users: Pass the
-c
flag topluto
orplutoc
.
The following sections will go more in-depth on source-level mitigations (for scripters).
Compile-time Configuration (pluto_use)
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.
For example, to disable all non-compatible keywords except for switch
:
-- @pluto_use * = false, switch
It is also possible to specify a version number, which is a shorthand for the keywords available at that version:
"0.2.0"
corresponds to* = false, switch, continue
"0.5.0"
corresponds to* = false, switch, continue, enum
"0.6.0"
corresponds to* = false, switch, continue, enum, new, class, parent, export
"0.8.0"
corresponds to* = false, switch, continue, enum, new, class, parent, export, try, catch
So, writing a portable script that only makes use of Pluto 0.8.0's features requires this at the beginning:
pluto_use "0.8.0"
This feature also supports quick encompassing of optional features. So, instead of:
pluto_use "0.8.0", global
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 (global
).
pluto_use "0.9.0+"
-- The same as pluto_use "0.9.0", global
For module developers and scripts which may be used in future versions of Pluto, we recommend you use pluto_use
for two reasons:
- Portability. This will override the compatibility mode settings compiled into Pluto so your script will be parsed identically in all Pluto environments.
- 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.
Compatible Keywords
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.
These are what they look like:
pluto_switch
pluto_continue
pluto_enum
pluto_new
pluto_class
pluto_parent
pluto_export
pluto_try
pluto_catch
Default Table Metatable
This is a feature in Pluto that, by itself, is a benign QoL improvement for developers. However, in combination with our added standard library functions like table.min, it can be an unexpected semantic change:
local function roll(opts)
return math.random(opts.min or 1, opts.max or 100)
end
print(roll{ max = 10 })
pluto: test.pluto:2: bad argument #1 to 'random' (number expected, got function)
stack traceback:
[C]: in function 'math.rand'
test.pluto:2: in local 'roll'
test.pluto:4: in main chunk
Integrators can disable this feature by defining the PLUTO_NO_DEFAULT_TABLE_METATABLE
macro in their luaconf.h or build config, to aid in a smooth transition, should scripts in their ecosystem require it.
Scripters are advised to use rawget
and/or type
to better codify their expectations. For example, the example above seems to care only about providing fallback values and not at all about type-checking, so rawget
would be an excellent fit for it:
local function roll(opts)
return math.random(rawget(opts, "min") or 1, rawget(opts, "max") or 100)
end
print(roll{ max = 10 })