Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

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.

       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(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. 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).
       ok
       9> {L, _} = Descriptor.
       {4,abcd}
       10> L.
       4
       11> {P, Q, R} = Descriptor.
       ** exception error: no match of right hand side value {4,abcd}
       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).
       ** exception error: no match of right hand side value 1
            in function  test1:demo/1
       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{}.
       ** exception error: undefined shell command val/0
       35> #rec{b = 3}.
       #rec{a = undefined,b = 3}
       36> rp(v(-1)).
       #rec{a = undefined,b = 3}
       ok
       37> rd(rec, {f = orddict:new()}).
       rec
       38> #rec{}.
       #rec{f = []}
       ok
       39> rd(rec, {c}), A.
       * 1: variable 'A' is unbound **
       40> #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
       ** exception exit: killed
       42> E = ets:new(t, []).
       17
       43> ets:insert({d,1,2}).
       ** exception error: undefined function ets:insert/1
       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})
       45> f(E).
       ok
       46> catch_exception(true).
       false
       47> E = ets:new(t, []).
       18
       48> ets:insert({d,1,2}).
       * exception error: undefined function ets:insert/1
       49> ets:insert(E, {d,1,2}).
       true
       50> 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 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:

                 --> ?
                 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  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:

       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}.

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.

EXPORTS

       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. The default number is 20.

       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. The default number is 20.

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

       prompt_func(PromptFunc) -> PromptFunc2

              Types:

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

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

       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.  The
              default is true which means that lists of integers will be printed using the string
              syntax, when possible. The value false means that no lists will  be  printed  using
              the string syntax.