Moonscript debugging with ZeroBrane Studio

Moonscript is an interesting dynamic scripting language that compiles to Lua. Moonscript can be dynamically compiled and run using a component called moonloader and because moonloader keeps a mapping between the moonscript code and the produced Lua code, I thought it could be possible to extend the debugging in ZeroBrane Studio to take that mapping into account in some way.

The version of the debugging bundled with ZeroBrane Studio v0.70+ provides a way to specify a line mapper that can be used to map the current line in the Lua code to the line number in the "original" moonscript code. This code is "injected" in the debugger when the debugging session is started, so any line number used by the debugger (whether to show the current line, set a breakpoint, or display a stack trace) goes through that mapping.

Let's see how you can now debug moonscript files.

ZeroBrane Studio configuration.

1. Get ZeroBrane Studio (0.70+). These instructions are for Windows, but the debugging should work on Linux and OSX as well.

2. Get Moonscript plugin and save it to ZBS/packages/ or HOME/.zbstudio/packages folder (where ZBS is the path to ZeroBrane Studio location and HOME is the path specified by the HOME environment variable); the second option may also be preferable for Mac OS X users as the packages/ folder may be overwritten during an application upgrade.

3. (Optional) If moon executable is in a folder listed in the PATH environment variable, you don't need to do anything as the plugin will find it; if the executable is in some other location, you may need to add path.moonscript = [[/full/path/moon.exe]] to the ZBS configuration file (Edit | Preferences | Settings: User).

4. Start ZBS (zbstudio.exe or

Script debugging.

Let's now debug a simple three line script:

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

Save it as sum.moon and set the project directory to the folder where you saved the script (Project | Project Directory | Set From Current File) and select Moonscript as the current interpreter by going to Project | Lua Interpreter | Moonscript (this option is only available when the Moonscript plugin is installed).

Now if you Run the script, you should see "The sum is 30" in the output. If you select Debug, you should see the debugging started at line 1 and should be able to step through the script, set breakpoints, look at the stack trace, and use all other debugging functionality available in ZeroBrane Studio. Note that all the line numbers are from the moonscript source and not from the (dynamically) generated Lua code, as can be seen on the screenshot:

Moonscript debugging

You may notice that stepping in the debugger through the moonscript code spends more time on the same line than you'd expect. One of the most prominent examples is class definitions or table comprehensions that map few lines of Moonscript code to a (potentially) large number of lines in the corresponding Lua code, which causes the debugger to stay on the same line for each "step" through the Lua code. This may be improved in the future, but for now it's something to keep in mind; if you want to get to your destination faster, you can use breakpoints.

That's not all you can use the debugger for. You can also use moonscript expressions in the Watch panel; for example, if you enter sum 10, 20, you'll see 30 as the result after sum function is defined.

But there is more. You can also execute moonscript expressions in the Remote console. As can be seen on the screenshot, you can execute sum 1, 2 and get 3 as the result. You can also execute export mult = (x, y) -> x * y and then execute mult 10, 20 to get 200 as the result. Essentially, you can use the Remote console as Moonscript REPL with access to your application state. The only current limitation with the console commands is that they need to be single commands; this is a feature of command execution in the console that "flattens" multi-line scripts into one-liners (which doesn't work well with Moonscript, because of its whitespace sensitivity).

And one more thing. Not only syntax highlighting and folding is supported to some degree (as it's based on the Coffeescript lexer), but auto-complete for Lua functions also works with both . and \ notations, so using str = "" and str\ will offer "string" methods in the auto-complete list.

This functionality is highly experimental and has been tested with Moonscript 0.2.5 and 0.2.6 using the current ZeroBrane Studio (0.70). Give it a try with your moonscript application and share your experience in the comments or using any other method that works for you.

You should get a copy of my slick ZeroBrane Studio IDE.

Leave a comment

what will you say?