DTE-SYNTAX(5)

🦋 DTE-SYNTAX(5) — the file format manual, but make it cute 🦋

okay bestie, so this is dte-syntax, the whole entire vibe of the syntax highlighting files that dte(1) uses. yes THE editor. she reads these files, she highlights ur code, she slays. let's get into it 💅

---

✨ SYNOPSIS ✨

Commands, in all their glory:

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 🌸

So a dte syntax file is literally just a bunch of states. Each state has some optional conditionals and then exactly one default action. that's the whole structure, no cap.

The best way to actually get it is to go read some of the built-in syntax files, which you can print out with dte -b, like:

dte -b syntax/dte

The base syntax is the same as in dterc(5) files, but the commands available are different. same grammar, different menu, iykyk.

Conditionals and default actions both have a destination state. And there's one special destination state — this — which jumps you to the current state. she's a lil shortcut, she's iconic.

---

👑 COMMANDS 👑

💖 Main commands

• syntax name — Start a whole new syntax. One syntax file can hold multiple syntax definitions, but bestie, you should only define one real syntax in one syntax file. fr.

See also: sub-syntaxes. (they're down below, don't worry 🫶)

• state name [emit-color] — Add a new state. Conditionals (if there are any) and one default action must follow it. The first state is the start state. she goes first, main character energy.
• default color name... — Set the default color for an emitted name.

Example:

default numeric oct dec hex

So if there's no color defined for oct, dec or hex, then the color numeric gets used instead. fallback queen 💅

• list [-i] name string... — Define a list of strings.

Example:

list keyword if else for while do continue switch case

Then use the inlist command to check whether a buffered string is in the list.

• -i — Make the list case-insensitive.

🌈 Conditionals

• bufis [-i] string destination [emit-name] — Test whether the buffered bytes are the same as string. If they are: emit emit-name and jump to the destination state.
  • -i — Case-insensitive.
• char [-bn] characters destination [emit-name] — Test whether the current byte is in the characters list. If it is, then emit emit-color and jump to the destination state. If emit-name isn't given, then the destination state's emit name gets used instead.

characters is a list of strings. Ranges are supported — a-d is the same as abcd. cute right?

• -b — Add byte to buffer.
• -n — Invert character bitmap.

• heredocend destination — Compare the following characters to the heredoc end delimiter, and go to the destination state if the comparison is true.
• inlist list destination [emit-name] — Test whether the buffered bytes are found in list. If found: emit emit-name and jump to the destination state.
• str [-i] string destination [emit-name] — See if the following bytes are the same as string. If they are: emit emit-name and jump to the destination state.
  • -i — Case-insensitive.

⚠️ NOTE: This conditional can be slow, especially if string is longer than two bytes. she's pretty but she's not fast, ok 😭

🎀 Default actions

The last command of every state must be a default action. It's an unconditional jump. no conditions, she just goes.

• eat destination [emit-name] — Consume a byte, emit the emit-name color, and continue to the destination state.
• heredocbegin subsyntax return-state — Store the buffered bytes as the heredoc end delimiter and go to subsyntax. A sub-syntax is like any other sub-syntax, except it must contain a heredocend conditional. mandatory. non-negotiable.
• noeat [-b] destination — Continue to the destination state without emitting color and without consuming a byte.
  • -b — Don't stop buffering.

🍓 Other commands

• recolor color [count] — If count is given, recolor count previous bytes. Otherwise, recolor the buffered bytes.

---

🧚 SUB-SYNTAXES 🧚

Sub-syntaxes are lowkey the best thing ever when you need the same states in a bunch of different contexts. reusable. sustainable. iconic.

Sub-syntax names must be prefixed with .. And it's recommended that you 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 gets replaced by the state specified in another syntax. she's a placeholder, she's a chameleon 💅

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

So 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 gets copied into the main syntax, and every destination state in the sub-syntax whose name is END gets replaced with c. it's a copy-paste but make it elegant ✨

---

🔥 SEE ALSO 🔥

dte(1), dterc(5)

---

💜 AUTHORS 💜

Craig Barnes Timo Hirvonen

---

okay and that's the whole page bestie — this was the <b>File Formats Manual</b> entry DTE-SYNTAX(5), dated May 2020, and yes that date is giving vintage but she still eats. go forth and highlight ur little heart out 🫶✨