DOKK / manpages / debian 12 / dte / dte-syntax.5.en
DTE-SYNTAX(5) File Formats Manual DTE-SYNTAX(5)

dte-syntax - Format of syntax highlighting files used by dte(1)

Commands:

Main commands:
syntax name
state name [emit-color]
default color name...
list [-i] name string...

Conditionals:
bufis [-i] string destination [emit-name]
char [-bn] characters destination [emit-name]
heredocend destination
inlist list destination [emit-name]
str [-i] string destination [emit-name]

Default actions:
eat destination [emit-name]
heredocbegin subsyntax return-state
noeat [-b] destination

Other commands:
recolor color [count]

A dte syntax file consists of multiple states. A state consists of optional conditionals and one default action. The best way understand the syntax is to read through some of the built-in syntax files, which can be printed with dte -b, for example:

dte -b syntax/dte

The basic syntax used is the same as in dterc(5) files, but the available commands are different.

Conditionals and default actions have a destination state. The special destination state this can be used to jump to the current state.

syntax name

Begin a new syntax. One syntax file can contain multiple syntax definitions, but you should only define one real syntax in one syntax file.

See also: sub-syntaxes.

state name [emit-color]

Add new state. Conditionals (if any) and one default action must follow. The first state is the start state.

default color name...

Set default color for emitted name.

Example:

default numeric oct dec hex

If there is no color defined for oct, dec or hex then color numeric is used instead.

list [-i] name string...

Define a list of strings.

Example:

list keyword if else for while do continue switch case

Use the inlist command to test if a buffered string is in a list.

Make list case-insensitive.

bufis [-i] string destination [emit-name]

Test if buffered bytes are same as string. If they are, emit emit-name and jump to destination state.
Case-insensitive.

char [-bn] characters destination [emit-name]

Test if current byte is in the characters list. If it is then emit emit-color and jump to destination state. If emit-name is not given then the destination state's emit name is used.

characters is a list of strings. Ranges are supported (a-d is the same as abcd).

Add byte to buffer.
Invert character bitmap.

heredocend destination

Compare following characters to heredoc end delimiter and go to destination state if comparison is true.

inlist list destination [emit-name]

Test if buffered bytes are found in list. If found, emit emit-name and jump to destination state.

str [-i] string destination [emit-name]

See if following bytes are same as string. If they are, emit emit-name and jump to destination state.
Case-insensitive.

NOTE: This conditional can be slow, especially if string is longer than two bytes.

The last command of every state must be a default action. It is an unconditional jump.

eat destination [emit-name]

Consume byte, emit emit-name color and continue to destination state.

heredocbegin subsyntax return-state

Store buffered bytes as heredoc end delimiter and go to subsyntax. Sub-syntax is like any other sub-syntax but it must contain a heredocend conditional.

noeat [-b] destination

Continue to destination state without emitting color or consuming byte.
Don't stop buffering.

recolor color [count]

If count is given, recolor count previous bytes, otherwise recolor buffered bytes.

Sub-syntaxes are useful when the same states are needed in many contexts.

Sub-syntax names must be prefixed with .. It's recommended to also use the main syntax name in the prefix. For example .c-comment if c is the main syntax.

A sub-syntax is a syntax in which some destination state's name is END. END is a special state name that is replaced by the state specified in another syntax.

Example:

# Sub-syntax
syntax .c-comment
state comment
    char "*" star
    eat comment
state star comment
    # END is a special state name
    char / END comment
    noeat comment
# Main syntax
syntax c
state c code
    char " \t\n" c
    char -b a-zA-Z_ ident
    char "\"" string
    char "'" char
    # Call sub-syntax
    str "/*" .c-comment:c
    eat c
# Other states removed

In this example the destination state .c-comment:c is a special syntax for calling a sub-syntax. .c-comment is the name of the sub-syntax and c is the return state defined in the main syntax. The whole sub-syntax tree is copied into the main syntax and all destination states in the sub-syntax whose name is END are replaced with c.

dte(1), dterc(5)

Craig Barnes
Timo Hirvonen

May 2020