shell

shell(3erl)                 Erlang Module Definition                 shell(3erl)



NAME
       shell - The Erlang shell.

DESCRIPTION
       This module provides 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 history/1 and
       results/1, or by setting the application configuration parameters
       shell_history_length and shell_saved_results for the STDLIB application.

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

       Variable bindings, and local process dictionary changes that 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 reused.

       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 module user_default, where
       customized local commands can be placed. If found, the function is
       evaluated, otherwise an attempt is made to evaluate the function in
       module shell_default. 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 that 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 represents a
       record, and the record definitions used by the compiler are unavailable
       at runtime. So, to read the record syntax and print tuples as records
       when possible, record definitions must be maintained by the shell itself.

       The shell commands for reading, defining, forgetting, listing, and
       printing records are described below. Notice that each job has its own
       set of record definitions. To facilitate matters, record definitions in
       modules shell_default and user_default (if loaded) are read each time a
       new job is started. For example, adding the following line to
       user_default makes the definition of file_info readily available in the
       shell:

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

       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
       The commands below are the built-in shell commands that are always
       available. In most system the commands listed in the c(3erl) module are
       also available in the shell.

         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. Defaults to 20.

         results(N):
           Sets the number of results from previous commands to keep in the
           history list to N. The previous number is returned. Defaults to 20.

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

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

         help():
           Evaluates shell_default:help().

         c(Mod):
           Evaluates shell_default:c(Mod). This compiles and loads the module
           Mod and purges old versions of the code, if necessary. Mod can be
           either a module name or a a source file path, with or without .erl
           extension.

         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. This means, for example, that
           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/1,2,3 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. To remove all record definitions, use '_'.

         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(3erl), 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. To read all record
           definitions, use '_' as value of RecordNames.

EXAMPLE
       The following example is a long dialog with the shell. Commands starting
       with > are inputs to the shell. All other lines are output from the
       shell.

       strider 1> erl
       Erlang (BEAM) emulator version 5.3 [hipe] [threads:0]

       Eshell V5.3  (abort with ^G)
       1> Str = "abcd".
       "abcd"

       Command 1 sets variable Str to string "abcd".

       2> L = length(Str).
       4

       Command 2 sets L to the length of string Str.

       3> Descriptor = {L, list_to_atom(Str)}.
       {4,abcd}

       Command 3 builds the tuple Descriptor, evaluating the BIF list_to_atom/1.

       4> L.
       4

       Command 4 prints the value of variable L.

       5> b().
       Descriptor = {4,abcd}
       L = 4
       Str = "abcd"
       ok

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

       6> f(L).
       ok

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

       7> b().
       Descriptor = {4,abcd}
       Str = "abcd"
       ok

       Command 7 prints the new bindings.

       8> f(L).
       ok

       Command 8 has no effect, as L has no value.

       9> {L, _} = Descriptor.
       {4,abcd}

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

       10> L.
       4

       Command 10 prints the current value of L.

       11> {P, Q, R} = Descriptor.
       ** exception error: no match of right hand side value {4,abcd}

       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 a warning printed by the system to inform the user that an error has
       occurred. The values of the other variables (L, Str, and so on) are
       unchanged.

       12> P.
       * 1: variable 'P' is unbound
       13> Descriptor.
       {4,abcd}

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

       14>{P, Q} = Descriptor.
       {4,abcd}
       15> P.
       4

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

       16> f().
       ok

       Command 16 clears all bindings.

       The next few commands assume that test1:demo(X) is defined as follows:

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

       17> put(aa, hello).
       undefined
       18> get(aa).
       hello

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

       19> Y = test1:demo(1).
       11

       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 dictionary item aa can be seen in command 20.

       20> get().
       [{aa,worked}]
       21> put(aa, hello).
       worked
       22> Z = test1:demo(2).
       ** exception error: no match of right hand side value 1
            in function  test1:demo/1

       Commands 21 and 22 change the value of 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.

       23> Z.
       * 1: variable 'Z' is unbound
       24> get(aa).
       hello

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

       25> erase(), put(aa, hello).
       undefined
       26> spawn(test1, demo, [1]).
       <0.57.0>
       27> get(aa).
       hello

       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.

       28> io:format("hello hello\n").
       hello hello
       ok
       29> e(28).
       hello hello
       ok
       30> v(28).
       ok

       Commands 28, 29 and 30 use the history facilities of the shell. Command
       29 re-evaluates command 28. Command 30 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 as follows:

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

       val() ->
       3.

       31> c(ex).
       {ok,ex}
       32> rr(ex).
       [rec]

       Commands 31 and 32 compile file ex.erl and read 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.

       33> rl(rec).
       -record(rec,{a,b = val()}).
       ok

       Command 33 prints the definition of the record named rec.

       34> #rec{}.
       ** exception error: undefined shell command val/0

       Command 34 tries to create a rec record, but fails as function val/0 is
       undefined.

       35> #rec{b = 3}.
       #rec{a = undefined,b = 3}

       Command 35 shows the workaround: explicitly assign values to record
       fields that cannot otherwise be initialized.

       36> rp(v(-1)).
       #rec{a = undefined,b = 3}
       ok

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

       37> rd(rec, {f = orddict:new()}).
       rec

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

       38> #rec{}.
       #rec{f = []}
       ok

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

       39> rd(rec, {c}), A.
       * 1: variable 'A' is unbound
       40> #rec{}.
       #rec{c = undefined}
       ok

       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 as
       follows:

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

       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
       ** exception exit: killed

       Command 41 evaluates test1:loop(0), which puts the system into an
       infinite loop. At this point the user types ^G (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, command i ("interrupt") terminates the looping
       program, and command c connects to the shell again. As the process was
       running in the background before we killed it, more printouts occur
       before message "** exception exit: killed" is shown.

       42> E = ets:new(t, []).
       #Ref<0.1662103692.2407923716.214192>

       Command 42 creates an ETS table.

       43> ets:insert({d,1,2}).
       ** exception error: undefined function ets:insert/1

       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.

       44> ets:insert(E, {d,1,2}).
       ** exception error: argument is of wrong type
            in function  ets:insert/2
               called as ets:insert(16,{d,1,2})

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

       45> f(E).
       ok
       46> catch_exception(true).
       false

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

       47> E = ets:new(t, []).
       #Ref<0.1662103692.2407923716.214197>
       48> ets:insert({d,1,2}).
       * exception error: undefined function ets:insert/1

       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.

       49> ets:insert(E, {d,1,2}).
       true

       Command 49 successfully inserts the tuple into the ETS table.

       50> ets:insert(#Ref<0.1662103692.2407923716.214197>, {e,3,4}).
       true

       Command 50 inserts another tuple into the ETS table. This time the first
       argument is the table identifier itself. The shell can parse commands
       with pids (<0.60.0>), ports (#Port<0.536>), references
       (#Ref<0.1662103692.2407792644.214210>), and external functions
       (#Fun<a.b.1>), but the command fails unless the corresponding pid, port,
       reference, or function can be created in the running system.

       51> halt().
       strider 2>

       Command 51 exits the Erlang runtime system.

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

       All jobs that do not use standard I/O 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 [shell]         - start local shell
       r [node [shell]]  - 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 that use standard I/O by the current job are
           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. So, any variable bindings
           and the process dictionary are 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 are not 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 is assigned the new index [nn], which can be
           used in references.

         s [shell]:
           Starts a new job. This is assigned the new index [nn], which can be
           used in references. If optional argument shell is specified, 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 optional argument shell is
           specified, it is assumed to be a module that implements an
           alternative shell.

         q:
           Quits Erlang. Notice that this option is disabled if Erlang is
           started with the ignore break, +Bi, system flag (which can be useful,
           for example when running a restricted shell, see the next section).

         ?:
           Displays the help message above.

       The behavior of shell escape can be changed by 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), start Erlang with flag -remsh, for
       example, erl -remsh other_node@other_host

RESTRICTED SHELL
       The shell can 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
       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) -> {boolean(),NewState}

           This is used to determine if the call to the local function Func with
           arguments ArgList is to be allowed.


         * non_local_allowed(FuncSpec, ArgList, State) -> {boolean(),NewState} |
           {{redirect,NewFuncSpec,NewArgList},NewState}

           This is used to determine if the call to non-local function FuncSpec
           ({Module,Func} or a fun) with arguments ArgList is to 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 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.)

       Argument State is a tuple {ShellState,ExprState}. The return value
       NewState has the same form. This can 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 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 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 run in restricted or normal mode, respectively.

         * If restricted mode has been enabled on a particular node, remote
           shells connecting to this node 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 STDLIB 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 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 prompt_func/1 or by
       setting application configuration parameter shell_prompt_func for the
       STDLIB application.

       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 is to return a list
       of characters or an atom. This constraint is because of the Erlang I/O
       protocol. Unicode characters beyond code point 255 are allowed in the
       list and the atom. Notice that in restricted mode the call Mod:Func(L)
       must be allowed or the default shell prompt function is called.

EXPORTS
       catch_exception(Bool) -> boolean()

              Types:

                 Bool = boolean()

              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
              example, ports and ETS tables as well as processes linked to the
              evaluator process survive the exception.


       history(N) -> integer() >= 0

              Types:

                 N = integer() >= 0

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


       prompt_func(PromptFunc) -> PromptFunc2

              Types:

                 PromptFunc = PromptFunc2 = default | {module(), atom()}

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


       results(N) -> integer() >= 0

              Types:

                 N = integer() >= 0

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


       start_restricted(Module) -> {error, Reason}

              Types:

                 Module = module()
                 Reason = code:load_error_rsn()

              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() -> no_return()

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


       strings(Strings) -> Strings2

              Types:

                 Strings = Strings2 = boolean()

              Sets pretty printing of lists to Strings. The previous value of
              the flag is returned.

              The flag can also be set by the STDLIB application variable
              shell_strings. Defaults to true, which means that lists of
              integers are printed using the string syntax, when possible. Value
              false means that no lists are printed using the string syntax.



Ericsson AB                        stdlib 3.13                       shell(3erl)