moonscript/docs/standard_lib.md

    target: reference/standard_lib
    template: reference
    title: MoonScript v0.2.0 - 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.