3.1.5 REPL Escapes

Normally the REPL evaluates an expression and prints the value it returns. The REPL also supports a set of special escapes that bypass the normal evaluation. There are two kinds of escapes:

,(command arg …)

,command

tells the REPL to perform a special action. The symbol command specifies the action to perform; the arg elements are command specific. A command that can be used with no arg elements can be abbreviated by dropping the parentheses. Additionally, command can be shortened to any unique prefix, such as po for pop. Note that command is not evaluated. An arg is not evaluated, unless it starts with a comma, in which case it is evaluated in the current REPL environment.

,,expression

evaluates expression in user-initial-environment instead of the current REPL environment. This is especially useful when working with library environments, where many of the usual definitions, for example debug, are not available.

The rest of this section documents the commands that can be used with the first form of escape. The most important command is help:

REPL command: help [name] ¶

Prints each of the available commands along with a summary of what they do. If name is given, show only commands that match name.

,(help p)
-| ;,pop
-| ;    Pops an environment off the stack and moves the REPL there.
-| ;,push
-| ;,(push env)
-| ;    Push the REPL env on the env stack and move the REPL to a new env.
-| ;    
-| ;    If ENV is provided, it is converted to an environment in the usual
-| ;    way.  The the current REPL env is pushed on the env stack and the REPL
-| ;    is moved to ENV.
-| ;    
-| ;    If ENV is not provided, the current REPL env is exchanged with the top
-| ;    of the env stack.

A number of the commands manipulate the REPL’s environment in various ways. These involve the following parts:

• The current REPL environment is the environment that’s used to evaluate expressions.
• The environment stack contains additional environments that are saved for future use. This stack is modified by the push, pop, bury, and ge commands.
• A set of named environments that have been given symbolic names. This set is modified by name and unname.

REPL command: envs [env-name] ¶

Prints a summary of the environments. If env-name is given, prints only the named environments matching env-name.

For example, here is the output when the system is started:

,envs
-| ;here: (user) #[environment 12]
-| ;The env stack is empty
-| ;no named envs

Where ;here: marks the current REPL environment.

Several commands take an env argument, specifying an environment. This argument can have several forms:

a symbol

Refers to a named environment.

a library name

Refers to the environment of a loaded library. For example, ‘(scheme base)’.

a package name

Refers to the environment of a loaded MIT/GNU Scheme package. For example, ‘(runtime)’.

,expression

Evaluates expression in the current environment; its value must be an environment object.

REPL command: push [env] ¶

Pushes the current REPL environment on the environment stack, then moves the REPL to a new environment. If env is not given, then this swaps the current REPL environment and the environment on the top of the stack. Otherwise env specifies the new environment in the usual way.

If the command completes successfully, it prints the current REPL environment and the environment stack:

,(push (srfi 133))
-| ;here: #[environment 28]
-| ;stack:
-| ;    0: (user) #[environment 12]

We can swap the two environments:

,push
-| ;Package: (user)
-| ;here: (user) #[environment 12]
-| ;stack:
-| ;    0: #[environment 28]

REPL command: pop ¶

Pops off the top of the environment stack and moves the current REPL environment there.

,pop
-| ;Package: (user)
-| ;here: (user) #[environment 12]
-| ;The env stack is empty

REPL command: bury ¶

Saves the current REPL environment at the bottom of the stack, then pops off the top of the environment stack and moves the current REPL environment there.

,(push (runtime))
-| ;Package: (runtime)
-| ;here: (runtime) #[environment 30]
-| ;stack:
-| ;    0: #[environment 28]
-| ;    1: (user) #[environment 12]

,bury
-| ;here: #[environment 28]
-| ;stack:
-| ;    0: (user) #[environment 12]
-| ;    1: (runtime) #[environment 30]

REPL command: ge [env] ¶

Sets the current REPL environment to the specified environment without affecting the environment stack. If env is not given, a newly created top-level environment is used.

This is basically the same as the ge procedure.

REPL command: ve [env] ¶

Creates a new child REPL, setting its current environment to the specified one. If env is not given, a newly created top-level environment is used.

This is basically the same as the ve procedure.

REPL command: name env-name ¶

Gives the current REPL environment a name env-name and adds it to the set of named environments. The argument env-name must be a symbol.

,(name foobar)
-| ;env named foobar has been assigned

,envs
-| ;here: foobar #[environment 28]
-| ;stack:
-| ;    0: (user) #[environment 12]
-| ;    1: (runtime) #[environment 30]
-| ;named envs
-| ;    foobar #[environment 28]

REPL command: unname [env-name] ¶

Removes the environment with name env-name from the set of named environments. If env-name is not given, removes all named environments.

,(unname foobar)
-| ;env named foobar has been unassigned

,envs
-| ;here: #[environment 28]
-| ;stack:
-| ;    0: (user) #[environment 12]
-| ;    1: (runtime) #[environment 30]
-| ;no named envs

This group of commands manages nested REPL instances.

REPL command: down ¶

Creates a new child REPL with the same current environment as this one.

REPL command: import import-set … ¶

Imports the given import-sets into the current REPL environment. The syntax is described in R7RS section 5.2.

REPL command: up ¶

Pops up one level to the parent REPL.

This is equivalent to calling cmdl-interrupt/abort-previous.

REPL command: top-level ¶

Pops up to the top-level REPL.

This is equivalent to calling cmdl-interrupt/abort-top-level.