Additions to language standard library - List of all additions to language and library

During implementation of the standard library, several additions have been made, either to support MoonSharp specific functionalities or simply to extend the set of available functions with helpers.

NOTE : this is a list of all additions MoonSharp provides; if you are scripting for an application embedding MoonSharp, the list can be limited by the application author to a stricter subset.

Language differences

  • Multiple expressions can be used as indices but the value to be indexed must be a userdata, or a table resolving to userdata through the metatable (but without using metamethods). So, for example, x[1,2,i] is parsed correctly but might raise an error if x is not a userdata.
  • Metalua short anonymous functions (lambda-style) are supported. So |x, y| x + y is shorthand for function(x,y) return x+y end.
  • A non-yieldable __iterator metamethod has been added. It’s called if the argument f of a for ... in ... loop is not actually a function.
  • A default iterator looping over values (not keys) is provided if the argument f of a for ... in ... loop is a table without __iterator or __call metamethods
  • \u{xxx} escapes, where x are up to 8 hexadecimal digits, are supported inside strings and will output the specified Unicode codepoint, as it does in Lua 5.3

The _MOONSHARP table

The global namespace will contain a new _MOONSHARP table which exposes some members specific to MoonSharp

  • version : the version of the MoonSharp interpreter (as a string)
  • luacompat : the version of the Lua interpreter MoonSharp attempts to emulate (currently, “5.2”)
  • platform : the name of the platform it is running on
  • is_aot : a boolean - true if running on an AOT platform
  • is_unity : a boolean - true if running inside Unity
  • is_mono : a boolean - true if running on Mono
  • is_clr4 : a boolean - true if running on .NET 4.x
  • is_pcl : a boolean - true if running as a portable class library
  • banner : a banner similar to the one in the REPL interpreter

New functions in the global namespace

  • loadsafe (ld [, source [, mode [, env]]]) : Same as load, except that “env” defaults to the current environment of the function calling load, instead of the actual global environment.
  • loadfilesafe ([filename [, mode [, env]]]) : Same as loadfile, except that “env” defaults to the current environment of the function calling load, instead of the actual global environment.
  • pack(...) and unpack(...) : The functions table.pack and table.unpack are exposed on the global namespace too, to improve compatibility with code targeting Lua 5.1.

New functions in the ‘string’ module

  • string.unicode(s [, i [, j]]) : Same as string.byte except that it returns a unicode codepoint instead of byte value
  • string.contains(str1, str2) : Returns true if str2 is contained inside str1
  • string.startsWith(str1, str2) : Returns true if str2 is contained at the very start of str1
  • string.endsWith(str1, str2) : Returns true if str2 is contained at the very end of str1

The ‘dynamic’ module

MoonSharp offers a dynamic module which allows for expression evaluation without compiling Lua bytecode using the current execution context.

The evaluation will always perform raw access and will never call any function - it can be used to implement debuggers or things like a data load from a table source (using tables as if it was a format like JSON.. except Lua).

The expression evaluation is guaranteed to be side-effects free.

  • dynamic.eval(expr) : Evaluates dynamically the expression contained in expr which can be a string or an expression object created with dynamic.prepare.
  • dynamic.prepare(expr) : Creates a prepared expression object which can be passed to dynamic.eval for a faster execution than passing the string itself.

The ‘json’ module

MoonSharp offers a json module which converts between JSON scripts and Lua tables.

A major point is that JSON can represent nulls while tables cannot contain a nil value; in order to overcome this, a special value is used to represent nulls read from a JSON and the function json.isNull(val) can be used to check for this special value. The same value (generated by json.null()) can be used in tables which will be translated to JSON to represent explicit nulls.

  • json.parse(jsonString) : Returns a table with the contents of the specified json string.
  • json.serialize(table) : Returns a json string with the contents of the specified table.
  • json.isNull(val) : Returns true if the value specified is a null read from a json
  • json.null() : Returns a special value which is a representation of a null in a json