File: shell.html

package info (click to toggle)
erlang-doc-html 1%3A8.0-1
links: PTS
area: main
in suites: woody
size: 18,028 kB
ctags: 7,419
sloc: perl: 1,841; ansic: 323; erlang: 155
file content (451 lines) | stat: -rw-r--r-- 14,414 bytes
<HTML>
<HEAD>
<!-- refpage -->
<TITLE>shell</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<CENTER>


<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Erlang Systems]" SRC="min_head.gif"></A>
<H1>shell</H1>
</CENTER>
<H3>MODULE</H3>
<UL>
shell</UL>
<H3>MODULE SUMMARY</H3>
<UL>
The Erlang Shell</UL>
<H3>DESCRIPTION</H3>
<UL>
<P>The module <CODE>shell</CODE> implements an Erlang shell.

<P>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 <CODE>shell:history/1</CODE> and
<CODE>shell:results/1</CODE>, or by setting the application configuration
parameters <CODE>shell_history_length</CODE> and
<CODE>shell_saved_results</CODE> for the application <CODE>stdlib</CODE>.

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

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

<P>If a command (local function call) is not recognized by the
shell, an attempt is first made to find the function in the
module <CODE>user_default</CODE>, 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 <CODE>shell_default</CODE>. The module
<CODE>user_default</CODE> must be explicitly loaded.

<P>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.<P>The shell runs in two modes: <P><UL>
<LI><CODE>Normal</CODE> mode, in which commands can be edited and expressions evaluated</LI><BR>
<LI>Job Control Mode <CODE>JCL</CODE>, in which jobs can be started, killed,
detached and connected.</LI><BR>
</UL>
<P>Only the currently connected job can
'talk' to the shell.
</UL>
<H3>Shell Commands</H3>
<UL>
<P><DL>
<DT><CODE>b()</CODE></DT>
<DD>Prints the current variable bindings.
<BR>
</DD>
<DT><CODE>f()</CODE></DT>
<DD>Removes all variable bindings.

<BR>
</DD>
<DT><CODE>f(X)</CODE></DT>
<DD>Removes the binding of variable <CODE>X</CODE>.

<BR>
</DD>
<DT><CODE>h()</CODE></DT>
<DD>Prints the history list.

<BR>
</DD>
<DT><CODE>history(N)</CODE></DT>
<DD>Sets the number of previous commands to keep in the
history list to <CODE>N</CODE>. The previous number is returned.
The default number is 20.

<BR>
</DD>
<DT><CODE>results(N)</CODE></DT>
<DD>Sets the number of results from previous commands to keep in
the history list to <CODE>N</CODE>. The previous number is returned.
The default number is 20.

<BR>
</DD>
<DT><CODE>e(N)</CODE></DT>
<DD>Repeats the command <CODE>N</CODE>, if <CODE>N</CODE> is positive. If
         it is negative, the <CODE>N</CODE>th previous command is repeated
         (i.e., <CODE>e(-1)</CODE> repeats the previous command).

<BR>
</DD>
<DT><CODE>v(N)</CODE></DT>
<DD>Uses the return value of the command <CODE>N</CODE> in the
         current command.

<BR>
</DD>
<DT><CODE>help()</CODE></DT>
<DD> Evaluates <CODE>shell_default:help()</CODE>.

<BR>
</DD>
<DT><CODE>c(File)</CODE></DT>
<DD>Evaluates <CODE>shell_default:c(File)</CODE>. This compiles
         and loads code in <CODE>File</CODE> and purges old versions of
         code, if necessary. Assumes that the file and module names
         are the same.
<BR>
</DD>
</DL>
</UL>
<H3>Example</H3>
<UL>
<P>The following example is a long dialogue with the shell. Commands
starting with <CODE>&#62;</CODE> 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.
.<PRE>strider 1&#62; <STRONG>erl</STRONG>
Erlang (BEAM) emulator version 4.9

Eshell V4.9  (abort with ^G)
1&#62;<STRONG> Str = &#34;abcd&#34;.</STRONG>
&#34;abcd&#34;
2&#62; <STRONG>L = length(Str).</STRONG>
4
3&#62; <STRONG>Descriptor = {L, list_to_atom(Str)}.</STRONG>
{4,abcd}
4&#62; <STRONG>L.</STRONG> 
4
5&#62; <STRONG>b().</STRONG>
Descriptor = {4,abcd}
L = <STRONG>4</STRONG>
Str = &#34;abcd&#34;
ok
6&#62; <STRONG>f(L).</STRONG> 
ok
7&#62; <STRONG>b().</STRONG>
Descriptor = {4,abcd}
Str = &#34;abcd&#34;
ok
8&#62; <STRONG>f(L).</STRONG>
ok
9&#62; <STRONG>{L, _} = Descriptor.</STRONG>
{4,abcd}
10&#62; <STRONG>L.</STRONG>
4
11&#62; <STRONG>{P, Q, R} = Descriptor.</STRONG>
** exited: {{badmatch,{4,abcd}},{erl_eval,expr,3}} **
12&#62; <STRONG>P.</STRONG>
** exited: {{unbound,'P'},{erl_eval,expr,3}} **
13&#62; <STRONG>Descriptor.</STRONG>
{4,abcd}
14&#62;<STRONG> {P, Q} = Descriptor.</STRONG>
{4,abcd}
15&#62; <STRONG>P.</STRONG>
4
16&#62; <STRONG>f().</STRONG>
ok
17&#62; <STRONG>put(aa, hello).</STRONG>
undefined
18&#62; <STRONG>get(aa).</STRONG>
hello
19&#62; <STRONG>Y = test1:demo(1).</STRONG>
11
20&#62; <STRONG>get().</STRONG>
[{aa,worked}]
21&#62; <STRONG>put(aa, hello).</STRONG>
worked
22&#62; <STRONG>Z = test1:demo(2).</STRONG>
** exited: {{badmatch,1},{test1,demo,[2]}} **

=ERROR REPORT==== 24-Jan-1997::07:48:46 ===
!!! Error in process &#60;0.22.0&#62; with exit value: {{badmatch,1}
,{test1,demo,[2]}}
23&#62; <STRONG>Z.</STRONG>
** exited: {{unbound,'Z'},{erl_eval,expr,3}} **
24&#62; <STRONG>get(aa).</STRONG>
hello
25&#62; <STRONG>erase(), put(aa, hello).</STRONG>
undefined
26&#62; <STRONG>spawn(test1, demo, [1]).</STRONG>
&#60;0.25.0&#62;
27&#62; <STRONG>get(aa).</STRONG>
hello
28&#62; <STRONG>io:format(&#34;hello hello\n&#34;).</STRONG>
hello hello
ok
29&#62; <STRONG>e(28).</STRONG>
hello hello
ok
30&#62;<STRONG> v(28).</STRONG>
ok
31&#62; <STRONG>test1:loop(0).</STRONG>
Hello Number: 0
Hello Number: 1
Hello Number: 2
Hello Number: 3

User switch command
 --&#62; i
 --&#62; c
.
.
.
Hello Number: 3374
Hello Number: 3375
Hello Number: 3376
Hello Number: 3377
Hello Number: 3378
** exited: killed **
32&#62; <STRONG>halt().</STRONG>
strider 2&#62;
</PRE>
</UL>
<H3>Comments</H3>
<UL>
<P>Command 1 sets the variable <CODE>Str</CODE> to the string
<CODE>&#34;abcd&#34;</CODE>.

<P>Command 2 sets <CODE>L</CODE> to the length of the string evaluating
the BIF <CODE>atom_to_list</CODE>.

<P>Command 3 builds the tuple <CODE>Descriptor</CODE>.

<P>Command 4 prints the value of the variable <CODE>L</CODE>.

<P>Command 5 evaluates the internal shell command <CODE>b()</CODE>, which
is an abbreviation of &#34;bindings&#34;. This prints 
the current shell variables and their bindings. The <CODE>ok</CODE> at
the end is the return value of the <CODE>b()</CODE> function.

<P>Command 6 <CODE>f(L)</CODE> evaluates the internal shell command
<CODE>f(L)</CODE> (abbreviation of &#34;forget&#34;). The value of the variable
<CODE>L</CODE> is removed.

<P>Command 7 prints the new bindings.

<P>Command 8 shows that the value of <CODE>L</CODE> has disappeared from
the bindings.

<P>Command 9 performs a pattern matching operation on
<CODE>Descriptor</CODE>, binding a new value to <CODE>L</CODE>.

<P>Command 10 prints the current value of <CODE>L</CODE>.

<P>Command 11 tries to match <CODE>{P, Q, R}</CODE> against
<CODE>Descriptor</CODE> which is <CODE>{4, abc}</CODE>. 
The match fails and none of the new variables become bound.
The printout starting with &#34;<CODE>** exited:</CODE>&#34; 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 (<CODE>L</CODE>, <CODE>Str</CODE>, etc.) are unchanged.

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

<P>Commands 14 and 15 show a correct match where <CODE>P</CODE> and
<CODE>Q</CODE> are bound.

<P>Command 16 clears all bindings.

<P>The next few commands assume that <CODE>test1:demo(X)</CODE> is
defined in the following way:<PRE>demo(X) -&#62;
    put(aa, worked),
    X = 1,
    X + 10.</PRE>
<P>Commands 17 and 18 set and inspect the value of the item
<CODE>aa</CODE> in the process dictionary.

<P>Command 19 evaluates <CODE>test1:demo(1)</CODE>. The evaluation
succeeds and the changes made in the process dictionary become
visible to the shell. The new value of the dictionary item
<CODE>aa</CODE> can be seen in command 20.

<P>Commands 21 and 22 change the value of the dictionary item
<CODE>aa</CODE> to <CODE>hello</CODE> and call <CODE>test1:demo(2)</CODE>. Evaluation
fails and the changes made to the dictionary in
<CODE>test1:demo(2)</CODE>, before the error occurred, are discarded.

<P>Commands 23 and 24 show that <CODE>Z</CODE> was not bound and that the
dictionary item <CODE>aa</CODE> has retained its original value.

<P>Commands 25, 26 and 27 show the effect of evaluating
<CODE>test1:demo(1)</CODE> 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.

<P>Commands 28, 29 and 30 use the history facilities of the shell.

<P>Command 29 is <CODE>e(28)</CODE>. This re-evaluates command
28. Command 30 is <CODE>v(28)</CODE>. 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.

<P>For the next command, it is assumed that <CODE>test1:loop(N)</CODE> is
defined in the following way:
<PRE>loop(N) -&#62;
    io:format(&#34;Hello Number: ~w~n&#34;, [N]), 
    loop(N+1).
    </PRE>
<P>Command 31 evaluates <CODE>test1:loop(0)</CODE>, which puts the
system into an infinite loop. At this point the user types
<CODE>Control G</CODE>, which suspends output from the current process,
which is stuck in a loop, and activates <CODE>JCL</CODE> mode. In <CODE>JCL</CODE>
mode the user can start and stop jobs.

<P>In this particular case, the <CODE>i</CODE> command (&#34;interrupt&#34;) is
used to terminate the looping program, and the <CODE>c</CODE> 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 &#34;<CODE>** exited: killed **</CODE>&#34; message is
shown.

<P>The <CODE>halt()</CODE> command exits the Erlang runtime system.

</UL>
<H3>JCL Mode</H3>
<UL>
<P>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 <CODE>job</CODE>. Only the current job,
which is said to be <CODE>connected</CODE>, can perform operations
with standard IO. All other jobs, which are said to be <CODE>detached</CODE>, are
<CODE>blocked</CODE> if they attempt to use standard IO.

<P>All jobs which do not use standard IO run in the normal way.

<P><CODE>^G</CODE> (Control G) detaches the current job and JCL mode is
activated. The <CODE>JCL</CODE> mode prompt is <CODE>&#34;--&#62;&#34;</CODE>. If <CODE> &#34;?&#34;</CODE> is entered at the prompt, the following help message is
displayed:<PRE>          --&#62; ?
          c [nn]   - connect to job 
          i [nn]   - interrupt job
          k [nn]   - kill job
          j        - list all jobs
          s        - start local shell
          r [node] - start remote shell
          q        - quit Erlang
          ?  | h   - this message</PRE>
<P>The <CODE>JCL</CODE> commands have the following meaning:
<P><DL>
<DT><CODE>c [nn]</CODE></DT>
<DD> Connects to job number <CODE>&#60;nn&#62;</CODE> 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.

<BR>
</DD>
<DT><CODE>i [nn]</CODE></DT>
<DD> Stops the current evaluator process for job number
<CODE>nn</CODE> 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.

<BR>
</DD>
<DT><CODE>k [nn]</CODE></DT>
<DD> Kills job number <CODE>nn</CODE> or the current
         job. All spawned processes in the job are
         killed, provided they have not evaluated the
         <CODE>group_leader/1</CODE> BIF and are located on
         the local machine. Processes spawned on remote nodes will
         not be killed.

<BR>
</DD>
<DT><CODE>j</CODE></DT>
<DD> Lists all jobs. A list of all known jobs is
         printed. The current job name is prefixed with '*'.

<BR>
</DD>
<DT><CODE>s</CODE></DT>
<DD>Starts a new job. This will be assigned the new index
         <CODE>[nn]</CODE> which can be used in references.

<BR>
</DD>
<DT><CODE>r [node]</CODE></DT>
<DD>Starts a remote job on <CODE>node</CODE>. 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.

<BR>
</DD>
<DT><CODE>q</CODE></DT>
<DD> Quits Erlang.

<BR>
</DD>
<DT><CODE>?</CODE></DT>
<DD> Displays this message.
<BR>
</DD>
</DL>
</UL>
<H3>EXPORTS</H3>
<P><A NAME="history%1"><STRONG><CODE>history(N) -&#62; integer()</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>N = integer()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P> Sets the number of previous commands to keep in the
history list to <CODE>N</CODE>. The previous number is returned.
The default number is 20.
</UL>
<P><A NAME="results%1"><STRONG><CODE>results(N) -&#62; integer()</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>N = integer()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P> Sets the number of results from previous commands to keep in
the history list to <CODE>N</CODE>. The previous number is returned.
The default number is 20.
</UL>
<H3>AUTHORS</H3>
<UL>
Robert Virding - support@erlang.ericsson.se<BR>
</UL>
<CENTER>
<HR>
<FONT SIZE=-1>stdlib 1.10<BR>
Copyright &copy; 1991-2001
<A HREF="http://www.erlang.se">Ericsson Utvecklings AB</A><BR>
<!--#include virtual="/ssi/otp_footer.html"-->
</FONT>
</CENTER>
</BODY>
</HTML>