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.
- Setting Up Your Editor
- Creating Programs
- What’s Next?
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:
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,
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
Create a directory somewhere on your computer where you want your MoonScript
installation to be. For example, I will use
Extract all the files from the zip into the new directory.
lua5.1.dll must be present for MoonScript to work.
Next, from the control panel goto
Advanced Tab. Click on the
Environment Variables button.
User variables, see if there is an existing
PATH entry. If there isn’t,
New, else select
PATH and click
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
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:
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
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.
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
moonscript package is now visible to Lua, but the MoonScript binaries
aren’t in out path yet. By default LuaRocks will install binaries to
~/.profile and add:
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.
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
moonccommands from anywhere. If you wish you can install locally by leaving off the sudo.
Assuming everything builds correctly, the executables
now be installed, along with the
moonscript Lua module.
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
$ luarocks build http://moonscript.org/rocks/moonscript-dev-1.rockspec
Setting Up Your Editor
The following editors have support for MoonScript:
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.
Compiling & Running
The MoonScript package comes with two executables,
moonc we can compile MoonScript code into Lua. Let’s try it out, create
a new file called
-- 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
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!
moonautomatically compiles the file in memory and then executes it right away inside the Lua runtime.
moonc can do a couple interesting things worth mentioning. If you run
-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
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:
- New files aren’t picked up, you have to restart
mooncdoesn’t compile everything on start up. Use
-wflag 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
$ moonc -w -t my_lua .
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.