Syntax Highlighting Filters

There are several highlighting filters in the filters subdirectory. These all are programs that read a file, usually from the standard input, and write to the standard output. Vile invokes these, uses the marked-up text to display highlighting.

Except for the manpage filter (a special case) all of these can be (and most are) implemented using lex.

Keywords

Each filter reads one or more keyword files, which list specific keywords and their highlighting attributes, as well as classes of keywords.

The filters search for these files in the current, $HOME, $HOME/vile and startup directories. On Unix, the keyword files in the current and $HOME directories are hidden using a "." prefix. Except for MS-DOS, the suffix is ".keywords"; on that platform it is ".key". In the source distribution, these files are ".key", to keep them compatible with MS-DOS 8.3 filename lengths.

You can specify the root name to search, otherwise they search for "vile" and the compiled-in filter name. The locations checked are:

• the current directory
• the home-directory (as well as a vile-specific subdirectory of that)
• one or more locations known as the "startup path". There is a compiled-in default startup path list which can be overridden by the VILE_STARTUP_PATH environment variable.

./.vile.keywords
$HOME/.vile.keywords
$HOME/.vile/vile.keywords
$VILE_STARTUP_PATH/vile.keywords

and then here:

./.c.keywords
$HOME/.c.keywords
$HOME/.vile/c.keywords
$VILE_STARTUP_PATH/c.keywords

In each case, vile-c-filt stops as soon as it finds the desired file. On a non-Unix host, the search looks like this:

./vile.keywords
$HOME/vile.keywords
$HOME/vile/vile.keywords
$VILE_STARTUP_PATH/vile.keywords

./c.keywords
$HOME/c.keywords
$HOME/vile/c.keywords
$VILE_STARTUP_PATH/c.keywords

The vile.keywords file contains color information for the most common classes. The c.keywords file contains the actual keywords to be highlighted, referenced to the classes which are in turn colored. You can see the search for keyword files by running the filter with a -v option, repeating the option (-vv) to obtain more verbose traces. Note that filters may be compiled-into vile. In that case (vile calls the filter using the attribute-directly command), you can still get a trace by adding the -v option to the filtername line of the majormode. The trace will go to the message line, but also if you have

set popup-msgs

specified, to the [Messages] buffer.

Predefined keyword classes include (but may not necessarily be used in specific filters):

Action
Comment
Ident
Ident2
Keyword
Keyword2
Literal
Number
Preproc
Type

A few filters, e.g., cweb, latex, diff, use additional classes. The predefined classes are a guideline, to implement a common style across the different filters.

Each line in the keyword file consists of two strings separated by a colon (:). If the first string is empty, the line is treated as a comment. The second string is interpreted as follows:

• if quoted with single quotes, any value is permitted. Use a doubled quote to insert a quote character. Literal values of this type are used to override internal parameters of the filter programs. See m4-filt.c for an example.
• otherwise (the usual case), the string is an identifier, which happens to include the characters used in vile's control/A highlighting attributes (digits plus the characters ABCDEFIRU).

  If the second string matches a keyword class (or in fact, any other keyword), the highlighting attributes of that keyword are used. An empty attribute string implies the default class, which usually is "Keyword".

  If the second string does not match a keyword, it must be a set of highlighting attributes, which will be used for the first string. A special case is made for a string beginning "N", which is treated as no-attributes.

  See "Writing your own filters" in vile.hlp for additional details about attribute strings.

The keyword file reader supports a limited include facility. In each case, the parameter of the include is the root name of the keyword file, e.g., "c" for "c.key".

• If a line begins with ".include", it reads from the given keyword file.
• A few filters (such as yacc) require multiple symbol tables; these include using ".source".
• Use the ".table" directive to simply switch to a different symbol table in the same file with the same effect as ".source".
• Use the ".merge" directive to read into the current symbol table from another file.

Specify abbreviations using a '*' character, e.g.,

vi*le

to match any of vi, vil, vile. You can change the '*' character using the ".abbrev" directive. A special case is provided for languages such as SQL*PLUS, using the '?' character, e.g.,

rem?ark

Use ".brief" to alter the special character '?'.

For either ".abbrev" or ".brief", omitting the parameter disables the feature.

Use the ".default" directive to change the default class. The parameter must be the name of a class which has already been defined. Omit the parameter to reset the default back to "Keyword".

You can change the characters assigned to ':' and '.' using ".equals" and ".meta" directives, respectively.

Some of the filters match case-independent keywords (e.g., the DOS batchfiles). The keywords file must give these names in lowercase, since the filtered text is converted to lowercase when matching.

You can modify the behavior slightly, by giving an absolute pathname with the -k option, but otherwise the filters search for both "vile" and the specific language keywords, if any.

OPTIONS

A few options are common to all filters:

-d

is recognized when the filters have been compiled with "DEBUG" defined. This is used in the more complicated filters such as perl, ruby and sql to show the parsing.

-i

is used (in all except for html and imake) to tell vile to ignore case when matching keywords. It is ignored in the few instances mentioned because those filters contain logic to distinguish between caseless and case-sensitive syntax.

-k FILE

specifies the keyword file to use.

-q

exits the filter before writing the marked-up output. This happens after processing the class definitions, so it is useful in combination with the -v option to simply obtain the class information.

-Q

is like "-q", but also writes to stderr (or [Filter Messages]) the resulting keyword information.

-t

holds the tabstop setting, which can be used in a filter for column computations.

-v

verbose, turns on extra output which can be used for troubleshooting configuration problems.

The C syntax filter recognizes additional options to customize it for Java, JavaScript and Objective-C:

-j

Extend name- and literal-syntax to include Java.

-o

Allow '@' in names, for directives.

-p

Disallow preprocessor lines.

-s

for JavaScript (to support jsmode). This controls whether to allow regular expressions in certain cases.

-#

support C# verbatim string literals

The HTML filter recognizes a "-a" option to customize it for "asp" files, as well as a "-j" option to customize for JavaScript script-tags.

The keyword filter recognizes a "-c" option to tell it to highlight color codes with the corresponding color rather than the "Action" color.

The MAN filter recognizes a "-8" option which tells it to use 8-bit approximations for some common UTF-8 equivalents such as hyphen.

The Ruby filter recognizes a "-e" option to customize it for "ERB" files.

The SH filter recognizes a "-K" option to turn on Korn shell's syntax for dotted variable names. The ksh93 "vnames" allow a dotted name such as "$foo.bar" to be defined it is root ("$foo") is already defined. That affects portability of scripts because other sh-like programs do not behave this way. The "-K" option also handles ksh's so-called "ANSI C quoting" which uses single-quotes after a dollar sign as if those were actually double-quotes.

The XML filter recognizes "-A" and "-M" options to recognize Ant and Maven macrodef and property tags, respectively.

PROGRAMS

The following are implemented:

Not all majormodes require a special filter for highlighting, since they use the same syntax as other majormodes:

NOTE

The lex filters have been well tested only with flex, which treats newlines differently. Older versions of lex may not support the %x states.