[Erlang Systems]

2 The Erlang editing mode for Emacs

2.1 Introduction

If you want to get started immediately, the chapters "An Example for UNIX" and "An Example for Windows" gives you examples of the configurations you need to make to use the Erlang Editing mode for Emacs.

Emacs has been the text editor of choice for programmers in the UNIX community for many years. Thanks to a continuing development process Emacs is the most powerful editor available. Today Emacs run under most operating systems including MS-Windows, OS/2, Macintosh, and several dialects of UNIX.

Emacs has editing support for all major programming languages and quite a lot of minor and unknown languages are supported as well.

Emacs is designed to be extendible. In the unlikely event that you would miss a feature in Emacs you can add it yourself, or you might find it in the large number of add-on packages that people all over the world have written.

This book is the documentation to the Emacs package erlang.el. It provides support for the programming language Erlang. The package provides an editing mode with lots of bells and whistles, compilation support, and it makes it possible for the user to start Erlang shells that run inside Emacs.

Emacs is written by the Free Software Foundation and is part of the GNU project. Emacs, including the source code and documentation, is released under the GNU General Public License.

2.1.1 Overview of this Book

This book can be divided into the following sections:

The terminology used in this book is the terminology used in the documentation to Emacs. The chapter "Notation" contains a list of commonly used words and their meaning in the Emacs world.

The intended readers of this book are Emacs users. The book contains some examples on how to customize this package using the Emacs extension language Emacs Lisp. You can safely skip those sections.

2.2 Emacs

The first component needed to get this package up and running is, of course, an Emacs editor. You can use either the standard Emacs distribution from FSF or XEmacs, an alternative distribution. Both brands have their advantages and disadvantages.

Regardless of the brand, it is recommended to use a modern version. If an old version is used it is possible that some of the features provided by the editing mode can't be used.

The chapter "Emacs Distributions" below contain a short summary on the differences between the Emacs brands as well as instructions where to get the distributions and how to install them.

2.3 Installing the Erlang Support Packages

Once Emacs has been installed it must be informed about the presence of the Erlang support packages.

If you don't know if the packages as been installed open an Erlang source file. The mode line should contain the word "Erlang". You can check the version of the installed package by selecting the "version" entry in the Erlang menu in Emacs. Should no Erlang menu be present, or if the menu doesn't contain a "Version" item you are using an old version.

The packages can either be installed for all users by the system administrator, or each individual user can install it in their own Emacs setup. The chapter "Installation of the Erlang Editing Mode" contain a description on how to install the packages.

2.4 The Editing Mode

The Erlang editing for Emacs provides a number of features described in this and the following chapters. The editing mode can work with either Erlang source mode or Mnesia database rules. The Erlang editing mode for Emacs is in Emacs terminology a Major mode .

When Erlang mode is correctly installed it is automatically activated when a file ending in .erl or .hrl is opened in Emacs. It is possible to activate Erlang mode for other buffers as well.

The editing mode provides a menu containing a selection of commands structured into logical subgroups. The menu is designed to help new users get an overview of the features provided by the Erlang packages while still giving full power to more advanced users.

Erlang mode has got a local key map that contains keyboard bindings for a number of commands. In the chapter "Custom Key Bindings" below we will demonstrate how the users can bind their favorite commands to the local Erlang key map.

It is possible for the users to perform advanced customizations by adding their own functions to the "hook" variables provided by this package. This will be described in the "Customization" chapter below.

2.4.1 The Mode

2.4.2 The Version

2.4.3 Module Name Check

When a file is saved the name in the -module(). line is checked against the file name. Should they mismatch Emacs can change the module specifier so that it match the file name. By default, the user is asked before the change is performed.

2.4.4 Variables

There are several variables that control the behavior of the Erlang Editing mode.

2.5 Indentation

The "Oxford Advanced Learners Dictionary of Current English" says the following about the word "indent":

"start (a line of print or writing) farther from the margin than the others".

Possibly the most important feature of an editor designed for programmers is the ability to indent a line of code in accordance with the structure of the programming language.

The Erlang mode does, of course, provide this feature. The layout used is based on the common use of the language.

It is strongly recommend to use this feature and avoid to indent lines in a nonstandard way. Some motivations are:

2.5.1 The Layout

The basic layout is that the clause headers start in the first column, and the bodies of clauses and complex expressions (e.g. "case" and "if") are indented more that the surrounding code. For example:

remove_bugs([]) ->
    [];
remove_bugs([X | Xs])
    case X of
        bug ->
            test(Xs);
        _ ->
            [X | test(Xs)]
    end.

2.5.2 Indentation of comments

Lines containing comment are indented differently depending on the number of %-characters used:

Example:

%%%
%%% Function: remove_bugs
%%%

remove_bugs([]) ->
    [];
remove_bugs([X | Xs])
    case X of
        bug ->                                  % Oh no, a bug!
                                                % Remove it.
            test(Xs);
        %% This element is not a bug, let's keep it.
        _ ->
            [X | test(Xs)]
    end.

2.5.3 Indentation commands

The following command are directly available for indentation.

2.5.4 Customization

The most common customization of the indentation system is to bind the return key to newline-and-indent. Please see the chapter "Custom Key Bindings" below for an example.

There are several Emacs variables that control the indentation system.

2.6 General Commands

This chapter contains a group of commands that doesn't find into any other category. Unlike most other books we don't have a chapter named "Miscellaneous xxx" found at the end of most books. This chapter is placed near the beginning to reflect the importance and usefulness of the commands.

2.6.1 Filling comments

How many times have you edited a section of text in a comment only to wind up with a unevenly formatted paragraph? Or even worse, have you ever decided not to edit a comment just because the formatting would look bad?

When editing normal text in text mode you can let Emacs reformat the text by the fill-paragraph command. This command will not work for comments since it will treat the comment characters as words.

The Erlang editing mode provides a command that known about the Erlang comment structure and can be used to fill text paragraphs in comments.

Example:

For the sake of this example, let's assume that fill-column is set to column 30. Assume that we have an Erlang comment paragraph on the following form:

%% This is just a test to show
%% how the Erlang fill 
%% paragraph command works.

Assume that you would add the words "very simple" before the word "test":

%% This is just a very simple test to show
%% how the Erlang fill
%% paragraph command works.

Clearly, the text is badly formatted. Instead of formatting this paragraph line by line, let's try erlang-fill-paragraph by pressing M-q. The result is:

%% This is just a very simple
%% test to show how the Erlang
%% fill paragraph command
%% works.

As you can see the paragraph is now evenly formatted.

2.6.2 Creating Comments

In Erlang it is possible to write comments to the right of the code. The indentation system described in the chapter "Indentation" above is able to indent lines containing only comments, and gives support for end-of-the-line comments.

2.6.3 Comment Region

The standard command comment-region can be used to comment out all lines in a region. To uncomment the lines in a region precede this command with C-u.

2.7 Syntax Highlighting

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.

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. Haven't 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.

The syntax highlighting can be activated from the Erlang menu. There are four different alternatives:

The syntax highlighting is based on the standard Emacs package "font-lock". It is possible to use the font-lock commands and variables to enable syntax highlighting. The commands in question are:

The variable font-lock-maximum-decoration is used to specify the level of highlighting. If the variable is bound to an integer that level is used, if it is bound to t the highest possible level is used. (It is possible to set different levels for different editing modes, please see the font-lock documentation for more information.)

It is possible to change the color used. It is even possible to use bold, underlined, and italic fonts in combination with colors. However, the method to do this differ between Emacs and XEmacs, and between different versions of Emacs. For Emacs 19.34 the variable font-lock-face-attributes control the colors. For version 20 of Emacs and XEmacs the faces can be defined in the interactive custom system.

2.7.1 Customization

Font-lock mode is activated in different ways in different versions of Emacs. For modern versions of GNU Emacs place the following lines in your ~/.emacs file:

(setq font-lock-maximum-decoration t)
(global-font-lock-mode 1)

For modern versions of XEmacs the following code can be used:

(setq auto-font-lock-mode 1)

For older versions of Emacs and XEmacs font-lock mode must be activated individually for each buffer. The following will add a function to the Erlang mode hook that activates font-lock mode for all Erlang buffers.

(defun my-erlang-font-lock-hook ()
  (font-lock-mode 1))

(add-hook 'erlang-mode-hook 'my-erlang-font-lock-hook)

2.7.2 Known Problems

Emacs has one problem with the syntactic structure of Erlang, namely the $ character. The normal Erlang use of the $ character is to denote the ASCII value of a character, for example:

ascii_value_of_a() -> $a.

In order to get the font-lock mechanism to work for the next example, the $ character must be marked as an "escape" character that changes the ordinary Emacs interpretation of the following double-quote character.

ascii_value_of_quote() -> $".

The problem is that Emacs will also treat the $ character as an "escape" character at the end of strings and quoted atoms. Practically, this means that Emacs will not detect the end of the following string:

the_id() -> "$id: $".

Fortunately, there are ways around this. From Erlang's point of view the following two strings are equal: "test$" and "test\$". The \-character is also marked as an Emacs "escape" character, hence it will change the Emacs interpretation of the $-character.

This work-around can't always be used. For example, when the string is used by an external version control program. In this situation we can try to avoid placing the $-character at the end of the string, for example:

-vsn(" $Revision: 1.1 $ ").

Should this not be possible we can try to create an artificial end of the string by placing an extra quote sign in the file. We do this as a comment:

-vsn("$Revision: 1.1 $").    % "

The comment will be ignored by Erlang since it's a comment. From Emacs point of view the comment character is part of the string.

This problem is a generic problem for languages with similar syntax. For example, the major mode for Perl suffers from the same problem.

2.8 Electric Commands

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.

Since some people find electric commands annoying they can be deactivated, see section "Unplugging the Electric Commands" below.

2.8.1 The Commands

2.8.2 Undo

All electric command will set an undo marker after the initial character has been inserted but before the special action has been performed. By executing the undo command (C-x u) the effect of the special action will be undone while leaving the character. Execute undo a second time to remove the character itself.

2.8.3 Variables

The electric commands are controlled by a number of variables.

2.8.4 Unplugging the Electric Commands

To disable all electric commands set the variable erlang-electric-commands to the empty list. In short, place the following line in your ~/.emacs file:

(setq erlang-electric-commands '())

2.8.5 Customizing the Electric Commands

To activate all electric commands, including erlang-electric-newline, add the following line to your ~/.emacs file:

(setq erlang-electric-commands t)

2.9 Function and Clause Commands

The Erlang editing mode has a set of commands that are aware of the Erlang functions and function clauses. The commands can be used to move the point (cursor) to the end of, or to the beginning of Erlang functions, or to jump between functions. The region can be placed around a function. Function headers can be cloned (copied).

2.9.1 Movement Commands

There is a set of commands that can be used to move the point to the beginning or the end of an Erlang clause or function. The commands are also designed for movement between Erlang functions and clauses.

When one of the movement commands is executed and the point is already placed at the beginning or end of a function or clause, the point is moved to the previous/following function or clause.

When the point is above the first or below the last function in the buffer, and an erlang-beginning-of-, or erlang-end-of- command is issued, the point is moved to the beginning or to the end of the buffer, respectively.

2.9.1.1 Development Tips

The functions described above can be used both as user commands and called as functions in programs written in Emacs Lisp.

Example:

The sequence below will move the point to the beginning of the current function even if the point should already be positioned at the beginning of the function:

    (end-of-line)
    (erlang-beginning-of-function)

Example:

To repeat over all the function in a buffer the following code can be used. It will first move the point to the beginning of the buffer, then it will locate the first Erlang function. Should the buffer contain no functions at all the call to erlang-beginning-of-function will return nil and hence the loop will never be entered.

    (goto-char (point-min))
    (erlang-end-of-function 1)
    (let ((found-func (erlang-beginning-of-function 1)))
       (while found-func
         ;; Do something with this function.
         ;; Go to the beginning of the next function.
         (setq found-func (erlang-beginning-of-function -1))))

2.9.2 Region Commands

2.9.3 Function Header Commands

2.9.4 Limitations

Several clauses are considered to be part of the same Erlang function if they have the same name. It is possible that in the future the arity of the function also will be checked. To avoid to perform a full parse of the entire buffer the functions described in the chapter only look at lines where the function starts in the first column. This means that the commands does not work properly if the source code contain non-standardized indentation.

2.10 Skeletons

A skeleton is a piece of pre-written code that can be inserted into the buffer. Erlang mode comes with a set of predefined skeletons ranging from simple if expressions to stand-alone applications.

The skeletons can be accessed either from the Erlang menu of from commands named tempo-template-erlang-X.

The skeletons is defined using the standard Emacs package "tempo". It is possible to define new skeletons for your favorite erlang constructions.

2.10.1 Commands

2.10.2 Predefined Skeletons

The following skeletons will complete almost ready-to-run modules.

2.10.3 Defining New Skeletons

It is possible to define new Erlang skeletons. The skeletons are defined using the standard package "tempo". The skeleton is described using the following variables:

2.10.3.1 Examples

Below is two example on skeletons and one example on how to add an entry to the erlang-skel variable. Please see the Tempo reference manual for details about the format.

Example 1:

The "If" skeleton is defined by the following variable (slightly rearranged for pedagogical reasons):

(defvar erlang-skel-if
  '((erlang-skel-skip-blank)   ;;  1
    o                          ;;  2
    >                          ;;  3
    "if"                       ;;  4
    n>                         ;;  5
    p                          ;;  6
    " ->"                      ;;  7
    n>                         ;;  8
    p                          ;;  9
    "ok"                       ;; 10
    n>                         ;; 11
    "end"                      ;; 12
    p))                        ;; 13

Each line describes an action to perform:

Example 2:

This example contains very few entries. Basically, what it does is to include other skeletons in the correct place.

(defvar erlang-skel-small-header
  '(o                                         ;; 1
    (erlang-skel-include erlang-skel-module   ;; 2
                         erlang-skel-author)
    n                                         ;; 3
    (erlang-skel-include erlang-skel-compile  ;; 4
                         erlang-skel-export   ;; 5
                         erlang-skel-vc)))    ;; 6

The lines performs the following actions:

Example 3:

Here we assume that we have defined a new skeleton named erlang-skel-example. The best time to add this skeleton to the variable erlang-skel is when Erlang mode has been loaded but before it has been activated. We define a function that adds two entries to erlang-skel, the first is () that represent a divisor in the menu, the second is the entry for the Example skeleton. We then add the function to the erlang-load-hook, a hook that is called when Erlang mode is loaded into Emacs.

(defun my-erlang-skel-hook ()
  (setq erlang-skel
        (append erlang-skel
                '(()
                  ("Example" "example" erlang-skel-example)))))

(add-hook 'erlang-load-hook 'my-erlang-skel-hook)

2.11 Manual Pages

The UNIX version of Erlang tools contain a set of manual pages that can be accessed by the standard UNIX command "man". The Erlang mode place a list of all available manual pages in the "Erlang" menu.

Unfortunately this feature is not available in the Windows version of the Erlang editing mode since the Erlang tools are not delivered with the manual pages.

2.11.1 The Menu

In the Erlang menu a list of all Erlang manual pages can be found. The menu item "Man Pages". The sub-menu to this menu item contains a list of categories, normally "Man - Commands" and "Man - Modules". Under these is a menu containing the names of the man pages. Should this menu be to large it is split alphabetically into a number of sub-menus.

The menu item "Man - Function" is capable of finding the man page of a named Erlang function. This commands understands the module:function notation. This command defaults to the name under the point. Should the name not contain a module name the list of imported modules is searched.

2.11.2 Customization

The following variables control the manual page feature.

2.12 Tags

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 it's 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.

2.12.1 Creating a TAGS file

In order to use the Tags system a file named TAGS must be created. The file can be seen as a database over all functions, records, and macros in all files in the project. The TAGS file can be created using to different methods for Erlang. The first is the standard Emacs utility "etags", the second is by using the Erlang module tags.

2.12.2 The etags utility

The etags 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.

The etags 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 etags --help 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.

As seen in the help text -- unless you haven't upgraded your Emacs yet (well, what are you waiting around here for? Off you go and upgrade!) -- etags associate the file extensions .erl and .hrl with Erlang.

Basically, the etags utility is runed using the following form:

    etags file1.erl file2.erl

This will create a file named TAGS in the current directory.

The etags utility can also read a list of files from it's 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 find can be used to generate the list of files, e.g:

    file . -name "*.[he]rl" -print | etags -

The above line will create a TAGS file covering all the Erlang source files in the current directory, and in the subdirectories below.

Please see the GNU Emacs Manual and the etags man page for more info.

The code implementing the Erlang support for the etags program has been donated to the Free Software Foundation by the company Anders Lindgren Development.

2.12.3 The tags Erlang module

One of the tools in the Erlang distribution is a module named tags. This tool can create a TAGS file from Erlang source files.

The following are examples of useful functions in this module. Please see the reference manual on tags for details.

2.12.4 Additional Erlang support

The standard Tags system has only support for simple names. The naming convention module:function used by Erlang is not supported.

The Erlang mode supplies an alternative set of Tags functions that is aware of the format module:function. When selecting a the default search string for the commands the name under the point is first selected. Should the name not contain a module name the -import list at the beginning of the buffer is scanned.

2.12.4.1 Limitations

Currently, the additional Erlang module name support is not compatible with the etags.el package that is part of XEmacs.

2.12.5 Useful Tags Commands

2.13 IMenu

IMenu is a standard package of GNU Emacs. With IMenu it is possible to get a menu in the menu bar containing all the functions in the buffer. Erlang mode provides support for Erlang source files.

2.13.1 Starting IMenu

2.13.2 Customization

See chapter "Customization" below for a general description on how to customize the Erlang mode.

To automatically create the IMenu menu for all Erlang buffers, place the lines below into the appropriate init file (e.g. ~/.emacs). The function my-erlang-imenu-hook will be called each time an Erlang source file is read. It will call the imenu-add-to-menubar function. The menu will be named "Functions".

(add-hook 'erlang-mode-hook 'my-erlang-imenu-hook)

(defun my-erlang-imenu-hook ()
  (if (and window-system (fboundp 'imenu-add-to-menubar))
      (imenu-add-to-menubar "Functions")))

2.14 Running Erlang from Emacs

One of the strengths of Emacs is its ability to start slave processes. Since Emacs is extendible it is possible let Emacs be a part of a large application. For example, Emacs could be used as the user interface for Erlang applications.

The Erlang editing mode provides two simple, yet very useful, applications. The first is to start an Erlang shell and use an Emacs buffer for input and output. The second is a compile commands that makes it possible to compile Erlang modules and to locate the lines containing the compilation errors.

The actual communication between Emacs and Erlang can be performed by different low-level techniques. The Erlang editing mode provides a technique called "inferior" processes. The add on package Erl'em supplies a technically much more advanced communication technique known as an Erl'em link. All the commands that are provided by the editing mode can use either technique. However, more advanced packages will probably need features only provided by the Erl'em package.

2.14.1 Inferior Erlang

The editing mode is capable of starting a so called "inferior" Erlang process. This is a normal subprocess that use one Emacs buffer for input and output. The effect is that a command line shell, or an Erlang shell, can be displayed inside Emacs.

The big drawback with an inferior process is that the communication between Emacs and the process is limited to commands issued at the command line. Since this is the interface that is used by the user it is difficult, to say the least, to write an Emacs application that communicate with the inferior process. For example, the erlang-compile command described in the section "Compilation" below really stretch the capabilities of the inferior Erlang process. In fact, should the user have issued a command that would take some time to complete it is impossible for Emacs to perform the erlang-compile command.

2.14.2 The Erl'em Link

The Erl'em package established a low-level communication channel between Emacs and an Erlang node. This communication channel can be used by Emacs to issue several independent Erlang commands, to start Erlang processes and to open several Erlang IO streams. It is also possible for Erlang to call Emacs functions.

In short the Erl'em package is designed to be the base of complex application that is partially implemented in Emacs and partially in Erlang.

It is the hope of the author that the Erl'em link in the future will be used as the base for porting the user interface of the Erlang debugger to Emacs. If this could be possible, Emacs could be used as an Integrated Debugger Environment (IDE) for Erlang.

The structure of the Erl'em link and its programming interface is described in the text "Erl'em Developers Manual".

2.15 Erlang Shell

It is possible to start an Erlang shell inside Emacs. The shell will use an Emacs buffer for input and output. Normal Emacs commands can be used to edit the command line and to recall lines from the command line history.

The output will never be erased from the buffer so you will never risk letting important output fall over the top edge of the display.

As discussed in the previous chapter there are two low-level 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.

2.15.1 The shell

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

2.15.2 Command line history

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:

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.

2.15.3 The Erlang Shell Mode

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

2.15.4 Variables

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

2.15.5 Inferior Erlang Variables

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.

2.16 Compilation

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.

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.

2.16.1 Commands

2.16.2 Variables

2.17 Customization

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.

Normally, Emacs is customized through the user and system init files, ~/.emacs and site-start.el, 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.

2.17.1 Emacs Lisp

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

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

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

2.17.2 Hooks

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

To add a function to a hook you must use the function add-hook. To remove it use remove-hook.

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

2.17.3 Custom Key Bindings

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.

The commands global-set-key and local-set-key defines keys in the global and in the current local key-map, respectively.

If we would like to redefine a key in the Erlang editing mode we can do that by activating Erlang mode and call local-set-key. To automate this we must define a function that calls local-set-key. This function can then be added to the Erlang mode hook so that the correct local key map is active when the key is defined.

Example:

Here we bind C-c C-c to the command erlang-compile, the function key f1 to erlang-shell, and M-f1 to erlang-shell-display . The calls to local-set-key will not be performed when the init file is loaded, they will be called first when the functions in the hook erlang-mode-hook is called, i.e. when Erlang mode is started.

(defun my-erlang-keymap-hook ()
  (local-set-key (read-kbd-macro "C-c C-c") 'erlang-compile)
  (local-set-key (read-kbd-macro "<f1>")    'erlang-shell)
  (local-set-key (read-kbd-macro "M-<f1>")  'erlang-shell-display))
(add-hook 'erlang-mode-hook 'my-erlang-keymap-hook)

The function read-kbd-macro used in the above example converts a string of readable keystrokes into Emacs internal representation.

Example:

In Erlang mode the tags commands understand the Erlang module naming convention. However, the normal tags commands does not. This line will bind M-. in the global map to erlang-find-tag.

(global-set-key (read-kbd-macro "M-." 'erlang-find-tag))

2.18 Emacs Distributions

Today there are two major Emacs development streams. The first is GNU Emacs from Free Software Foundation and the second is XEmacs. Both have advantages and disadvantages, you have to decide for yourself which Emacs you prefer.

2.18.1 GNU Emacs

This is the standard distribution from The Free Software Foundation, an organization lead by the original author of Emacs, Richard M. Stallman.

The source code for the latest version of Emacs can be fetched from http://www.gnu.org. A binary distribution for Window NT and 95 can be found at http://www.cs.washington.edu/homes/voelker/ntemacs.html.

2.18.2 XEmacs

This is an alternative version of Emacs. Historically XEmacs is based on Lucid Emacs that in turn was based on an early version of Emacs 19. The big advantage of XEmacs is that it can handle graphics much better. One difference is a list of icons that contains a number of commonly used commands. Another is the ability to display graphical images in the buffer.

The major drawback is that when a new feature turns up in GNU Emacs, it will often take quite a long time before it will be incorporated into XEmacs.

The latest distribution can be fetched from http://www.xemacs.org.

2.18.3 Installing Emacs

The source distributions usually comes in a tared and gzipped format. Unpack this with the following command:

    tar zxvf <file>.tar.gz

If your tar command don't know how to handle the "z" (unpack) option you can unpack it separately:

    gunzip <file>.tar.gz
    tar xvf <file>.tar

The program gunzip is part of the gzip package that can be found on the http://www.gnu.org site.

Next, read the file named INSTALL. The build process is normally performed in three steps: in the first the build system performs a number of tests on your system, the next step is to actually build the Emacs executable, finally Emacs is installed.

2.19 Installation of the Erlang Editing Mode

In the OTP installation, the Erlang editing mode is already installed. All that is needed is that the system administrator or the individual user configures their Emacs Init files to use it.

If we assume that OTP has been installed in OTP_ROOT, the editing mode can be found in OTP_ROOT/misc/emacs.

The erlang.el file found in the installation directory is already compiled. If it needs to be recompiled, the following command line should create a new erlang.elc file:

    emacs -batch -q -no-site-file -f batch-byte-compile erlang.el

2.19.1 Editing the right Emacs Init file

System administrators edit site-start.el, individuals edit their .emacs files.

On UNIX systems, individuals should edit/create the file .emacs in their home directories.

On Windows NT/95, individuals should also edit/create their .emacs file, but the location of the file depends on the configuration of the system.

2.19.2 Extending the load path

The directory with the editing mode, OTP_ROOT/misc/emacs, must be in the load path for Emacs.

Add the following line to the selected initialization file (replace OTP_ROOT with the name of the installation directory for OTP, keep the quote characters):

     (setq load-path (cons "OTP_ROOT/misc/emacs" load-path))

Note: When running under Windows, use / or \\ as separator in pathnames in the Emacs configuration files. Using a single \ in strings does not work, as it is interpreted by Emacs as an escape character.

2.19.3 Specifying the OTP installation directory

Some functions in the Erlang editing mode require that the OTP installation directory is known. The following is an example where we assume that they are installed in the directory OTP_ROOT, change this to reflect the location on your system.

        (setq erlang-root-dir "OTP_ROOT")

2.19.4 Extending the execution path

To use inferior Erlang Shells, you need to do the following configuration. If your PATH environment variable already includes the location of the erl or erl.exe executable this configuration is not necessary.

You can either extend the PATH environment variable with the location of the erl/erl.exe executable. Please refer to instructions for setting environment variables on your particular platform for details.

You can also extend the execution path for Emacs as described below. If the executable is located in OTP_ROOT/bin then you add the following line to you Emacs Init file:

   (setq exec-path (cons "OTP_ROOT/bin" exec-path))

2.19.5 Final setup

Finally, add the following line to the init file:

   (require 'erlang-start)

This will inform Emacs that the Erlang editing mode is available. It will associate the file extensions .erl and .hrl with Erlang mode. Also it will make sure that files with the extension .jam will be ignored when using file name completion.

2.19.6 An Example for UNIX

Below is a complete example of what should be added to a user's .emacs provided that OTP is installed in the directory /usr/local/otp:

(setq load-path (cons  "/usr/local/otp/misc/emacs"
                       load-path))
(setq erlang-root-dir "/usr/local/otp")
(setq exec-path (cons "/usr/local/otp/bin" exec-path))
(require 'erlang-start)

Any additional user configurations can be added after this. See for instance section "Customization" for some useful customizations.

2.19.7 An Example for Windows

Below is a complete example of what should be added to a user's .emacs provided that OTP is installed in the directory C:\Program Files\erl-4.7:

(setq load-path (cons  "C:/Program Files/erl-4.7/misc/emacs"
                       load-path))
(setq erlang-root-dir "C:/Program Files/erl-4.7")
(setq exec-path (cons "C:/Program Files/erl-4.7/bin" exec-path))
(require 'erlang-start)

Any additional user configurations can be added after this. See for instance section "Customization" for some useful customizations.

2.19.8 Check the Installation

Restart the Emacs and load or create an Erlang file (with the .erl extension). If the installation was performed correctly the mode line should contain the word "Erlang". Select the "Version" menu item in the "Erlang" menu, check that the version number matches the version in found in the files in OTP_ROOT/misc/emacs.

2.20 Notation

In this book we use the same terminology used in the Emacs documentation. This chapter contain a short glossary of words and their meaning in the Emacs world.

2.21 Keys

All commands in Emacs have names. A named command can be executed by pressing M-x, typing the name of the command, and hitting RET .

2.22 Further reading

In this chapter I present some references to material on Emacs. They are divided into the two categories "Usage" and "Development". The first is for normal Emacs users who would like to know how to get more power out of their editor. The second is for people who would like to develop their own applications in Emacs Lisp.

Personally, I would recommend the series of books from the Free Software Foundation, they are written by the people that wrote Emacs and they form a coherent series useful for everyone from beginners to experienced Emacs Lisp developers.

2.22.1 Usage

2.22.2 Development

2.23 Reporting Bugs

Please send bug reports to the following email address:

     support@erlang.ericsson.se

Please state as accurate as possible:

Should the Emacs generate an error, please set the emacs variable debug-on-error to t. Repeat the error and enclose the debug information in your bug-report.

To set the variable you can use the following command:

    M-x set-variable RET debug-on-error RET t RET

Copyright © 1991-98 Ericsson Telecom AB