path: root/lib/tools/doc/src/erlang_mode_chapter.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2003</year><year>2016</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>The Erlang mode for Emacs</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>erlang_mode_chapter.xml</file>
  </header>

  <section>
    <title>Purpose</title>
    <p>The purpose of this user guide is to introduce you to the
      Erlang mode for Emacs and gives some relevant background
      information of the functions and features. See also <seealso marker="erlang.el">Erlang mode reference manual</seealso> The
      purpose of the Erlang mode itself is to facilitate the developing
      process for the Erlang programmer.</p>
  </section>

  <section>
    <title>Pre-requisites</title>
    <p>Basic knowledge of Emacs and Erlang/OTP. </p>
  </section>

  <section>
    <title>Elisp</title>
    <p>There are two Elisp modules included in this tool package
      for Emacs. There is erlang.el that defines the actual erlang mode
      and there is erlang-start.el that makes some nice initializations.</p>
  </section>

  <section>
    <title>Setup on UNIX</title>
    <p>To set up the Erlang Emacs mode on a UNIX systems, edit/create
      the file <c>.emacs</c> in the your home directory.</p>
    <p>Below is a complete example of what should be added to a user's
      <c>.emacs</c> provided that OTP is installed in the directory
      <c>/usr/local/otp </c>: </p>
    <code type="none"><![CDATA[
      (setq load-path (cons  "/usr/local/otp/lib/tools-<ToolsVer>/emacs"
      load-path))
      (setq erlang-root-dir "/usr/local/otp")
      (setq exec-path (cons "/usr/local/otp/bin" exec-path))
      (require 'erlang-start)
    ]]></code>
  </section>

  <section>
    <title>Setup on Windows </title>
    <p>To set up the Erlang Emacs mode on a Windows systems,
      edit/create the file <c>.emacs</c>, the location of the file
      depends on the configuration of the system. If the <em>HOME</em>
      environment variable is set, Emacs will look for the
      <c>.emacs</c> file in the directory indicated by the
      <em>HOME</em> variable. If <em>HOME</em> is not set, Emacs
      will look for the <c>.emacs</c> file in <c>C:\ </c>.</p>
    <p>Below is a complete example of what should be added to a user's
      <c>.emacs</c> provided that OTP is installed in the directory
      <c><![CDATA[C:\Program Files\erl<Ver>]]></c>: </p>
    <code type="none"><![CDATA[
      (setq load-path (cons  "C:/Program Files/erl<Ver>/lib/tools-<ToolsVer>/emacs"
      load-path))
      (setq erlang-root-dir "C:/Program Files/erl<Ver>")
      (setq exec-path (cons "C:/Program Files/erl<Ver>/bin" exec-path))
      (require 'erlang-start)
    ]]></code>
    <note>
      <p>In .emacs, the slash character "/" can be used as path
        separator. But if you decide to use the backslash character "\",
        please not that you must use double backslashes, since they are
        treated as escape characters by Emacs.</p>
    </note>
  </section>

  <section>
    <title>Indentation</title>
    <p>The "Oxford Advanced Learners Dictionary of Current English" says the
      following about the word "indent":</p>
    <quote>
      <p>"start (a line of print or writing) farther from
        the margin than the others".</p>
    </quote>
    <p>The Erlang mode does, of course, provide this feature. The layout
      used is based on the common use of the language.</p>
    <p>It is strongly recommend to use this feature and avoid to indent lines
      in a nonstandard way.  Some motivations are:</p>
    <list type="bulleted">
      <item>Code using the same layout is easy to read and maintain. </item>
      <item>Since several features of Erlang mode is based on the
       standard layout they might not work correctly if a nonstandard layout
       is used. </item>
    </list>
    <p>The indentation features can be used to reindent large sections
      of a file.  If some lines use nonstandard indentation they will
      be reindented.</p>
  </section>

  <section>
    <title>Editing</title>
    <list type="bulleted">
      <item><em><c>M-x erlang-mode RET</c></em> - This command activates
       the Erlang major mode for the current buffer.  When this
       mode is active the mode line contain the word "Erlang".</item>
    </list>
    <p>When the Erlang mode is correctly installed, it is
      automatically activated when a file ending in <c>.erl</c> or
      <c>.hrl</c> is opened in Emacs.</p>
    <p>When a file is saved the name in the <c>-module().</c> line is
      checked against the file name. Should they mismatch Emacs can
      change the module specifier so that it matches the file name.
      By default, the user is asked before the change is performed.</p>
    <p>An "electric" command is a character that in addition to just
      inserting the character performs some type of action.  For
      example the ";" character is typed in a situation where is ends
      a function clause a new function header is generated. The electric
      commands are as follows: </p>
    <list type="bulleted">
      <item><em><c>erlang-electric-comma</c></em> - Insert a comma
       character and possibly a new indented line. </item>
      <item><em><c>erlang-electric-semicolon</c></em> - Insert a
       semicolon character and possibly a prototype for the next line.</item>
      <item><em><c>erlang-electric-gt</c></em> - "Insert a '>'-sign
       and possible a new indented line.</item>
    </list>
    <p>To disable all electric commands set the variable
      <c>erlang-electric-commands</c> to the empty list.  In short,
      place the following line in your <c>.emacs</c>-file:</p>
    <code type="none">
      (setq erlang-electric-commands '())</code>
  </section>

  <section>
    <title>Syntax highlighting</title>
    <p>It is possible for Emacs to use colors when displaying a buffer. By
      "syntax highlighting", we mean that syntactic components, for example
      keywords and function names, will be colored.</p>
    <p>The basic idea of syntax highlighting is to make the structure of a
      program clearer. For example, the highlighting will make it easier to
      spot simple bugs.  Have not you ever written a variable in lower-case
      only?  With syntax highlighting a variable will colored while atoms
      will be shown with the normal text color.</p>
  </section>

  <section>
    <marker id="tags"></marker>
    <title>Tags</title>
    <p>Tags is a standard Emacs package used to record information
      about source files in large development projects. In addition to
      listing the files of a project, a tags file normally contains
      information about all functions and variables that are defined.
      By far, the most useful command of the tags system is its ability
      to find the definition of functions in any file in the project.
      However the Tags system is not limited to this feature, for
      example, it is possible to do a text search in all files in a
      project, or to perform a project-wide search and replace.</p>
    <p>In order to use the Tags system a file named <c>TAGS</c> must be
      created.  The file can be seen as a database over all functions,
      records, and macros in all files in the project.  The
      <c>TAGS</c> file can be created using two different methods for
      Erlang.  The first is the standard Emacs utility "etags", the
      second is by using the Erlang module <c>tags</c>.</p>
  </section>

  <section>
    <title>Etags</title>
    <p><c>etags</c> is a program that is part of the Emacs
      distribution.  It is normally executed from a command line, like
      a unix shell or a DOS box.</p>
    <p>The <c>etags</c> program of fairly modern versions of Emacs and XEmacs
      has native support for Erlang.  To check if your version does include
      this support, issue the command <c>etags --help</c> at a the command
      line prompt.  At the end of the help text there is a list of supported
      languages.  Unless Erlang is a member of this list I suggest that you
      should upgrade to a newer version of Emacs.</p>
    <p>As seen in the help text -- unless you have not upgraded your
      Emacs yet (well, what are you waiting around here for?  Off you go and
      upgrade!)  -- <c>etags</c> associate the file extensions <c>.erl</c>
      and <c>.hrl</c> with Erlang.</p>
    <p>Basically, the <c>etags</c> utility is ran using the following form:</p>
    <code type="none">
      etags file1.erl file2.erl</code>
    <p>This will create a file named <c>TAGS</c> in the current directory.</p>
    <p>The <c>etags</c> utility can also read a list of files from its
      standard input by supplying a single dash in place of the file
      names.  This feature is useful when a project consists of a
      large number of files.  The standard UNIX command <c>find</c>
      can be used to generate the list of files, e.g:</p>
    <code type="none">
      find . -name "*.[he]rl" -print | etags -</code>
    <p>The above line will create a <c>TAGS</c> file covering all the
      Erlang source files in the current directory, and in the
      subdirectories below.</p>
    <p>Please see the GNU Emacs Manual and the etags man page for more
      info.</p>
  </section>

  <section>
    <title>Shell</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 type="bulleted">
      <item><em><c>C-up </c></em>  or <em><c>M-p </c></em>
       (<c>comint-previous-input</c>) -
       Move to the previous line in the input history.</item>
      <item><em><c>C-down </c></em> or <em><c>M-n </c></em>
       (<c>comint-next-input</c>) - Move to the next line in the
       input history.</item>
    </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>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>
</chapter>