Skip to main content

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 to pluto or plutoc.

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 })