Skip to content

Latest commit

 

History

History
712 lines (700 loc) · 25 KB

syntax-naming-conventions.md

File metadata and controls

712 lines (700 loc) · 25 KB
Raw
title
Syntax Naming Conventions

Syntax Naming Conventions

Naming conventions provide predefined names for similar tokens in different languages. These language-agnostic names, called syntax classes, help themes highlight code without relying on language-specific vocabulary.

When creating a language grammar, use these conventions to determine which syntax classes correspond to your syntax nodes. When creating a syntax theme, use these conventions to determine which syntax classes correspond to your theme colors.

Guidelines for Language Grammars

The syntax classes are organized into nested categories. In a language grammar, multiple nested classes can be applied to a syntax node by appending them with periods, as in entity.function.call. The order in which classes are appended does not affect the resulting highlighting. However, we recommend following their hierarchy to stay consistent.

Root classes, like ▶ entity, must not be appended to other root classes, unless explicitly allowed in this documentation. Main classes indicated in bold green, like function, must be used for coherent highlighting. Shared classes indicated in brackets, like [call], can be appended when relevant. You may create additional classes if they clarify your grammar and do not introduce conflicts with existing classes.

Guidelines for Syntax Themes

In a syntax theme, styling can be applied to a syntax class with the syntax-- prefix, as in syntax--entity. When targeting a nested class, specify its parent classes by prepending them with periods, as in syntax--entity.syntax--function.syntax--call. A typical styling rule would look like this:

.syntax--entity.syntax--function.syntax--call {
  color: blue;
}

List of Syntax Classes

Click on root classes to reveal more nested classes.

__`keyword`__ — A keyword.
  • __`[symbolic]`__ — A keyword with no alphabetic characters.
  • __`control`__ — A control or structure keyword.
    • `condition` — A condition keyword. Examples: `if`, `else`, `elif`.
    • `loop` — A loop keyword. Examples: `for`, `for`...`in`, `for`...`of`, `do`, `while`.
    • `exception` — An exception keyword. Examples: `try`, `catch`, `finally`.
    • `jump` — A keyword used to jump to/from a statement. Examples: `break`, `continue`, `pass`, `return`, `yield`, `throw`, `await`.
    • `package` — A keyword for imports or exports. Examples: `import`, `from`, `include`, `export`, `require`.
    • `directive` — An instruction given to the compiler. Examples: `#include`, `#define`, `#ifdef`, `using`, `package`, `use strict`.
    • `evaluate` — A keyword used to evaluate an expression. Examples: `assert`, `with`...`as`.
  • __`storage`__ — A storage keyword.
    • `modifier` — A keyword to detail the behavior of an entity. Examples: `static`, `abstract`, `final`, `throws`, `get`, `extends`.
    • `declaration` — A keyword to declare an entity. Examples: `let`, `const`, `func`, `def`, `class`, `enum`, `typedef`, `namespace`.
  • __`type`__ — A type keyword. Examples: `char`, `int`, `bool`, `void`.
    • `wildcard` — A wildcard keyword for an unknown type. Example: `?` in `List list`.
  • __`operator`__ — An operator keyword. Includes overloaded operators.
    • `logical` — A logical operator. Examples: `and`, `not`, `or`, `!`, `&&`, `||`.
    • `ternary` — A ternary condition operator. Examples: `?`, `:`.
    • `assignment` `(compound)` — An assignment operator. Examples: `=`, `:=`, `+=`, `-=`, `*=`, `%=`.
    • `comparison` — A comparison operator. Examples: `==`, `<`, `>`, `!=`, `in`, `instanceof`.
    • `arithmetic` — An arithmetic operator. Examples: `+`, `-`, `/`, `*`, `@`, `++`, `--`.
    • `pointer` `(reference)` `(dereference)` — A pointer operator. Examples: `&`, `*`.
    • `bitwise` — A bitwise operator. Examples: `<<`, `>>`, `|`, `&`, `^`, `~`.
    • `instance` — A instance operator. Examples: `del`, `delete`, `new`, `typeof`.
    • `composition` — A composition operator (Haskell). Example: `.`.
    • `combinator` — A combinator operator (CSS). Examples: `>`, `+`, `~`, `&`.
  • __`function`__ — A function keyword. Example: `super`.
  • __`variable`__ — A variable keyword. Examples: `this`, `self`, `@`.
__`entity`__ — An identifier.
  • `[parameter]` — A parameter in a definition or declaration or call. Examples: `myFunction(parameter = argument)`, `class MyClass {}`.
  • `[argument]` — An argument in a call. Examples: `instance.method(argument)`, `new MyClass(argument)`.
  • `[definition]` — An entity that is being defined or declared. Examples: `my_variable` in `let my_variable`, `myFunction` in `def myFunction()`.
  • `[call]` — An entity that is being called. Examples: `myFunction` in `myFunction()`, `MyClass` in `new MyClass(argument)`.
  • `[mutable]` — An entity whose properties or value can be changed. Examples: `var mutable`, `let mutable`.
  • `[immutable]` — An entity whose properties or value cannot be changed. Examples: `const immutable`, `final immutable`.
  • __`[support]`__ — A built-in/imported/conventional entity that can usually be redefined. Examples: `self`, `cls`, `arguments`, `iota`, `len`, `print`, `loop`, `int`, `bool`.
  • __`variable`__ — A variable.
    • `member` — A member variable in an object. Examples: `{property: value}`, `object.attribute`.
  • __`function`__ — A function.
    • `cast` — A type casting function that is not a type itself. Examples: `as.matrix()`, `toInt()`.
    • `method` `(constructor)`— A method in an object. Examples: `{method: (parameter) => value}`, `object.method()`.
    • `lambda` — A lambda. Example: `lambda = ->() {}`.
    • `infix` — A function used in infix notation. Example: ``1 `function` 2``.
  • __`operator`__ — An operator.
    • __`[symbolic]`__ — An operator with no alphabetic characters. Examples: `%>%`, `<+>`.
  • __`type`__ — A type.
    • `[cast]` — A type used for type casting, eventually in functional notation. Examples: `float(32)`, `int(3.2)`, `matrix()`.
    • `[constructor]` — A type used as a constructor, eventually in functional notation. Examples: `new MyClass()`.
    • __`fundamental`__ — A fundamental primitive or composite type. Examples: `char`, `int`, `bool`, `rune`, `list`, `map`, `tuple`.
    • `class` — A class. Examples: `MyClass`, `String`, `List`.
      • `inherited` — An inherited class. Example: `class Child < Inherited`.
      • `mixin` — A mixin class. Example: `module Mixin` (Ruby).
      • `generic` — A generic class. Examples: ``, ``.
      • `exception` — An exception. Example: `AssertionError`.
      • `abstract` — An abstract class. Example: `abstract class Abstract` (Java)
    • `interface` — An interface. Example: `Vehicle` in `public interface Vehicle {}`.
    • `enumeration` — An enumeration. Example: `Color` in `enum Color{red, green, blue}`.
    • `structure` — A structure. Examples: `Address` in `type Address struct {}`.
    • `union` — An union. Example: `IPv4` in `union IPv4 {}`.
    • `alias` — An alias. Example: `Number` in `typedef int Number`.
  • `annotation` — An annotation. Examples: `@Override` (Java), `#[test]` (Rust), `[Obsolete]` (C#).
  • `namespace` — A namespace. Examples: `namespace Namespace {}` (C++), `namespace::function()` (Rust).
  • `package` — A package. Example: `from package import entity`.
  • `label` — A statement label. Example: `goto label`.
  • `lifetime` — A lifetime (Rust). Example: `'static`.
  • __`tag`__ — A tag (HTML). Examples: `body`, `div`, `input`.
  • __`attribute`__ `(id)` `(class)` — An attribute (HTML). Example: ``.
  • __`property`__ — A property (CSS). Example: `{property: value}`.
  • __`selector`__ `(tag)` `(id)` `(class)` `(pseudo-)` `(attribute)` — A selector (CSS). Examples: `#id`, `.class`, `:hover`, `:not`, `::before`, `::after`, `[attribute]`.
__`string`__ — A string or part of a string.
  • `[argument]` — An argument in a call. Examples: `myFunction("string")`, `new MyClass('string')`.
  • `[mutable]` — A mutable string. Specified when mutable and immutable coexist. Example: `'string'` (Ruby).
  • `[immutable]` — An immutable string. Specified when mutable and immutable coexist. Example: `:immutable` (Ruby).
  • `[key]` — A key in a key-value pair. Example: `{"key" => value}`.
  • `[quoted]` — A quoted string. Examples: `"string"`, `'string'`, `$"template string"`, `/^regexp string$/`.
  • `[unquoted]` — An unquoted string. Example: `'key': unquoted`.
  • __`[part]`__ — A part of a string.
    • `interpolation` — An interpolation. Examples: `${variable}`, `{variable:<30}`.
    • `placeholder` — A placeholder. Examples: `%()d`, `{0:.2f}`, `%-#10x`, `\1`.
    • `format` — A format specifier. Examples: `<30`, `d`, `.2f`, `-#10x`.
  • __`regexp`__ — A regular expression. Example: `/^regexp$/`.
    • __`[part]`__ — A part of a regular expression.
      • __`language`__ — A regular expression keyword.
        • __`[symbolic]`__ — A keyword with no alphabetic characters.
        • `control` `(anchor)` `(reference)` `(mode)` — A control token. Examples: `^`, `$`, `\b`, `\k`, `\1`, `i` in `(?i)`, `g` in `/^regexp$/g`.
        • `operator` `(quantifier)` — A quantifier operator. Examples; `?`, `*`, `+`, `{1,2}`.
      • __`variable`__ — A regular expression variable. Examples: `(?)`, `\k`.
      • `group` — A regular expression group. Examples: `(capture)`, `(?:non-capture)`.
      • `lookaround` — A regular expression lookaround. Example: `(?=lookahead)`.
      • `set` — A regular expression set. Example: `[^A-Z]`.
  • `template` — A template string. Examples: `$"string {interpolation}"`, `` `string ${interpolation}` ``.
  • `heredoc` — A here document. Example: `<
__`constant`__ — A literal other than a string.
  • `[argument]` — An argument in a call. Examples: `myFunction(constant)`, `float(constant)`.
  • `[key]` — A key in a key-value pair. Example: `{key: value}`.
  • `[quoted]` — A quoted constant. Example: `'a'`.
  • `[unquoted]` — An unquoted constant. Example: `#color`.
  • __`[support]`__ — A built-in or imported or conventional constant. Examples: `absolute`, `blue`, `screen`.
  • __`[language]`__ — A literal keyword.
    • __`[symbolic]`__ — A keyword with no alphabetic characters. Example: `...` (Python).
    • `boolean` — A boolean. Examples: `true`, `false`.
    • `null` — A null value. Examples: `None`, `null`, `nil`.
    • `undefined` — An undefined value. Example: `undefined`.
    • `numeric` — A numeric word. Example: `Infinity`.
  • __`numeric`__ — A number.
    • `integer` — An integer. Example: `2`.
    • `decimal` — A decimal number. Example: `.17`.
    • `hexadecimal` — A hexadecimal number. Example: `0x29`.
    • `unit` — A length unit (CSS). Examples: `%`, `px`, `pt`, `em`.
    • `duration` — A duration (Lilypond). Examples: `8`, `2.`.
  • __`character`__ — A character. Example: `'a'`.
    • `[escape]` — An escape sequence. Examples: `\"`, `\\`, `\i`, `\?`, `\u2661`, `\n`, `\d`, `\W`.
    • __`code`__ — A substitute for another character. Examples: `<`, `\x2f`, `\n`.
      • `shorthand` — A shorthand for other characters (RegExp). Examples: `.`, `\d`, `\W`, `\s`.
      • `range` — A range of characters (RegExp). Examples: `a-z`, `0-9`.
      • `whitespace` — A whitespace character. Examples: `\t`, `\f`.
        • `newline` — A newline character. Examples: `\n`, `\r`.
      • `unicode` — A unicode code point. Example: `\u2661`.
      • `hexadecimal` — A hexadecimal code point. Example: `\x2f`.
      • `octal` — An octal code point. Example: `\143`.
  • `color` — A color (CSS). Examples: `crimson`, `#a35`.
    • `prefix` — A color prefix. Example: `#`.
  • `font` — A font (CSS). Examples: `Helvetica`, `Times New Roman`.
  • `style` — A style (CSS). Examples: `break-word`, `solid`, `absolute`.
__`text`__ — Plain text.
__`markup`__ — Stylized text.
  • `heading` — A heading. Example: `# Heading`.
  • `list` — A list item. Examples: `1. item`, `- item`.
  • `quote` — A quote. Example: `> quote`.
  • `bold` — Bold text. Example: `**bold**`.
  • `italic` — Italic text. Example: `*italic*`.
  • `underline` — Underlined text. Example: `__underline__`.
  • `strike` — Striked-through text. Example: `~~strike~~`.
  • `raw` — Raw unformatted text or code. Example: `` `raw` ``.
  • `link` — An url or path or reference. Examples: `url.com`, `(path)` in `[alt](path)`, `[reference]`.
  • `alt` — Alternate text for a link. Examples: `[alt]`, `![alt]`.
  • `critic` — A critic.
    • `inserted` — An insertion. Example: `{++ inserted ++}`.
    • `deleted` — A deletion. Example: `{-- deleted --}`.
    • `changed` — A modification. Example: `{~~ from ~> to ~~}`.
    • `commented` — A comment. Example: `{>> commented <<}`.
    • `highlighted` — A highlight. Example: `{== highlighted ==}`.
__`comment`__ — A comment or part of a comment. Includes comments in strings.
  • __`[part]`__ — A part of a comment.
    • `caption` — A caption in a comment. Examples: `@param`, ``, `NOTE`, `TODO`, `FIXME`.
    • `path` — A path in a comment. Example: `path/to/my-file`.
    • `term` `(variable)` `(function)` `(operator)` `(type)` — A documented entity. Examples: `type` and `variable` in `@param {type} variable`.
  • `line` — A one-line comment. Example: `# comment`.
  • `block` — A multi-line comment. Example: `/* ... */`.
__`punctuation`__ — A punctuation mark.
  • __`definition`__ — Punctuation that defines tokens.
    • __`string`__ — Punctuation for a string. Examples: `"`, `'`, `$"`.
      • __`regexp`__ — Punctuation for a regular expression. Examples: `r"`, `/`.
    • __`constant`__ — Punctuation for a literal other than a string.
      • __`character`__ — Punctuation for a character. Example: `'`.
    • __`markup`__ — Punctuation for text styling (Markdown). Examples: `_`, `*`, `~`, `#`, `-`. `1.`, `[`, `]`.
    • __`comment`__ — Punctuation for a comment. Examples: `//`, `#`, ``.
    • `collection` — Punctuation for a collection (array, set, map, etc.). Examples: `[`, `]`, `{`, `}`.
    • `variable` — Punctuation for a variable. Example: `$`.
    • `function` `(generator)` — Punctuation for a function. Examples: `` ` ``, `*`.
    • `operator` — Punctuation for an operator. Examples: `(`, `)`.
    • `package` `(wildcard)` — Punctuation for a package. Examples: `.`, `*`.
    • `annotation` — Punctuation for an annotation. Examples: `@` (Java), `#![]` (Rust).
    • `decorator` — Punctuation for a decorator. Example: `@` (Python).
    • `tag` — Punctuation for a tag (HTML). Examples: `<`, `/>`.
    • `selector` `(wildcard)` — Punctuation for a selector (CSS). Examples: `*`, `.`, `#`, `:`, `::`, `[`, `]`.
  • __`operation`__ — Punctuation to operate on tokens.
    • `variadic` — Punctuation to operate on variadic arguments. Examples: `...`, `*`, `**`.
    • `lambda` — Punctuation to operate on lambda parameters. Example: `->` in `(parameter) -> expression`.
  • __`association`__ — Punctuation to associate values to tokens.
    • `pair` — Punctuation to associate an expression to a key. Examples: `:` in `key: value`, `=>` in `None => println!("Nothing")`.
    • `iterator` — Punctuation to associate an expression to an iterator. Example: `:` in `auto& iterator : items`.
  • __`accessor`__ — Punctuation to access contained entities.
    • `member` — Punctuation for member access. Examples: `.`, `->`.
    • `scope` — Punctuation for scope resolution. Example: `::`.
  • __`delimiter`__ — Punctuation to delimit tokens.
    • __`string`__ — Punctuation to delimit tokens in a string.
      • __`[part]`__ — Punctuation to delimit a part of a string.
        • `interpolation` — Punctuation to delimit an interpolation. Examples: `#{`, `${`, `}`.
        • `placeholder` — Punctuation to delimit a placeholder. Examples: `{`, `}`, `%`, `%(`, `)`.
        • `format` — Punctuation to delimit a format specifier. Example: `:`.
      • __`regexp`__ — Punctuation to delimit tokens in a regular expression.
        • __`[part]`__ — Punctuation to delimit a part of a regular expression.
          • `group` — Punctuation to delimit a group. Examples: `(?:`, `(`, `(?P`, `)`.
          • `lookaround` — Punctuation to delimit a lookaround. Examples: `(?=`, `(?!`, `)`.
          • `disjunction` — Punctuation to delimit a disjunction. Example: `|`.
          • `set` — Punctuation to delimit a set. Examples: `[^`, `[`, `]`.
          • `mode` — Punctuation to delimit a mode specifier. Examples: `(?`, `)`.
    • __`comment`__ — Punctuation to delimit tokens in a comment.
      • __`[part]`__ — Punctuation to delimit a part of a comment.
        • `caption` — Punctuation to delimit a caption. Examples: `<`, `>`, `:`.
        • `term` — Punctuation to delimit a documented entity. Examples: `{` and `}` in `{type}`.
    • `parameters` — Punctuation to delimit parameters. Examples: `(`, `)`.
    • `arguments` — Punctuation to delimit arguments. Examples: `(`, `)`.
    • `subscript` — Punctuation to delimit a subscript. Examples: `[`, `]`.
    • `type` — Punctuation to delimit a type or return type. Examples: `<`, `:`, `->`, `(`, `)`.
    • `body` — Punctuation to delimit a body. Examples: `{`, `}`, `:`.
    • `statement` — Punctuation to delimit a statement. Examples: `{`, `}`, `:`.
    • `expression` — Punctuation to delimit an expression. Examples: `(`, `)`.
    • `embedded` — Punctuation to delimit embedded code. Examples: `~~~`, `<%=`, `%>`.
    • `package` — Punctuation to delimit package imports or exports. Examples: `(` `)`, `{`, `}`.
  • __`separator`__ — Punctuation to separate similar tokens. Examples: `,`, `\`.
  • __`terminator`__ — Punctuation to terminate a statement. Example: `;`.
`[invalid]` — An invalid token. Appendable to every class.
  • `deprecated` — A deprecated token which should no longer be used.
  • `illegal` — An illegal token which doesn't belong there.
`meta` — A larger part of the document encompassing multiple tokens.
  • `function` — A function definition block.
  • `class` — A class definition block.
  • `embedded` — A language embedded in another.