Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com
Answertopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

Previous: Locals, Up: Variables


57.3.4 Local Variables in Files

A file can specify local variable values for use when you edit the file with Emacs. Visiting the file checks for local variable specifications; it automatically makes these variables local to the buffer, and sets them to the values specified in the file.

There are two ways to specify local variable values: in the first line, or with a local variables list. Here's how to specify them in the first line:

     -*- mode: modename; var: value; ... -*-

You can specify any number of variables/value pairs in this way, each pair with a colon and semicolon as shown above. mode: modename; specifies the major mode; this should come first in the line. The values are not evaluated; they are used literally. Here is an example that specifies Lisp mode and sets two variables with numeric values:

     ;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-

You can also specify the coding system for a file in this way: just specify a value for the “variable” named coding. The “value” must be a coding system name that Emacs recognizes. See Coding Systems. ‘unibyte: t’ specifies unibyte loading for a particular Lisp file. See Enabling Multibyte.

The eval pseudo-variable, described below, can be specified in the first line as well.

In shell scripts, the first line is used to identify the script interpreter, so you cannot put any local variables there. To accommodate for this, when Emacs visits a shell script, it looks for local variable specifications in the second line.

A local variables list goes near the end of the file, in the last page. (It is often best to put it on a page by itself.) The local variables list starts with a line containing the string ‘Local Variables:’, and ends with a line containing the string ‘End:’. In between come the variable names and values, one set per line, as ‘variable: value’. The values are not evaluated; they are used literally. If a file has both a local variables list and a ‘-*-’ line, Emacs processes everything in the ‘-*-’ line first, and everything in the local variables list afterward.

Here is an example of a local variables list:

     ;;; Local Variables: ***
     ;;; mode:lisp ***
     ;;; comment-column:0 ***
     ;;; comment-start: ";;; "  ***
     ;;; comment-end:"***" ***
     ;;; End: ***

As you see, each line starts with the prefix ‘;;; ’ and each line ends with the suffix ‘ ***’. Emacs recognizes these as the prefix and suffix based on the first line of the list, by finding them surrounding the magic string ‘Local Variables:’; then it automatically discards them from the other lines of the list.

The usual reason for using a prefix and/or suffix is to embed the local variables list in a comment, so it won't confuse other programs that the file is intended as input for. The example above is for a language where comment lines start with ‘;;; ’ and end with ‘***’; the local values for comment-start and comment-end customize the rest of Emacs for this unusual syntax. Don't use a prefix (or a suffix) if you don't need one.

If you write a multi-line string value, you should put the prefix and suffix on each line, even lines that start or end within the string. They will be stripped off for processing the list. If you want to split a long string across multiple lines of the file, you can use backslash-newline, which is ignored in Lisp string constants. Here's an example of doing this:

     # Local Variables:
     # compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \
     #   -Dmumble=blaah"
     # End:

Some “variable names” have special meanings in a local variables list. Specifying the “variable” mode really sets the major mode, while any value specified for the “variable” eval is simply evaluated as an expression (its value is ignored). A value for coding specifies the coding system for character code conversion of this file, and a value of t for unibyte says to visit the file in a unibyte buffer. These four “variables” are not really variables; setting them in any other context has no special meaning.

If mode is used to set a major mode, it should be the first “variable” in the list. Otherwise, the entries that precede it will usually be ignored, since most modes kill all local variables as part of their initialization.

You can use the mode “variable” to set minor modes as well as the major modes; in fact, you can use it more than once, first to set the major mode and then to set minor modes which are specific to particular buffers. But most minor modes should not be specified in the file at all, regardless of how, because they represent user preferences.

For example, you may be tempted to try to turn on Auto Fill mode with a local variable list. That is a mistake. The choice of Auto Fill mode or not is a matter of individual taste, not a matter of the contents of particular files. If you want to use Auto Fill, set up major mode hooks with your .emacs file to turn it on (when appropriate) for you alone (see Init File). Don't use a local variable list to impose your taste on everyone.

The start of the local variables list must be no more than 3000 characters from the end of the file, and must be in the last page if the file is divided into pages. Otherwise, Emacs will not notice it is there. The purpose of this rule is so that a stray ‘Local Variables:’ not in the last page does not confuse Emacs, and so that visiting a long file that is all one page and has no local variables list need not take the time to search the whole file.

Use the command normal-mode to reset the local variables and major mode of a buffer according to the file name and contents, including the local variables list if any. See Choosing Modes.

The variable enable-local-variables controls whether to process local variables in files, and thus gives you a chance to override them. Its default value is t, which means do process local variables in files. If you set the value to nil, Emacs simply ignores local variables in files. Any other value says to query you about each file that has local variables, showing you the local variable specifications so you can judge.

The eval “variable,” and certain actual variables, create a special risk; when you visit someone else's file, local variable specifications for these could affect your Emacs in arbitrary ways. Therefore, the variable enable-local-eval controls whether Emacs processes eval variables, as well variables with names that end in ‘-hook’, ‘-hooks’, ‘-function’ or ‘-functions’, and certain other variables. The three possibilities for the variable's value are t, nil, and anything else, just as for enable-local-variables. The default is maybe, which is neither t nor nil, so normally Emacs does ask for confirmation about file settings for these variables.

The safe-local-eval-forms is a customizable list of eval forms which are safe to eval, so Emacs should not ask for confirmation to evaluate these forms, even if enable-local-variables says to ask for confirmation in general.


 
 
  Published under the terms of the GNU General Public License Design by Interspire