The MoonScript installation comes with a small kernel of functions that can be used to perform various common things.

The entire library is currently contained in a single object. We can bring this moon object into scope by requiring "moon".

moon = require "moon"
-- `moon.p` is the debug printer
moon.p { hello: "world" }

If you prefer to just inject all of the functions into the current scope, you can require "moon.all" instead. The following has the same effect as above:

require "moon.all"
p { hello: "world" }

All of the functions are compatible with Lua in addition to MoonScript, but some of them only make sense in the context of MoonScript.

MoonScript Standard Library

This is an overview of all the included functions. All of the examples assume that the standard library has been included with require "moon.all".

Printing Functions

p(arg)

Prints a formatted version of an object. Excellent for inspecting the contents of a table.

Table Functions

run_with_scope(fn, scope, [args...])

Mutates the environment of function fn and runs the function with any extra arguments in args.... Returns the result of the function.

The environment of the function is set to a new table whose metatable will use scope to look up values. scope must be a table. If scope does not have an entry for a value, it will fall back on the original environment.

my_env = {
  secret_function: -> print "shhh this is secret"
  say_hi: -> print "hi there!"
}

say_hi = -> print "I am a closure"

fn = ->
  secret_function!
  say_hi!

run_with_scope fn, my_env

Note that any closure values will always take precedence against global name lookups in the environment. In the example above, the say_hi in the environment has been shadowed by the local variable say_hi.

defaultbl([tbl,] fn)

Sets the __index of table tbl to use the function fn to generate table values when a missing key is looked up.

extend(arg1, arg2, [rest...])

Chains together a series of tables by their metatable’s __index property. Overwrites the metatable of all objects except for the last with a new table whose __index is set to the next table.

Returns the first argument.

a = { hello: "world" }
b = { okay: "sure" }

extend a, b

print a.okay

copy(tbl)

Creates a shallow copy of a table, equivalent to:

copy = (arg) -> {k,v for k,v in pairs self}

Class/Object Functions

is_class(value)

Returns true if value is a MoonScript class table, false otherwise. Returns false for instances, __base tables, plain tables, and non-table values.

Works by checking that the value is a table with a __base field set directly on it, and that its metatable has a __call field (the constructor). Both are properties unique to MoonScript class tables.

class MyClass

is_class MyClass        -- true
is_class MyClass!       -- false
is_class MyClass.__base -- false

is_instance(value)

Returns true if value is an instance of a MoonScript class, false otherwise. Returns false for class tables, __base tables, plain tables, and non-table values.

Works by checking that the value is a table whose metatable is a __base table (identified by having a self-referencing __index), and that the value itself is not a __base table.

class MyClass

is_instance MyClass!       -- true
is_instance MyClass        -- false
is_instance MyClass.__base -- false

is_instance_of(value, class)

Returns true if value is an instance of class or any of its parent classes, false otherwise. Throws an error if value is not a MoonScript instance. First verifies that value is a valid instance using is_instance, then walks the __parent chain to check if the instance’s class matches or inherits from class.

class Parent
class Child extends Parent

is_instance_of Child!, Child  -- true
is_instance_of Child!, Parent -- true (checks parent classes)
is_instance_of Parent!, Child -- false

To check if a value is a direct instance of a specific class without considering inheritance, use type(value) == MyClass instead.

is_subclass_of(cls, parent)

Returns true if cls is a subclass of parent, false otherwise. Throws an error if cls is not a MoonScript class. Note that a class is not considered a subclass of itself. Walks the __parent chain starting from cls to check if any ancestor matches parent.

class Parent
class Child extends Parent

is_subclass_of Child, Parent -- true
is_subclass_of Parent, Child -- false
is_subclass_of Child, Child  -- false

type(value)

Returns a class-aware type for a value. If value is an instance of a MoonScript class, returns its class object. If value is a class table, returns the string "class". Returns the result of calling Lua’s built-in type for all other values, including __base tables and plain tables.

class MyClass

x = MyClass!
assert type(x) == MyClass
assert type(MyClass) == "class"
assert type(MyClass.__base) == "table"

is_object(value)

Legacy method for testing if a value is an instance.

Deprecated: Use is_instance or is_class instead. is_object returns truthy for instances, classes, and __base tables, any table with __class accessible. It cannot distinguish between these cases.

bind_methods(obj)

Takes an instance of an object, returns a proxy to the object whose methods can be called without providing self as the first argument.

obj = SomeClass!

bound_obj = bind_methods obj

-- following have the same effect
obj\hello!
bound_obj.hello!

It lazily creates and stores in the proxy table the bound methods when they are first called.

mixin(obj, class, [args...])

Copies the methods of a class cls into the table obj, then calls the constructor of the class with the obj as the receiver.

In this example we add the functionality of First to an instance of Second without ever instancing First.

class First
  new: (@var) =>
  show_var: => print "var is:", @var

class Second
  new: =>
    mixin self, First, "hi"

a = Second!
a\show_var!

Be weary of name collisions when mixing in other classes, names will be overwritten.

mixin_object(obj, other_obj, method_names)

Inserts into obj methods from other_obj whose names are listed in method_names. The inserted methods are bound methods that will run with other_obj as the receiver.

class List 
  add: (item) => print "adding to", self
  remove: (item) => print "removing from", self

class Encapsulation
  new: =>
    @list = List!
    mixin_object self, @list, {"add", "remove"}

e = Encapsulation!
e.add "something"

mixin_table(a, b, [names])

Copies the elements of table b into table a. If names is provided, then only those names are copied.

Misc Functions

fold(items, fn)

Calls function fn repeatedly with the accumulated value and the current value by iterating over items. The accumulated value is the result of the last call to fn, or, in the base case, the first value. The current value is the value being iterated over starting with the second item.

items is a normal array table.

For example, to sum all numbers in a list:

numbers = {4,3,5,6,7,2,3}
sum = fold numbers, (a,b) -> a + b

Debug Functions

debug.upvalue(fn, key[, value])

Gets or sets the value of an upvalue for a function by name.