NAME

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

SYNOPSIS

       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]

DESCRIPTION

       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.

COMMANDS

   Main commands
       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.

              -i     Make list case-insensitive.

   Conditionals
       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.

              -i     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).

              -b     Add byte to buffer.

              -n     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.

              -i     Case-insensitive.

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

   Default actions
       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.

              -b     Don't stop buffering.

   Other commands
       recolor color [count]
              If count is given, recolor count previous bytes, otherwise recolor buffered bytes.

SUB-SYNTAXES

       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.

SEE ALSO

       dte(1), dterc(5)

AUTHORS

       Craig Barnes
       Timo Hirvonen

                                                    May 2020                                       DTE-SYNTAX(5)