using stella

What is Stella?

Stella is a Lua development environment for Mac OS. Lua is a really cool scripting language that is being developed at TeCGraf, the Computer Graphics Technology Group of PUC-Rio (the Pontifical Catholic University of Rio de Janeiro in Brazil) by Waldemar Celes,Roberto Ierusalimschy, and Luiz Henrique de Figueiredo (see http://www.lua.org/). Lua is very easy to embed in other applications. So simple, in fact, that it was a piece of cake to write a REALbasic plugin for it and build a development environment with that plugin. The result is Stella.

Files and Folders

Open the Stella folder and you should see the following items:

Please read the ReadMe file for information about the limitations on using and distributing Stalla. The docs folder contains this user guide. For Lua documentation please visit the Lua web site. The Examples folder contains the Lua examples that come with the Lua 4.0 distribution. Also in the Stella 1.0 folder is startup.lua, which is a file of Lua code that Stella reads when it starts up. More about that later. Finally, there is the Stella app itself. Launch Stella now to continue.

startup.lua

At startup, Stella will look for a file entitled startup.lua in the same folder as the Stella application. If it finds such a file it will execute the contents of the file as if it were a Lua script. I have not experimented with large startup.lua files, so I can't say what the impact will be on startup time.

Output

Upon launch, Stella always shows at least its Output window:

The output window is where Stella puts all of Lua's output. For example, executing a script with the function print("Hello, world!") will cause Hello, world! to be written to the output window (more on exactly how to execute such a script later). The output in the example above is from the startup.lua script that comes with the Stella distribution.

Editing Scripts

Here is an example of a Stella edit window:

Notice that the edit window syntax colors the Lua code. Currently the syntax coloring is primitive. Keywords are shown in blue, comments are shown in red, and strings are shown in green.

There is also some auto completion of Lua keywords. As you type a keyword you will see the complete keyword in gray. Hitting <tab> at this point will complete the keyword.

Running Scripts

Scripts can be run by choosing Run from the Script menu, or by typing <command>-R. All output from the script will go to the output window.

QuickScripts

Choose QuickScript from the Window menu or type <command>-K to bring up the QuickScript dialog, which looks like this:

A very short script or command can be typed into the edit field and executed by clicking Run. Any output will go to the output window. One example use is to test a script being edited in a separate edit window.

Input

Lua scripts can ask for user input. In a command-line environement the user can simply type the input at the command line. But Stella has no command line. To compensate, Stella has an input dialog, which looks like the following:

Whenever Lua requires input, Stella will present this dialog to the user. Whatever is typed into the edit field will be returned to the Lua script. Hitting the OK button will cause the contents of the input field to be returned to Lua with a newline appended to it. Hitting the cancel button will cause an EOF to be returned to Lua. The cancel button causes the contents of the input field to be ignored. Only the EOF will be returned. How this all works can best be seen with a script that uses read("*a"), which asks for input until an EOF is returned, which indicates the entire file has been read. If a script contains read("*a"), then the input window will reappear as long as the user hits the OK button. Each appearance of the Input window simulates one line on the command line. This process will only end when the user hits the cancel button to indicate the end of input.

To see the input dialog in action, type the following Lua script into Stella's QuickScript dialog and run it:

print(read())

If you type "hello" into the input dialog's edit field and hit OK, you should see "hello" appear in the output window.

Gotchas

Currently Stella always converts a script's line endings to Mac OS line endings (a carriage return). This means that if you open a script with a different kind of line endings and then save that file, you will end up with a file of Mac line endings. This may cause problems when moving that script to a different environment. In the future I hope to support and preserve all line endings.

Strings delimited by "[[" and "]]" are currently not colored like other stings. This is a limitation that I hope to remove in a future release.

Acknowledgments

WASTEfield is a REALbasic plugin that is being developed by Doug Holton (see http://people.vanderbilt.edu/~doug.holton/basic/plugins/).

The syntax coloring engine was written by Jeromy Alexander (jabody@together.net).