shell

The Erlang Shell

The module shell implements an Erlang shell.

The shell is a user interface program
for entering expression sequences. The expressions are
evaluated and a value is returned.
A history mechanism saves previous commands and their
values, which can then be incorporated in later commands.
How many commands and results to save can be determined by the user,
either interactively, by calling shell:history/1 and
shell:results/1, or by setting the application configuration
parameters shell_history_length and
shell_saved_results for the application STDLIB.

The shell uses a helper process for evaluating commands in
order to protect the history mechanism from exceptions. By
default the evaluator process is killed when an exception
occurs, but by calling shell:catch_exception/1 or by
setting the application configuration parameter
shell_catch_exception for the application STDLIB
this behavior can be changed. See also the example below.

Variable bindings, and local process dictionary changes
which are generated in user expressions are preserved, and the variables
can be used in later commands to access their values. The
bindings can also be forgotten so the variables can be re-used.

The special shell commands all have the syntax of (local)
function calls. They are evaluated as
normal function calls and many commands can be used in one
expression sequence.

If a command (local function call) is not recognized by the
shell, an attempt is first made to find the function in the
module user_default, where customized local commands
can be placed. If found, then the function is evaluated.
Otherwise, an attempt is made to evaluate the function in the
module shell_default. The module
user_default must be explicitly loaded.

The shell also permits the user to start multiple concurrent
jobs. A job can be regarded as a set of processes which can
communicate with the shell.

There is some support for reading and printing records in
the shell. During compilation record expressions are translated
to tuple expressions. In runtime it is not known whether a tuple
actually represents a record. Nor are the record definitions
used by compiler available at runtime. So in order to read the
record syntax and print tuples as records when possible, record
definitions have to be maintained by the shell itself. The shell
commands for reading, defining, forgetting, listing, and
printing records are described below. Note that each job has its
own set of record definitions. To facilitate matters record
definitions in the modules shell_default and
user_default (if loaded) are read each time a new job is
started. For instance, adding the line

-include_lib("kernel/include/file.hrl").

to user_default makes the definition of file_info
readily available in the shell.

The shell runs in two modes:

Normal (possibly restricted) mode, in which
commands can be edited and expressions evaluated.

Job Control Mode JCL, in which jobs can be
started, killed, detached and connected.

Only the currently connected job can 'talk' to the shell.

Shell Commands

b()

Prints the current variable bindings.

f()

Removes all variable bindings.

f(X)

Removes the binding of variable X.

h()

Prints the history list.

history(N)

Sets the number of previous commands to keep in the
history list to N. The previous number is returned.
The default number is 20.

results(N)

Sets the number of results from previous commands to keep in
the history list to N. The previous number is returned.
The default number is 20.

e(N)

Repeats the command N, if N is positive. If
it is negative, the Nth previous command is repeated
(i.e., e(-1) repeats the previous command).

v(N)

Uses the return value of the command N in the
current command, if N is positive. If it is negative,
the return value of the Nth previous command is used
(i.e., v(-1) uses the value of the previous command).

help()

Evaluates shell_default:help().

c(File)

Evaluates shell_default:c(File). This compiles
and loads code in File and purges old versions of
code, if necessary. Assumes that the file and module names
are the same.

catch_exception(Bool)

Sets the exception handling of the evaluator process. The
previous exception handling is returned. The default
(false) is to kill the evaluator process when an
exception occurs, which causes the shell to create a new
evaluator process. When the exception handling is set to
true the evaluator process lives on which means that
for instance ports and ETS tables as well as processes
linked to the evaluator process survive the exception.

rd(RecordName, RecordDefinition)

Defines a record in the shell. RecordName is
an atom and RecordDefinition lists the field names
and the default values. Usually record definitions are made
known to the shell by use of the rr commands
described below, but sometimes it is handy to define records
on the fly.

rf()

Removes all record definitions, then reads record
definitions from the modules shell_default and
user_default (if loaded). Returns the names of the
records defined.

rf(RecordNames)

Removes selected record definitions.
RecordNames is a record name or a list of record names.
Use '_' to remove all record definitions.

rl()

Prints all record definitions.

rl(RecordNames)

Prints selected record definitions.
RecordNames is a record name or a list of record names.

rp(Term)

Prints a term using the record definitions known to the
shell. All of Term is printed; the depth is not
limited as is the case when a return value is printed.

rr(Module)

Reads record definitions from a module's BEAM file. If
there are no record definitions in the BEAM file, the
source file is located and read instead. Returns the names
of the record definitions read. Module is an atom.

rr(Wildcard)

Reads record definitions from files. Existing
definitions of any of the record names read are replaced.
Wildcard is a wildcard string as defined in
filelib(3) but not an atom.

rr(WildcardOrModule, RecordNames)

Reads record definitions from files but
discards record names not mentioned in RecordNames (a
record name or a list of record names).

rr(WildcardOrModule, RecordNames, Options)

Reads record definitions from files. The compiler
options {i, Dir}, {d, Macro}, and
{d, Macro, Value} are recognized and used
for setting up the include path and macro definitions. Use
'_' as value of RecordNames to read all record
definitions.

Example

The following example is a long dialogue with the shell. Commands
starting with > are inputs to the shell. All other lines
are output from the shell. All commands in this example are explained at the end of the dialogue.
.

Comments

Command 2 sets L to the length of the string evaluating
the BIF atom_to_list.

Command 3 builds the tuple Descriptor.

Command 4 prints the value of the variable L.

Command 5 evaluates the internal shell command b(), which
is an abbreviation of "bindings". This prints
the current shell variables and their bindings. The ok at
the end is the return value of the b() function.

Command 6 f(L) evaluates the internal shell command
f(L) (abbreviation of "forget"). The value of the variable
L is removed.

Command 7 prints the new bindings.

Command 8 has no effect since L has no value.

Command 9 performs a pattern matching operation on
Descriptor, binding a new value to L.

Command 10 prints the current value of L.

Command 11 tries to match {P, Q, R} against
Descriptor which is {4, abc}. The match fails and
none of the new variables become bound. The printout starting
with "** exception error:" is not the value of the
expression (the expression had no value because its evaluation
failed), but rather a warning printed by the system to inform
the user that an error has occurred. The values of the other
variables (L, Str, etc.) are unchanged.

Commands 12 and 13 show that P is unbound because the
previous command failed, and that Descriptor has not
changed.

Commands 14 and 15 show a correct match where P and
Q are bound.

Command 16 clears all bindings.

The next few commands assume that test1:demo(X) is
defined in the following way:

demo(X) ->
put(aa, worked),
X = 1,
X + 10.

Commands 17 and 18 set and inspect the value of the item
aa in the process dictionary.

Command 19 evaluates test1:demo(1). The evaluation
succeeds and the changes made in the process dictionary become
visible to the shell. The new value of the dictionary item
aa can be seen in command 20.

Commands 21 and 22 change the value of the dictionary item
aa to hello and call test1:demo(2). Evaluation
fails and the changes made to the dictionary in
test1:demo(2), before the error occurred, are discarded.

Commands 23 and 24 show that Z was not bound and that the
dictionary item aa has retained its original value.

Commands 25, 26 and 27 show the effect of evaluating
test1:demo(1) in the background. In this case, the
expression is evaluated in a newly spawned process. Any
changes made in the process dictionary are local to the newly
spawned process and therefore not visible to the shell.

Commands 28, 29 and 30 use the history facilities of the shell.

Command 29 is e(28). This re-evaluates command
28. Command 30 is v(28). This uses the value (result) of
command 28. In the cases of a pure function (a function
with no side effects), the result is the same. For a function
with side effects, the result can be different.

The next few commands show some record manipulation. It is
assumed that ex.erl defines a record like this:

-record(rec, {a, b = val()}).
val() ->
3.

Commands 31 and 32 compiles the file ex.erl and reads
the record definitions in ex.beam. If the compiler did not
output any record definitions on the BEAM file, rr(ex)
tries to read record definitions from the source file instead.

Command 33 prints the definition of the record named
rec.

Command 34 tries to create a rec record, but fails
since the function val/0 is undefined. Command 35 shows
the workaround: explicitly assign values to record fields that
cannot otherwise be initialized.

Command 36 prints the newly created record using record
definitions maintained by the shell.

Command 37 defines a record directly in the shell. The
definition replaces the one read from the file ex.beam.

Command 38 creates a record using the new definition, and
prints the result.

Command 39 and 40 show that record definitions are updated
as side effects. The evaluation of the command fails but
the definition of rec has been carried out.

For the next command, it is assumed that test1:loop(N) is
defined in the following way:

loop(N) ->
io:format("Hello Number: ~w~n", [N]),
loop(N+1).

Command 41 evaluates test1:loop(0), which puts the
system into an infinite loop. At this point the user types
Control G, which suspends output from the current process,
which is stuck in a loop, and activates JCL mode. In JCL
mode the user can start and stop jobs.

In this particular case, the i command ("interrupt") is
used to terminate the looping program, and the c command
is used to connect to the shell again. Since the process was
running in the background before we killed it, there will be
more printouts before the "** exception exit: killed"
message is shown.

Command 42 creates an ETS table.

Command 43 tries to insert a tuple into the ETS table but the
first argument (the table) is missing. The exception kills the
evaluator process.

Command 44 corrects the mistake, but the ETS table has been
destroyed since it was owned by the killed evaluator process.

Command 46 sets the exception handling of the evaluator process
to true. The exception handling can also be set when
starting Erlang, like this: erl -stdlib shell_catch_exception
true.

Command 48 makes the same mistake as in command 43, but this time
the evaluator process lives on. The single star at the beginning
of the printout signals that the exception has been caught.

Command 49 successfully inserts the tuple into the ETS table.

The halt() command exits the Erlang runtime system.

JCL Mode

When the shell starts, it starts a single evaluator
process. This process, together with any local processes which
it spawns, is referred to as a job. Only the current job,
which is said to be connected, can perform operations
with standard IO. All other jobs, which are said to be detached, are
blocked if they attempt to use standard IO.

All jobs which do not use standard IO run in the normal way.

The shell escape key ^G (Control G) detaches the current job
and activates JCL mode. The JCL mode prompt is "-->". If "?" is entered at the prompt, the following help message is
displayed:

Connects to job number <nn> or the current
job. The standard shell is resumed. Operations which use
standard IO by the current job will be interleaved with
user inputs to the shell.

i [nn]

Stops the current evaluator process for job number
nn or the current job, but does not kill the shell
process. Accordingly, any variable bindings and the process dictionary
will be preserved and the job can be connected again.
This command can be used to interrupt an endless loop.

k [nn]

Kills job number nn or the current
job. All spawned processes in the job are
killed, provided they have not evaluated the
group_leader/1 BIF and are located on
the local machine. Processes spawned on remote nodes will
not be killed.

j

Lists all jobs. A list of all known jobs is
printed. The current job name is prefixed with '*'.

s

Starts a new job. This will be assigned the new index
[nn] which can be used in references.

s [shell]

Starts a new job. This will be assigned the new index
[nn] which can be used in references.
If the optional argument shell is given, it is assumed
to be a module that implements an alternative shell.

r [node]

Starts a remote job on node. This is used in
distributed Erlang to allow a shell running on one node to
control a number of applications running on a network of
nodes.
If the optional argument shell is given, it is assumed
to be a module that implements an alternative shell.

q

Quits Erlang. Note that this option is disabled if
Erlang is started with the ignore break, +Bi,
system flag (which may be useful e.g. when running
a restricted shell, see below).

?

Displays this message.

It is possible to alter the behavior of shell escape by means
of the STDLIB application variable shell_esc. The value of
the variable can be either jcl (erl -stdlib shell_esc jcl)
or abort (erl -stdlib shell_esc abort). The
first option sets ^G to activate JCL mode (which is also
default behavior). The latter sets ^G to terminate the current
shell and start a new one. JCL mode cannot be invoked when
shell_esc is set to abort.

If you want an Erlang node to have a remote job active from the start
(rather than the default local job), you start Erlang with the
-remsh flag. Example: erl -sname this_node -remsh other_node@other_host

Restricted Shell

The shell may be started in a
restricted mode. In this mode, the shell evaluates a function call
only if allowed. This feature makes it possible to, for example,
prevent a user from accidentally calling a function from the
prompt that could harm a running system (useful in combination
with the the system flag +Bi).

When the restricted shell evaluates an expression and
encounters a function call or an operator application,
it calls a callback function (with
information about the function call in question). This callback
function returns true to let the shell go ahead with the
evaluation, or false to abort it. There are two possible
callback functions for the user to implement:

to determine if the call to non-local function
FuncSpec ({Module,Func} or a fun) with arguments
ArgList should be allowed. The return value
{redirect,NewFuncSpec,NewArgList} can be used to let
the shell evaluate some other function than the one specified by
FuncSpec and ArgList.

These callback functions are in fact called from local and
non-local evaluation function handlers, described in the
erl_eval
manual page. (Arguments in ArgList are evaluated before the
callback functions are called.)

The State argument is a tuple
{ShellState,ExprState}. The return value NewState
has the same form. This may be used to carry a state between calls
to the callback functions. Data saved in ShellState lives
through an entire shell session. Data saved in ExprState
lives only through the evaluation of the current expression.

There are two ways to start a restricted shell session:

Use the STDLIB application variable restricted_shell
and specify, as its value, the name of the callback
module. Example (with callback functions implemented in
callback_mod.erl): $ erl -stdlib restricted_shell callback_mod

From a normal shell session, call function
shell:start_restricted/1. This exits the current evaluator
and starts a new one in restricted mode.

Notes:

When restricted shell mode is activated or
deactivated, new jobs started on the node will run in restricted
or normal mode respectively.

If restricted mode has been enabled on a
particular node, remote shells connecting to this node will also
run in restricted mode.

The callback functions cannot be used to allow or disallow
execution of functions called from compiled code (only functions
called from expressions entered at the shell prompt).

Errors when loading the callback module is handled in different
ways depending on how the restricted shell is activated:

If the restricted shell is activated by setting the kernel
variable during emulator startup and the callback module cannot be
loaded, a default restricted shell allowing only the commands
q() and init:stop() is used as fallback.

If the restricted shell is activated using
shell:start_restricted/1 and the callback module cannot be
loaded, an error report is sent to the error logger and the call
returns {error,Reason}.

Prompting

The default shell prompt function displays the name of the node
(if the node can be part of a distributed system) and the
current command number. The user can customize the prompt
function by calling
shell:prompt_func/1 or by setting the application
configuration parameter shell_prompt_func for the
application STDLIB.

A customized prompt function is stated as a tuple
{Mod, Func}. The function is called as
Mod:Func(L), where L is a list of key-value pairs
created by the shell. Currently there is only one pair:
{history, N}, where N is the current command number. The
function should return a list of characters or an atom. This
constraint is due to the Erlang I/O-protocol. Unicode characters
beyond codepoint 255 are allowed in the list. Note
that in restricted mode the call Mod:Func(L) must be
allowed or the default shell prompt function will be called.

Functions

history(N) -> integer()

N = integer()

Sets the number of previous commands to keep in the
history list to N. The previous number is returned.
The default number is 20.

results(N) -> integer()

N = integer()

Sets the number of results from previous commands to keep in
the history list to N. The previous number is returned.
The default number is 20.

catch_exception(Bool) -> Bool

Bool = bool()

Sets the exception handling of the evaluator process. The
previous exception handling is returned. The default
(false) is to kill the evaluator process when an
exception occurs, which causes the shell to create a new
evaluator process. When the exception handling is set to
true the evaluator process lives on which means that
for instance ports and ETS tables as well as processes
linked to the evaluator process survive the exception.

prompt_func(PromptFunc) -> prompt_func()

PromptFunc = prompt_func()

prompt_func() = default | {Mod, Func}

Mod = Func = atom()

Sets the shell prompt function to PromptFunc. The
previous prompt function is returned.

start_restricted(Module) -> ok | {error, Reason}

Module = atom()

Reason = atom()

Exits a normal shell and starts a restricted
shell. Module specifies the callback module for the
functions local_allowed/3 and non_local_allowed/3.
The function is meant to be called from the shell.

If the callback module cannot be loaded, an error tuple is
returned. The Reason in the error tuple is the one
returned by the code loader when trying to load the code of the callback
module.

stop_restricted() -> ok

Exits a restricted shell and starts a normal shell. The function
is meant to be called from the shell.