MoonScript is a programming language that compiles to Lua. This guide expects the reader to have basic familiarity with Lua. For each code snippet below, the MoonScript is on the left and the compiled Lua is on right right.

This is the official language reference manual, installation directions and the homepage are located at http://moonscript.org.

The Language

Whitespace

MoonScript is a whitespace sensitive language. This means that instead of using do and end (or { and }) to delimit sections of code we use line-breaks and indentation.

This means that how you indent your code is important. Luckily MoonScript doesn’t care how you do it but only requires that you be consistent.

An indent must be at least 1 space or 1 tab, but you can use as many as you like. All the code snippets on this page will use two spaces.

Should you happen to mix tabs and spaces, a tab is equivalent to 4 spaces. I shouldn’t be telling you this though because you should never do it.

Assignment

Assigning to an undeclared name will cause it to be declared as a new local variable. The language is dynamically typed so you can assign any value to any variable. You can assign multiple names and values at once just like Lua:

hello = "world"
a,b,c = 1, 2, 3
hello = 123 -- uses the existing variable

local hello = "world"
local a, b, c = 1, 2, 3
hello = 123

If you wish to create a global variable it must be done using the export keyword.

The local keyword can be used to forward declare a variable, or shadow an existing one.

Update Assignment

+=, -=, /=, *=, %=, ..=, or=, and= operators have been added for updating and assigning at the same time. They are aliases for their expanded equivalents.

x = 0
x += 10

s = "hello "
s ..= "world"

b = false
b and= true or false

local x = 0
x = x + 10
local s = "hello "
s = s .. "world"
local b = false
b = b and (true or false)

Comments

Like Lua, comments start with -- and continue to the end of the line. Comments are not written to the output.

-- I am a comment

Literals & Operators

All of the primitive literals in Lua can be used. This applies to numbers, strings, booleans, and nil.

All of Lua’s binary and unary operators are available. Additionally != is as an alias for ~=.

Unlike Lua, Line breaks are allowed inside of single and double quote strings without an escape sequence:

some_string = "Here is a string
  that has a line break in it."

local some_string = "Here is a string\n  that has a line break in it."

Function Literals

All functions are created using a function expression. A simple function is denoted using the arrow: ->

my_function = ->
my_function() -- call the empty function

local my_function
my_function = function() end
my_function()

The body of the function can either be one statement placed directly after the arrow, or it can be a series of statements indented on the following lines:

func_a = -> print "hello world"

func_b = ->
  value = 100
  print "The value:", value

local func_a
func_a = function()
  return print("hello world")
end
local func_b
func_b = function()
  local value = 100
  return print("The value:", value)
end

If a function has no arguments, it can be called using the ! operator, instead of empty parentheses. The ! invocation is the preferred way to call functions with no arguments.

func_a!
func_b()

func_a()
func_b()

Functions with arguments can be created by preceding the arrow with a list of argument names in parentheses:

sum = (x, y) -> print "sum", x + y

local sum
sum = function(x, y)
  return print("sum", x + y)
end

Functions can be called by listing the arguments after the name of an expression that evaluates to a function. When chaining together function calls, the arguments are applied to the closest function to the left.

sum 10, 20
print sum 10, 20

a b c "a", "b", "c"

sum(10, 20)
print(sum(10, 20))
a(b(c("a", "b", "c")))

In order to avoid ambiguity in when calling functions, parentheses can also be used to surround the arguments. This is required here in order to make sure the right arguments get sent to the right functions.

print "x:", sum(10, 20), "y:", sum(30, 40)

print("x:", sum(10, 20), "y:", sum(30, 40))

There must not be any space between the opening parenthesis and the function.

Functions will coerce the last statement in their body into a return statement, this is called implicit return:

sum = (x, y) -> x + y
print "The sum is ", sum 10, 20

local sum
sum = function(x, y)
  return x + y
end
print("The sum is ", sum(10, 20))

And if you need to explicitly return, you can use the return keyword:

sum = (x, y) -> return x + y

local sum
sum = function(x, y)
  return x + y
end

Just like in Lua, functions can return multiple values. The last statement must be a list of values separated by commas:

mystery = (x, y) -> x + y, x - y
a,b = mystery 10, 20

local mystery
mystery = function(x, y)
  return x + y, x - y
end
local a, b = mystery(10, 20)

Fat Arrows

Because it is an idiom in Lua to send an object as the first argument when calling a method, a special syntax is provided for creating functions which automatically includes a self argument.

func = (num) => @value + num

local func
func = function(self, num)
  return self.value + num
end

Argument Defaults

It is possible to provide default values for the arguments of a function. An argument is determined to be empty if its value is nil. Any nil arguments that have a default value will be replace before the body of the function is run.

my_function = (name="something", height=100) ->
  print "Hello I am", name
  print "My height is", height

local my_function
my_function = function(name, height)
  if name == nil then
    name = "something"
  end
  if height == nil then
    height = 100
  end
  print("Hello I am", name)
  return print("My height is", height)
end

An argument default value expression is evaluated in the body of the function in the order of the argument declarations. For this reason default values have access to previously declared arguments.

some_args = (x=100, y=x+1000) ->
  print x + y

local some_args
some_args = function(x, y)
  if x == nil then
    x = 100
  end
  if y == nil then
    y = x + 1000
  end
  return print(x + y)
end

Considerations

Because of the expressive parentheses-less way of calling functions, some restrictions must be put in place to avoid parsing ambiguity involving whitespace.

The minus sign plays two roles, a unary negation operator and a binary subtraction operator. Consider how the following examples compile:

a = x - 10
b = x-10
c = x -y
d = x- z

local a = x - 10
local b = x - 10
local c = x(-y)
local d = x - z

The precedence of the first argument of a function call can be controlled using whitespace if the argument is a literal string. In Lua, it is common to leave off parentheses when calling a function with a single string or table literal.

When there is no space between a variable and a string literal, the function call takes precedence over any following expressions. No other arguments can be passed to the function when it is called this way.

Where there is a space following a variable and a string literal, the function call acts as show above. The string literal belongs to any following expressions (if they exist), which serves as the argument list.

x = func"hello" + 100
y = func "hello" + 100

local x = func("hello") + 100
local y = func("hello" + 100)

Multi-line arguments

When calling functions that take a large number of arguments, it is convenient to split the argument list over multiple lines. Because of the white-space sensitive nature of the language, care must be taken when splitting up the argument list.

If an argument list is to be continued onto the next line, the current line must end in a comma. And the following line must be indented more than the current indentation. Once indented, all other argument lines must be at the same level of indentation to be part of the argument list

my_func 5,4,3,
  8,9,10

cool_func 1,2,
  3,4,
  5,6,
  7,8

my_func(5, 4, 3, 8, 9, 10)
cool_func(1, 2, 3, 4, 5, 6, 7, 8)

This type of invocation can be nested. The level of indentation is used to determine to which function the arguments belong to.

my_func 5,6,7,
  6, another_func 6,7,8,
    9,1,2,
  5,4

my_func(5, 6, 7, 6, another_func(6, 7, 8, 9, 1, 2), 5, 4)

Because tables also use the comma as a delimiter, this indentation syntax is helpful for letting values be part of the argument list instead of being part of the table.

x = {
  1,2,3,4, a_func 4,5,
    5,6,
  8,9,10
}

local x = {
  1,
  2,
  3,
  4,
  a_func(4, 5, 5, 6),
  8,
  9,
  10
}

Although uncommon, notice how we can give a deeper indentation for function arguments if we know we will be using a lower indentation further on.

y = { my_func 1,2,3,
   4,5,
  5,6,7
}

local y = {
  my_func(1, 2, 3, 4, 5),
  5,
  6,
  7
}

The same thing can be done with other block level statements like conditionals. We can use indentation level to determine what statement a value belongs to:

if func 1,2,3,
  "hello",
  "world"
    print "hello"
    print "I am inside if"

if func 1,2,3,
    "hello",
    "world"
  print "hello"
  print "I am inside if"

if func(1, 2, 3, "hello", "world") then
  print("hello")
  print("I am inside if")
end
if func(1, 2, 3, "hello", "world") then
  print("hello")
  print("I am inside if")
end

Table Literals

Like in Lua, tables are delimited in curly braces.

some_values = { 1, 2, 3, 4 }

local some_values = {
  1,
  2,
  3,
  4
}

Unlike Lua, assigning a value to a key in a table is done with : (instead of =).

some_values = {
  name: "Bill",
  age: 200,
  ["favorite food"]: "rice"
}

local some_values = {
  name = "Bill",
  age = 200,
  ["favorite food"] = "rice"
}

The curly braces can be left off if a single table of key value pairs is being assigned.

profile =
  height: "4 feet",
  shoe_size: 13,
  favorite_foods: {"ice cream", "donuts"}

local profile = {
  height = "4 feet",
  shoe_size = 13,
  favorite_foods = {
    "ice cream",
    "donuts"
  }
}

Newlines can be used to delimit values instead of a comma (or both):

values = {
  1,2,3,4
  5,6,7,8
  name: "superman"
  occupation: "crime fighting"
}

local values = {
  1,
  2,
  3,
  4,
  5,
  6,
  7,
  8,
  name = "superman",
  occupation = "crime fighting"
}

When creating a single line table literal, the curly braces can also be left off:

my_function dance: "Tango", partner: "none"

y = type: "dog", legs: 4, tails: 1

my_function({
  dance = "Tango",
  partner = "none"
})
local y = {
  type = "dog",
  legs = 4,
  tails = 1
}

The keys of a table literal can be language keywords without being escaped:

tbl = {
  do: "something"
  end: "hunger"
}

local tbl = {
  ["do"] = "something",
  ["end"] = "hunger"
}

If you are constructing a table out of variables and wish the keys to be the same as the variable names, then the : prefix operator can be used:

hair = "golden"
height = 200
person = { :hair, :height, shoe_size: 40 }

print_table :hair, :height

local hair = "golden"
local height = 200
local person = {
  hair = hair,
  height = height,
  shoe_size = 40
}
print_table({
  hair = hair,
  height = height
})

If you want the key of a field in the table to to be result of an expression, then you can wrap it in [ ], just like in Lua. You can also use a string literal directly as a key, leaving out the square brackets. This is useful if your key has any special characters.

t = {
  [1 + 2]: "hello"
  "hello world": true
}

local t = {
  [1 + 2] = "hello",
  ["hello world"] = true
}

Comprehensions

Comprehensions provide a convenient syntax for constructing a new table by iterating over some existing object and applying an expression to its values. There are two kinds of comprehensions: list comprehensions and table comprehensions. They both produce Lua tables; list comprehensions accumulate values into an array-like table, and table comprehensions let you set both the key and the value on each iteration.

List Comprehensions

The following creates a copy of the items table but with all the values doubled.

items = { 1, 2, 3, 4 }
doubled = [item * 2 for i, item in ipairs items]

local items = {
  1,
  2,
  3,
  4
}
local doubled
do
  local _accum_0 = { }
  local _len_0 = 1
  for i, item in ipairs(items) do
    _accum_0[_len_0] = item * 2
    _len_0 = _len_0 + 1
  end
  doubled = _accum_0
end

The items included in the new table can be restricted with a when clause:

iter = ipairs items
slice = [item for i, item in iter when i > 1 and i < 3]

local iter = ipairs(items)
local slice
do
  local _accum_0 = { }
  local _len_0 = 1
  for i, item in iter do
    if i > 1 and i < 3 then
      _accum_0[_len_0] = item
      _len_0 = _len_0 + 1
    end
  end
  slice = _accum_0
end

Because it is common to iterate over the values of a numerically indexed table, an * operator is introduced. The doubled example can be rewritten as:

doubled = [item * 2 for item in *items]

local doubled
do
  local _accum_0 = { }
  local _len_0 = 1
  local _list_0 = items
  for _index_0 = 1, #_list_0 do
    local item = _list_0[_index_0]
    _accum_0[_len_0] = item * 2
    _len_0 = _len_0 + 1
  end
  doubled = _accum_0
end

The for and when clauses can be chained as much as desired. The only requirement is that a comprehension has at least one for clause.

Using multiple for clauses is the same as using nested loops:

x_coords = {4, 5, 6, 7}
y_coords = {9, 2, 3}

points = [{x,y} for x in *x_coords for y in *y_coords]

local x_coords = {
  4,
  5,
  6,
  7
}
local y_coords = {
  9,
  2,
  3
}
local points
do
  local _accum_0 = { }
  local _len_0 = 1
  for _index_0 = 1, #x_coords do
    local x = x_coords[_index_0]
    for _index_1 = 1, #y_coords do
      local y = y_coords[_index_1]
      _accum_0[_len_0] = {
        x,
        y
      }
      _len_0 = _len_0 + 1
    end
  end
  points = _accum_0
end

Numeric for loops can also be used in comprehensions:

evens = [i for i=1,100 when i % 2 == 0]

local evens
do
  local _accum_0 = { }
  local _len_0 = 1
  for i = 1, 100 do
    if i % 2 == 0 then
      _accum_0[_len_0] = i
      _len_0 = _len_0 + 1
    end
  end
  evens = _accum_0
end

Table Comprehensions

The syntax for table comprehensions is very similar, only differing by using { and } and taking two values from each iteration.

This example makes a copy of the tablething:

thing = {
  color: "red"
  name: "fast"
  width: 123
}

thing_copy = {k,v for k,v in pairs thing}

local thing = {
  color = "red",
  name = "fast",
  width = 123
}
local thing_copy
do
  local _tbl_0 = { }
  for k, v in pairs(thing) do
    _tbl_0[k] = v
  end
  thing_copy = _tbl_0
end

Table comprehensions, like list comprehensions, also support multiple for and when clauses. In this example we use a when clause to prevent the value associated with the color key from being copied.

no_color = {k,v for k,v in pairs thing when k != "color"}

local no_color
do
  local _tbl_0 = { }
  for k, v in pairs(thing) do
    if k ~= "color" then
      _tbl_0[k] = v
    end
  end
  no_color = _tbl_0
end

The * operator is also supported. Here we create a square root look up table for a few numbers.

numbers = {1,2,3,4}
sqrts = {i, math.sqrt i for i in *numbers}

local numbers = {
  1,
  2,
  3,
  4
}
local sqrts
do
  local _tbl_0 = { }
  for _index_0 = 1, #numbers do
    local i = numbers[_index_0]
    _tbl_0[i] = math.sqrt(i)
  end
  sqrts = _tbl_0
end

The key-value tuple in a table comprehension can also come from a single expression, in which case the expression should return two values. The first is used as the key and the second is used as the value:

In this example we convert an array of pairs to a table where the first item in the pair is the key and the second is the value.

tuples = {{"hello", "world"}, {"foo", "bar"}}
tbl = {unpack tuple for tuple in *tuples}

local tuples = {
  {
    "hello",
    "world"
  },
  {
    "foo",
    "bar"
  }
}
local tbl
do
  local _tbl_0 = { }
  for _index_0 = 1, #tuples do
    local tuple = tuples[_index_0]
    local _key_0, _val_0 = unpack(tuple)
    _tbl_0[_key_0] = _val_0
  end
  tbl = _tbl_0
end

Slicing

A special syntax is provided to restrict the items that are iterated over when using the * operator. This is equivalent to setting the iteration bounds and a step size in a for loop.

Here we can set the minimum and maximum bounds, taking all items with indexes between 1 and 5 inclusive:

slice = [item for item in *items[1,5]]

local slice
do
  local _accum_0 = { }
  local _len_0 = 1
  local _list_0 = items
  local _max_0 = 5
  for _index_0 = 1, _max_0 < 0 and #_list_0 + _max_0 or _max_0 do
    local item = _list_0[_index_0]
    _accum_0[_len_0] = item
    _len_0 = _len_0 + 1
  end
  slice = _accum_0
end

Any of the slice arguments can be left off to use a sensible default. In this example, if the max index is left off it defaults to the length of the table. This will take everything but the first element:

slice = [item for item in *items[2,]]

local slice
do
  local _accum_0 = { }
  local _len_0 = 1
  local _list_0 = items
  for _index_0 = 2, #_list_0 do
    local item = _list_0[_index_0]
    _accum_0[_len_0] = item
    _len_0 = _len_0 + 1
  end
  slice = _accum_0
end

If the minimum bound is left out, it defaults to 1. Here we only provide a step size and leave the other bounds blank. This takes all odd indexed items: (1, 3, 5, …)

slice = [item for item in *items[,,2]]

local slice
do
  local _accum_0 = { }
  local _len_0 = 1
  local _list_0 = items
  for _index_0 = 1, #_list_0, 2 do
    local item = _list_0[_index_0]
    _accum_0[_len_0] = item
    _len_0 = _len_0 + 1
  end
  slice = _accum_0
end

String Interpolation

You can mix expressions into string literals using #{} syntax.

print "I am #{math.random! * 100}% sure."

print("I am " .. tostring(math.random() * 100) .. "% sure.")

String interpolation is only available in double quoted strings.

For Loop

There are two for loop forms, just like in Lua. A numeric one and a generic one:

for i = 10, 20
  print i

for k = 1,15,2 -- an optional step provided
  print k

for key, value in pairs object
  print key, value

for i = 10, 20 do
  print(i)
end
for k = 1, 15, 2 do
  print(k)
end
for key, value in pairs(object) do
  print(key, value)
end

The slicing and * operators can be used, just like with comprehensions:

for item in *items[2,4]
  print item

local _list_0 = items
local _max_0 = 4
for _index_0 = 2, _max_0 < 0 and #_list_0 + _max_0 or _max_0 do
  local item = _list_0[_index_0]
  print(item)
end

A shorter syntax is also available for all variations when the body is only a single line:

for item in *items do print item

for j = 1,10,3 do print j

local _list_0 = items
for _index_0 = 1, #_list_0 do
  local item = _list_0[_index_0]
  print(item)
end
for j = 1, 10, 3 do
  print(j)
end

A for loop can also be used as an expression. The last statement in the body of the for loop is coerced into an expression and appended to an accumulating array table.

Doubling every even number:

doubled_evens = for i=1,20
  if i % 2 == 0
    i * 2
  else
    i

local doubled_evens
do
  local _accum_0 = { }
  local _len_0 = 1
  for i = 1, 20 do
    if i % 2 == 0 then
      _accum_0[_len_0] = i * 2
    else
      _accum_0[_len_0] = i
    end
    _len_0 = _len_0 + 1
  end
  doubled_evens = _accum_0
end

You can also filter values by combining the for loop expression with the continue statement.

For loops at the end of a function body are not accumulated into a table for a return value (Instead the function will return nil). Either an explicit return statement can be used, or the loop can be converted into a list comprehension.

func_a = -> for i=1,10 do i
func_b = -> return for i=1,10 do i

print func_a! -- prints nil
print func_b! -- prints table object

local func_a
func_a = function()
  for i = 1, 10 do
    local _ = i
  end
end
local func_b
func_b = function()
  return (function()
    local _accum_0 = { }
    local _len_0 = 1
    for i = 1, 10 do
      _accum_0[_len_0] = i
      _len_0 = _len_0 + 1
    end
    return _accum_0
  end)()
end
print(func_a())
print(func_b())

This is done to avoid the needless creation of tables for functions that don’t need to return the results of the loop.

While Loop

The while loop also comes in two variations:

i = 10
while i > 0
  print i
  i -= 1

while running == true do my_function!

local i = 10
while i > 0 do
  print(i)
  i = i - 1
end
while running == true do
  my_function()
end

Like for loops, the while loop can also be used an expression. Additionally, for a function to return the accumulated value of a while loop, the statement must be explicitly returned.

Continue

A continue statement can be used to skip the current iteration in a loop.

i = 0
while i < 10
  continue if i % 2 == 0
  print i

local i = 0
while i < 10 do
  local _continue_0 = false
  repeat
    if i % 2 == 0 then
      _continue_0 = true
      break
    end
    print(i)
    _continue_0 = true
  until true
  if not _continue_0 then
    break
  end
end

continue can also be used with loop expressions to prevent that iteration from accumulating into the result. This examples filters the array table into just even numbers:

my_numbers = {1,2,3,4,5,6}
odds = for x in *my_numbers
  continue if x % 2 == 1
  x

local my_numbers = {
  1,
  2,
  3,
  4,
  5,
  6
}
local odds
do
  local _accum_0 = { }
  local _len_0 = 1
  for _index_0 = 1, #my_numbers do
    local _continue_0 = false
    repeat
      local x = my_numbers[_index_0]
      if x % 2 == 1 then
        _continue_0 = true
        break
      end
      local _value_0 = x
      _accum_0[_len_0] = _value_0
      _len_0 = _len_0 + 1
      _continue_0 = true
    until true
    if not _continue_0 then
      break
    end
  end
  odds = _accum_0
end

Conditionals

have_coins = false
if have_coins
  print "Got coins"
else
  print "No coins"

local have_coins = false
if have_coins then
  print("Got coins")
else
  print("No coins")
end

A short syntax for single statements can also be used:

have_coins = false
if have_coins then print "Got coins" else print "No coins"

local have_coins = false
if have_coins then
  print("Got coins")
else
  print("No coins")
end

Because if statements can be used as expressions, this can also be written as:

have_coins = false
print if have_coins then "Got coins" else "No coins"

local have_coins = false
print((function()
  if have_coins then
    return "Got coins"
  else
    return "No coins"
  end
end)())

Conditionals can also be used in return statements and assignments:

is_tall = (name) ->
  if name == "Rob"
    true
  else
    false

message = if is_tall "Rob"
  "I am very tall"
else
  "I am not so tall"

print message -- prints: I am very tall

local is_tall
is_tall = function(name)
  if name == "Rob" then
    return true
  else
    return false
  end
end
local message
if is_tall("Rob") then
  message = "I am very tall"
else
  message = "I am not so tall"
end
print(message)

The opposite of if is unless:

unless os.date("%A") == "Monday"
  print "it is not Monday!"

if not (os.date("%A") == "Monday") then
  print("it is not Monday!")
end

print "You're lucky!" unless math.random! > 0.1

if not (math.random() > 0.1) then
  print("You're lucky!")
end

With Assignment

if and elseif blocks can take an assignment in place of a conditional expression. Upon evaluating the conditional, the assignment will take place and the value that was assigned to will be used as the conditional expression. The assigned variable is only in scope for the body of the conditional, meaning it is never available if the value is not truthy.

if user = database.find_user "moon"
  print user.name

do
  local user = database.find_user("moon")
  if user then
    print(user.name)
  end
end

if hello = os.getenv "hello"
  print "You have hello", hello
elseif world = os.getenv "world"
  print "you have world", world
else
  print "nothing :("

do
  local hello = os.getenv("hello")
  if hello then
    print("You have hello", hello)
  else
    do
      local world = os.getenv("world")
      if world then
        print("you have world", world)
      else
        print("nothing :(")
      end
    end
  end
end

Line Decorators

For convenience, the for loop and if statement can be applied to single statements at the end of the line:

print "hello world" if name == "Rob"

if name == "Rob" then
  print("hello world")
end

And with basic loops:

print "item: ", item for item in *items

local _list_0 = items
for _index_0 = 1, #_list_0 do
  local item = _list_0[_index_0]
  print("item: ", item)
end

Switch

The switch statement is shorthand for writing a series of if statements that check against the same value. Note that the value is only evaluated once. Like if statements, switches can have an else block to handle no matches. Comparison is done with the == operator.

name = "Dan"
switch name
  when "Robert"
    print "You are Robert"
  when "Dan", "Daniel"
    print "Your name, it's Dan"
  else
    print "I don't know about your name"

local name = "Dan"
local _exp_0 = name
if "Robert" == _exp_0 then
  print("You are Robert")
elseif "Dan" == _exp_0 or "Daniel" == _exp_0 then
  print("Your name, it's Dan")
else
  print("I don't know about your name")
end

A switch when clause can match against multiple values by listing them out comma separated.

Switches can be used as expressions as well, here we can assign the result of the switch to a variable:

b = 1
next_number = switch b
  when 1
    2
  when 2
    3
  else
    error "can't count that high!"

local b = 1
local next_number
local _exp_0 = b
if 1 == _exp_0 then
  next_number = 2
elseif 2 == _exp_0 then
  next_number = 3
else
  next_number = error("can't count that high!")
end

We can use the then keyword to write a switch’s when block on a single line. No extra keyword is needed to write the else block on a single line.

msg = switch math.random(1, 5)
  when 1 then "you are lucky"
  when 2 then "you are almost lucky"
  else "not so lucky"

local msg
local _exp_0 = math.random(1, 5)
if 1 == _exp_0 then
  msg = "you are lucky"
elseif 2 == _exp_0 then
  msg = "you are almost lucky"
else
  msg = "not so lucky"
end

It is worth noting the order of the case comparison expression. The case’s expression is on the left hand side. This can be useful if the case’s expression wants to overwrite how the comparison is done by defining an eq metamethod.

Object Oriented Programming

In these examples, the generated Lua code may appear overwhelming. It is best to focus on the meaning of the MoonScript code at first, then look into the Lua code if you wish to know the implementation details.

A simple class:

class Inventory
  new: =>
    @items = {}

  add_item: (name) =>
    if @items[name]
      @items[name] += 1
    else
      @items[name] = 1

local Inventory
do
  local _base_0 = {
    add_item = function(self, name)
      if self.items[name] then
        self.items[name] = self.items[name] + 1
      else
        self.items[name] = 1
      end
    end
  }
  _base_0.__index = _base_0
  local _class_0 = setmetatable({
    __init = function(self)
      self.items = { }
    end,
    __base = _base_0,
    __name = "Inventory"
  }, {
    __index = _base_0,
    __call = function(cls, ...)
      local _self_0 = setmetatable({}, _base_0)
      cls.__init(_self_0, ...)
      return _self_0
    end
  })
  _base_0.__class = _class_0
  Inventory = _class_0
end

A class is declared with a class statement followed by a table-like declaration where all of the methods and properties are listed.

The new property is special in that it will become the constructor.

Notice how all the methods in the class use the fat arrow function syntax. When calling methods on a instance, the instance itself is sent in as the first argument. The fat arrow handles the creation of a self argument.

The @ prefix on a variable name is shorthand for self.. @items becomes self.items.

Creating an instance of the class is done by calling the name of the class as a function.

inv = Inventory!
inv\add_item "t-shirt"
inv\add_item "pants"

local inv = Inventory()
inv:add_item("t-shirt")
inv:add_item("pants")

Because the instance of the class needs to be sent to the methods when they are called, the \ operator is used.

All properties of a class are shared among the instances. This is fine for functions, but for other types of objects, undesired results may occur.

Consider the example below, the clothes property is shared amongst all instances, so modifications to it in one instance will show up in another:

class Person
  clothes: {}
  give_item: (name) =>
    table.insert @clothes, name

a = Person!
b = Person!

a\give_item "pants"
b\give_item "shirt"

-- will print both pants and shirt
print item for item in *a.clothes

The proper way to avoid this problem is to create the mutable state of the object in the constructor:

class Person
  new: =>
    @clothes = {}

Inheritance

The extends keyword can be used in a class declaration to inherit the properties and methods from another class.

class BackPack extends Inventory
  size: 10
  add_item: (name) =>
    if #@items > size then error "backpack is full"
    super name

local BackPack
do
  local _parent_0 = Inventory
  local _base_0 = {
    size = 10,
    add_item = function(self, name)
      if #self.items > size then
        error("backpack is full")
      end
      return _parent_0.add_item(self, name)
    end
  }
  _base_0.__index = _base_0
  setmetatable(_base_0, _parent_0.__base)
  local _class_0 = setmetatable({
    __init = function(self, ...)
      return _parent_0.__init(self, ...)
    end,
    __base = _base_0,
    __name = "BackPack",
    __parent = _parent_0
  }, {
    __index = function(cls, name)
      local val = rawget(_base_0, name)
      if val == nil then
        return _parent_0[name]
      else
        return val
      end
    end,
    __call = function(cls, ...)
      local _self_0 = setmetatable({}, _base_0)
      cls.__init(_self_0, ...)
      return _self_0
    end
  })
  _base_0.__class = _class_0
  if _parent_0.__inherited then
    _parent_0.__inherited(_parent_0, _class_0)
  end
  BackPack = _class_0
end

Here we extend our Inventory class, and limit the amount of items it can carry.

In this example, we don’t define a constructor on the subclass, so the parent class' constructor is called when we make a new instance. If we did define a constructor then we can use the super method to call the parent constructor.

Whenever a class inherits from another, it sends a message to the parent class by calling the method __inherited on the parent class if it exists. The function receives two arguments, the class that is being inherited and the child class.

class Shelf
  @__inherited: (child) =>
    print @__name, "was inherited by", child.__name

-- will print: Shelf was inherited by Cupboard
class Cupboard extends Shelf

Super

super is a special keyword that can be used in two different ways: It can be treated as an object, or it can be called like a function. It only has special functionality when inside a class.

When called as a function, it will call the function of the same name in the parent class. The current self will automatically be passed as the first argument. (As seen in the inheritance example above)

When super is used as a normal value, it is a reference to the parent class object.

It can be accessed like any of object in order to retrieve values in the parent class that might have been shadowed by the child class.

When the \ calling operator is used with super, self is inserted as the first argument instead of the value of super itself. When using . to retrieve a function, the raw function is returned.

A few examples of using super in different ways:

class MyClass extends ParentClass
  a_method: =>
    -- the following have the same effect:
    super "hello", "world"
    super\a_method "hello", "world"
    super.a_method self, "hello", "world"

    -- super as a value is equal to the parent class:
    assert super == ParentClass

local MyClass
do
  local _parent_0 = ParentClass
  local _base_0 = {
    a_method = function(self)
      _parent_0.a_method(self, "hello", "world")
      _parent_0.a_method(self, "hello", "world")
      _parent_0.a_method(self, "hello", "world")
      return assert(_parent_0 == ParentClass)
    end
  }
  _base_0.__index = _base_0
  setmetatable(_base_0, _parent_0.__base)
  local _class_0 = setmetatable({
    __init = function(self, ...)
      return _parent_0.__init(self, ...)
    end,
    __base = _base_0,
    __name = "MyClass",
    __parent = _parent_0
  }, {
    __index = function(cls, name)
      local val = rawget(_base_0, name)
      if val == nil then
        return _parent_0[name]
      else
        return val
      end
    end,
    __call = function(cls, ...)
      local _self_0 = setmetatable({}, _base_0)
      cls.__init(_self_0, ...)
      return _self_0
    end
  })
  _base_0.__class = _class_0
  if _parent_0.__inherited then
    _parent_0.__inherited(_parent_0, _class_0)
  end
  MyClass = _class_0
end

super can also be used on left side of a Function Stub. The only major difference is that instead of the resulting function being bound to the value of super, it is bound to self.

Types

Every instance of a class carries its type with it. This is stored in the special __class property. This property holds the class object. The class object is what we call to build a new instance. We can also index the class object to retrieve class methods and properties.

b = BackPack!
assert b.__class == BackPack

print BackPack.size -- prints 10

local b = BackPack()
assert(b.__class == BackPack)
print(BackPack.size)

Class Objects

The class object is what we create when we use a class statement. The class object is stored in a variable of the same name of the class.

The class object can be called like a function in order to create new instances. That’s how we created instances of classes in the examples above.

A class is made up of two tables. The class table itself, and the base table. The base is used as the metatable for all the instances. All properties listed in the class declaration are placed in the base.

The class object’s metatable reads properties from the base if they don’t exist in the class object. This means we can access functions and properties directly from the class.

It is important to note that assigning to the class object does not assign into the base, so it’s not a valid way to add new methods to instances. Instead the base must explicitly be changed. See the __base field below.

The class object has a couple special properties:

The name of the class as when it was declared is stored as a string in the __name field of the class object.

print BackPack.__name -- prints Backpack

print(BackPack.__name)

The base object is stored in __base. We can modify this table to add functionality to instances that have already been created and ones that are yet to be created.

If the class extends from anything, the parent class object is stored in __parent.

Class Variables

We can create variables directly in the class object instead of in the base by using @ in the front of the property name in a class declaration.

class Things
  @some_func: => print "Hello from", @__name

Things\some_func!

-- class variables not visible in instances
assert Things().some_func == nil

In expressions, we can use @@ to access a value that is stored in the __class of self. Thus, @@hello is shorthand for self.__class.hello.

class Counter
  @count: 0

  new: =>
    @@count += 1

Counter!
Counter!

print Counter.count -- prints 2

The calling semantics of @@ are similar to @. Calling a @@ name will pass the class in as the first argument using Lua’s colon syntax.

@@hello 1,2,3,4

self.__class:hello(1, 2, 3, 4)

Class Declaration Statements

In the body of a class declaration, we can have normal expressions in addition to key/value pairs. In this context, self is equal to the class object.

Here is an alternative way to create a class variable compared to what’s described above:

class Things
  @class_var = "hello world"

local Things
do
  local _base_0 = { }
  _base_0.__index = _base_0
  local _class_0 = setmetatable({
    __init = function() end,
    __base = _base_0,
    __name = "Things"
  }, {
    __index = _base_0,
    __call = function(cls, ...)
      local _self_0 = setmetatable({}, _base_0)
      cls.__init(_self_0, ...)
      return _self_0
    end
  })
  _base_0.__class = _class_0
  local self = _class_0
  self.class_var = "hello world"
  Things = _class_0
end

These expressions are executed after all the properties have been added to the base.

All variables declared in the body of the class are local to the classes properties. This is convenient for placing private values or helper functions that only the class methods can access:

class MoreThings
  secret = 123
  log = (msg) -> print "LOG:", msg

  some_method: =>
    log "hello world: " .. secret

@ and @@ Values

When @ and @@ are prefixed in front of a name they represent, respectively, that name accessed in self and self.__class.

If they are used all by themselves, they are aliases for self and self.__class.

assert @ == self
assert @@ == self.__class

assert(self == self)
assert(self.__class == self.__class)

For example, a quick way to create a new instance of the same class from an instance method using @@:

some_instance_method = (...) => @@ ...

local some_instance_method
some_instance_method = function(self, ...)
  return self.__class(...)
end

Class Expressions

The class syntax can also be used as an expression which can be assigned to a variable or explicitly returned.

x = class Bucket
  drops: 0
  add_drop: => @drops += 1

Anonymous classes

The name can be left out when declaring a class. The __name attribute will be nil, unless the class expression is in an assignment. The name on the left hand side of the assignment is used instead of nil.

BigBucket = class extends Bucket
  add_drop: => @drops += 10

assert Bucket.__name == "BigBucket"

You can even leave off the body, meaning you can write a blank anonymous class like this:

x = class

Export Statement

Because all assignments to variables that are not lexically visible will be declared as local, special syntax is required to declare a variable globally.

The export keyword makes it so any following assignments to the specified names will not be assigned locally.

export var_name, var_name2
var_name, var_name3 = "hello", "world"

local var_name3
var_name, var_name3 = "hello", "world"

This is especially useful when declaring what will be externally visible in a module:

-- my_module.moon
module "my_module", package.seeall
export print_result

length = (x, y) -> math.sqrt x*x + y*y

print_result = (x, y) ->
  print "Length is ", length x, y

-- main.moon
require "my_module"

my_module.print_result 4, 5 -- prints the result

print my_module.length 6, 7 -- errors, `length` not visible

module("my_module", package.seeall)
local length
length = function(x, y)
  return math.sqrt(x * x + y * y)
end
print_result = function(x, y)
  return print("Length is ", length(x, y))
end
require("my_module")
my_module.print_result(4, 5)
print(my_module.length(6, 7))

Assignment can be combined with the export keyword to assign to global variables directly:

export some_number, message_str = 100, "hello world"

some_number, message_str = 100, "hello world"

Additionally, a class declaration can be prefixed with the export keyword in order to export it.

Export will have no effect if there is already a local variable of the same name in scope.

Export All & Export Proper

The export statement can also take special symbols * and ^.

export * will cause any name declared after the statement to be exported in the current scope. export ^ will export all proper names, names that begin with a capital letter.

Local Statement

Sometimes you want to declare a variable name before the first time you assign it. The local statement can be used to do that.

In this example we declare the variable a in the outer scope so its value can be accessed after the if statement. If there was no local statement then a would only be accessible inside the if statement.

local a
if something
  a = 1
print a

local a
if something then
  a = 1
end
print(a)

local can also be used to shadow existing variables for the rest of a scope.

x = 10
if something
  local x
  x = 12
print x -- prints 10

local x = 10
if something then
  local x
  x = 12
end
print(x)

When you have one function that calls another, you typically order them such that the second function can access the first. If both functions happen to call each other, then you must forward declare the names:

local first, second

first = ->
  second!

second = ->
  first!

local first, second
first = function()
  return second()
end
second = function()
  return first()
end

The same problem occurs with declaring classes and regular values too.

Because forward declaring is often better than manually ordering your assigns, a special form of local is provided:

local *

first = ->
  print data
  second!

second = ->
  first!

data = {}

local first, second, data
first = function()
  print(data)
  return second()
end
second = function()
  return first()
end
data = { }

local * will forward declare all names below it in the current scope.

Similarly to export one more special form is provided, local ^. This will forward declare all names that begin with a capital letter.

Import Statement

Often you want to bring some values from a table into the current scope as local variables by their name. The import statement lets us accomplish this:

import insert from table

local insert
insert = table.insert

The multiple names can be given, each separated by a comma:

import C, Ct, Cmt from lpeg

local C, Ct, Cmt
do
  local _obj_0 = lpeg
  C, Ct, Cmt = _obj_0.C, _obj_0.Ct, _obj_0.Cmt
end

Sometimes a function requires that the table be sent in as the first argument (when using the \ syntax). As a shortcut, we can prefix the name with a \ to bind it to that table:

-- some object
my_module =
  state: 100
  add: (value) =>
    self.state + value

import \add from my_module

print add 22 -- equivalent to calling my_module\get 22

local my_module = {
  state = 100,
  add = function(self, value)
    return self.state + value
  end
}
local add
do
  local _base_0 = my_module
  local _fn_0 = _base_0.add
  add = function(...)
    return _fn_0(_base_0, ...)
  end
end
print(add(22))

When handing multiple imports you can substitute the comma with a newline and any amount of whitespace. When working with a lot of imports you might write something like this:

import
  assert_csrf
  assert_timezone
  not_found
  require_login
  from require "helpers"

local assert_csrf, assert_timezone, not_found, require_login
do
  local _obj_0 = require("helpers")
  assert_csrf, assert_timezone, not_found, require_login = _obj_0.assert_csrf, _obj_0.assert_timezone, _obj_0.not_found, _obj_0.require_login
end

With Statement

A common pattern involving the creation of an object is calling a series of functions and setting a series of properties immediately after creating it.

This results in repeating the name of the object multiple times in code, adding unnecessary noise. A common solution to this is to pass a table in as an argument which contains a collection of keys and values to overwrite. The downside to this is that the constructor of this object must support this form.

The with block helps to alleviate this. Within a with block we can use a special statements that begin with either . or \ which represent those operations applied to the object we are using with on.

For example, we work with a newly created object:

with Person!
  .name = "Oswald"
  \add_relative my_dad
  \save!
  print .name

do
  local _with_0 = Person()
  _with_0.name = "Oswald"
  _with_0:add_relative(my_dad)
  _with_0:save()
  print(_with_0.name)
end

The with statement can also be used as an expression which returns the value it has been giving access to.

file = with File "favorite_foods.txt"
  \set_encoding "utf8"

local file
do
  local _with_0 = File("favorite_foods.txt")
  _with_0:set_encoding("utf8")
  file = _with_0
end

Or…

create_person = (name,  relatives) ->
  with Person!
    .name = name
    \add_relative relative for relative in *relatives

me = create_person "Leaf", {dad, mother, sister}

local create_person
create_person = function(name, relatives)
  do
    local _with_0 = Person()
    _with_0.name = name
    for _index_0 = 1, #relatives do
      local relative = relatives[_index_0]
      _with_0:add_relative(relative)
    end
    return _with_0
  end
end
local me = create_person("Leaf", {
  dad,
  mother,
  sister
})

In this usage, with can be seen as a special form of the K combinator.

The expression in the with statement can also be an assignment, if you want to give a name to the expression.

with str = "Hello"
  print "original:", str
  print "upper:", \upper!

do
  local str = "Hello"
  print("original:", str)
  print("upper:", str:upper())
end

Do

When used as a statement, do works just like it does in Lua.

do
  var = "hello"
  print var
print var -- nil here

do
  local var = "hello"
  print(var)
end
print(var)

MoonScript’s do can also be used an expression . Allowing you to combine multiple lines into one. The result of the do expression is the last statement in its body.

counter = do
  i = 0
  ->
    i += 1
    i

print counter!
print counter!

local counter
do
  local i = 0
  counter = function()
    i = i + 1
    return i
  end
end
print(counter())
print(counter())

tbl = {
  key: do
    print "assigning key!"
    1234
}

local tbl = {
  key = (function()
    print("assigning key!")
    return 1234
  end)()
}

Destructuring Assignment

Destructuring assignment is a way to quickly extract values from a table by their name or position in array based tables.

Typically when you see a table literal, {1,2,3}, it is on the right hand side of an assignment because it is a value. Destructuring assignment swaps the role of the table literal, and puts it on the left hand side of an assign statement.

This is best explained with examples. Here is how you would unpack the first two values from a table:

thing = {1,2}

{a,b} = thing
print a,b

local thing = {
  1,
  2
}
local a, b
a, b = thing[1], thing[2]
print(a, b)

In the destructuring table literal, the key represents the key to read from the right hand side, and the value represents the name the read value will be assigned to.

obj = {
  hello: "world"
  day: "tuesday"
  length: 20
}

{hello: hello, day: the_day} = obj
print hello, the_day

local obj = {
  hello = "world",
  day = "tuesday",
  length = 20
}
local hello, the_day
hello, the_day = obj.hello, obj.day
print(hello, the_day)

This also works with nested data structures as well:

obj2 = {
  numbers: {1,2,3,4}
  properties: {
    color: "green"
    height: 13.5
  }
}

{numbers: {first, second}} = obj2
print first, second, color

local obj2 = {
  numbers = {
    1,
    2,
    3,
    4
  },
  properties = {
    color = "green",
    height = 13.5
  }
}
local first, second
first, second = obj2.numbers[1], obj2.numbers[2]
print(first, second, color)

If the destructuring statement is complicated, feel free to spread it out over a few lines. A slightly more complicated example:

{
  numbers: { first, second }
  properties: {
    color: color
  }
} = obj2

local first, second, color
do
  local _obj_0 = obj2
  first, second, color = _obj_0.numbers[1], _obj_0.numbers[2], _obj_0.properties.color
end

It’s common to extract values from at table and assign them the local variables that have the same name as the key. In order to avoid repetition we can use the : prefix operator:

{:concat, :insert} = table

local concat, insert
do
  local _obj_0 = table
  concat, insert = _obj_0.concat, _obj_0.insert
end

This is effectively the same as import, but we can rename fields we want to extract by mixing the syntax:

{:mix, :max, random: rand } = math

local mix, max, rand
do
  local _obj_0 = math
  mix, max, rand = _obj_0.mix, _obj_0.max, _obj_0.random
end

Destructuring In Other Places

Destructuring can also show up in places where an assignment implicitly takes place. An example of this is a for loop:

tuples = {
  {"hello", "world"}
  {"egg", "head"}
}

for {left, right} in *tuples
  print left, right

local tuples = {
  {
    "hello",
    "world"
  },
  {
    "egg",
    "head"
  }
}
for _index_0 = 1, #tuples do
  local _des_0 = tuples[_index_0]
  local left, right
  left, right = _des_0[1], _des_0[2]
  print(left, right)
end

We know each element in the array table is a two item tuple, so we can unpack it directly in the names clause of the for statement using a destructure.

Function Stubs

It is common to pass a function from an object around as a value, for example, passing an instance method into a function as a callback. If the function expects the object it is operating on as the first argument then you must somehow bundle that object with the function so it can be called properly.

The function stub syntax is a shorthand for creating a new closure function that bundles both the object and function. This new function calls the wrapped function in the correct context of the object.

Its syntax is the same as calling an instance method with the \ operator but with no argument list provided.

my_object = {
  value: 1000
  write: => print "the value:", @value
}

run_callback = (func) ->
  print "running callback..."
  func!

-- this will not work:
-- the function has to no reference to my_object
run_callback my_object.write

-- function stub syntax
-- lets us bundle the object into a new function
run_callback my_object\write

local my_object = {
  value = 1000,
  write = function(self)
    return print("the value:", self.value)
  end
}
local run_callback
run_callback = function(func)
  print("running callback...")
  return func()
end
run_callback(my_object.write)
run_callback((function()
  local _base_0 = my_object
  local _fn_0 = _base_0.write
  return function(...)
    return _fn_0(_base_0, ...)
  end
end)())

The Using Clause; Controlling Destructive Assignment

While lexical scoping can be a great help in reducing the complexity of the code we write, things can get unwieldy as the code size increases. Consider the following snippet:

i = 100

-- many lines of code...

my_func = ->
  i = 10
  while i > 0
    print i
    i -= 1

my_func!

print i -- will print 0

local i = 100
local my_func
my_func = function()
  i = 10
  while i > 0 do
    print(i)
    i = i - 1
  end
end
my_func()
print(i)

In my_func, we've overwritten the value of i mistakenly. In this example it is quite obvious, but consider a large, or foreign code base where it isn’t clear what names have already been declared.

It would be helpful to say which variables from the enclosing scope we intend on change, in order to prevent us from changing others by accident.

The using keyword lets us do that. using nil makes sure that no closed variables are overwritten in assignment. The using clause is placed after the argument list in a function, or in place of it if there are no arguments.

i = 100

my_func = (using nil) ->
  i = "hello" -- a new local variable is created here

my_func!
print i -- prints 100, i is unaffected

local i = 100
local my_func
my_func = function()
  local i = "hello"
end
my_func()
print(i)

Multiple names can be separated by commas. Closure values can still be accessed, they just cant be modified:

tmp = 1213
i, k = 100, 50

my_func = (add using k,i) ->
  tmp = tmp + add -- a new local tmp is created
  i += tmp
  k += tmp

my_func(22)
print i,k -- these have been updated

local tmp = 1213
local i, k = 100, 50
local my_func
my_func = function(add)
  local tmp = tmp + add
  i = i + tmp
  k = k + tmp
end
my_func(22)
print(i, k)

Misc.

Implicit Returns on Files

By default, a file will also implicitly return like a function. This is useful for writing modules, where you can put your module’s table as the last statement in the file so it is returned when loaded with require.

Writing Modules

Lua 5.2 has removed the module function for creating modules. It is recommended to return a table instead when defining a module.

We can cleanly define modules by using the shorthand hash table key/value syntax:

MY_CONSTANT = "hello"

my_function = -> print "the function"
my_second_function = -> print "another function"

{ :my_function, :my_second_function, :MY_CONSTANT}

local MY_CONSTANT = "hello"
local my_function
my_function = function()
  return print("the function")
end
local my_second_function
my_second_function = function()
  return print("another function")
end
return {
  my_function = my_function,
  my_second_function = my_second_function,
  MY_CONSTANT = MY_CONSTANT
}

If you need to forward declare your values so you can access them regardless of their written order you can add local * to the top of your file.

License (MIT)

Copyright (C) 2015 by Leaf Corcoran

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.