Provided by:
erlang-manpages_11.b.5-1_all 
NAME
shell - The Erlang Shell
DESCRIPTION
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.
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.
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. .
strider 1>erl
Erlang (BEAM) emulator version 5.3 [hipe] [threads:0]
Eshell V5.3 (abort with ^G)
1> Str = "abcd".
"abcd"
2>L = length(Str).
4
3>Descriptor = {L, list_to_atom(Str)}.
{4,abcd}
4>L.
4
5>b().
Descriptor = {4,abcd}
L = 4
Str = "abcd"
ok
6>f(L).
ok
7>b().
Descriptor = {4,abcd}
Str = "abcd"
ok
8>f(L).
** 1: variable βLβ is unbound **
9>{L, _} = Descriptor.
{4,abcd}
10>L.
4
11>{P, Q, R} = Descriptor.
** exited: {{badmatch,{4,abcd}},[{erl_eval,expr,3}]} **
12>P.
** 1: variable βPβ is unbound **
13>Descriptor.
{4,abcd}
14> {P, Q} = Descriptor.
{4,abcd}
15>P.
4
16>f().
ok
17>put(aa, hello).
undefined
18>get(aa).
hello
19>Y = test1:demo(1).
11
20>get().
[{aa,worked}]
21>put(aa, hello).
worked
22>Z = test1:demo(2).
=ERROR REPORT==== 19-Feb-2003::10:04:14 ===
Error in process <0.40.0> with exit value: {{badmatch,1},[{test1,demo,1},
{erl_eval,expr,4},{shell,eval_loop,2}]}
** exited: {{badmatch,1},
[{test1,demo,1},{erl_eval,expr,4},{shell,eval_loop,2}]} **
23>Z.
** 1: variable βZβ is unbound **
24>get(aa).
hello
25>erase(), put(aa, hello).
undefined
26>spawn(test1, demo, [1]).
<0.57.0>
27>get(aa).
hello
28>io:format("hello hello\n").
hello hello
ok
29>e(28).
hello hello
ok
30>v(28).
ok
31>c(ex).
{ok,ex}
32>rr(ex).
[rec]
33>rl(rec).
-record(rec, {a,
b = val()}).
ok
34>#rec{}.
** exited: {undef,[{shell_default,val,[]},
{erl_eval,do_apply,5},
{erl_eval,expr_list,6},
{erl_eval,expr,5},
{shell,eval_loop,2}]} **
35>#rec{b = 3}.
{rec,undefined,3}
36>rp(v(-1)).
#rec{a = undefined,
b = 3}
ok
37>rd(rec, {f = orddict:new()}).
rec
38>rp(#rec{}).
#rec{f = []}
ok
39>rd(rec, {c}), A.
** 1: variable βAβ is unbound **
40>rp(#rec{}).
#rec{c = undefined}
ok
41>test1:loop(0).
Hello Number: 0
Hello Number: 1
Hello Number: 2
Hello Number: 3
User switch command
--> i
--> c
.
.
.
Hello Number: 3374
Hello Number: 3375
Hello Number: 3376
Hello Number: 3377
Hello Number: 3378
** exited: killed **
42>halt().
strider 2>
Comments
Command 1 sets the variable Str to the string "abcd".
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 shows that L is no longer bound to a 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 "** exited:" 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 "** exited:
killed **" message is shown.
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:
--> ?
c [nn] - connect to job
i [nn] - interrupt job
k [nn] - kill job
j - list all jobs
s - start local shell
r [node] - start remote shell
q - quit Erlang
? | h - this message
The JCL commands have the following meaning:
c [nn]:
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.
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.
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:
local_allowed(Func, ArgList, State) -> {true, NewState} | {false,
NewState}
to determine if the call to the local function Func with arguments
ArgList should be allowed.
non_local_allowed(FuncSpec, ArgList, State) -> {true, NewState} |
{false, NewState} | {{redirect, NewFuncSpec, NewArgList}, NewState}
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}.
EXPORTS
history(N) -> integer()
Types 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()
Types 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.
start_restricted(Module) -> ok | {error, Reason}
Types 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.
AUTHORS
Robert Virding - support@erlang.ericsson.se
Peter Andersson - support@erlang.ericsson.se