2. MMM Mode Basics

This chapter explains the most important parts of how to use MMM Mode.

2.1 The MMM Minor Mode

An Emacs minor mode is an optional feature which can be turned on or off in a given buffer, independently of the major mode. See section `Minor Modes' in The Emacs Manual. MMM Mode is implemented as a minor mode which manages the submode regions. This minor mode must be turned on in a buffer for submode regions to be effective. When activated, the MMM Minor mode is denoted by `MMM' in the mode line (see section 3.3 Customizing the Mode Line Display).

2.1.1 Enabling MMM Mode

If mmm-global-mode is non-nil (see section 2.7 MMM Global Mode), then the MMM minor mode will be turned on automatically whenever a file with associated submode classes is opened (see section 2.3 How MMM Mode selects submode classes). It is also turned on by interactive mmm-ification (see section 2.6 Interactive MMM-ification Functions), although the interactive commands do not have key bindings when it is not on and must be invoked via M-x. You can also turn it on (or off) manually with M-x mmm-mode, in which case it applies all submode classes associated with the buffer. Turning MMM Mode off automatically removes all submode regions from the buffer.

Command: mmm-mode arg

Toggle the state of MMM Mode in the current buffer. If arg is supplied, turn MMM Mode on if and only if arg is positive.

Function: mmm-mode-on

Turn MMM Mode on unconditionally in the current buffer.

Function: mmm-mode-off

Turn MMM Mode off unconditionally in the current buffer.

Variable: mmm-mode

This variable represents whether MMM Mode is on in the current buffer. Do not set this variable directly; use one of the above functions.

2.1.2 Key Bindings in MMM Mode

When MMM Mode is on, it defines a number of key bindings. By default, these are bound after the prefix sequence C-c %. Minor mode keymaps are supposed to use C-c punctuation sequences, and I find this one to be a good mnemonic because `%' is used by Mason to denote special tags. This prefix key can be customized; 3.4 Customizing the MMM Mode Key Bindings.

There are two types of key bindings in MMM Mode: commands and insertions. Command bindings run MMM Mode interactive functions to do things like re-parse the buffer or end the current submode region, and are defined statically as normal Emacs key-bindings. Insertion bindings insert submode region skeletons with delimiters into the buffer, and are defined dynamically, according to which submode classes (see section 2.2 Understanding Submode Classes) are in effect, via a keymap default binding.

To distinguish between the two, MMM Mode uses distinct modifier keys for each. By default, command bindings use the control key (e.g. C-c % C-b re-parses the buffer), and insertion bindings do not (e.g. C-c % p, when the Mason class is in effect, inserts a `<%perl>...</%perl>' region). This makes the command bindings different from in previous versions, however, so the variable mmm-use-old-bindings is provided. If this variable is set to `t' before MMM Mode is loaded, the bindings will be reversed: insertion bindings will use the control key and command bindings will not.

Normally, Emacs gives help on a prefix command if you type C-h after that command (e.g. C-x C-h displays all key bindings starting with C-x). Because of how insertion bindings are implemented dynamically with a default binding, they do not show up when you hit C-c % C-h. For this reason, MMM Mode defines the command C-c % h which displays a list of all currently valid insertion key sequences. If you use the defaults for command and insertion bindings, the C-h and h should be mnemonic.

In the rest of this manual, I will assume you are using the defaults for the mode prefix (C-c %) and the command and insertion modifiers. You can customize them, however; 3.4 Customizing the MMM Mode Key Bindings.

2.2 Understanding Submode Classes

A submode class represents a "type" of submode region. It specifies how to find the regions, what their delimiters look like, what submode they should be, how to insert them, and how they behave in other ways. It is represented by a symbol, such as mason or eval-elisp.

For example, in the Mason set of classes, there is one class representing all `<%...%>' inline Perl regions, and one representing regions such as `<%perl>...</%perl>', `<%init>...</%init>', and so on. These are different to Mason, but to Emacs they are all just Perl sections, so they are covered by the same submode class.

But it would be tedious if whenever we wanted to use the Mason classes, we had to specify both of these. (Actually, this is a simplification: there are some half a dozen Mason submode classes.) So submode classes can also "group" others together, and we can refer to the mason class and mean all of them.

The way a submode class is used is to apply it to a buffer. This scans the buffer for regions which should be submode regions according to that class, and also remembers the class for later, so that new submode regions can be inserted and scanned for later.

2.3 How MMM Mode selects submode classes

Submode classes that apply to a buffer come from three sources: mode/extension-associated classes, file-local classes, and interactive MMM-ification (see section 2.6 Interactive MMM-ification Functions). Whenever MMM Mode is turned on in a buffer (see section 2.1 The MMM Minor Mode, and 2.7 MMM Global Mode), it inspects the value of two variables to determine which classes to automatically apply to the buffer. This covers the first two sources; the latter is covered in a later chapter.

2.3.1 File-Local Submode Classes

Variable: mmm-classes

This variable is always buffer-local when set. Its value should be either a single symbol or a list of symbols. Each symbol represents a submode class that is applied to the buffer.

mmm-classes is usually set in a file local variables list. See section `File Variables' in The Emacs Manual. The easiest way to do this is for the first line of the file to contain the string `-*- mmm-classes: classes -*-', where classes is the desired value of mmm-classes for the file in question. It can also be done with a local variables list at the end of the file.

2.3.2 Submode Classes Associated with Modes and Extensions

User Option: mmm-mode-ext-classes-alist

This global variable associates certain submode classes with major modes and/or file extensions. Its value is a list of elements of the form (mode ext class). Any buffer whose major mode is mode (a symbol) and whose file name matches ext (a regular expression) will automatically have the submode class class applied to it.

If mode is nil, then only ext is considered to determine if a buffer fits the criteria, and vice versa. Thus if both mode and ext are nil, then class is applied to all buffers in which MMM Mode is on. Note that ext can be any regular expression, although its name indicates that it most often refers to the file extension.

If class is the symbol t, then no submode class is actually applied for this association. However, if mmm-global-mode is non-nil and non-t, MMM Mode will be turned on in matching buffers even if there are no actual submode classes being applied. See section 2.7 MMM Global Mode.

Function: mmm-add-mode-ext-class mode ext class

This function adds an element to mmm-mode-ext-classes-alist, associating the submode class class with the major mode mode and extension ext.

Older versions of MMM Mode required this function to be used to control the value of mmm-mode-ext-classes-alist, rather than setting it directly. In this version it is provided purely for convenience and backward compatibility.

2.3.3 Globally Applied Classes and the Universal Class

In addition to file-local and mode-ext-associated submode classes, MMM Mode also allows you to specify that certain submode classes apply to all buffers in which MMM Mode is enabled.

User Option: mmm-global-classes

This variable's value should be a list of submode classes that apply to all buffers with MMM Mode on. It can be overriden in a file local variables list, such as to disable global class for a specific file. Its default value is (universal).

The default global class is the "universal class", which is defined in the file `mmm-univ.el' (loaded automatically), and allows the author of text to specify that a certain section of it be in a specific major mode. Thus, for example, when writing an email message that includes sample code, the author can allow readers of the message (who use emacs and MMM) to view the code in the appropriate major mode. The syntax used is `{%mode%} ... {%/mode%}', where mode should be the name of the major mode, with or without the customary `-mode' suffix: for example, both `cperl' and `cperl-mode' are acceptable.

The universal class also defines an insertion key, `/', which prompts for the submode to use. See section 2.4 Inserting new submode regions. The universal class is most useful when mmm-global-mode is set to t; 2.7 MMM Global Mode.

2.4 Inserting new submode regions

So much for noticing submode regions already present when you open a file. When editing a file with MMM Mode on, you will often want to add a new submode region. MMM Mode provides several facilities to help you. The simplest is to just hit a few keys and have the region and its delimiters inserted for you.

Each submode class can define an association of keystrokes with "skeletons" to insert a submode region. If there are several submode classes enabled in a buffer, it is conceivable that the keys they use for insertion might conflict, but unlikely as most buffers will not use more than one or two submode classes groups.

As an example of how insertion works, consider the Mason classes. In a buffer with MMM Mode enabled and Mason associated, the key sequence C-c % p inserts the following perl section (the semicolon is to prevent CPerl Mode from getting confused---see section 4.1 Mason: Perl in HTML):

<%perl>-<-;
-!-
->-</%perl>

In this schematic representation, the string `-!-' represents the position of point (the cursor), `-<-' represents the beginning of the submode region, and `->-' its end.

All insertion keys come after the MMM Mode prefix keys (by default C-c %; see section 3.4 Customizing the MMM Mode Key Bindings) and are by default single characters such as p, %, and i. To avoid confusion, all the MMM Mode commands are bound by default to control characters (after the same prefix keys), such as C-b, C-% and C-r. This is a change from earlier versions of MMM Mode, and can be customized; see 3.4 Customizing the MMM Mode Key Bindings.

To find out what insertion keys are available, consult the documentation for the submode class you are using. If it is one of the classes supplied with MMM Mode, you can find it in this Info file.

Because insertion keys are implemented with a "default binding" for flexibility, they do not show up in the output of C-h m and cannot be found with C-h k. For this reason, MMM Mode supplies the command C-c % h (mmm-insertion-help to view the available insertion keys.

2.5 Re-Parsing Submode Regions

Describe mmm-parse-buffer, mmm-parse-region, mmm-parse-block, and mmm-clear-current-region.

2.6 Interactive MMM-ification Functions

There are several commands you can use to create submode regions interactively, rather than by applying a submode class to a buffer. These commands (in particular, mmm-ify-region), can be useful when editing a file or email message containing a snippet of code in some other language. Also see 2.3.3 Globally Applied Classes and the Universal Class, for an alternate approach to the same problem.

C-c % C-r

Creates a submode region between point and mark. Prompts for the submode to use, which must be a valid Emacs major mode name, such as emacs-lisp-mode or cperl-mode. Adds markers to the interactive history. (mmm-ify-region)

C-c % C-c

Applies an already-defined submode class to the buffer, which it prompts for. Adds this class to the interactive history. (mmm-ify-by-class)

C-c % C-x

Scans the buffer for submode regions (prompts for the submode) using front and back regular expressions that it also prompts for. Briefly, it starts at the beginning of the buffer and searches for the front regexp. If it finds a match, it searches for the back regexp. If it finds a match for that as well, it makes a submode region between the two matches and continues searching until no more matches are found. Adds the regexps to the interactive history. (mmm-ify-by-regexp)

These commands are also useful when designing a new submode class (see section 2.2 Understanding Submode Classes). Working with the regexps interactively can make it easier to debug and tune the class before starting to use it on automatic. All these commands also add to value of the following variable.

Variable: mmm-interactive-history

Stores a history of all interactive mmm-ification that has been performed in the current buffer. This way, for example, the re-parsing functions (see section 2.5 Re-Parsing Submode Regions) will respect interactively added regions, and the insertion keys for classes that were added interactively are available.

If for any reason you want to "wipe the slate clean", this command should help you. By default, it has no key binding, so you must invoke it with M-x mmm-clear-history RET.

Command: mmm-clear-history

Clears all history of interactive mmm-ification in the current buffer. This command does not affect existing submode regions; to remove them, you may want to re-parse the buffer with C-c % C-b (mmm-parse-buffer).

2.7 MMM Global Mode

When a file has associated submode classes (see section 2.3 How MMM Mode selects submode classes), you may want MMM Mode to turn itself on and parse that file for submode regions automatically whenever it is opened in an Emacs buffer. The value of the following variable controls when MMM Mode turns itself on automatically.

User Option: mmm-global-mode

Do not be misled by the fact that this variable's name ends in `-mode': it is not a simple on/off switch. There are three possible (meanings of) values for it: t, nil, and anything else.

When this variable is nil, MMM Mode is never enabled automatically. If it is enabled manually, such as by typing M-x mmm-mode, any submode classes associated with the buffer will still be used, however.

When this variable is t, MMM Mode is enabled automatically in all buffers, including those not visiting files, except those whose major mode is an element of mmm-never-modes. The default value of this variable contains modes such as help-mode and dired-mode in which most users would never want MMM Mode, and in which MMM might cause problems.

When this variable is neither nil nor t, MMM Mode is enabled automatically in all buffers that would have associated submode classes; i.e. only if there would be something for it to do. The value of mmm-never-modes is still respected, however. Note that this can include buffers not visiting files, if that buffer's major mode is present in mmm-mode-ext-classes-alist with a nil value for ext (see section 2.3.2 Submode Classes Associated with Modes and Extensions). Submode class values of t in mmm-mode-ext-classes-alist cause MMM Mode to be enabled in matching buffers, but supply no submode classes to be applied.

2.7.1 The Major Mode Hook

This section is intended for users who understand Emacs Lisp and want to know how MMM Global Mode is implemented, and perhaps use the same technique. In fact, MMM Mode exports a hook variable that you can use easily, without understanding any of the details--see below.

In order to enable itself in all buffers, however, MMM Mode has to hook itself into all major modes. Global Font Lock Mode from the standard Emacs distribution (see section `Font Lock' in The Emacs Manual) has a similar problem, and solves it by adding a function to change-major-mode-hook, which is run by kill-all-local-variables, which is run in turn by all major mode functions at the beginning. This function stores a list of which buffers need fontification. It then adds a different function to post-command-hook, which checks if the current buffer needs fontification, and if so performs it. MMM Global Mode uses the same technique.

In the interests of generality, and for your use, the function that MMM Mode runs in post-command-hook (mmm-run-major-mode-hook) is not specific to MMM Mode, but rather runs the hook variable mmm-major-mode-hook, which by default contains a function (mmm-mode-on-maybe) which possibly turns MMM Mode on, depending on the value of mmm-global-mode. Thus, to run another function in all major modes, all you need to do is add it to this hook. For example, the following line in an initialization file will turn on Auto Fill Mode (see section `Auto Fill' in The Emacs Manual) in all buffers:

(add-hook 'mmm-major-mode-hook 'turn-on-auto-fill)

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.