# shell

### MODULE

shell

### MODULE SUMMARY

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 `N`th 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 `N`th 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 behaviour 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 behaviour). The latter sets ^G to terminate the current shell and start a new one. `JCL` mode can not 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, it calls a predicate function (with information about the function call in question). This predicate function returns `true` to let the shell go ahead with the evaluation, or `false` to abort it. There are two possible predicate 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}`

to determine if the call to non-local function `FuncSpec` (`{Module,Func}` or a fun) with arguments `ArgList` should be allowed.

These predicate 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 predicates 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 predicate 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 predicate function module. Example (with predicate functions implemented in pred_mod.erl): `$ erl -stdlib restricted_shell pred_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 predicate functions can not be used to allow or disallow execution of functions called from compiled code (only functions called from expressions entered at the shell prompt).

### 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`

Types:

`Module = atom()`

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

`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

stdlib 1.14.1
Copyright © 1991-2006 Ericsson AB