Difference between revisions of "Wordfiles"

Revision as of 14:03, 11 August 2017

A wordfile used for syntax highlighting in UltraEdit

As discussed in the Syntax highlighting topic, UltraEdit applies syntax highlighting from definitions and configurations in wordfiles. Wordfiles must be in plain text, ANSI format with DOS style line endings and a .uew file extension. The wordfiles are loaded on startup, or when modified via the Add another language... dialog. Wordfiles are loaded from the folder shown in the Editor Display » Syntax Highlighting section of Settings (subfolders are ignored).

The easiest way to create your own wordfile is to take one of the existing wordfiles and modify it as desired, saving it into the wordfiles directory with a unique name and .uew file extension. You will need to restart UltraEdit in order to initialize the new wordfile, but once initialized, any changes you make to it should be reflected in real-time.

This topic exhaustively documents all possible options and sections of the wordfile.

Language definition

The first step to creating a valid wordfile is defining the language it will apply highlighting for. This is done on the first line of the wordfile via the following syntax:

/L#"Language Name"

...where "#" is a number (no longer used for sorting purposes but still required) and "Language Name" is the name as it will appear in the list of available syntax highlighting languages.

Language options

There are several keywords available for specifying syntax highlighting behavior options in the wordfile. These options are set by simply including the keyword in the wordfile. These are typically added immediately after the language definition on line 1 of the wordfile, but can be listed on their own line if you desire. Note: If the option is on its own line in the wordfile, it must be preceded by a forward slash, e.g.:

/DisableMLS F

Special "_LANG" language flags

In order to apply correct syntax highlighting and other wordfile-based functionality, for several languages, special internal handling is required. These languages are determined via special flags in the wordfile. There are a fixed number of special language flags, and more may be added in the future. The available flags are described in detail below.

The language flag must exist on the line 1 of the wordfile somewhere after the language definition.

Important note: each language flag may exist only once in a single wordfile. Adding a language flag to multiple wordfiles will result in unexpected / incorrect highlighting for the associated language(s).

AASM_LANG Language flag for: AT&T Assembly

ASP_LANG Language flag for: ASP

Note: the .asp(x) file extension (and all variants) should be listed in the HTML wordfile to support multi-language embedded ASP highlighting. This will not adversely affect standalone ASP files.

COBOL_LANG Language flag for: COBOL

CSHARP_LANG Language flag for: C#

CSS_LANG Language flag for: CSS

C_LANG Language flag for: C/C++

ECMA_LANG Language flag for: EcmaScript

FORTRAN_LANG Language flag for: FORTRAN

HTML_LANG Language flag for: HTML

HTML is considerably different from other coding languages. With the HTML_LANG keyword, in the wordfile itself, the special characters "<" and optionally "/" can be prepended to any keyword in the wordfile without having to sort lines as is normally required for wordfile color groups. For example, all keywords beginning with "<a" or "</a" should be on the same line as other words beginning with "a". In the same way, all words beginning with "<b" or "</b" should be on the same line as other words beginning with "b", but on a different line from those starting with "<a", "</a", or "a".

This flag also controls HTML tag matching and some other special internal handling for HTML syntax highlighting.

This flag also sets which language type to allow multi-language web-based highlighting; for example, CSS, JavaScript, or PHP embedded in a .html file.

JAVA_LANG Language flag for: Java

JSCRIPT_LANG Language flag for: JavaScript

LATEX_LANG Language flag for: LaTeX

With the LaTeX language flag, UltraEdit applies special highlighting to allow words to be appropriately handled and highlighted with the "\", and with consecutive words.

This also allows the keywords to be sorted in the wordfile color group without all of them being on the same line. If the keyword begins with "\" then the second character is used to determine which line the word should be on. For example, all words beginning with "\a" should be on the same line as other words beginning with "\a" or "a". In the same way, all words beginning with "\b" should be on the same line as other words beginning with "\b" or "b" but on a different line from those starting with "\a".

MASM_LANG Language flag for: Microsoft Assembly

MATLAB_LANG Language flag for: MATLAB

NASM_LANG Language flag for: Netwide Assembly

PASCAL_LANG Language flag for: Pascal

PERL_LANG Language flag for: Perl

PHP_LANG Language flag for: PHP

Note: the .php file extension should be listed in the HTML wordfile to support multi-language embedded PHP highlighting. This will not adversely affect standalone PHP files.

PLB_LANG Language flag for: PLB

PUREBASIC_LANG Language flag for: PureBasic

PYTHON_LANG Language flag for: Python

RUBY_LANG Language flag for: Ruby

SQL_LANG Language flag for: SQL

VBSCRIPT_LANG Language flag for: VBScript

VB_LANG Language flag for: Visual Basic

XML_LANG Language flag for: XML

XSL_LANG Language flag for: XSL

Comments

Line comments

Line comments can be defined with the following syntax, typically placed on line 1 of the wordfile:

Line Comment = #
/Line Comment = # (if on its own line in wordfile)

The above would cause all text following a "#" character to be colored as a comment until the end of the line.

Note: If Block Comment On or Block Comment On Alt is defined in the wordfile, but the Block Comment Off/Block Comment Off Alt is not, the block commenting will stop at the end of the line. This effectively allows block comments to be used as line comments also. (See Block comments section below)

Line comments must be 5 characters or less. If less than 5 characters and on the first line of the wordfile, the characters must be followed by a space.

You can define a second set of line comments with the following syntax:

Line Comment Alt = //
/Line Comment Alt = // (if on its own line in wordfile)

The above would cause all text following "//" to be colored as a comment until the end of the line.

Some languages may require a space follow the line comment character. To facilitate this, the following wordfile definition is available:

Line Comment Num = xCC
/Line Comment Num = xCC (if on its own line in wordfile)

...where x specifies the number of characters (1 to 5) and immediately following are the characters to be used as line comments. In the example above, x would be 3 since the line comment would be "CC " (note the space after "CC").

By default, UltraEdit will treat all characters preceding a comment as valid, but some languages may require that line comments are only valid if they occur after specific characters. To facilitate this, the following wordfile definition is available:

Line Comment Preceding Chars = [a-z] /Line Comment Preceding Chars = [a-z] (if on its own line in wordfile)

In the example above, UltraEdit would only identify line comments if the line comment character immediately follow any character a – z.

You can also use the tilde (~) to specify a negative matching set of characters (i.e., comments are not valid if they are preceded by the following characters):

Line Comment Preceding Chars = [~a-z] /Line Comment Preceding Chars = [~a-z] (if on its own line in wordfile)

In the example above, UltraEdit would only identify line comments if the line comment character does not immediately follow any character a – z.

By default, UltraEdit will treat comment characters in any column as a valid comment, but some languages may require that line comments must start in a specific column(s). To facilitate this, the following wordfile definition is available:

Line Comment Valid Columns = [1-7,10] /Line Comment Valid Columns = [1-7,10] (if on its own line in wordfile)

In the example above, UltraEdit would only identify and highlight line comments if the line comment character occurs at columns 1 through 7, or at column 10.

Block comments

Block comments can be defined with the following syntax, typically placed on line 1 of the wordfile:

Block Comment On = /* Block Comment Off = */
/Block Comment On = /*
/Block Comment Off = */ (if on its own line in wordfile)

The above would cause all text between "/*" and "*/" to be highlighted as a block comment, even if it spans multiple lines.

Note: If Block Comment On is defined in the wordfile, but the Block Comment Off is not, the blcok commenting will stop at the end of the line. This effectively allows the block comments to be used as line comments also.

You can define a second set of alternative block comments as well. These can be defined with the following syntax, typically placed on line 1 of the wordfile:

Block Comment On Alt = /* Block Comment Off Alt = */
/Block Comment On Alt = /*
/Block Comment Off Alt = */ (if on its own line in wordfile)

Both block comments and alternate block comments must be no more than 19 characters.

By default, ULtraEdit will end block comment highlighting at the next block comment close string in the source code. To force UltraEdit to explicitly match all block comment start strings with all block comment end strings, use the NestBlockComments directive as described above.

Strings

By default, in any syntax highlighted file, UltraEdit will highlight any text following a double quote (") or single quote (') as a string. The string highlighting occurs until a matching string character of the same type.

You can override the string characters in the wordfile, or disable them completely with the Noquote directive on line 1. To set custom string characters, use the following syntax, typically placed on line 1 of the wordfile:

String Chars = "
/String Chars = " (if on its own line in wordfile)

In the above, only text following " would be highlighted as a string. No more than 2 string characters can be defined.

If you have 2 different string characters set (or are using the defaults) and want a different highlighting color for both types of strings, you can include the string character in one of the color groups in a line by itself, then configure the color for the string's color group in your theme. This will override the default string highlighting color in your them. For example:

/L1"My language" Line Comment = // Block Comment On = /* Block Comment Off = */ String Chars = '"
/C1"Special strings"
"

In the above, any strings encapsulated by " would be highlighted with the color set for the "Special strings" color group, whereas any strings encapsulated by ' would be highlighted with the regular color for strings.

UltraEdit supports multi-line string highlighting, however you can configure this. By default, UltraEdit will highlight strings spanning multiple lines. To disable this, add the following directive in line 1 of the wordfile:

DisableMLS

String literal prefix

You can define a string prefix character for string literals in the wordfile as well. For example, in C# the string literal is defined by an "@" sign preceding the string. To set the string literal character, use the following syntax, typically placed on line 1 of the wordfile:

String Literal Prefix = @
/String Literal Prefix = @ (if on its own line in wordfile)

In the example above, the "@" before the string indicates that a backslash is not an escape character which is useful for encapsulating file paths in strings. To illustrate, the following two statements are equivalent:

"c:\\data\\"
@"c:\data\"

The only special character in a @"..." literal is the double quote ("), which is simply doubled if you need to embed one.

Escape characters

Most languages support an escape character (usually "\") for overriding string characters (and other characters with special meanings as well). You can define the escape character using the following syntax, typically placed on line 1 of the wordfile:

Escape Char = \
/Escape Char = \ (if on its own line in wordfile)

File extensions / names

File extensions

In most cases, UltraEdit uses a file's extension to determine which wordfile/language to use for its syntax highlighting. The file extensions for a particular wordfile / language are set in the wordfile, typically at the end of line 1, using the following syntax with each file extension separated by a space:

File Extensions = C CPP CC CXX H HPP AWK
/File Extensions = C CPP CC CXX H HPP AWK (if on its own line in wordfile)

File extensions are not case sensitive. When checking a file's extension, UltraEdit will only evaluate the characters after the last dot in the file's name. A maximum of 97 single-byte characters are supported for this setting.

You can set a default syntax highlighting language by adding an asterisk (*) to the file extensions definition. This would force all files not matching a file extension in any other wordfile to use this wordfile / language for syntax highlighting. This includes new unsaved files and files without an extension.

File names

In some cases, you may want to assign a wordfile / language based upon the full file name. This can be set typically on line 1 of the wordfile, use the following syntax with each file name separated by a space:

File Names = config myfile.xml
/File Names = config myfile.xml (if on its own line in wordfile)

In the example above, any file named "config" or "myfile.xml" would be highlighted with this wordfile.

A maximum of 125 single-byte characters are supported for this setting. Names including spaces may not be used.

Shebang parsing

Perl, XML, and other script source files are frequently saved without an extension. To ensure proper, automatic highlighting of these, if the file's extension does not match any of the existing wordfiles' definitions, UltraEdit will search for a language marker / shebang in the first line of the source file. The following defaults are used:

Other script files (especially Unix shell scripts) often use some form of the shebang line to identify the language or script to be used, for example "#!/bin/ksh". To support these, you can extend the internal functionality with the language marker setting using the following syntax on a separate line in the wordfile:

/LanguageMarker = #!/bin/ksh

You can also set multiple flags using the following syntax:

/LanguageMarker = "ksh" "sh" "csh"

In the above example, any files with the following lines would be matched and the syntax highlighting of the wordfile would be applied:

#!/bin/ksh
#! /usr/bin/sh
#!/usr/local/bin/csh

Function list strings

Delimiters

Indent / unindent strings

Code folding strings

Marker characters

Keyword color groups