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 Note:
93 If a huge value is stored in a variable binding, you have to both
94 call f(X) and call history(0) or results(0) to free up that memory.
95 h():
98 Prints the history list.
99 history(N):
101 Sets the number of previous commands to keep in the history list to
102 N. The previous number is returned. Defaults to 20.
103 results(N):
105 Sets the number of results from previous commands to keep in the
106 history list to N. The previous number is returned. Defaults to 20.
107 e(N):
109 Repeats command N, if N is positive. If it is negative, the Nth
110 previous command is repeated (that is, e(-1) repeats the previous
111 command).
112 v(N):
114 Uses the return value of command N in the current command, if N is
115 positive. If it is negative, the return value of the Nth previous
116 command is used (that is, v(-1) uses the value of the previous com‐
117 mand).
118 help():
120 Evaluates shell_default:help().
121 h(Module, Function):
123 Print the documentation for Module:Function in the shell if avail‐
124 able.
125 ht(Module, Type):
127 Print the documentation for Module:Type in the shell if available.
128 hcb(Module, Callback):
130 Print the documentation for Module:Callback in the shell if avail‐
131 able.
132 c(Mod):
134 Evaluates shell_default:c(Mod). This compiles and loads the module
135 Mod and purges old versions of the code, if necessary. Mod can be
136 either a module name or a a source file path, with or without .erl
137 extension.
138 catch_exception(Bool):
140 Sets the exception handling of the evaluator process. The previous
141 exception handling is returned. The default (false) is to kill the
142 evaluator process when an exception occurs, which causes the shell
143 to create a new evaluator process. When the exception handling is
144 set to true, the evaluator process lives on. This means, for exam‐
145 ple, that ports and ETS tables as well as processes linked to the
146 evaluator process survive the exception.
147 rd(RecordName, RecordDefinition):
149 Defines a record in the shell. RecordName is an atom and RecordDef‐
150 inition lists the field names and the default values. Usually
151 record definitions are made known to the shell by use of the
152 rr/1,2,3 commands described below, but sometimes it is handy to de‐
153 fine records on the fly.
154 rf():
156 Removes all record definitions, then reads record definitions from
157 the modules shell_default and user_default (if loaded). Returns the
158 names of the records defined.
159 rf(RecordNames):
161 Removes selected record definitions. RecordNames is a record name
162 or a list of record names. To remove all record definitions, use
163 '_'.
164 rl():
166 Prints all record definitions.
167 rl(RecordNames):
169 Prints selected record definitions. RecordNames is a record name or
170 a list of record names.
171 rp(Term):
173 Prints a term using the record definitions known to the shell. All
174 of Term is printed; the depth is not limited as is the case when a
175 return value is printed.
176 rr(Module):
178 Reads record definitions from a module's BEAM file. If there are no
179 record definitions in the BEAM file, the source file is located and
180 read instead. Returns the names of the record definitions read.
181 Module is an atom.
182 rr(Wildcard):
184 Reads record definitions from files. Existing definitions of any of
185 the record names read are replaced. Wildcard is a wildcard string
186 as defined in filelib(3), but not an atom.
187 rr(WildcardOrModule, RecordNames):
189 Reads record definitions from files but discards record names not
190 mentioned in RecordNames (a record name or a list of record names).
191 rr(WildcardOrModule, RecordNames, Options):
193 Reads record definitions from files. The compiler options {i, Dir},
194 {d, Macro}, and {d, Macro, Value} are recognized and used for set‐
195 ting up the include path and macro definitions. To read all record
196 definitions, use '_' as value of RecordNames.
197
199 The following example is a long dialog with the shell. Commands start‐
200 ing with > are inputs to the shell. All other lines are output from the
201 shell.
202 strider 1> erl
204 Erlang (BEAM) emulator version 5.3 [hipe] [threads:0]
205 Eshell V5.3 (abort with ^G)
207 1> Str = "abcd".
208 "abcd"
209 Command 1 sets variable Str to string "abcd".
211 2> L = length(Str).
213 4
214 Command 2 sets L to the length of string Str.
216 3> Descriptor = {L, list_to_atom(Str)}.
218 {4,abcd}
219 Command 3 builds the tuple Descriptor, evaluating the BIF
221 list_to_atom/1.
222 4> L.
224 4
225 Command 4 prints the value of variable L.
227 5> b().
229 Descriptor = {4,abcd}
230 L = 4
231 Str = "abcd"
232 ok
233 Command 5 evaluates the internal shell command b(), which is an abbre‐
235 viation of "bindings". This prints the current shell variables and
236 their bindings. ok at the end is the return value of function b().
237 6> f(L).
239 ok
240 Command 6 evaluates the internal shell command f(L) (abbreviation of
242 "forget"). The value of variable L is removed.
243 7> b().
245 Descriptor = {4,abcd}
246 Str = "abcd"
247 ok
248 Command 7 prints the new bindings.
250 8> f(L).
252 ok
253 Command 8 has no effect, as L has no value.
255 9> {L, _} = Descriptor.
257 {4,abcd}
258 Command 9 performs a pattern matching operation on Descriptor, binding
260 a new value to L.
261 10> L.
263 4
264 Command 10 prints the current value of L.
266 11> {P, Q, R} = Descriptor.
268 ** exception error: no match of right hand side value {4,abcd}
269 Command 11 tries to match {P, Q, R} against Descriptor, which is {4,
271 abc}. The match fails and none of the new variables become bound. The
272 printout starting with "** exception error:" is not the value of the
273 expression (the expression had no value because its evaluation failed),
274 but a warning printed by the system to inform the user that an error
275 has occurred. The values of the other variables (L, Str, and so on) are
276 unchanged.
277 12> P.
279 * 1:1: variable 'P' is unbound
280 13> Descriptor.
281 {4,abcd}
282 Commands 12 and 13 show that P is unbound because the previous command
284 failed, and that Descriptor has not changed.
285 14>{P, Q} = Descriptor.
287 {4,abcd}
288 15> P.
289 4
290 Commands 14 and 15 show a correct match where P and Q are bound.
292 16> f().
294 ok
295 Command 16 clears all bindings.
297 The next few commands assume that test1:demo(X) is defined as follows:
299 demo(X) ->
301 put(aa, worked),
302 X = 1,
303 X + 10.
304 17> put(aa, hello).
306 undefined
307 18> get(aa).
308 hello
309 Commands 17 and 18 set and inspect the value of item aa in the process
311 dictionary.
312 19> Y = test1:demo(1).
314 11
315 Command 19 evaluates test1:demo(1). The evaluation succeeds and the
317 changes made in the process dictionary become visible to the shell. The
318 new value of dictionary item aa can be seen in command 20.
319 20> get().
321 [{aa,worked}]
322 21> put(aa, hello).
323 worked
324 22> Z = test1:demo(2).
325 ** exception error: no match of right hand side value 1
326 in function test1:demo/1
327 Commands 21 and 22 change the value of dictionary item aa to hello and
329 call test1:demo(2). Evaluation fails and the changes made to the dic‐
330 tionary in test1:demo(2), before the error occurred, are discarded.
331 23> Z.
333 * 1:1: variable 'Z' is unbound
334 24> get(aa).
335 hello
336 Commands 23 and 24 show that Z was not bound and that dictionary item
338 aa has retained its original value.
339 25> erase(), put(aa, hello).
341 undefined
342 26> spawn(test1, demo, [1]).
343 <0.57.0>
344 27> get(aa).
345 hello
346 Commands 25, 26, and 27 show the effect of evaluating test1:demo(1) in
348 the background. In this case, the expression is evaluated in a newly
349 spawned process. Any changes made in the process dictionary are local
350 to the newly spawned process and therefore not visible to the shell.
351 28> io:format("hello hello\n").
353 hello hello
354 ok
355 29> e(28).
356 hello hello
357 ok
358 30> v(28).
359 ok
360 Commands 28, 29 and 30 use the history facilities of the shell. Command
362 29 re-evaluates command 28. Command 30 uses the value (result) of com‐
363 mand 28. In the cases of a pure function (a function with no side ef‐
364 fects), the result is the same. For a function with side effects, the
365 result can be different.
366 The next few commands show some record manipulation. It is assumed that
368 ex.erl defines a record as follows:
369 -record(rec, {a, b = val()}).
371 val() ->
373 3.
374 31> c(ex).
376 {ok,ex}
377 32> rr(ex).
378 [rec]
379 Commands 31 and 32 compile file ex.erl and read the record definitions
381 in ex.beam. If the compiler did not output any record definitions on
382 the BEAM file, rr(ex) tries to read record definitions from the source
383 file instead.
384 33> rl(rec).
386 -record(rec,{a,b = val()}).
387 ok
388 Command 33 prints the definition of the record named rec.
390 34> #rec{}.
392 ** exception error: undefined shell command val/0
393 Command 34 tries to create a rec record, but fails as function val/0 is
395 undefined.
396 35> #rec{b = 3}.
398 #rec{a = undefined,b = 3}
399 Command 35 shows the workaround: explicitly assign values to record
401 fields that cannot otherwise be initialized.
402 36> rp(v(-1)).
404 #rec{a = undefined,b = 3}
405 ok
406 Command 36 prints the newly created record using record definitions
408 maintained by the shell.
409 37> rd(rec, {f = orddict:new()}).
411 rec
412 Command 37 defines a record directly in the shell. The definition re‐
414 places the one read from file ex.beam.
415 38> #rec{}.
417 #rec{f = []}
418 ok
419 Command 38 creates a record using the new definition, and prints the
421 result.
422 39> rd(rec, {c}), A.
424 * 1:15: variable 'A' is unbound
425 40> #rec{}.
426 #rec{c = undefined}
427 ok
428 Command 39 and 40 show that record definitions are updated as side ef‐
430 fects. The evaluation of the command fails, but the definition of rec
431 has been carried out.
432 For the next command, it is assumed that test1:loop(N) is defined as
434 follows:
435 loop(N) ->
437 io:format("Hello Number: ~w~n", [N]),
438 loop(N+1).
439 41> test1:loop(0).
441 Hello Number: 0
442 Hello Number: 1
443 Hello Number: 2
444 Hello Number: 3
445 User switch command
447 --> i
448 --> c
449 Hello Number: 3374
450 Hello Number: 3375
451 Hello Number: 3376
452 Hello Number: 3377
453 Hello Number: 3378
454 ** exception exit: killed
455 Command 41 evaluates test1:loop(0), which puts the system into an infi‐
457 nite loop. At this point the user types ^G (Control G), which suspends
458 output from the current process, which is stuck in a loop, and acti‐
459 vates JCL mode. In JCL mode the user can start and stop jobs.
460 In this particular case, command i ("interrupt") terminates the looping
462 program, and command c connects to the shell again. As the process was
463 running in the background before we killed it, more printouts occur be‐
464 fore message "** exception exit: killed" is shown.
465 42> E = ets:new(t, []).
467 #Ref<0.1662103692.2407923716.214192>
468 Command 42 creates an ETS table.
470 43> ets:insert({d,1,2}).
472 ** exception error: undefined function ets:insert/1
473 Command 43 tries to insert a tuple into the ETS table, but the first
475 argument (the table) is missing. The exception kills the evaluator
476 process.
477 44> ets:insert(E, {d,1,2}).
479 ** exception error: argument is of wrong type
480 in function ets:insert/2
481 called as ets:insert(16,{d,1,2})
482 Command 44 corrects the mistake, but the ETS table has been destroyed
484 as it was owned by the killed evaluator process.
485 45> f(E).
487 ok
488 46> catch_exception(true).
489 false
490 Command 46 sets the exception handling of the evaluator process to
492 true. The exception handling can also be set when starting Erlang by
493 erl -stdlib shell_catch_exception true.
494 47> E = ets:new(t, []).
496 #Ref<0.1662103692.2407923716.214197>
497 48> ets:insert({d,1,2}).
498 * exception error: undefined function ets:insert/1
499 Command 48 makes the same mistake as in command 43, but this time the
501 evaluator process lives on. The single star at the beginning of the
502 printout signals that the exception has been caught.
503 49> ets:insert(E, {d,1,2}).
505 true
506 Command 49 successfully inserts the tuple into the ETS table.
508 50> ets:insert(#Ref<0.1662103692.2407923716.214197>, {e,3,4}).
510 true
511 Command 50 inserts another tuple into the ETS table. This time the
513 first argument is the table identifier itself. The shell can parse com‐
514 mands with pids (<0.60.0>), ports (#Port<0.536>), references
515 (#Ref<0.1662103692.2407792644.214210>), and external functions
516 (#Fun<a.b.1>), but the command fails unless the corresponding pid,
517 port, reference, or function can be created in the running system.
518 51> halt().
520 strider 2>
521 Command 51 exits the Erlang runtime system.
523
525 When the shell starts, it starts a single evaluator process. This
526 process, together with any local processes that it spawns, is referred
527 to as a job. Only the current job, which is said to be connected, can
528 perform operations with standard I/O. All other jobs, which are said to
529 be detached, are blocked if they attempt to use standard I/O.
530 All jobs that do not use standard I/O run in the normal way.
532 The shell escape key ^G (Control G) detaches the current job and acti‐
534 vates JCL mode. The JCL mode prompt is "-->". If "?" is entered at the
535 prompt, the following help message is displayed:
536 --> ?
538 c [nn] - connect to job
539 i [nn] - interrupt job
540 k [nn] - kill job
541 j - list all jobs
542 s [shell] - start local shell
543 r [node [shell]] - start remote shell
544 q - quit erlang
545 ? | h - this message
546 The JCL commands have the following meaning:
548 c [nn]:
550 Connects to job number <nn> or the current job. The standard shell
551 is resumed. Operations that use standard I/O by the current job are
552 interleaved with user inputs to the shell.
553 i [nn]:
555 Stops the current evaluator process for job number nn or the cur‐
556 rent job, but does not kill the shell process. So, any variable
557 bindings and the process dictionary are preserved and the job can
558 be connected again. This command can be used to interrupt an end‐
559 less loop.
560 k [nn]:
562 Kills job number nn or the current job. All spawned processes in
563 the job are killed, provided they have not evaluated the
564 group_leader/1 BIF and are located on the local machine. Processes
565 spawned on remote nodes are not killed.
566 j:
568 Lists all jobs. A list of all known jobs is printed. The current
569 job name is prefixed with '*'.
570 s:
572 Starts a new job. This is assigned the new index [nn], which can be
573 used in references.
574 s [shell]:
576 Starts a new job. This is assigned the new index [nn], which can be
577 used in references. If optional argument shell is specified, it is
578 assumed to be a module that implements an alternative shell.
579 r [node]:
581 Starts a remote job on node. This is used in distributed Erlang to
582 allow a shell running on one node to control a number of applica‐
583 tions running on a network of nodes. If optional argument shell is
584 specified, it is assumed to be a module that implements an alterna‐
585 tive shell.
586 q:
588 Quits Erlang. Notice that this option is disabled if Erlang is
589 started with the ignore break, +Bi, system flag (which can be use‐
590 ful, for example when running a restricted shell, see the next sec‐
591 tion).
592 ?:
594 Displays the help message above.
595 The behavior of shell escape can be changed by the STDLIB application
597 variable shell_esc. The value of the variable can be either jcl (erl
598 -stdlib shell_esc jcl) or abort (erl -stdlib shell_esc abort). The
599 first option sets ^G to activate JCL mode (which is also default behav‐
600 ior). The latter sets ^G to terminate the current shell and start a new
601 one. JCL mode cannot be invoked when shell_esc is set to abort.
602 If you want an Erlang node to have a remote job active from the start
604 (rather than the default local job), start Erlang with flag -remsh, for
605 example, erl -remsh other_node@other_host
606
608 The shell can be started in a restricted mode. In this mode, the shell
609 evaluates a function call only if allowed. This feature makes it possi‐
610 ble to, for example, prevent a user from accidentally calling a func‐
611 tion from the prompt that could harm a running system (useful in combi‐
612 nation with system flag +Bi).
613 When the restricted shell evaluates an expression and encounters a
615 function call or an operator application, it calls a callback function
616 (with information about the function call in question). This callback
617 function returns true to let the shell go ahead with the evaluation, or
618 false to abort it. There are two possible callback functions for the
619 user to implement:
620 * local_allowed(Func, ArgList, State) -> {boolean(),NewState}
622 This is used to determine if the call to the local function Func
624 with arguments ArgList is to be allowed.
625 * non_local_allowed(FuncSpec, ArgList, State) -> {boolean(),NewState}
627 | {{redirect,NewFuncSpec,NewArgList},NewState}
628 This is used to determine if the call to non-local function Func‐
630 Spec ({Module,Func} or a fun) with arguments ArgList is to be al‐
631 lowed. The return value {redirect,NewFuncSpec,NewArgList} can be
632 used to let the shell evaluate some other function than the one
633 specified by FuncSpec and ArgList.
634 These callback functions are called from local and non-local evaluation
636 function handlers, described in the erl_eval manual page. (Arguments in
637 ArgList are evaluated before the callback functions are called.)
638 From OTP 25.0, if there are errors evaluating Erlang constructs, such
640 as badmatch during pattern matching or bad_generator in a comprehen‐
641 sion, the evaluator will dispatch to erlang:raise(error, Reason, Stack‐
642 trace). This call will be checked against the non_local_allowed/3 call‐
643 back function. You can either forbid it, allow it, or redirect to an‐
644 other call of your choice.
645 Argument State is a tuple {ShellState,ExprState}. The return value New‐
647 State has the same form. This can be used to carry a state between
648 calls to the callback functions. Data saved in ShellState lives through
649 an entire shell session. Data saved in ExprState lives only through the
650 evaluation of the current expression.
651 There are two ways to start a restricted shell session:
653 * Use STDLIB application variable restricted_shell and specify, as
655 its value, the name of the callback module. Example (with callback
656 functions implemented in callback_mod.erl): $ erl -stdlib re‐
657 stricted_shell callback_mod.
658 * From a normal shell session, call function start_restricted/1. This
660 exits the current evaluator and starts a new one in restricted
661 mode.
662 Notes:
664 * When restricted shell mode is activated or deactivated, new jobs
666 started on the node run in restricted or normal mode, respectively.
667 * If restricted mode has been enabled on a particular node, remote
669 shells connecting to this node also run in restricted mode.
670 * The callback functions cannot be used to allow or disallow execu‐
672 tion of functions called from compiled code (only functions called
673 from expressions entered at the shell prompt).
674 Errors when loading the callback module is handled in different ways
676 depending on how the restricted shell is activated:
677 * If the restricted shell is activated by setting the STDLIB variable
679 during emulator startup, and the callback module cannot be loaded,
680 a default restricted shell allowing only the commands q() and
681 init:stop() is used as fallback.
682 * If the restricted shell is activated using start_restricted/1 and
684 the callback module cannot be loaded, an error report is sent to
685 the error logger and the call returns {error,Reason}.
686
688 The default shell prompt function displays the name of the node (if the
689 node can be part of a distributed system) and the current command num‐
690 ber. The user can customize the prompt function by calling
691 prompt_func/1 or by setting application configuration parameter
692 shell_prompt_func for the STDLIB application.
693 A customized prompt function is stated as a tuple {Mod, Func}. The
695 function is called as Mod:Func(L), where L is a list of key-value pairs
696 created by the shell. Currently there is only one pair: {history, N},
697 where N is the current command number. The function is to return a list
698 of characters or an atom. This constraint is because of the Erlang I/O
699 protocol. Unicode characters beyond code point 255 are allowed in the
700 list and the atom. Notice that in restricted mode the call Mod:Func(L)
701 must be allowed or the default shell prompt function is called.
702
704 catch_exception(Bool) -> boolean()
705 Types:
707 Bool = boolean()
709 Sets the exception handling of the evaluator process. The previ‐
711 ous exception handling is returned. The default (false) is to
712 kill the evaluator process when an exception occurs, which
713 causes the shell to create a new evaluator process. When the ex‐
714 ception handling is set to true, the evaluator process lives on,
715 which means that, for example, ports and ETS tables as well as
716 processes linked to the evaluator process survive the exception.
717 history(N) -> integer() >= 0
719 Types:
721 N = integer() >= 0
723 Sets the number of previous commands to keep in the history list
725 to N. The previous number is returned. Defaults to 20.
726 prompt_func(PromptFunc) -> PromptFunc2
728 Types:
730 PromptFunc = PromptFunc2 = default | {module(), atom()}
732 Sets the shell prompt function to PromptFunc. The previous
734 prompt function is returned.
735 results(N) -> integer() >= 0
737 Types:
739 N = integer() >= 0
741 Sets the number of results from previous commands to keep in the
743 history list to N. The previous number is returned. Defaults to
744 20.
745 start_restricted(Module) -> {error, Reason}
747 Types:
749 Module = module()
751 Reason = code:load_error_rsn()
752 Exits a normal shell and starts a restricted shell. Module spec‐
754 ifies the callback module for the functions local_allowed/3 and
755 non_local_allowed/3. The function is meant to be called from the
756 shell.
757 If the callback module cannot be loaded, an error tuple is re‐
759 turned. The Reason in the error tuple is the one returned by the
760 code loader when trying to load the code of the callback module.
761 stop_restricted() -> no_return()
763 Exits a restricted shell and starts a normal shell. The function
765 is meant to be called from the shell.
766 strings(Strings) -> Strings2
768 Types:
770 Strings = Strings2 = boolean()
772 Sets pretty printing of lists to Strings. The previous value of
774 the flag is returned.
775 The flag can also be set by the STDLIB application variable
777 shell_strings. Defaults to true, which means that lists of inte‐
778 gers are printed using the string syntax, when possible. Value
779 false means that no lists are printed using the string syntax.
780Ericsson AB stdlib 4.3.1.3 shell(3)