5.2 KiB
target: reference/standard_lib
template: reference
title: MoonScript v0.2.3 - Standard Library
short_name: stdlib
--
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:
```moon
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.
```moon
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 exept for the last with a new table
whose __index
is set to the next table.
Returns the first argument.
```moon
a = { hello: "world" }
b = { okay: "sure" }
extend a, b
print a.okay
```
copy(tbl)
Creates a shallow copy of a table, equivalent to:
```moon
copy = (arg) -> {k,v for k,v in pairs self}
```
Class/Object Functions
is_object(value)
Returns true if value
is an instance of a MoonScript class, false otherwise.
type(value)
If value
is an instance of a MoonScript class, then return it's class object.
Otherwise, return the result of calling Lua's type method.
```moon
class MyClass
nil
x = MyClass!
assert type(x) == MyClass
```
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.
```moon
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
.
```moon
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 listen in
method_names
. The inserted methods are bound methods that will run with
other_obj
as the receiver.
```moon
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:
```moon
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.