emacs.sgml

OTP是开放电信平台的简称

methods for Emacs to communicate with Erlang.  The first is by
starting an inferior process, the second is by using an Erl'em link.
When using inferior processes each new shell will start a new Erlang
node.  Should the Erl'em link be used it is possible to start several
shells on the same node, a feature not normally available.
</P>

<SECTION>
<TITLE>The shell</TITLE>

<P>
In this section we describe how to start a shell. In the next we cover
how to use it once it has been started.
</P>

<LIST>
  <ITEM><C> M-x erlang-shell RET </C><BR>

<P>
Start a new Erlang shell.  When an inferior process is used a new
Erlang node is started for each shell.  Should the Erl'em link package
be installed several shells can be started on the same Erlang node.
</P>

<P>
A word of warning.  The Erlang function <C>halt().</C> will kill the
current Erlang node, including all shells running on it.
</P>


  <ITEM><C> M-x erlang-shell-display RET </C><BR>

<P>
Display one Erlang shell.  If there are no Erlang shells active a new
will be started.
</P>

</LIST>

</SECTION>

<SECTION>

<TITLE>Command line history</TITLE>

<P>
The look and feel on an Erlang shell inside Emacs should be the same
as in a normal Erlang shell.  There is just one major difference, the
cursor keys will actually move the cursor around just like in any
normal Emacs buffer.  The command line history can be accessed by the
following commands:
</P>

<LIST>

  <ITEM><C> C-up </C>  or <C> M-p </C>  (<C>comint-previous-input</C>)<BR>

<P>
Move to the previous line in the input history.
</P>


  <ITEM><C> C-down </C> or <C> M-n </C>  (<C>comint-next-input</C>)<BR>

<P>
Move to the next line in the input history.
</P>

</LIST>

<P>
If the Erlang shell buffer would be killed the command line history is
saved to a file.  The command line history is automatically retrieved
when a new Erlang shell is started.
</P>

</SECTION>

<SECTION>

<TITLE>The Erlang Shell Mode</TITLE>

<P>
The buffers that are used to run Erlang shells use the major mode
<C>erlang-shell-mode</C>.  This major mode is based on the standard
mode <C>comint-mode</C>.
</P>

<LIST>
  <ITEM><C> erlang-shell-mode </C><BR>

<P>
Enter Erlang shell mode.  To operate correctly the buffer should be in
Comint mode when this command is called. 
</P>

</LIST>

</SECTION>

<SECTION>

<TITLE>Variables</TITLE>

<P>
In this section we present the variables that control the behavior of
the Erlang shell.  See also the next section "Inferior Erlang
Variables".
</P>

<LIST>

<ITEM> <EM>Variable: </EM> <C>erlang-shell-mode-hook</C>
(default <C>()</C>)<BR>

<P>
Function to run when this mode is activated.  See chapter "<SEEALSO
MARKER="#customization">Customization</SEEALSO>" below for examples.
</P>


<ITEM> <EM>Variable: </EM> <C>erlang-input-ring-file-name</C>
(default "~/.erlang_history")<BR>

<P>
The file name used to save the command line history.
</P>


<ITEM> <EM>Variable: </EM> <C>erlang-shell-function</C>
(default <C>inferior-erlang</C>)<BR>

<P>
This variable contain the low-level function to call to start an
Erlang shell.  This variable will be changed by the Erl'em
installation.
</P>


<ITEM> <EM>Variable: </EM> <C>erlang-shell-display-function</C>
(default <C>inferior-erlang-run-or-select</C>)<BR>

<P>
This variable contain the low-level function to call when the
<C>erlang-shell-display</C> is issued.  This variable will be changed by
the Erl'em installation.
</P>

</LIST>

</SECTION>

<SECTION>
<TITLE>Inferior Erlang Variables</TITLE>

<P>
The variables described in this chapter are only used when inferior
Erlang processes are used.  They do not affect the behavior of the
shell when using an Erl'em link.
</P>

<LIST>

  <ITEM> <EM>Variable: </EM> 
<C>inferior-erlang-display-buffer-any-frame</C> (default
<C>nil</C>)<BR>

<P>
When this variable is <C>nil</C> the command
<C>erlang-shell-display</C> will display the inferior process in the
current frame.  When <C>t</C>, it will do nothing when it already is
visible in another frame.  When it is bound to the atom <C>raise</C>
the frame displaying the buffer will be raised.
</P>

  <ITEM> <EM>Variable: </EM> <C>inferior-erlang-shell-type</C>
(default <C>newshell</C>)<BR>

<P>
There are two different variants of the Erlang shell, named the old
and the new shell.  The old is a simple variant that does not provide
command line editing facilities.  The new, on the other hand, provide
full edition features.  Apart from this major difference, they differ
on some subtle points.  Since Emacs itself takes care of the command
line edition features you can switch between the two shell types if
your shell behaves strange.
</P>

<P>
To use the new or the old shell bind this variable to <C>newshell</C> or
<C>oldshell</C>, respectively.
</P>

  <ITEM> <EM>Variable: </EM> <C>inferior-erlang-machine</C>
(default <C>"erl"</C>)<BR>

<P>
The command name of the Erlang runtime system.
</P>


  <ITEM> <EM>Variable: </EM> <C>inferior-erlang-machine-options</C>
(default <C>()</C>)<BR>

<P>
A list of strings containing command line options that is used when
starting an inferior Erlang.
</P>


  <ITEM> <EM>Variable: </EM> <C>inferior-erlang-buffer-name</C>
(default <C>"*erlang*"</C>)<BR>

<P>
The base name of the Erlang shell buffer.  Should several Erlang shell
buffers be used they will be named <C>*erlang*<2></C>,
<C>*erlang*<3></C> etc.
</P>

</LIST>

</SECTION>
</SECTION>

<!-- CHAPTER -->

<SECTION>
<TITLE>Compilation</TITLE>

<P>
The classic edit-compile-bugfix cycle for Erlang is to edit the source
file in an editor, save it to a file and switch to an Erlang shell.
In the shell the compilation command is given.  Should the compilation
fail you have to bring out the editor and locate the correct line.
</P>

<P>
With the Erlang editing mode the entire edit-compile-bugfix cycle can
be performed without leaving Emacs.  Emacs can order Erlang to compile
a file and it can parse the error messages to automatically place the
point on the erroneous lines.
</P>

<SECTION>

<TITLE>Commands</TITLE>

<LIST>

  <ITEM><C>C-c C-k</C> (<C>erlang-compile</C>)<BR>

<P>
This command compiles the file in the current buffer.
</P>

<P>
The action performed by this command depend on the low-level
communication method used.  Should an inferior Erlang process be used
Emacs tries to issue a compile command at the Erlang shell prompt.
The compilation output will be sent to the shell buffer.
This command will fail if it is not possible to issue a command at the
Erlang shell prompt.
</P>

<P>
Should an Erl'em link be used the compile command sent to Erlang will
be independent of any active shell.  The output will be sent to a
dedicated buffer.
</P>


  <ITEM><C>C-x ` </C>  (<C>erlang-next-error</C>)<BR>

<P>
This command will place the point on the line where the first error
was found.  Each successive use of this command will move the point to
the next error.  The buffer displaying the compilation errors will be
updated so that the current error will be visible.
</P>

<P>
You can reparse the compiler output from the beginning by preceding
this command by <C> C-u </C>.
</P>

  <ITEM><C>erlang-compile-display</C><BR>

<P>
Show the output generated by the compile command.
</P>

</LIST>
</SECTION>

<SECTION>
<TITLE>Variables</TITLE>

<LIST>

  <ITEM> <EM>Variable: </EM> <C>erlang-compile-use-outdir</C>
(default <C>t</C>)<BR>

<P>
In some versions of Erlang the <C>outdir</C> options contains a bug.
Should the directory not be present in the current Erlang load path
the object file will not be loaded.
</P>

<P>
Should this variable be set to <C>nil</C> the <C>erlang-compile</C>
command will use a workaround by change current directory, compile the
file, and change back.
</P>


  <ITEM> <EM>Variable: </EM> <C>erlang-compile-function</C>
(default <C>inferior-erlang-compile</C>)<BR>

<P>
The low-level function to use to compile an Erlang module.
</P>


  <ITEM> <EM>Variable: </EM> <C>erlang-compile-display-function</C>
(default <C>inferior-erlang-run-or-select</C>)<BR>

<P>
The low-level function to call when the result of a compilation should
be shown.
</P>


  <ITEM> <EM>Variable: </EM> <C>erlang-next-error-function</C>
(default <C>inferior-erlang-next-error</C>)<BR>

<P>
The low-level function to use when <C>erlang-next-error</C> is used.
</P>

</LIST>

</SECTION>
</SECTION>

<!-- CHAPTER -->

<SECTION>
<TITLE>Customization</TITLE>

<P>
One of the strengths of Emacs is that users can fairly easy customize
the behavior of almost every detail.  The Erlang editing mode is not
an exception to this rule.
</P>

<P>
Normally, Emacs is customized through the user and system init files,
<C>~/.emacs</C> and <C>site-start.el</C>, respectively.  The content
of the files are expressions written in the Emacs extension language
Emacs Lisp.  The semantics of Lisp is fairly similar Erlang's.
However, the syntax is very different.  Fortunately, most
customizations require only very minor knowledge of the language.
</P>

<SECTION>

<TITLE>Emacs Lisp</TITLE>

<P>
In this section we show the basic constructions of Emacs Lisp needed to
perform customizations.
</P>

<P>
In addition to placing the expressions in the init file, they can be
evaluated while Emacs is started.  One method is to use the <C> M-:
</C> (On older versions of Emacs this is bound to <C> ESC ESC</C>)
function that evaluates Emacs Lisp expressions in the minibuffer.
Another method is to write the expressions in the <C> *scratch* </C> buffer,
place the point at the end of the line and press <C>C-j</C>.
</P>

<P>
Below is a series of example that we use to demonstrate simple Emacs
Lisp constructions.
</P>

<LIST>


  <ITEM> <EM>Example 1:</EM> <BR>

<P>
In this example we set the variable <C>foo</C> to the value 10 added
to the value of the variable <C>a</C>.  As we can see by this example,
Emacs Lisp use prefix form for all function calls, including simple
functions like <C>+</C>.
</P>

<CODE>
(setq foo (+ 10 a))
</CODE>


  <ITEM> <EM>Example 2:</EM> <BR>

<P>
In this example we first define a function <C>bar</C> that sums the value
of its four parameters.  Then we evaluated an expression that first
calls <C>bar</C> then calls the standard Emacs function <C>message</C>.
</P>

<CODE>
(defun bar (a b c d)
  (+ a b c d))

(message "The sum becomes %d" (bar 1 2 3 4))
</CODE>


  <ITEM> <EM>Example 3:</EM><BR>

<P>
Among the Emacs Lisp data types we have atoms.  However, in
the following expressions we assign the variable <C>foo</C> the value of
the variable <C>bar</C>.
</P>

<CODE>
(setq foo bar)
</CODE>

<P>
To assign the variable <C>foo</C> the atom <C>bar</C> we must quote
the atom with a <C>'</C>-character.  Note the syntax, we should precede the
expression (in this case <C>bar</C>) with the quote, not surround it.
</P>

<CODE>
(setq foo 'bar)
</CODE>

</LIST>

</SECTION>


<SECTION>
<TITLE>Hooks</TITLE>

<P>
A hook variable is a variable that contain a list of functions to
run.  In Emacs there is a large number of hook variables, each is
runed at a special situation.  By adding functions to hooks the user
make Emacs automatically perform anything (well, almost).
</P>

<P>
To add a function to a hook you must use the function <C>add-hook</C>.
To remove it use <C>remove-hook</C>.
</P>

<P>
See chapter "The Editing Mode" above for a list of hooks defined by
the Erlang editing mode.
</P>

<LIST>
  <ITEM> <EM> Example: </EM> <BR>

<P>
In this example we add <C>tempo-template-erlang-large-header</C> to
the hook <C>erlang-new-file-hook</C>.  The effect is that whenever a
new Erlang file is created a file header is immediately inserted.
</P>

<CODE>
  (add-hook 'erlang-new-file-hook 'tempo-template-erlang-large-header)
</CODE>

<ITEM> <EM> Example: </EM> <BR>

<P>
Here we define a new function that sets a few variables when it is
called.  We then add the function to the hook <C>erlang-mode-hook</C> that
gets called every time Erlang mode is activated.
</P>

<CODE>
(defun my-erlang-mode-hook ()
  (setq erlang-electric-commands t))

(add-hook 'erlang-mode-hook 'my-erlang-mode-hook)
</CODE>

</LIST>

</SECTION>

<SECTION>
<MARKER ID="key_bindings">
<TITLE>Custom Key Bindings</TITLE>

<P>
It is possible to bind keys to your favorite commands.  Emacs use a
number of key-maps: the global key-map defines the default value of
keys, local maps are used by the individual major modes, minor modes
can have their own key map etc.
</P>

<P>
The commands <C>global-set-key</C> and <C>local-set-key</C> defines
keys in the glo