Manual:Lua

Summary

• Version 4.0beta3 introduces preliminary support for Lua scripting language. Integration with console is still in progress.
• RouterOS v4 RC1 removes Lua support until v5beta

Changes in console

• ':' and '/' namespaces are merged. Lookup rules have been changed so as not to affect existing scripts:
  • Without leading ':' or '/' names are looked up starting from the current path.
  • With leading ':' and '/' names are looked up starting from the root of the hierarchy.
  • With leading '/' current path of all subcommands is set to the path of command.
  • With leading ':' current path of subcommands is kept the same as the current path of command.

Example:

/ip address { #changes current path
    print   #/ip address print
    :queue simple print where interface=[get 0 interface]
        #this 'get' is '/ip address get', because
        #leading ':' does not change current path
        #for subcommands
}

• Value of type 'nothing' is gone.
• Command 'nothing' returns same value as the empty command '[]'. It is kept for compatibility with earlier versions.
• Value of type 'error' is gone, console error handling is unified with the Lua error hadling.
• 'error' command now immedeately raises an exception.
• New value type 'lua', holds arbitrary Lua values.
• New command 'lua' that returns lua function created from the given source string.
• Command can now also be a variable substitution, an expression or a command substitution. Result is evaluated. Example:

global a [parse "/interface print"]; $a
($a)
[parse "/interface print"]
[lua "io.write 'this works\\n'"]

• Global variables are shared between Lua and console scripts.
• There is no ':log' command anymore, it is replace by four commands 'log info', 'log error', 'log warning', 'log debug'. This change was necessary because of the root namespace merge. It preserves compatibility with previous scripts, but note that name of log topic cannot be a result of an expression.
• '/system script' items has new property 'language' that can be either 'cmd' or 'lua'. 'cmd' is for console scripts, 'lua' is for Lua scripts.
• New operator '%' that computes remainder.
• Logical operators now treat all values except nil and 'false' as 'true'. Note that empty string, empty array, number 0, IP address 0.0.0.0 and similar values are treated as a 'true', this is consistent with the Lua behaviour. Previously values of non-boolean type were causing an error.
• Logical 'and' and 'or' operators ('&&' and '||') now use shortcut evaluation. If left hand value is sufficient for computing the operation, it is returned and the right hand value is not computed. Otherwise, operation returns the right hand value. Example:

put (9 or (1 / 0)) #prints 9, division is not computed

Changes in Lua compared to the standard release

• Lua base version is 5.1.4
• Number type is 64 bit signed integer. Floating point constants are not supported. Exponentiation does not work with negative exponents.
• Following patches are applied:
  • Byte swapping for loading bytecode [1].
  • Patch by Thierry Grellier that adds '&' '|' '^^' '<<' '>>' '~' bitwise operators. Integer division operator is not included. [2]
• Following libraries are included:
  • bitlib [3], adapted for 64 bit integer numbers.
  • md5 1.1.2 [4]
  • lpeg 0.9 [5]
• Following features of standard libraries are not available:
  • 'io.popen', 'io.pclose', 'io.tmpfile'.
  • 'os.execute', 'os.tmpname', 'os.getenv', 'os.setlocale', 'os.exit'.
  • 'debug' library.
  • All functions and constants from 'math', except 'math.abs', 'math.ceil', 'math.floor', 'math.max', 'math.min' and 'math.random'.
  • 'print'
• Following changes are made to standard functions:
  • 'pairs' now calls "__pairs" metamethod of it's argument, and falls back to 'rawpairs' call. Original 'pairs' is now renamed to 'rawpairs'. These changes allow simple way of implementing default iteration behaviour for objects, by providing "__pairs" metamethod.
  • math.random without arguments can return any 64 bit integer number. All bits of the result are random.
• "/LIB" is a virtual path that contains additional libraries. This path is not accessible for file operations.