The SAL Interpreter

Using the Interpreter

Interaction

The SAL interpreter uses the GNU readline package as the basis for getting user commands. This package automatically handles history maintenance. For example, ``!!'' repeats the previous command, ``Ctrl-p'' goes back to the previous command (further back upon repetition), and ``Ctrl-r'' searches back through the interaction history for a command containing a specified string. It also defines a number of Emacs-style key bindings for manipulating the current input line. For example, ``Ctrl-a'' goes to the front of the input line, ``Ctrl-f'' moves forward a character, and ``Ctrl-k'' kills the input to the right of the current cursor position.

By default, SAL catches segmentation faults, interrupts (``Ctrl-c''), and so forth, and returns to the top-level input loop. Running the interpreter with the flag ``-debug'' instructs SAL not to catch these signals.

Functions

Most of the functionality of the interpreter is simply calls to corresponding SAL library functions, such as aggregate, classify, and redescribe. In addition to these SAL-specific function calls, the interpreter provides a few generic primitive functions. The following list details these commands.

• abort : () -> ()
  Returns to the interpreter top-level.
• apropos : (String n1, String n2, ...) -> ()
  Lists functions/variables whose documentation contains any of the names.
• cd : (String d) -> ()
  Changes the working directory to d.
• help : (String n) -> ()
  Prints the documentation for the named function/variable; if none is given, provides general information.
• source : (String f) -> ()
  Executes the commands in the file.
• source_halt : () -> ()
  Halts the current sourcing.
• source_step : () -> ()
  Begins stepping the current source.
• step : (String f) -> ()
  Allows the user to bring the commands in the file to the prompt with ``Ctrl-g.''
• step_halt : () -> ()
  Halts the current stepping.
• step_run : () -> ()
  Reads in the remaining input from the currently stepped file.
• quit : () -> ()
  Exits the interpreter.

Extending the Interpreter

The lib subdirectory of the interpreter contains code implementing the functions supported by the library. The functions consist mainly of wrapper calls to the SAL library, packaging and unpackaging argument lists and return values. A set of scripts helps automate the process of extending the interpreter's functionality.

Defining a New Type

The interpreter type-checks arguments to function calls. In order to do this, the interpreter needs to know the structure of the library class hierarchy. Adding a new type requires placing it correctly in the hierarchy and generating a meta-type for use by the type checker. This process is simplified by the gen_type script, which inputs a file describing the types. The script separately handles two kinds of types, one for a class hierarchy, and one for function types. The following list details the syntax of the input file lines for these two types.

• Class hierarchy
  

  class-name : superclass-name
  

• Function types

  type-name : function (arg-type-1 arg-1, ..., arg-type-n arg-n)
                    -> (return-type return)
  

The script outputs a file to register the class and function meta-types; the file should be linked to the interpreter and its registration function invoked in the interpreter's initialization routine.

An additional step must be taken to create Ops to wrap up functions passed as arguments. The gen_ops script takes the same input file as gen_type and generates the appropriate Ops. This file will be included as a header for the function wrappers described below.

Defining a New Function

Functions to be supported by the interpreter must be explicitly registered, with a proper type signature specified and a pointer to the function code provided. Again, scripts provided with the interpreter help automate the process. The input file describes each function with a lines of the following form:

function-name = extern function (arg-type-1 arg-1, ..., arg-type-n arg-n) 
                             -> (return-type return)
: documentation
: c-function-name

The documentation is used by the help and apropos commands of the interpeter. The C function name is the name of the wrapper function to be called to execute the function.

The gen_register script uses such an input file to generate a header file and code file that inform the interpreter of the function's name, type signature, documentation, and code pointer. The code file should be linked to the interpreter and its registration function invoked in the interpreter's initialization routine.

The gen_wrappers script uses the same input file to generate wrappers converting from an interpreter-based argument vector to C++ objects to be passed to a library function. The conversions involve boxing/unboxing numbers (the interpreter stores everything as an object, while some library functions use, for example doubles), wrapping/unwrapping function pointers as Ops, and so forth. While code for the conversions is done automatically, the actual body of the wrapper is left blank and must be filled in with a call to the appropriate SAL library function.