Getting started with MoonScript

Last updated Fri May 2 2014

MoonScript is an open source prgramming language which compiles into Lua. Lua is a very powerful dynamically typed language. It supports features like functions as first class objects, closures, tail-recursion and a high performance.

Lua has made its way into a variety of locations, like games, text editors, and window managers, due to its simplicity to embed in addition to its ability to be run from the command line like any other scripting language.

MoonScript is built on top of Lua to take advantage of the same excellent platform in addition to providing a collection of syntactic features which aid in rapid development.

You can think of MoonScript as an easier and faster way to write Lua. MoonScript is compatible with all existing Lua code, and Lua code can natively work with MoonScript code. MoonScript is just another way to write Lua.

This is a guide to get your system ready for MoonScript development.

If you have any trouble, or find something outdated in the guide please leave a comment at the bottom.

• Installing
• Windows
• OSX
• Install Homebrew
• Install LuaRocks and MoonScript
• Linux
• From Source
• Setting Up Your Editor
• SciTE Windows Binary
• Creating Programs
• Compiling & Running
• Watch Mode
• Compile To Directory
• What’s Next?

Installing

Installation of MoonScript is slightly different depending on the platform. MoonScript is written in pure Lua but some of its dependencies are written in C. Chose your platform to begin:

• Windows
• OSX
• Linux

Windows

Because compiling the dependencies can be challenging, pre-built Windows binaries have been created.

Download moonscript-0.2.5.zip, the latest version as of this guide.

All versions can be found here: http://moonscript.org/bin/

Within the zip file, moon.exe and moonc.exe are the MoonScript executables. We want to be able to run these executables from the command line easily so we'll need to put them in one of the directories listed by the PATH environment variable.

Create a directory somewhere on your computer where you want your MoonScript installation to be. For example, I will use C:\moonscript.

Extract all the files from the zip into the new directory. moon.exe, moonc.exe and lua5.1.dll must be present for MoonScript to work.

Next, from the control panel goto System > Advanced Tab. Click on the Environment Variables button.

Under User variables, see if there is an existing PATH entry. If there isn’t, click New, else select PATH and click Edit.

If the variable value is empty, then just paste the MoonScript installation directory in. If it isn’t empty, then the new directory can be added at the end but it must be separated by a ; character.

Below is an image of my PATH, I happened to have another directory in it so I separated the new entry with a ;.

Now we can test our installation, open up a new command prompt and type in:

moon --version

If the installation was successful, then the version of MoonScript is printed.

If you see 'moon' is not recognized... then the installation was not done successfully. Go through the directions again and make sure nothing was left out.

Although not required, it is recommended to also install both Lua and LuaRocks. This will give you access to the rich collection of packages available to Lua.

Once you're ready, head to Setting Up Your Editor.

OSX

We'll use Homebrew to install LuaRocks, the Lua package manager.

Install Homebrew

If you don’t Hombrew installed already follow the Hombrew installation instructions, then return here.

If you do Homebrew installed, update it:

$ brew update

It’s best to have the latest version of LuaRocks that Hombrew provides, and this will ensure we get it.

Install LuaRocks and MoonScript

With Hombrew installed we can easily install LuaRocks:

$ brew install luarocks

This will also install Lua.

Now we can install the latest version of moonscript:

$ luarocks install moonscript

The moonscript package is now visible to Lua, but the MoonScript binaries aren’t in out path yet. By default LuaRocks will install binaries to /usr/local/lib/luarocks/bin/.

Edit your ~/.profile and add:

export PATH=$PATH:/usr/local/lib/luarocks/bin/

Test your installation by running in a new terminal:

$ moon --version

Test that we can require moonscript by running this command, it should produce no output:

$ lua -e 'require "moonscript"'

Once you are ready, head to Setting Up Your Editor.

Linux

We're going to use LuaRocks, the Lua package manager. It will handle building all the dependencies for you in addition to installing MoonScript to the right spot. This method depends on having a build tools installed.

Most mainstream distributions will have LuaRocks in their package repository. If not, you can follow the LuaRocks installation directions.

To install, just run:

$ sudo luarocks install moonscript

We use sudo here to install globally to the system, enabling us to use the moon and moonc commands from anywhere. If you wish you can install locally by leaving off the sudo.

Assuming everything builds correctly, the executables moon and moonc will now be installed, along with the moonscript Lua module.

From Source

The source code can be downloaded from GitHub at http://github.com/leafo/moonscript.

The latest development version can be installed from source using LuaRocks with the special dev rockspec:

$ luarocks build http://moonscript.org/rocks/moonscript-dev-1.rockspec

Setting Up Your Editor

The following editors have support for MoonScript:

• Vim: moonscript-vim
• SciTE: scintillua lexer
• TextMate (and Sublime Text): moonscript-tmbundle

If you are unsure what to use and are on Windows, download the SciTE Windows binary.

SciTE Windows Binary

If you're on Windows then you're in luck! I've packaged SciTE, scintillua and the MoonScript highlighter together into one package. I've even installed the custom moon theme.

You can download the latest version at http://moonscript.org/scite/moonscript-scite.zip.

Just extract, and run scite.exe. You're now ready to start creating programs.

Creating Programs

Compiling & Running

The MoonScript package comes with two executables, moon and moonc.

With moonc we can compile MoonScript code into Lua. Let’s try it out, create a new file called hello.moon:

-- I'm a comment!
print "Hello from MoonScript!"

From your terminal:

$ moonc hello.moon
Built    ./hello.moon

This created a file called hello.lua. Feel free to run this code using lua.

The moon executable lets us run our code without having to manually compile it to Lua first. We can run the script we just created like so:

$ moon hello.moon
Hello from MoonScript!

moon automatically compiles the file in memory and then executes it right away inside the Lua runtime.

Watch Mode

moonc can do a couple interesting things worth mentioning. If you run moonc -h you can see an entire list of all of it’s command line options.

We're going to take a look at watch mode, which is activated using -w.

Watch mode will watch all of the input files and recompile them if they change.

For example, to automatically rebuild a single moon file if it’s changed:

$ moonc -w my_file.moon

If you want to watch all the moon files in the current directory you can simply do:

$ moonc -w *.moon

If you want to watch an entire directory (along with it’s children) for modified moon files, just use the directory’s name:

$ moonc -w code_directory

And finally, if you want to watch the current directory and all sub directories for changes you can just use .:

$ moonc -w .

Watch mode will tell you every time it compiles a file in the terminal. It will also tell you if there are any compilation errors.

There are two things to be aware of:

1. New files aren’t picked up, you have to restart moonc
2. moonc doesn’t compile everything on start up. Use moonc without the -w flag to excplicity compile everything

Compile To Directory

If you want to save your compiled MoonScript’s Lua files elsewhere, use the -t flag to specify a directory. The entire directory structure of your MoonScript code will be preserved.

It can also be used with watch mode, for example:

The following will recursively watch all moon files from the current directory, and write them into the directory my_lua.

$ moonc -w -t my_lua .

What’s Next?

After you're comfortable with compiling and running code, the next step is to start learning the language. The MoonScript Reference Manual is the most comprehensive guide to everything provided by MoonScript.

If you're interested in contributing to the language, the MoonScript github repository is a good place to start.

If you're interested in using MoonScript as a web scripting language, I've written a nice guide to setting up Lua on Heroku.

There’s also an online compiler if you want to experiment without installing, or share snippets with other people. It’s located at http://moonscript.org/compiler/.

If you've created something with MoonScript I'd love to hear about it. Feel free to leave a comment.

Good Luck!