Next Chapter
Previous Chapter
Table of Contents

The Basics

Starting Stella

To start up Stella, boot Common Music and then use the (stella) function:

<cl> (stella)
Type ? for help.
Stella [Top-Level]:

About the prompt

After Stella starts up a help message is printed and the Lisp prompt changes to

Stella [Top-Level]:
The new prompt consists of the name of the editor followed by the name of the current "focus object" printed inside square brackets []. The focus object provides a selection context. Think of the editor as being "inside" the focus object. The focus object is important because it allows other objects to be selected based on their position(s) relative to the current focus. Stella has a number of commands for moving to a new focus object. Whenever the focus changes the [] portion of the prompt is updated to display the name of the new focus. When Stella first starts up its focus is Top-Level, a system container holding all the user's containers. Much more about this later.

Using the Help Facility

First, type ? to learn about the help command:

Stella [Top-Level]: ?

    ?                  Show this help.
    ADD                Add objects to container.
    ARCHIVE            Archive objects to file.
    CHANGE             Change the class of objects.

[... rest of  help listing deleted]

    Use the HELP command for detailed help about the commands 
    summarized above, or to see overviews about the following 
    general topics: REFERENCING INTERPRETER EXPRESSIONS.

Stella [Top-Level]: 
Stella's on-line help facility includes both short and long help. To see short help use the ? command. Use help to see long help about a particular command or topic. For example, to read documentation about the help command itself, type:

Stella [Top-Level]: help help

HELP {topic}

    Arguments:

      {topic}         Command name or topic.

    Overview:

    The HELP command displays detailed help about {topic}, which
    may be a command name or a general topic. For  a listing of
    available commands and topics use the ? command.

    See also:

    ?

Stella [Top-Level]: 
Try using help on several commands, for example show, list, or map.

About the Command Interpreter

Let's stop briefly to examine some of the more important properties of Stella's command interpreter.

Command Invocation

Command names are case insensitive and only enough of the name needs to be typed to distinguish it from other commands. For example, the previous example:

Stella [Top-Level]: help help
could be typed:
Stella [Top-Level]: he he
because he is enough to uniquely identify help in the full command set.

Command Arguments

Command arguments are information necessary for a command to execute. In the previous example:

Stella [Top-Level]: help help
the first help is the name of the command, and the second help is a command argument, in this case the name of a command to read help about.

Command Prompting

Commands normally prompt for missing or erroneous arguments. For example, if the help command is invoked without any arguments it prompts for the topic:
Stella [Top-Level]: help
Help topic: help

[help text omitted]

Stella [Top-Level]:
The global variable *command-prompting* enables or disables interactive command prompting. Set *command-prompting* to nil to make the interpreter behave more "tersely", like a UNIX shell.

Command Syntax

Most commands follow the form:

    command references arg1 ... argn
where command is the name of the command, references are the names or positions of one or more objects separated by comma and arg1 through argn are additional command arguments.

Object references can be fairly complex and are covered in a later section of this tutorial. See the on-line help topic referencing for complete information.

Responding to Command Prompts

There are several possible ways to answer a command prompt.

Typing Lisp to the Command Interpreter

Stella's editor is actually a full Lisp interpreter. To evaluate a Lisp expression, simply type the expression at the main command loop prompt:

Stella [Top-Level]: (floor 1 2)
0 
1 
Stella [Top-Level]: 
Since Stella is both a Lisp and command interpreter, you must distinguish command names from Lisp variables. To evaluate name, precede it with a comma:

Stella [Top-Level]: ,2pi
6.283185307179586
Stella [Top-Level]:

Continuing From Errors

To return to the editor from an error break in ACL or GCL use the :tl error break command. Use :tl even if it isn't listed in the error break message. (:tl stands for Top Level, the name of Stella's interpreter.) In Macintosh Common Lisp, type Command-. (a period with the Apple command key depressed) or select "Return to Top-Level" from "Restarts..." under the main Eval menu. In Clisp, type tl or whatever you are offered as a restart option from the system, such as r1.

Stella [Top-Level]: (/ 1 0)
Error: An attempt was made to divide by zero.
Restart actions (select using :continue):
    0: Return to Top-Level.
    1: Exit Top-Level.
[1] <cl> :tl
Stella [Top-Level]: 
If for some reason you end up in the main Lisp environment after resuming from an error just use the (stella) function to start up Stella again. No work is lost.

Quit

The quit command exits the editor and returns to the general Lisp environment.

Next Chapter
Previous Chapter
Table of Contents