1shell(3) Erlang Module Definition shell(3)
2
6 shell - The Erlang shell.
7
9 This module provides an Erlang shell.
10 The shell is a user interface program for entering expression se‐
12 quences. The expressions are evaluated and a value is returned. The
13 shell provides an Emacs like set of shortcuts for editing the text of
14 the current line. See tty - A Command-Line Interface in the ERTS
15 User's Guide for a list of all available shortcuts.
16 A history mechanism saves previous commands and their values, which can
18 then be incorporated in later commands. How many commands and results
19 to save can be determined by the user, either interactively, by calling
20 history/1 and results/1, or by setting the application configuration
21 parameters shell_history_length and shell_saved_results for the STDLIB
22 application. The shell history can be saved to disk by setting the ap‐
23 plication configuration parameter shell_history for the Kernel applica‐
24 tion.
25 The shell uses a helper process for evaluating commands to protect the
27 history mechanism from exceptions. By default the evaluator process is
28 killed when an exception occurs, but by calling catch_exception/1 or by
29 setting the application configuration parameter shell_catch_exception
30 for the STDLIB application this behavior can be changed. See also the
31 example below.
32 Variable bindings, and local process dictionary changes that are gener‐
34 ated in user expressions are preserved, and the variables can be used
35 in later commands to access their values. The bindings can also be for‐
36 gotten so the variables can be reused.
37 The special shell commands all have the syntax of (local) function
39 calls. They are evaluated as normal function calls and many commands
40 can be used in one expression sequence.
41 If a command (local function call) is not recognized by the shell, an
43 attempt is first made to find the function in module user_default,
44 where customized local commands can be placed. If found, the function
45 is evaluated, otherwise an attempt is made to evaluate the function in
46 module shell_default. Module user_default must be explicitly loaded.
47 The shell also permits the user to start multiple concurrent jobs. A
49 job can be regarded as a set of processes that can communicate with the
50 shell.
51 There is some support for reading and printing records in the shell.
53 During compilation record expressions are translated to tuple expres‐
54 sions. In runtime it is not known whether a tuple represents a record,
55 and the record definitions used by the compiler are unavailable at run‐
56 time. So, to read the record syntax and print tuples as records when
57 possible, record definitions must be maintained by the shell itself.
58 The shell commands for reading, defining, forgetting, listing, and
60 printing records are described below. Notice that each job has its own
61 set of record definitions. To facilitate matters, record definitions in
62 modules shell_default and user_default (if loaded) are read each time a
63 new job is started. For example, adding the following line to user_de‐
64 fault makes the definition of file_info readily available in the shell:
65 -include_lib("kernel/include/file.hrl").
67 The shell runs in two modes:
69 * Normal (possibly restricted) mode, in which commands can be edited
71 and expressions evaluated
72 * Job Control Mode, JCL, in which jobs can be started, killed, de‐
74 tached, and connected
75 Only the currently connected job can 'talk' to the shell.
77
79 The commands below are the built-in shell commands that are always
80 available. In most system the commands listed in the c(3) module are
81 also available in the shell.
82 b():
84 Prints the current variable bindings.
85 f():
87 Removes all variable bindings.
88 f(X):
90 Removes the binding of variable X.
91 h():
93 Prints the history list.
94 history(N):
96 Sets the number of previous commands to keep in the history list to
97 N. The previous number is returned. Defaults to 20.
98 results(N):
100 Sets the number of results from previous commands to keep in the
101 history list to N. The previous number is returned. Defaults to 20.
102 e(N):
104 Repeats command N, if N is positive. If it is negative, the Nth
105 previous command is repeated (that is, e(-1) repeats the previous
106 command).
107 v(N):
109 Uses the return value of command N in the current command, if N is
110 positive. If it is negative, the return value of the Nth previous
111 command is used (that is, v(-1) uses the value of the previous com‐
112 mand).
113 help():
115 Evaluates shell_default:help().
116 h(Module, Function):
118 Print the documentation for Module:Function in the shell if avail‐
119 able.
120 ht(Module, Type):
122 Print the documentation for Module:Type in the shell if available.
123 hcb(Module, Callback):
125 Print the documentation for Module:Callback in the shell if avail‐
126 able.
127 c(Mod):
129 Evaluates shell_default:c(Mod). This compiles and loads the module
130 Mod and purges old versions of the code, if necessary. Mod can be
131 either a module name or a a source file path, with or without .erl
132 extension.
133 catch_exception(Bool):
135 Sets the exception handling of the evaluator process. The previous
136 exception handling is returned. The default (false) is to kill the
137 evaluator process when an exception occurs, which causes the shell
138 to create a new evaluator process. When the exception handling is
139 set to true, the evaluator process lives on. This means, for exam‐
140 ple, that ports and ETS tables as well as processes linked to the
141 evaluator process survive the exception.
142 rd(RecordName, RecordDefinition):
144 Defines a record in the shell. RecordName is an atom and RecordDef‐
145 inition lists the field names and the default values. Usually
146 record definitions are made known to the shell by use of the
147 rr/1,2,3 commands described below, but sometimes it is handy to de‐
148 fine records on the fly.
149 rf():
151 Removes all record definitions, then reads record definitions from
152 the modules shell_default and user_default (if loaded). Returns the
153 names of the records defined.
154 rf(RecordNames):
156 Removes selected record definitions. RecordNames is a record name
157 or a list of record names. To remove all record definitions, use
158 '_'.
159 rl():
161 Prints all record definitions.
162 rl(RecordNames):
164 Prints selected record definitions. RecordNames is a record name or
165 a list of record names.
166 rp(Term):
168 Prints a term using the record definitions known to the shell. All
169 of Term is printed; the depth is not limited as is the case when a
170 return value is printed.
171 rr(Module):
173 Reads record definitions from a module's BEAM file. If there are no
174 record definitions in the BEAM file, the source file is located and
175 read instead. Returns the names of the record definitions read.
176 Module is an atom.
177 rr(Wildcard):
179 Reads record definitions from files. Existing definitions of any of
180 the record names read are replaced. Wildcard is a wildcard string
181 as defined in filelib(3), but not an atom.
182 rr(WildcardOrModule, RecordNames):
184 Reads record definitions from files but discards record names not
185 mentioned in RecordNames (a record name or a list of record names).
186 rr(WildcardOrModule, RecordNames, Options):
188 Reads record definitions from files. The compiler options {i, Dir},
189 {d, Macro}, and {d, Macro, Value} are recognized and used for set‐
190 ting up the include path and macro definitions. To read all record
191 definitions, use '_' as value of RecordNames.
192
194 The following example is a long dialog with the shell. Commands start‐
195 ing with > are inputs to the shell. All other lines are output from the
196 shell.
197 strider 1> erl
199 Erlang (BEAM) emulator version 5.3 [hipe] [threads:0]
200 Eshell V5.3 (abort with ^G)
202 1> Str = "abcd".
203 "abcd"
204 Command 1 sets variable Str to string "abcd".
206 2> L = length(Str).
208 4
209 Command 2 sets L to the length of string Str.
211 3> Descriptor = {L, list_to_atom(Str)}.
213 {4,abcd}
214 Command 3 builds the tuple Descriptor, evaluating the BIF
216 list_to_atom/1.
217 4> L.
219 4
220 Command 4 prints the value of variable L.
222 5> b().
224 Descriptor = {4,abcd}
225 L = 4
226 Str = "abcd"
227 ok
228 Command 5 evaluates the internal shell command b(), which is an abbre‐
230 viation of "bindings". This prints the current shell variables and
231 their bindings. ok at the end is the return value of function b().
232 6> f(L).
234 ok
235 Command 6 evaluates the internal shell command f(L) (abbreviation of
237 "forget"). The value of variable L is removed.
238 7> b().
240 Descriptor = {4,abcd}
241 Str = "abcd"
242 ok
243 Command 7 prints the new bindings.
245 8> f(L).
247 ok
248 Command 8 has no effect, as L has no value.
250 9> {L, _} = Descriptor.
252 {4,abcd}
253 Command 9 performs a pattern matching operation on Descriptor, binding
255 a new value to L.
256 10> L.
258 4
259 Command 10 prints the current value of L.
261 11> {P, Q, R} = Descriptor.
263 ** exception error: no match of right hand side value {4,abcd}
264 Command 11 tries to match {P, Q, R} against Descriptor, which is {4,
266 abc}. The match fails and none of the new variables become bound. The
267 printout starting with "** exception error:" is not the value of the
268 expression (the expression had no value because its evaluation failed),
269 but a warning printed by the system to inform the user that an error
270 has occurred. The values of the other variables (L, Str, and so on) are
271 unchanged.
272 12> P.
274 * 1:1: variable 'P' is unbound
275 13> Descriptor.
276 {4,abcd}
277 Commands 12 and 13 show that P is unbound because the previous command
279 failed, and that Descriptor has not changed.
280 14>{P, Q} = Descriptor.
282 {4,abcd}
283 15> P.
284 4
285 Commands 14 and 15 show a correct match where P and Q are bound.
287 16> f().
289 ok
290 Command 16 clears all bindings.
292 The next few commands assume that test1:demo(X) is defined as follows:
294 demo(X) ->
296 put(aa, worked),
297 X = 1,
298 X + 10.
299 17> put(aa, hello).
301 undefined
302 18> get(aa).
303 hello
304 Commands 17 and 18 set and inspect the value of item aa in the process
306 dictionary.
307 19> Y = test1:demo(1).
309 11
310 Command 19 evaluates test1:demo(1). The evaluation succeeds and the
312 changes made in the process dictionary become visible to the shell. The
313 new value of dictionary item aa can be seen in command 20.
314 20> get().
316 [{aa,worked}]
317 21> put(aa, hello).
318 worked
319 22> Z = test1:demo(2).
320 ** exception error: no match of right hand side value 1
321 in function test1:demo/1
322 Commands 21 and 22 change the value of dictionary item aa to hello and
324 call test1:demo(2). Evaluation fails and the changes made to the dic‐
325 tionary in test1:demo(2), before the error occurred, are discarded.
326 23> Z.
328 * 1:1: variable 'Z' is unbound
329 24> get(aa).
330 hello
331 Commands 23 and 24 show that Z was not bound and that dictionary item
333 aa has retained its original value.
334 25> erase(), put(aa, hello).
336 undefined
337 26> spawn(test1, demo, [1]).
338 <0.57.0>
339 27> get(aa).
340 hello
341 Commands 25, 26, and 27 show the effect of evaluating test1:demo(1) in
343 the background. In this case, the expression is evaluated in a newly
344 spawned process. Any changes made in the process dictionary are local
345 to the newly spawned process and therefore not visible to the shell.
346 28> io:format("hello hello\n").
348 hello hello
349 ok
350 29> e(28).
351 hello hello
352 ok
353 30> v(28).
354 ok
355 Commands 28, 29 and 30 use the history facilities of the shell. Command
357 29 re-evaluates command 28. Command 30 uses the value (result) of com‐
358 mand 28. In the cases of a pure function (a function with no side ef‐
359 fects), the result is the same. For a function with side effects, the
360 result can be different.
361 The next few commands show some record manipulation. It is assumed that
363 ex.erl defines a record as follows:
364 -record(rec, {a, b = val()}).
366 val() ->
368 3.
369 31> c(ex).
371 {ok,ex}
372 32> rr(ex).
373 [rec]
374 Commands 31 and 32 compile file ex.erl and read the record definitions
376 in ex.beam. If the compiler did not output any record definitions on
377 the BEAM file, rr(ex) tries to read record definitions from the source
378 file instead.
379 33> rl(rec).
381 -record(rec,{a,b = val()}).
382 ok
383 Command 33 prints the definition of the record named rec.
385 34> #rec{}.
387 ** exception error: undefined shell command val/0
388 Command 34 tries to create a rec record, but fails as function val/0 is
390 undefined.
391 35> #rec{b = 3}.
393 #rec{a = undefined,b = 3}
394 Command 35 shows the workaround: explicitly assign values to record
396 fields that cannot otherwise be initialized.
397 36> rp(v(-1)).
399 #rec{a = undefined,b = 3}
400 ok
401 Command 36 prints the newly created record using record definitions
403 maintained by the shell.
404 37> rd(rec, {f = orddict:new()}).
406 rec
407 Command 37 defines a record directly in the shell. The definition re‐
409 places the one read from file ex.beam.
410 38> #rec{}.
412 #rec{f = []}
413 ok
414 Command 38 creates a record using the new definition, and prints the
416 result.
417 39> rd(rec, {c}), A.
419 * 1:15: variable 'A' is unbound
420 40> #rec{}.
421 #rec{c = undefined}
422 ok
423 Command 39 and 40 show that record definitions are updated as side ef‐
425 fects. The evaluation of the command fails, but the definition of rec
426 has been carried out.
427 For the next command, it is assumed that test1:loop(N) is defined as
429 follows:
430 loop(N) ->
432 io:format("Hello Number: ~w~n", [N]),
433 loop(N+1).
434 41> test1:loop(0).
436 Hello Number: 0
437 Hello Number: 1
438 Hello Number: 2
439 Hello Number: 3
440 User switch command
442 --> i
443 --> c
444 Hello Number: 3374
445 Hello Number: 3375
446 Hello Number: 3376
447 Hello Number: 3377
448 Hello Number: 3378
449 ** exception exit: killed
450 Command 41 evaluates test1:loop(0), which puts the system into an infi‐
452 nite loop. At this point the user types ^G (Control G), which suspends
453 output from the current process, which is stuck in a loop, and acti‐
454 vates JCL mode. In JCL mode the user can start and stop jobs.
455 In this particular case, command i ("interrupt") terminates the looping
457 program, and command c connects to the shell again. As the process was
458 running in the background before we killed it, more printouts occur be‐
459 fore message "** exception exit: killed" is shown.
460 42> E = ets:new(t, []).
462 #Ref<0.1662103692.2407923716.214192>
463 Command 42 creates an ETS table.
465 43> ets:insert({d,1,2}).
467 ** exception error: undefined function ets:insert/1
468 Command 43 tries to insert a tuple into the ETS table, but the first
470 argument (the table) is missing. The exception kills the evaluator
471 process.
472 44> ets:insert(E, {d,1,2}).
474 ** exception error: argument is of wrong type
475 in function ets:insert/2
476 called as ets:insert(16,{d,1,2})
477 Command 44 corrects the mistake, but the ETS table has been destroyed
479 as it was owned by the killed evaluator process.
480 45> f(E).
482 ok
483 46> catch_exception(true).
484 false
485 Command 46 sets the exception handling of the evaluator process to
487 true. The exception handling can also be set when starting Erlang by
488 erl -stdlib shell_catch_exception true.
489 47> E = ets:new(t, []).
491 #Ref<0.1662103692.2407923716.214197>
492 48> ets:insert({d,1,2}).
493 * exception error: undefined function ets:insert/1
494 Command 48 makes the same mistake as in command 43, but this time the
496 evaluator process lives on. The single star at the beginning of the
497 printout signals that the exception has been caught.
498 49> ets:insert(E, {d,1,2}).
500 true
501 Command 49 successfully inserts the tuple into the ETS table.
503 50> ets:insert(#Ref<0.1662103692.2407923716.214197>, {e,3,4}).
505 true
506 Command 50 inserts another tuple into the ETS table. This time the
508 first argument is the table identifier itself. The shell can parse com‐
509 mands with pids (<0.60.0>), ports (#Port<0.536>), references
510 (#Ref<0.1662103692.2407792644.214210>), and external functions
511 (#Fun<a.b.1>), but the command fails unless the corresponding pid,
512 port, reference, or function can be created in the running system.
513 51> halt().
515 strider 2>
516 Command 51 exits the Erlang runtime system.
518
520 When the shell starts, it starts a single evaluator process. This
521 process, together with any local processes that it spawns, is referred
522 to as a job. Only the current job, which is said to be connected, can
523 perform operations with standard I/O. All other jobs, which are said to
524 be detached, are blocked if they attempt to use standard I/O.
525 All jobs that do not use standard I/O run in the normal way.
527 The shell escape key ^G (Control G) detaches the current job and acti‐
529 vates JCL mode. The JCL mode prompt is "-->". If "?" is entered at the
530 prompt, the following help message is displayed:
531 --> ?
533 c [nn] - connect to job
534 i [nn] - interrupt job
535 k [nn] - kill job
536 j - list all jobs
537 s [shell] - start local shell
538 r [node [shell]] - start remote shell
539 q - quit erlang
540 ? | h - this message
541 The JCL commands have the following meaning:
543 c [nn]:
545 Connects to job number <nn> or the current job. The standard shell
546 is resumed. Operations that use standard I/O by the current job are
547 interleaved with user inputs to the shell.
548 i [nn]:
550 Stops the current evaluator process for job number nn or the cur‐
551 rent job, but does not kill the shell process. So, any variable
552 bindings and the process dictionary are preserved and the job can
553 be connected again. This command can be used to interrupt an end‐
554 less loop.
555 k [nn]:
557 Kills job number nn or the current job. All spawned processes in
558 the job are killed, provided they have not evaluated the
559 group_leader/1 BIF and are located on the local machine. Processes
560 spawned on remote nodes are not killed.
561 j:
563 Lists all jobs. A list of all known jobs is printed. The current
564 job name is prefixed with '*'.
565 s:
567 Starts a new job. This is assigned the new index [nn], which can be
568 used in references.
569 s [shell]:
571 Starts a new job. This is assigned the new index [nn], which can be
572 used in references. If optional argument shell is specified, it is
573 assumed to be a module that implements an alternative shell.
574 r [node]:
576 Starts a remote job on node. This is used in distributed Erlang to
577 allow a shell running on one node to control a number of applica‐
578 tions running on a network of nodes. If optional argument shell is
579 specified, it is assumed to be a module that implements an alterna‐
580 tive shell.
581 q:
583 Quits Erlang. Notice that this option is disabled if Erlang is
584 started with the ignore break, +Bi, system flag (which can be use‐
585 ful, for example when running a restricted shell, see the next sec‐
586 tion).
587 ?:
589 Displays the help message above.
590 The behavior of shell escape can be changed by the STDLIB application
592 variable shell_esc. The value of the variable can be either jcl (erl
593 -stdlib shell_esc jcl) or abort (erl -stdlib shell_esc abort). The
594 first option sets ^G to activate JCL mode (which is also default behav‐
595 ior). The latter sets ^G to terminate the current shell and start a new
596 one. JCL mode cannot be invoked when shell_esc is set to abort.
597 If you want an Erlang node to have a remote job active from the start
599 (rather than the default local job), start Erlang with flag -remsh, for
600 example, erl -remsh other_node@other_host
601
603 The shell can be started in a restricted mode. In this mode, the shell
604 evaluates a function call only if allowed. This feature makes it possi‐
605 ble to, for example, prevent a user from accidentally calling a func‐
606 tion from the prompt that could harm a running system (useful in combi‐
607 nation with system flag +Bi).
608 When the restricted shell evaluates an expression and encounters a
610 function call or an operator application, it calls a callback function
611 (with information about the function call in question). This callback
612 function returns true to let the shell go ahead with the evaluation, or
613 false to abort it. There are two possible callback functions for the
614 user to implement:
615 * local_allowed(Func, ArgList, State) -> {boolean(),NewState}
617 This is used to determine if the call to the local function Func
619 with arguments ArgList is to be allowed.
620 * non_local_allowed(FuncSpec, ArgList, State) -> {boolean(),NewState}
622 | {{redirect,NewFuncSpec,NewArgList},NewState}
623 This is used to determine if the call to non-local function Func‐
625 Spec ({Module,Func} or a fun) with arguments ArgList is to be al‐
626 lowed. The return value {redirect,NewFuncSpec,NewArgList} can be
627 used to let the shell evaluate some other function than the one
628 specified by FuncSpec and ArgList.
629 These callback functions are called from local and non-local evaluation
631 function handlers, described in the erl_eval manual page. (Arguments in
632 ArgList are evaluated before the callback functions are called.)
633 From OTP 25.0, if there are errors evaluating Erlang constructs, such
635 as badmatch during pattern matching or bad_generator in a comprehen‐
636 sion, the evaluator will dispatch to erlang:raise(error, Reason, Stack‐
637 trace). This call will be checked against the non_local_allowed/3 call‐
638 back function. You can either forbid it, allow it, or redirect to an‐
639 other call of your choice.
640 Argument State is a tuple {ShellState,ExprState}. The return value New‐
642 State has the same form. This can be used to carry a state between
643 calls to the callback functions. Data saved in ShellState lives through
644 an entire shell session. Data saved in ExprState lives only through the
645 evaluation of the current expression.
646 There are two ways to start a restricted shell session:
648 * Use STDLIB application variable restricted_shell and specify, as
650 its value, the name of the callback module. Example (with callback
651 functions implemented in callback_mod.erl): $ erl -stdlib re‐
652 stricted_shell callback_mod.
653 * From a normal shell session, call function start_restricted/1. This
655 exits the current evaluator and starts a new one in restricted
656 mode.
657 Notes:
659 * When restricted shell mode is activated or deactivated, new jobs
661 started on the node run in restricted or normal mode, respectively.
662 * If restricted mode has been enabled on a particular node, remote
664 shells connecting to this node also run in restricted mode.
665 * The callback functions cannot be used to allow or disallow execu‐
667 tion of functions called from compiled code (only functions called
668 from expressions entered at the shell prompt).
669 Errors when loading the callback module is handled in different ways
671 depending on how the restricted shell is activated:
672 * If the restricted shell is activated by setting the STDLIB variable
674 during emulator startup, and the callback module cannot be loaded,
675 a default restricted shell allowing only the commands q() and
676 init:stop() is used as fallback.
677 * If the restricted shell is activated using start_restricted/1 and
679 the callback module cannot be loaded, an error report is sent to
680 the error logger and the call returns {error,Reason}.
681
683 The default shell prompt function displays the name of the node (if the
684 node can be part of a distributed system) and the current command num‐
685 ber. The user can customize the prompt function by calling
686 prompt_func/1 or by setting application configuration parameter
687 shell_prompt_func for the STDLIB application.
688 A customized prompt function is stated as a tuple {Mod, Func}. The
690 function is called as Mod:Func(L), where L is a list of key-value pairs
691 created by the shell. Currently there is only one pair: {history, N},
692 where N is the current command number. The function is to return a list
693 of characters or an atom. This constraint is because of the Erlang I/O
694 protocol. Unicode characters beyond code point 255 are allowed in the
695 list and the atom. Notice that in restricted mode the call Mod:Func(L)
696 must be allowed or the default shell prompt function is called.
697
699 catch_exception(Bool) -> boolean()
700 Types:
702 Bool = boolean()
704 Sets the exception handling of the evaluator process. The previ‐
706 ous exception handling is returned. The default (false) is to
707 kill the evaluator process when an exception occurs, which
708 causes the shell to create a new evaluator process. When the ex‐
709 ception handling is set to true, the evaluator process lives on,
710 which means that, for example, ports and ETS tables as well as
711 processes linked to the evaluator process survive the exception.
712 history(N) -> integer() >= 0
714 Types:
716 N = integer() >= 0
718 Sets the number of previous commands to keep in the history list
720 to N. The previous number is returned. Defaults to 20.
721 prompt_func(PromptFunc) -> PromptFunc2
723 Types:
725 PromptFunc = PromptFunc2 = default | {module(), atom()}
727 Sets the shell prompt function to PromptFunc. The previous
729 prompt function is returned.
730 results(N) -> integer() >= 0
732 Types:
734 N = integer() >= 0
736 Sets the number of results from previous commands to keep in the
738 history list to N. The previous number is returned. Defaults to
739 20.
740 start_restricted(Module) -> {error, Reason}
742 Types:
744 Module = module()
746 Reason = code:load_error_rsn()
747 Exits a normal shell and starts a restricted shell. Module spec‐
749 ifies the callback module for the functions local_allowed/3 and
750 non_local_allowed/3. The function is meant to be called from the
751 shell.
752 If the callback module cannot be loaded, an error tuple is re‐
754 turned. The Reason in the error tuple is the one returned by the
755 code loader when trying to load the code of the callback module.
756 stop_restricted() -> no_return()
758 Exits a restricted shell and starts a normal shell. The function
760 is meant to be called from the shell.
761 strings(Strings) -> Strings2
763 Types:
765 Strings = Strings2 = boolean()
767 Sets pretty printing of lists to Strings. The previous value of
769 the flag is returned.
770 The flag can also be set by the STDLIB application variable
772 shell_strings. Defaults to true, which means that lists of inte‐
773 gers are printed using the string syntax, when possible. Value
774 false means that no lists are printed using the string syntax.
775Ericsson AB stdlib 4.2 shell(3)