hilight(2)

NAME

hilight - Manage the buffer hilighting schemes

SYNOPSIS

0 hilight "hil-no" "flags" [ "nol" ] [ "buffer-scheme" [ "trunc-scheme" ] ]

hilight "hil-no" "type" "token" [ ["rtoken"]


[ ( [ "close" ["rclose"] "ignore" ] ) |

( ["continue"] ) |
( ["b-hil-no"] ) ]

"schemeNum"

hilight "hil-no" "0x200" "token"
hilight "hil-no" "0x400" "from-col" "to-col" "schemeNum"

-1 hilight "hil-no" "type" "token"

DESCRIPTION

The hilight command creates and manages the buffer hilighting, the process of creating a new hilighting scheme is best described in File Language Templates. The command takes various forms as defined by the arguments. Each of the argument configurations is defined as follows:-

Hilight Scheme Creation

0 hilight "hil-no" "flags" [ "nol" ] [ "buffer-scheme" [ "trunc-scheme" ] ]

With an argument of 0, hilight initializes or re-initializes the hilight scheme hil-no (1-255). Every buffer has a hilight scheme, the default is 0 which means no hi-lighting and only the $global-scheme(5) etc. are used. The hilighting scheme must be defined before use and is used to specify how the buffer is to be hilighted. MicroEmacs 2009 supports the following hilighting concepts:-

• hilight string, a user specified string is hilighted in any color scheme.
• Tokens, same as a hilight string except that the string must be enclosed in non alpha-numeric characters.
• Start-of-line hilights, the start of the hilight must be the first non-white character of the line.
• End-of-Line hilights, the hilight starts from the current position and continues until the end of the line. Optionally, the hilight may continue onto the next line if the current line ends in a given string. A bracket may also be searched for within the line.
• Bracket hilight, hi-lights from the current position until the closing bracket token is found.
• Replace string , allows the hilight string to be replaced with a different user specified string. (i.e. the displayed representation is different from the buffer contents)

Terminals that cannot display color directly may still be able to take advantage of the hi-lighting. A terminal that has fonts (i.e. Termcap) can use them in the same way using the add-color-scheme(2) command. The hi-light scheme is also used in printing (see print-buffer(2)). If your terminal cannot display color in any way, it is recommended that hi-lighting is disabled (except when printing) as it does take CPU time.

The "hil-no" argument specifies which hi-lighting scheme is being initialized. Once a hilighting scheme has been initialized, hi-light tokens can be added to it and it can be used by setting the current buffer's $buffer-hilight(5) variable to "hil-no". The "flags" argument is a bit based flag setting global hi-light characteristics, where:-

0x01


The hi-light scheme is case insensitive, i.e. the following tokens become equivalent:-

house == HOUSE == hOuSe

When the hilight scheme is attributed as case insensitive then the tokens must all be specified in lower case.

0x02


Set a hi-light look-back. During the process of determining the window hilighting then the hilight process has to determine whether the top of the window starts in a hi-light bracket or not. The look-back command tries looking "nol" lines backwards for an open bracket. If an open bracket is found then the top of the window is assumed to start with that bracket, else it is assumed that the top of the window is not in a bracket. For example, in `C', a comment starts with "/*" and ends with "*/" so if the hilight was initialized with

0 hilight 1 2 10 $global-scheme 

of the following, only the first would begin hi-lighted which is correct (assuming the "/*" is 10 or less lines away).

 /* ........         /*.........           ......... 
    ........           .........*/         ......... 
----------------    ---------------     --------------- top of 
    ........*/         .........           .........    window 

The optional argument "buffer-scheme" specifies the default scheme to use if there is no specific hi-light, when omitted the value of $global-scheme(5) is used. The buffer-scheme is a reference to a set of foreground and background color pairs previously defined with add-color-scheme(2). The last argument "trunc-scheme" is also optional and specifies the line truncation scheme, when omitted the value of $trunc-scheme(5) is used.

The hi-lighting scheme required is based on the type of file being edited and so is usually directly related to the file extension, thus it can be automatically set using file hooks (see add-file-hook(2)).

Hilight Scheme Token Creation

hilight "hil-no" "type" "token" [ ["rtoken"]


[ ( [ "close" ["rclose"] "ignore" ] ) |

( ["continue" ["rcontinue"] ] ) |
( ["b-hil-no"] ) ]

"schemeNum"

hilight "hil-no" "0x200" "token"
hilight "hil-no" "0x400" "from-col" "to-col" "schemeNum"

With the default argument of 1, hilight creates a hilight token to be used in hilight color scheme identified by "hil-no" (1-255) (see the section on Hilight Scheme Creation for a overview of hi-lighting). The second argument "type" specifies the token type and must always be specified, it determines which other arguments required.

Typically the last argument, schemeNum, is also required. This identifies the color scheme to use when hilighting the token, defining the foreground, background and selection color schemes. This is an index generated from add-color-scheme(2). If the schemeNum argument is omitted the default hilght color scheme is used.

The token "type" is a bit based flag of which 0, 1 or more of the bits may be set, the effect of the bits are defined as follows:

0x001


The "token" must be surrounded by non-word characters (word characters are typically the alpha-numeric characters), e.g. the following defines "if" as a token:

hilight 1 1 "if" .scheme.keyword 

this hilights the 'if' in " if " but not in "aifa".

0x002


Color this to the end of the line, often used for comments etc. For example in MicroEmacs macro language a ';' character signifies the rest of the line as a comment, hilighting is defined as follows:

; this is a comment line 
hilight 1 2 ";" .scheme.comment 

0x004


This is a bracket token, the closing bracket string "close" and an ignore character "ignore" must also be supplied. The ignore character indicates that when found it should ignore the next character; this prevents an early end on bracket miss-match. For example, in C a '"' character can be inserted into a string by 'protecting' it with a '\' character, such as "this is a string with a \" in it". In this example the ignore character should be '\' so the mid string '"' is correctly ignored, as follows:

hilight 1 4 "\"" "\"" "\\" .scheme.string 

An empty value, "", effectively disables the ignore feature. If replacing bit 0x040 is set the replacement close bracket "rclose" must be supplied.

0x008


The token has a continuation string, usually used with 0x02 but cannot be used with token types 0x004 and 0x080. The argument "continue" must be supplied and if the replacing bit 0x040 is set the replacement continue string "rcontinue" must also be supplied. The best example of its use can again be found in C; macros defined using the #define pre-processor construct may be constructed on single or multiple lines. The macro continues onto another line if the current line ends with a backslash '\' character, e.g.:

#define a_single_line_macro() printf("hello world\n") 

#define a_four_lined_macro()          \ 
do {                                  \ 
    printf("hello world\n") ;         \ 
} while(0) 

This can be correctly hilighted with the pre-processor scheme using:

; use to-end-of-line (2) and continuation (8), i.e. 2+8=10 
hilight 1 10 "#" "\\" .scheme.prepro 

0x010

If this is an end of line token (0x002) then


The rest of the line is checked for any valid brackets.

Else if this is a bracket token (0x004) then


This is still searched for after an end of line token is found.

Else


Ignored

This feature enables the searching and hilighting of specific brackets contained within a to-end-of-line scheme. For example, consider the following C code:

#define My_Token 0x01  /* This is a multi-lined comment 
                        * describing My_Token */ 

With the '#' pre-processor hilight (see bit 0x08 above) the #define line would all be hilighted with the pre-process scheme, the comment would be missed causing incorrect hilighting of the next line. Instead this feature may be used by both the pre-processor and comment hilight tokens to correctly hilight the above example:

hilight 1 26 "#" "\\" .scheme.prepro 
hilight 1 20 "/\\*" "*/" "" .scheme.comment 

0x020


This token must be the first non-white character of the line.

0x040


The token (and closing bracket tokens) are to be replaced by the given replacement strings. This is often utilized when displaying formated text such as MicroEmacs on-line help ehf(8) pages, the output from UNIX man(1) etc. In MicroEmacs help pages, the start of bold text is delimited with the character sequence "\C[cD" and ends with the character sequence "\C[cA", e.g.

"the word \C[cDbold\C[cA is in \C[cDbold\C[cA" 

Obviously the hilight delimiters should not appear so the character sequence may be correctly drawn using a bracket token, starting with "\C[cD" and ending with "\C[cA", replacing both with an empty string:

hilight 1 0x44 "\C[cD" "" "\C[cA" "" "" .scheme.bold 

0x080


This is a branch token. When this token is found, the token (or the replace string) is colored using the given color schemeNum and then the current hilighting scheme is changed to "b-hil-no" (which MUST be defined by the time it is first used). The "b-hil-no" hi-light scheme should also contain a branch token which branches back to "hil-no" or "0" (which branches to $buffer-hilight(5)). A branch does not have to branch back to "hil-no", it may branch to any other hi-light scheme. The branches are not stacked and there is no limit on the nesting.

0x100


The token must be at the start of the line.

0x200


This is an invalid token in its own right, which is used for optimizing a hi-lighting scheme.

This has the second highest precedence (see 0x400) and all other bits are ignored. Only the first 3 arguments are required. For example, if there are 11 tokens starting with "delete-" as with the hi-lighting of this buffer, then adding the token "delete-", while invalid in its own right, means that "delete-" is only checked for once. This also reduces the size of the internal hilighting tables so if the message "Table full" appears, the hilighting scheme should be reduced by removal of the common components.

0x400


This is a column hilighting token, which allows absolute columns within a window to be hilighted (irrespective of the contents). This bit takes precedence over all other bits and all other bits are ignored. Column highlighting is a different concept to token in that it requires a "from-col" and a "to-col" column positions and a line will be hilighted in the given scheme between these two columns.

0x800


The flag is used with bracket tokens (0x04) and indicates that the bracket is typically contained on a single line. This information is used by MicroEmacs in trying to avoid hilighting anomalies caused when the start and end tokens of the bracket are the same (e.g. a string's start and end token is '"'). Problems arise when the bracket starts on one line and closes on a later line, even with a large look-back, eventually the start bracket will become too far back and only the end bracket is found. But as this is the same as the open token it is mistaken for an open bracket and the strings become out of synch. This test can reset this if further down the file an open and close bracket is found on the same line. For this to have any effect, the hilighting scheme must use look-back (flag 0x02 of Hilight Creation).

0x1000


Flag is typically used with a branch token (0x04) and indicates that the hilight exists to the end of the line or is terminated by the new line (i.e. encountering the end of line will removes the branch hilight).

Note that 0x004, 0x008 and 0x080 are mutually exclusive and more than 1 should not be set in any one hilight token, if 2 or more are set the effect is undefined. Other than this there is no restrictions placed on the types of token used, although strange combinations like 0x006 may lead to unexpected results -- hopefully not a core dump, but not guaranteed !

The token and close token of brackets may contain a limited subset of regular expression tokens as follows:-

^


When specified as the first character of the token, the token must be at the start of the line.

$


The token must be at the end of the line, must be the last character.

\{


Indicates the start of the hilighted part of the token, only one may be used per token. This token use is different from regex. The \{ hilight start marker must be at a fixed point from the start of the token, that is a wild card sequence may NOT proceed the "\{" token, i.e. "A\{ *B" is correct, "A *\{B" is incorrect as it is proceeded by a wild card character.

\}


Indicates the end of the hilighted part of the token, only one may be used per token. The rest of the token must be matched for it to be used but is not considered part of the token, i.e. hilighting continues on the character immediately after the "\}", not at the end of the token. Similar to the \< token, the length of the rest of the token must be fixed. This token use is different from regex.

\(.\)


Groups are supported in hilighting, but they must only enclose a single character, closures ('*', '?' and '+') must come after the closure, i.e. use "\(.\)*", not "\(.*\)". Alternatives ("\|") are not supported.

Groups are used to capture a single, this single character may be tested again within the string using the syntax \1..\9 as with regular expressions. Where the inverse character is required then the syntax \!1..\!9 may be used. This NOT syntax is special to highlighting and is not present in the regular expression general syntax.

.


Matches any character.

[...]


Matches a single buffer character to a range of characters, for example to hilight MicroEmacs register variables (i.e. #g0-#g9, #p0-#p9, #l0-#l9) the following regex string may be used:

hilight 1 1 "#[gpl][0-9]" 

This matches a token which starts with a '#', followed by a 'g', 'p' or 'l' character and ends with a numerical digit. If the user required the replacement (bit 0x40) of the "#" to "#register" to aid readability, the replacement string some now needs to know whether the second character was a 'g', 'p' or 'l' and which digit. Up to 9 groups ("\(.\)") can be use to store a store a single search character, which can be used later in the search string and in the replacement string by using the form "\#", where # is the range test number counting from the left, e.g. for the given example use:

hilight 1 65 "#\\([gpl]\\)\\([0-9]\\)" "#register\\1\\2" 

The content of the brackets ([...]) include a set of special short cuts and regular expression syntax definitions as follows:-

[abc]


A list of characters.

[a-z]


A range of characters.

[-.0-9]


A combination of character lists and ranges.

[[:space:]]


A white space character. See set-char-mask(2) for a full description on MicroEmacs character range support.

[[:digit:]]


A digit, 0-9.

[[:xdigit:]]


A hexadecimal digit, 0-9, a-f, A-F.

[[:lower:]]


A lower case letter, by default a-z.

[[:upper:]]


An upper case letter, by default A-Z.

[[:alpha:]]


A lower or upper case letter.

[[:alnum:]]


A lower or upper case letter or a digit.

[[:sword:]]


A spell word character.

[^...]


Matches all characters except the given range of characters, e.g. "[^[:space:]]".

\#


The same character which matched the #th group token. This functionality is best explained using UNIX man(1) output as an example, to create a bold character 'X' it produces "X\CHX" where \CH is a backspace character thereby overstriking the first 'X' with another creating a bold character. This can be checked for and simulated in MicroEmacs using the following:

hilight 1 64 "\\(.\\)\CH\\1" "\\1" .scheme.bold 

The use of "\1" in the search string ensures that the second character is the same as the first. This is replace by a single character drawn in the bold scheme.

\!#


The inverse character that matched the #th group token, i.e. NOT \1.

? + *


Matches 0 or 1, 1 or more and 0 or more of the previous character or character range respectively.

\a \A \w \W \l \L \m \u \U \d \D \h \H \x \s \S \e \g \n \r


Marches (a)lphabetic lower, the special word characters (w)ord, (l)ower, (m)alhpanumeric, (u)pper, (d)igit, (h)exdigit (xxx) literal hexdecimal digit, white(s)pace, (eescape, (n)ewline, (g}bell, (r)formfeed. The uppercase letters are the inverse. (see Regular Expressions).

Following is a list of hilighting regular expression restrictions:

The number of characters to the left of a \{ and to the right of a \} token must be fixed, i.e. the '?', '+' and '*' tokens cannot be used before this token. Consider the hilighting of a C function name defined to be a token at the start of a line followed by 0 or more spaces followed by a '('. The following hilight token looks valid but the variable space match is incorrect as it is to the right of the \}:

hilight 1 0 "^\\w+\\}\\s*(" .scheme.function 

Instead either the space match must be include in the function token hilighting (which may cause problems, particularly if printing with underlining) or by fixing the number of spaces as follows:

; include the spaces in the function hilighting 
hilight 1 0 "^\\w+\\s*\\}(" .scheme.function 
; or fix the number of spaces to 0, 1 ... 
hilight .hilight.c    0 "^\\w+\\}(" .scheme.function 
hilight .hilight.c    0 "^\\w+\}\\s(" .scheme.function 

The + and * tokens match the longest string and do not narrow, e.g. consider the hilighting of a C goto label which takes the form of an alpha-numerical name at the start of a line followed by a ':' character. The token "^.*:" cannot be used as . will also match and move past the ending ':', ending only at the end of the line. As no narrowing is performed the final ':' in the token will not match and the label will not be hilighted. Instead a character range which excludes a ':' character must be used, e.g. "^[^:]*:".

A group should not be followed by a ? or * closure, it should either be a fixed single character or followed by a + closure (in which case the last matching character is stored).

Following is a list of hilight type bit / token regex equivalents:

0x01


"[^word]\{????\}[^word]"

0x02


"????.*"

0x20


"^\s*\{????" - (note that this is strictly incorrect as the \s* is to the left of the \{, it is correctly handled for the ease of use).

0x100


"^????"

Hilight Scheme Token Deletion

-1 hilight "hil-no" "type" "token" With a negative argument hilight deletes the given "token" from a hi-light color scheme identified by "hil-no". The token "type" must also be specified to distinguish between normal and column token types.

EXAMPLE

Example 1

Hilighting a MicroEmacs character given in hex form, checking its validity (i.e. "\x??" where ? is a hex digit):

hilight 1 0 "\\x[[:xdigit:]][[:xdigit:]]" .hilight.variable 

Hilighting a C style variable length hex number (i.e. "0x???"):

hilight 1 1 "0[xX][[:xdigit:]]+" .hilight.variable 

Example 2

Replacing a quoted character with just the character (i.e. 'x' -> x)

hilight 1 64 "'\\(.\\)'" "\\1" %magenta 

Example 3

The following example uses the branch hilighting feature to hilight each window line a different color to its neighbors by cycle through 3 different color schemes:

0 hilight .hilight.line1 0                        $global-scheme 
  hilight .hilight.line1 0x80 "\\n" .hilight.line2 .scheme.no1 
0 hilight .hilight.line2 0                        .scheme.no1 
  hilight .hilight.line2 0x80 "\\n" .hilight.line3 .scheme.no2 
0 hilight .hilight.line3 0                        .scheme.no2 
  hilight .hilight.line3 0x80 "\\n" .hilight.line1 $global-scheme 

Example 4

Simulate the hilighting from the output of a UNIX man page (taken from hkman.emf):

0 hilight  .hilight.man 0                                $global-scheme 
; ignore 
hilight .hilight.man 64 ".\CH" ""                        $global-scheme 
; normal underline/italic 
hilight .hilight.man 64 "_\CH\\(.\\)\\}[^\CH]" "\\1"     .scheme.italic 
hilight .hilight.man 64 "\\(.\\)\CH_\\}[^\CH]" "\\1"     .scheme.italic 
; bold - first is for nroff -man 
hilight .hilight.man 64 "\\(.\\)\CH\\1\\}[^\CH]" "\\1"   .scheme.bold 
hilight .hilight.man 64 "_\CH_\CH_\CH_\\}[^\CH]" "_"     .scheme.header 
hilight .hilight.man 64 "\\(.\\)\CH\\1\CH\\1\CH\\1\\}[^\CH]" "\\1" .scheme.header 
; bold underline 
hilight .hilight.man 64 "_\CH_\CH_\CH_\CH_\\}[^\CH]" "_" .scheme.italic 
hilight .hilight.man 64 "_\CH\\(.\\)\CH\\1\CH\\1\CH\\1\\}[^\CH]" "\\1" .scheme.italic 

This replaces the complex nroff character string with a single hi-lighted character (if you do not believe me then try it!).

NOTES

MicroEmacs hilight was written with speed and flexibility in mind, as a result the user is assumed to know what they are doing, if not the effects can sometimes be fatal.

Within MicroEmacs macro language then a single backslash "\" is the escape character of the macro pre-processor. When writing a regular expression search string in the macro language then search string backslashes should be escaped. Hence a regular expression defined as "\x41\\x41" searches for the character 'A' ('A' is hexadecimal 0x41 i.e. "\x41") followed by a single hexadecimal character ("\\x) followed by the literal string "41".

HISTORY

The March 2005 release modified the NOT replacement pattern with "\s!D" where D is the numeric group identifier 1..9.

The token 0x1000 was undocumented before March 2005 and is now a fully supported hilight mode.

SEE ALSO

Regular Expressions, File Language Templates, $buffer-hilight(5), add-file-hook(2), add-color-scheme(2), print-scheme(2), indent(2), $system(5), print-buffer(2).

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12