The REPL
********

When you invoke the stand-alone librep interpreter without giving it a script to execute the system is started in interactive mode. This means that the REPL is entered---the read-eval-print loop.

The REPL works as its name suggests. It reads Lisp forms from the console, evaluates them, and then prints the result back to the console. Here is an example REPL session:

     user> (+ 1 1)
     2
     user> (cons 'a 'b)
     (a . b)

The user> string is the prompt that the REPL prints when it is waiting for an input form. This form may span several lines, e.g.:

     user> (cons 'a
     'b)
     (a . b)

The prompt above contains the string user. This is the name of the module that the form will be evaluated in (see Modules).

As well as allowing arbitrary Lisp forms to be entered and evaluated, the REPL provides a rich set of meta-commands, these are used to configure and inspect the state of the system, as well as providing convenient shortcuts for common operations.

A meta-command is differentiated from a normal Lisp form by preceding it with a comma (,) character. The name of the command should follow the comma, with any argument forms after that. Note that unlike normal Lisp forms, no parentheses are used to mark the command application.

For example the whereis meta-command searches all loaded modules for those exporting a particular symbol. It might be used as follows:

     user> ,whereis string-match
     string-match is exported by: rep.regexp

The following table lists all currently supported meta-commands:

access STRUCT ...
     Add the modules named STRUCT ... to the list of structures whose exported definitions may be accessed by the current module (using the structure-ref special form).

accessible
     Print the names of the modules whose contents may be accessed using the structure-ref form from the current module.

apropos "REGEXP"
     Print the definitions in the scope of the current module whose names match the regular expression REGEXP.

bindings
     Print all bindings in the current module.

collect
     Run the garbage collector.

compile [STRUCT ...]
     Compile any uncompiled functions in the modules named STRUCT .... If no named modules are given, use the current module.

compile-proc PROCEDURE ...
     Compile the functions called PROCEDURE ... in the current module.

describe SYMBOL
     Look for documentation describing the current meaning of SYMBOL, if any is found, print it.

dis FORM
     Disassemble the bytecode form or compiled function that is the result of evaluating FORM.

expand FORM
     Print FORM with any outermost macro calls recursively expanded.

exports
     Print the names of the variables exported from the current module.

help
     List all REPL commands.

imports
     Print the names of the modules imported by the current module.

in STRUCT [FORM]
     If FORM is given, temporarily switch to the module called STRUCT, evaluate FORM printing the result, then switch back to the original module.

     If FORM isn't given, simply switch the current module to be STRUCT.

interfaces
     Print all defined module interfaces, and their definitions.

load STRUCT ...
     Attempt to load the module called STRUCT.

load-file "FILENAME" ...
     Load the file of Lisp forms called FILENAME.

locate SYMBOL
     Recursively scan from the current module for the module providing the binding of SYMBOL.

new STRUCT
     Create a new module called STRUCT, and set it as the current module. It will import the rep.module-system module, but nothing else (i.e. no actual language).

open STRUCT ...
     Import the modules called STRUCT ... to the current module. This is analogous to the open clause in the configuration form of the module's definition.

profile FORM
     Evaluate FORM, recording information about the frequency and duration of the calls it makes to subroutines (and the calls they make, and so on). This information is tabulated and printed after the evaluation has finished.

quit
     Terminate the Lisp interpreter.

reload STRUCT ...
     Reload the modules called STRUCT .... If modules of these names had previously been loaded, they will be deallocated when there are no remaining references to them.

     Note that importing the interface of one module into another does not create object references between the two modules (the references are purely symbolic). However, each closure (i.e. function) created in a module does contain a reference to the module it was created in.

step FORM
     Evaluate FORM in single-step mode (using the debugger).

structures
     Print the names of all currently defined modules.

time FORM
     Evaluate the form FORM, print the result and the time it took to perform the evaluation.

unload STRUCT ...
     Attempt to unload the modules called STRUCT .... As with reloading, unloading a module only removes the link between the module name and the module body. Only once no more references exist to the module body will it be freed.

whereis SYMBOL
     Scan all loaded modules for those that export a binding of SYMBOL, and print the results.