Syntax Highlighting Primitives

Summary

Syntax Highlighting Primitives
Macros
attach_syntax	Attach a syntax to a buffer.
create_syntax	Syntax table creation.
define_keywords	Add keywords to a syntax dictionary.
detach_syntax	Detach a syntax from a buffer.
get_color_pair	Retrieve the specific color.
hilite_create	Create a hilite resource.
hilite_delete	Delete a hilite resource.
hilite_destroy	Destroy hilite resources.
inq_hilite	Retrieve a hilite definition.
inq_syntax	Retrieve the syntax identifier.
inq_syntax_name	Retrieve the syntax name.
set_color_pair	Set a specific color.
set_syntax_flags	Set syntax flags.
syntax_build	Build a syntax hiliting engine.
syntax_column_ruler	Column syntax coloriser.
syntax_rule	Define a syntax hilite rule.
syntax_token	Define a syntax token.

Macros

attach_syntax

int attach_syntax( int|string syntable )

Attach a syntax to a buffer.

Description

The attach_syntax() primitive associates the current buffer with the syntax table specified by the name table.

Until another syntax table is associated with the buffer, the syntax table syntable shall be used in all operations that require a syntax; these include parenthesis matching and spell-checks.

Parameters

syntable

Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Returns

The attach_syntax() primitive returns the syntax identifier associated with the attached syntax table, otherwise -1 if table did not exist.

On invalid table reference errors the following diagnostics message(s) shall be echoed on the command prompt.

syntax: table 'xxx' undefined.

syntax: no current table.

Portability

A GriefEdit extension.

create_syntax

int create_syntax( string table )

Syntax table creation.

Description

The create_syntax primitive creates a new syntax table with the name specified by table. If the table already exists, the existing table shall be reinitialised.

Parameters

table

Unique syntaxtable name.

Returns

The create_syntax primitive returns the syntax identifier associated with the syntax table, otherwise -1 if the syntax could not be created.

Portability

A GriefEdit extension.

define_keywords

void define_keywords( [int|string] keywords,
string words|list words,
[int length],
[int flags],
[int|string syntable] )

Add keywords to a syntax dictionary.

Description

The define_keywords() primitive adds a set of keywords to the specified dictionary, which shall be color syntax highlighted in the associated color with the table specified by table.

Description

keywords	Keyword table identifier, see table below.
words	List of words, otherwise a string that is the concatenation of keywords each being of absolute length characters, optionally comma separated (See: <length>).
length	Length of the keywords. If positive the keyword string is assumed to contain non delimited words of all of same length. Otherwise if given as a negative value, the keyword string is assumed to contain comma separated values of variable length words.
flags	Optional control flags.

SYNF_IGNORECASE	Ignore case.
SYNK_NATCHCASE	Match case.
SYNF_PATTERN	Pattern match (glob style).

syntableOptional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Keyword Tables

Constant	Name	Attribute
SYNK_PRIMARY	primary	ATTR_KEYWORD
SYNK_FUNCTION	function	ATTR_KEYWORD_FUNCTION
SYNK_EXTENSION	extension	ATTR_KEYWORD_EXTENSION
SYNK_TYPE	type	ATTR_KEYWORD_TYPE
SYNK_STORAGECLASS	storageclass	ATTR_KEYWORD_STORAGECLASS
SYNK_DEFINITION	definition	ATTR_KEYWORD_DEFINTION
SYNK_CONDITIONAL	conditional	ATTR_KEYWORD_CONDITIONAL
SYNK_REPEAT	repeat	ATTR_KEYWORD_REPEAT
SYNK_EXCEPTION	exception	ATTR_KEYWORD_EXCEPTION
SYNK_DEBUG	debug	ATTR_KEYWORD_DEBUG
SYNK_LABEL	label	ATTR_KEYWORD_LABE
SYNK_STRUCTURE	structure	ATTR_KEYWORD_STRUCTURE
SYNK_TYPEDEF	typedef	ATTR_KEYWORD_TYPEDEF
SYNK_CONSTANT	constant	ATTR_CONSTANT
SYNK_OPERATOR	operator	ATTR_OPERATOR
SYNK_BOOLEAN	boolean	ATTR_BOOLEAN
SYNK_PREPROCESSOR	preprocessor	ATTR_PREPROCESSOR_KEYWORD
SYNK_PREPROCESSOR_INCLUDE	ppinclude	ATTR_PREPROCESSOR_INCLUDE
SYNK_PREPROCESSOR_DEFINE	ppdefine	ATTR_PREPROCESSOR_DEFINE
SYNK_PREPROCESSOR_CONDITIONAL	ppconditional	ATTR_PREPROCESSOR_CONDITIONAL
SYNK_TODO	todo	ATTR_TODO
SYNK_MARKUP	markup	ATTR_COMMENT_STANDOUT

Returns

nothing

Portability

A GriefEdit extension.

detach_syntax

void detach_syntax()

Detach a syntax from a buffer.

Description

The detach_syntax() primitive removes the associated syntax definition from the current buffer.

Parameters

none

Returns

The detach_syntax() primitive returns the syntax identifier which was associated with the buffer, otherwise -1 if no syntax was associated.

Portability

A GriefEdit extension.

get_color_pair

void get_color_pair( string name|int ident,
[int|string fg],
[int|string bg],
[int|string sf] )

Retrieve the specific color.

Description

The get_color_pair() primitive retrieves a specific attribute that GRIEF utilities on a color display. Attributes may be specified as integers or strings, with strings being case-insensitive see set_color for more details.

The specified attribute color values shall be assigned to the specified arguments foreground, backbround and style.

Parameters

ident	Attribute identifier.
fg	Optional variable reference to be populated with the foreground color. If an integer reference the numeric colour value is assigned otherwise if a string reference the associated name.
bg	Optional variable reference to be populated with the background color. If an integer reference the numeric colour value is assigned otherwise if a string reference the associated name.
sf	Optional variable reference to be populated with the style and flags. If an integer reference the numeric value is assigned otherwise when a string reference the human readable decoding version is assigned.

Returns

nothing

Portability

A GriefEdit extension.

hilite_create

int hilite_create( [int bufnam],
[int type],
[int timeout],
[int sline],
[int scol],
[int eline],
[int ecol],
[string | int attr],
[int ident] )

Create a hilite resource.

Description

The hilite_create() primitive creates a buffer hilite resource with the referenced buffer bufnum under the classification type; the given classification groups hilite resources allowing bulk management and removal.

Similar to the buffer anchors yet they can not be edited and there maybe as many as desired hilite’s are available for use by macros to mark elements within documents, for example search results.

The created resource decorators the region for the duration timeout between the stated starting position sline, eline upto the ending position eline, ecol using the display attribute attr.

Parameter

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
type	Optional type, default 0; user assignable label.
timeout	Specifies a timeout in seconds. If specified then the hilite shall be automatically deleted upon the timeout expiring. A timeout of -1 implies on next buffer change.
sline, scol	Start of the hilite region.
eline, ecol	End for the hilite region.
attr	Associated attribute.
ident	User assigned identifier.

Returns

The hilite_create() primitive returns the unique hilite identifier, otherwise -1 on error.

Portability

A GriefEdit extension, yet it was noted similar functionality has been introduced to CRiSP ™ in parallel; compatibility as yet confirmed.

hilite_delete

int hilite_delete( [int bufnum],
int hilite )

Delete a hilite resource.

Description

The hilite_delete() primitive removes the stated hilite’s hilite from the associated with the buffer bufnum.

Parameter

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
hilite	Unique hilite identifier which are returned during the hilite’s corresponding creation by hilite_create.

Returns

The hilite_delete() primitive returns 1 if the hilite existed and was removed successfully, 0 if the hilite did not exist, otherwise -1 on error.

Portability

A GriefEdit extension.

hilite_destroy

int hilite_destroy( [int bufnum],
[int type] )

Destroy hilite resources.

Description

The hilite_destroy() primitive either removes hilite’s of the specified type otherwise if omitted all hilite’s associated with the buffer bufnum.

Parameter

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
type	Optional hilite type, if omitted all buffer hilite’s are released.

Returns

The hilite_destroy() primitive returns the number of hilite’s removed, 0 if none were found, otherwise -1 on error.

Portability

A GriefEdit extension, yet it was noted similar functionality has been introduced to CRiSP ™ in parallel; compatibility as yet confirmed.

inq_hilite

int inq_hilite( [int bufnum],
[int line],
[int column],
[int &attribute],
[int &ident] )

Retrieve a hilite definition.

Description

The inq_hilite() primitive retrieves details about the hilite resource at the specified position.

Parameters

bufnum	Optional buffer number, if omitted the current buffer shall be referenced.
line	Optional integer line number within the referenced buffer, if omitted the current line number is used.
column	Optional integer column number within the referenced buffer, if omitted the current column number is used.
attribute	Optional integer variable, if specified shall be populated with the hilite assigned attribute.
indent	Optional integer variable, if specified shall be populated with the hilite user assigned user identifier.

Returns

The inq_hilite() primitive returns the type of the active hilite and populates attribute and ident, otherwise -1 and the arguments shall remain unmodified..

Portability

A GriefEdit extension, yet it was noted similar functionality has been introduced to CRiSP ™ in parallel; compatibility as yet confirmed.

inq_syntax

int inq_syntax( [int &flags],
[int|string syntable] )

Retrieve the syntax identifier.

Description

The inq_syntax() primitive retrieves the syntax identifier associated with the specified syntax.

Parameters

flags	Option integer reference, to be populated with the active flags of the referenced syntax-table.
syntable	Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Returns

The inq_syntax() primitive returns the syntax-table identifier, otherwise -1 on error.

Portability

A GriefEdit extension.

inq_syntax_name

int inq_syntax_name( [int bufnum] )

Retrieve the syntax name.

Description

The inq_syntax_name() primitive retrieves the name of the syntax associated with the specified buffer.

Parameters

bufnum

Optional buffer number, if omitted the current buffer shall be referenced.

Returns

The inq_syntax_name() primitive returns the syntax-table name, otherwise an empty string.

Portability

A GriefEdit extension.

set_color_pair

void set_color_pair( string|int ident,
[int|string fg],
[int|string bg],
[int|string sf] )

Set a specific color.

Description

The set_color_pair() primitive sets the pair of foreground and background colors associated with the color attribute indent.

The specified attribute shall be assigned the given foreground color fg, with an optional background bg and style sf. If the foreground is omitted the user shall be prompted.

Parameters

ident	Attribute identifier either using its their manifest integer constants or string aliases, with names being case-insensitive; see set_color for details.
fg	Optional foreground color. If omitted, then the foreground and (if required) background are prompted.
bg	Optional background color.
sf	Optional style and flags.

Returns

nothing

Portability

A GriefEdit extension.

set_syntax_flags

int set_syntax_flags( int flags,
[int|string syntable] )

Set syntax flags.

Description

The set_syntax_flags() primitive sets the active flags for the specified syntax table.

Parameters

flags	Integer syntax flags, one or more of the following flags OR’ed together control the attributes of the reference syntax table.
syntable	Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Flags

Flag	Description
SYNF_CASEINSENSITIVE	Case insensitive language tokens.
SYNF_FORTRAN	FORTRAN style language.
SYNF_STRING_ONELINE	String definitions dont continue over line breaks.
SYNF_LITERAL_NOQUOTES	Literals dont quote.
SYNF_COMMENTS_LEADINGWS	Dont hilite leading white-space.
SYNF_COMMENTS_TRAILINGWS	Dont hilite trailing white-space.
SYNF_COMMENTS_QUOTE	Allow comment charcter to be quoted.
SYNF_COMMENTS_CSTYLE	C-style comments.
SYNF_PREPROCESSOR_WS	Dont hilite leading white-space.
SYNF_LINECONT_WS	Allow white-space after cont token.
SYNF_HILITE_WS	Hilite white-space.
SYNF_HILITE_LINECONT	Hilite line continuations.
SYNF_HILITE_PREPROCESSOR	Hilite preprocessor directives.
SYNF_SPELL_WORD	Enable word spell check.
SYNF_SPELL_COMMENT	Enable comment spell check.

Returns

The set_syntax_flags() primitive returns the value of the resulting flags, otherwise -1 on error.

Portability

A GriefEdit extension.

syntax_build

void syntax_build( [int timestamp],
[string cache],
[int|string syntable] )

Build a syntax hiliting engine.

Description

The syntax_build() primitive constructs the underlying Deterministic Finite Automata (DFA) from the current set of defined rule via the syntax_rule primitive.

Parameters

timestamp	Optional numeric time reference, utilised to time-stamp the cache (See: time); should be modified upon each change to the DFA scheme.
cache	Optional name of the cache file image.
syntable	Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Returns

nothing

Portability

A GriefEdit extension.

syntax_column_ruler

int syntax_column_ruler( list ruler,
[string attribute],
[int|string syntable] )

Column syntax coloriser.

Description

The syntax_column_ruler() primitive sets the column originated syntax coloriser.

Parameters

ruler	Ruler specification, represented by a set of increasing integer columns plus an optional string containing an attribute name (See: set_color). If a columns trailing attribute is omitted then the default_attr argument is applied. A NULL ruler clears the current ruler.
default_attr	Optional default attribute specification, if omitted “hilite” is assumed.
syntable	Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Returns

The syntax_column_ruler() primitive returns the length of the resulting ruler, otherwise -1 on error.

Portability

A GriefEdit extension.

syntax_rule

void syntax_rule( string pattern,
string attribute,
[int|string syntable] )

Define a syntax hilite rule.

Description

The syntax_rule() primitive pushes a Deterministic Finite Automata (DFA) rule into the enhanced highlighting definition for the syntax table specified by syntable.

The rule is described by the regular expression contained within the string rule, and the associated attribute is then applied against any matched constructs.

These rules work alongside the basic syntax elements declared by syntax_token against the same syntax table.

For example, the rules to highlight floating point numbers could be encoding as;

syntax_rule("[0-9]+\\.[0-9]*([Ee][-+]?[0-9]*)?[fFlL]?[iIjJ]?", "float");
syntax_rule("[0-9]+[Ee][-+]?[0-9]*[fFlL]?[iIjJ]?", "float");

Note:

Consult the numerous bundled language mode definitions for working examples.

Parameters

pattern	Rule regular expression.
attribute	Attribute specification.
syntable	Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Attribute Specification

The attribute specification takes the following form. None or comma separated options plus the associated colour attribute (See: set_color).

[<option>[="....."] [, <option> ...] :] <attribute>

Options

word - possible word.
keyword - possible keyword.
tags - possible symbol within tagdb.
directive - possible preprocessor directive.
preproc/pp - enter preprocessor mode.
quick - quick expression evaluation. marks the regular expression for minimal closure, by default evaluation matches against the longest possible rule, quick short-circuits expression execution upon being matched, reducing the greedy nature of DFA regular expressions.
spell - apply spell checks.
todo - apply TODO checks.
markup - apply markup checks.
silent - silent regarding issues, for example non-existent children.
name=<name> - rule name.
group=<grpname> - group name, implied sub-rule.
color=<spec> - color specification, implies the creation of the attribute if it does not exist.
contains=<rule> - contains one or more rules.
contained - is contained within another rule.

Examples

Comment block, with both spelling and TODO token processing enabled.

"spell,todo:comment"

Normal text, yet token may be either a keyword or directive.

"keyword,directive:normal"

Rule Regular Expression

A regular expression is a pattern that the regular expression engine attempts to match in input text. A pattern consists of one or more character literals, operators, or constructs. For a brief introduction, see .NET Framework Regular Expressions.

Each section in this quick reference lists a particular category of characters, operators, and constructs that you can use to define regular expressions:

Character Escapes

The backslash character (\) in a regular expression indicates that the character that follows it either is a special character (as shown in the following table), or should be interpreted literally.

Escape	Description
\t	Tab.
\n	Newline.
\r	Return.
\f	Formfeed.
\a	Alarm (bell, beep, etc).
\e	Escape (\027).
\\	This escapes the meaning of a special.

Character Classes

A character class matches any one of a set of characters. Character classes include the language elements listed in the following table.

Escape	Description
[...]	Matches any one character contained within the character sequence.
.	Match any single character except newline.
\d	Same as [0-9].
\x	Same as [a-fA-f0-9].
\s	Same as [ \\t\\f].
\w	Same as [a-zA-Z_0-9].

Character Sequences

The conversion specification includes all subsequent characters in the format string up to and including the matching right square bracket (]).

The characters between the square brackets (the scanlist) comprise the scanset, unless the character after the left square bracket is a circumflex (^), in which case the scanset contains all characters that do not appear in the scanlist between the circumflex and the right square bracket.

If the conversion specification begins with “[]” or “[^]”, the right square bracket is included in the scanlist and the next right square bracket is the matching right square bracket that ends the conversion specification; otherwise the first right square bracket is the one that ends the conversion specification.

If a hyphen character (-) is in the scanlist and is not the first character, nor the second where the first character is a circumflex (^), nor the last character, it indicates a range of characters to be matched. To include a hyphen, make it the last character before the final close bracket. For instance, `[^]0-9-]’ means the set `everything except close bracket, zero through nine, and hyphen’.

Within a bracket expression, the name of a character class enclosed in [: and :] stands for the list of all characters (not all collating elements!) belonging to that class.

alnum	An alphanumeric (letter or digit).
alpha	A letter.
blank	A space, tab or form-feed character.
cntrl	A control character.
digit	A decimal digit.
graph	A character with a visible representation.
lower	A lower-case letter.
print	An alphanumeric (same as alnum).
punct	A punctuation character.
space	A character producing white space in displayed text.
upper	An upper-case letter.
word	”word” character (alphanumeric plus “_”).
xdigit	A hexadecimal digit.

Anchors

Anchors, or atomic zero-width assertions, cause a match to succeed or fail depending on the current position in the string, but they do not cause the engine to advance through the string or consume characters. The metacharacters listed in the following table are anchors.

Anchor	Description
^	If this is the first character of the regular expression, it matches the beginning of the line.
$	If this is the last character of the regular expression, it matches the end of the line.
\c	Anchor start of the matched text to the proceeding token.

Quantifiers

A quantifier specifies how many instances of the previous element must be present in the input string for a match to occur.

Anchor	Description
*	Match the preceding character or range of characters 0 or more times.
+	Match the preceding character or range of characters 1 or more times.
?	Match the preceding character or range of characters 0 or 1 times.

Specials

Grouping constructs delineate subexpressions of a regular expression and typically capture substrings of an input string.

Anchor	Description
\|	This symbol is used to indicate where to separate two sub regular expressions for a logical OR operation.
(..)	Group boundaries.
\\Q..\\E	A section enclosed in these symbols it taken literally. In side these sections, meta characters and special symbols have no meaning. If a \\E needs to appear in one of these sections, the \\ must be escaped with \\.

Returns

nothing

Portability

A GriefEdit extension.

syntax_token

void syntax_token( int type,
[<type1> param1],
[<type2> param2],
[int|string syntable] )

Define a syntax token.

Description

The syntax_token() primitive adds and/or modifies a syntax tokeniser element of the table specified by the first parameter table. The actual type and number of parameters vary according to the second parameter type.

Parameters

type	Table attribute.
param1	First parameter.
param2	Optional second parameter.
syntable	Optional syntax-table name or identifier, if omitted the current syntax table shall be referenced.

Table Attributes

The following SYNT table attribute are available;

SYNT_COMMENT	<COMMENT>, <open-string> [, <close>-string>] Comment syntax definition, defining either a block comment or an end-of-line comment. Block comments are specified as token pair, being an <open> and non new-line <close> strings, with end-of-line comments being a single <open> token.
SYNT_CSTYLE	<CSTYLE>, <character>\|<character-set>
SYNT_PREPROCESSOR	<PRE-PROCESSOR>, <character-set>
SYNT_STRING	<STRING>, <character-set>
SYNT_LITERAL	<LITERAL>, <character-set>
SYNT_LINECONT	<LINECONT>, <character>
SYNT_LINEJOIN	<LINEJOIN>, <character>
SYNT_QUOTE	<QUOTE>, <character-set>
SYNT_CHARACTER	<CHARACTER>, <character-set>
SYNT_BRACKET	<BRACKET>, <open> [, <close>]
SYNT_HTML	<HTML>, <open>, <close>
SYNT_TAG	<TAG>, <type>, <word,word...>
SYNT_WORD	<WORD>, <character-set> Defines the character-set which represent a single word.
SYNT_KEYWORD	<KEYWORD>, <character-set> Defines the character-set which represent a single keyword.
SYNT_NUMERIC	<NUMERIC>, <primary-set> [, <secondary-set>]
SYNT_OPERATOR	<OPERATOR>, <character>
SYNT_DELIMITER	<DELIMITER>, <character-set>
SYNT_FORTRAN	<FORTRAN>, <character-set>, <[left-margin], code [,comment-margin]>

Returns

nothing

Portability

A GriefEdit extension.

Syntax Highlighting Primitives

Macros

attach_syntax

Description

Parameters

Returns

Portability

See Also

create_syntax

Description

Parameters

Returns

Portability

See Also

define_keywords

Description

Description

Keyword Tables

Returns

Portability

See Also

detach_syntax

Description

Parameters

Returns

Portability

See Also

get_color_pair

Description

Parameters

Returns

Portability

See Also

hilite_create

Description

Parameter

Returns

Portability

See Also

hilite_delete

Description

Parameter

Returns

Portability

See Also

hilite_destroy

Description

Parameter

Returns

Portability

See Also

inq_hilite

Description

Parameters

Returns

Portability

See Also

inq_syntax

Description

Parameters

Returns

Portability

See Also

inq_syntax_name

Description

Parameters

Returns

Portability

See Also

set_color_pair

Description

Parameters

Returns

Portability

See Also

set_syntax_flags

Description

Parameters

Flags

Returns