File Variables

The find-file command examines a file's name and contents to determine an appropriate language mode for it. For instance, files with a .c extension are put in C mode. You can override this decision with a "file variable".

These are specially-formatted lines at the top or bottom of a file that indicate the file should use a particular language mode, tab size, or other setting. For example, you can put -*- mode: VBasic -*- anywhere on the first line of a file to force Epsilon to Visual Basic mode, or write -*- tab-size: 3 -*- to make Epsilon use that tab size setting.

Epsilon recognizes a syntax for file variables that's designed to be generally compatible with Emacs. The recognized formats are as follows. First, the first line of the file (or the second, if the first starts with #!, to accommodate the Unix "shebang" line) may contain text in one of these formats:

-*- mode: modename -*-

-*- modename -*-

-*- tab-width: number -*-

-*- mode: modename; tab-width: number -*-

Other characters may appear before or after each possibility above; typically there would be commenting characters, so a full line might read /* -*- mode: shell -*- */. The first two examples set that buffer to the specified mode name, such as Perl or VBasic or C, by running a command or function named modename-mode if one exists. (A mode name of "C++" makes Epsilon uses the C++ submode of C mode.) The third example sets the width of a tab character for that buffer.

In more detail, between the -*- sequences may be one or more definitions, separated by ; characters. Spacing and capitalization are ignored throughout. Each definition may either be a mode name alone, or a setting name followed by a colon : and a value.

The setting names recognized are "mode", as another way to specify the mode; "tab-size" or "tab-width" to set the buffer's tab size, or "margin-right" or "fill-column" to set the buffer's right margin. (The names tab-size and margin-right reflect the names of the Epsilon variables they set; the names "tab-width" and "fill-column" are more compatible with other programs, and recommended if users of other editors may edit the files.)

Similarly, you can use either "auto-fill-mode" or "fill-mode" to set whether Epsilon should break lines as you type, and either "indent-with-tabs" or "indent-tabs-mode" to set whether indenting should use tab characters in addition to spaces. The latter name, in each case, is the more compatible one. Also, you can write "nil" instead of 0 to turn off a setting, again for compatibility.

Epsilon also recognizes "compile-command" for use with the compile-buffer command; see Compiling From Epsilon for details. And it recognizes "coding" to indicate the file's Unicode encoding (but the detect-encodings variable may override this).

It recognizes "write-line-translate" as a way to set the style of line translation for the file after it has been read in; this is useful as a directory-wide setting, to permit files to be auto-detected when read, but forced into a consistent format when written. The recognized value names for this setting are: "windows" (or equivalently "dos"), "binary", "unix", "mac", and "auto". See Line Translation for details.

Another syntax for normal file variables only appears at the end of a file, starting within the last 3000 characters (but see the file-variables-search-limit variable). It looks like this:

Local Variables:
mode: modename
tab-size: number
End:

The first line shown is required, and the last is recommended for compatibility; inside are the settings, one per line. Each line may have additional text at the start and end of each line (so it will look like a comment in the file's programming language). The "coding" file variable doesn't use this alternative syntax; any specified encoding must be on the first line only.

When using this syntax, (or when using an .epsilon_vars file, as the next section explains), Epsilon also permits a file to set any numeric Epsilon variable defined as buffer-specific. These include auto-fill-indents , auto-fill-mode , c-indent , and many more. Such variables may also be set based on another such variable's value:

c-indent: 6
c-contin-offset: c-indent
c-label-indent: c-indent * 3
c-case-offset: c-indent * -1

Values for numeric file variables use a simple syntax. They may be either a number (perhaps with a 0x, 0o, or 0b prefix to indicate its base is hex, octal or binary, respectively), or else the name of an Epsilon variable that could be used as a file variable, or else two of these with an operator between them (+, -, *, or / only). (Either a number or a variable name may have a - prefix to negate it.) Those file variable names that Epsilon recognizes only for compatibility (fill-column and tab-width, for instance) may not be used with these expressions.

Bits in the variable use-file-variables enable scanning for file variables of different sorts.

Subtopics:

Directory-wide File Variables
Vi/Vim File Variables

Previous Up Next
File Name Case Commands by Topic Directory-wide File Variables