What are the rules for identifiers in Typst?

Yahuxo · September 25, 2024, 11:17am

The scripting part of Typst allows users to define their own functions and variables. From my tests it seems that these identifiers are allowed to contain Unicode characters (including underscores and dashes).

Example:

#let ÿøúr-nãmê = "Typst"
Hello, #ÿøúr-nãmê!

Using a plain underscore character “_” for identifiers does not fully work, though. You can define a variable like #let _ = [Foo] but referencing it seems to cause errors.

What are the exact rules for identifiers in Typst? And what are best practices, e.g. for shared templates?

xkevio · September 25, 2024, 12:11pm

According to the lexer inside of Typst’s source code, an identifier is valid if it follows the Unicode standard uax31 and, additionally, Typst allows _ as a starting and continuing character and - as a continuing character.

github.com

typst/typst/blob/main/crates/typst-syntax/src/lexer.rs#L898-L911


      
          /// Whether a string is a valid Typst identifier.
          ///
          /// In addition to what is specified in the [Unicode Standard][uax31], we allow:
          /// - `_` as a starting character,
          /// - `_` and `-` as continuing characters.
          ///
          /// [uax31]: http://www.unicode.org/reports/tr31/
          #[inline]
          pub fn is_ident(string: &str) -> bool {
              let mut chars = string.chars();
              chars
                  .next()
                  .is_some_and(|c| is_id_start(c) && chars.all(is_id_continue))
          }

As for how users should name their variables and functions, the standard seems to be kebab-case. Referencing a variable with just an underscore won’t work since that is probably reserved for explicitly nameless variables.