bat/src/syntax_mapping/builtins

/src/syntax_mapping/builtins

The files in this directory define path/name-based syntax mappings, which amend and take precedence over the extension/content-based syntax mappings provided by syntect.

File organisation

Each TOML file should describe the syntax mappings of a single application, or otherwise a set of logically-related rules.

What defines "a single application" here is deliberately vague, since the file-splitting is purely for maintainability reasons. (Technically, we could just as well use a single TOML file.) So just use common sense.

At compile time, the build script will collect all the syntax mappings defined by the TOML files within this directory, and embed them into the binary.

File syntax

Each TOML file should contain a single section named mappings, with each of its keys being a language identifier (first column of bat -L).

The value of each key should be an array of strings, with each item being a glob matcher. We will call each of these items a "rule".

For example, if foo-application uses both TOML and YAML configuration files, we could write something like this:

# 30-foo-application.toml
[mappings]
"TOML" = [
    # rules for TOML syntax go here
    "/usr/share/foo-application/toml-config/*.conf",
    "/etc/foo-application/toml-config/*.conf",
]
"YAML" = [
    # rules for YAML syntax go here
    # ...
]

Dynamic environment variable replacement

In additional to the standard glob matcher syntax, rules also support dynamic replacement of environment variables at runtime. This allows us to concisely handle things like XDG.

All environment variables intended to be replaced at runtime must be enclosed in ${}, for example "/foo/*/${YOUR_ENV}-suffix/*.log". Note that this is the only admissible syntax; other variable substitution syntaxes are not supported and are thus treated as plain text.

For example, if foo-application also supports per-user configuration files, we could write something like this:

# 30-foo-application.toml
[mappings]
"TOML" = [
    # rules for TOML syntax go here
    "/usr/share/foo-application/toml-config/*.conf",
    "/etc/foo-application/toml-config/*.conf",
    "${XDG_CONFIG_HOME}/foo-application/toml-config/*.conf",
    "${HOME}/.config/foo-application/toml-config/*.conf",
]
"YAML" = [
    # rules for YAML syntax go here
    # ...
]

If any environment variable replacement in a rule fails (for example when a variable is unset), the entire rule will be ignored.

Explicitly mapping to unknown

Sometimes it may be necessary to "unset" a particular syntect mapping - perhaps a syntax's matching rules are "too greedy", and is claiming files that it should not. In this case, there are two special identifiers: MappingTarget::MapToUnknown and MappingTarget::MapExtensionToUnknown (corresponding to the two variants of the syntax_mapping::MappingTarget enum).

An example of this would be *.conf files in general. So we may write something like this:

# 99-unset-ambiguous-extensions.toml
[mappings]
"MappingTarget::MapExtensionToUnknown" = [
    "*.conf",
]

Ordering

At compile time, all TOML files are processed in filesystem order. So 00-foo.toml takes precedence over 10-bar.toml, which takes precedence over 20-baz.toml, and so on. This may be occasionally useful for creating high/low priority rules, such as in the aforementioned example of explicitly mapping *.conf files to unknown.

Generally this should not be much of a concern, since rules should be written as specifically as possible for each application.

Rules within each TOML file are inserted (and therefore processed) in the order in which they are defined.