syntastica

Modern and easy syntax highlighting using tree-sitter

Note

If viewing this file on GitHub or crates.io, some links might not be working. Go to the custom docs page or the docs.rs page instead, which additionally include the Features section.

Overview

To use syntastica, you probably want to depend on three crates:

1. The main syntastica crate for all the logic.
2. A parser collection to provide language support (see parser collections)
3. The theme collection for some default themes (see theme collection)

So for example:

syntastica = "<version>"
syntastica-parsers = { version = "<version>", features = ["some"] }
syntastica-themes = "<version>"

Use cases

syntastica has three main ways of highlighting code, for three different use cases:

1. Highlight one input exactly once: see [highlight] and this example
2. Highlight one input multiple times (e.g. with different themes or renderers): see [Processor::process_once], [render], and this example
3. Highlight multiple different inputs any number of times: see [Processor], [render], and this example

Using syntastica as a Git Dependency

Using syntastica-queries, and in turn any crate in this workspace which depends on syntastica-queries, as a git dependency with cargo is not immediately possible, because the auto-generated query files are not checked in. For that purpose, the git-deploy is updated with the latest state of the main branch after every push. That means you can depend on for example syntastica-parsers-git like this:

syntastica-parsers-git = { git = "https://github.com/RubixDev/syntastica", branch = "git-deploy" }

Subprojects

Besides the main syntastica crate, many other crates for different purposes were developed and are included in the repository. This section aims to provide a good overview.

Parser collections

The main syntastica crate provides no tree-sitter parsers and queries by itself. However, the project does provide four different parser collections with different advantages and drawbacks each. Three of them depend on syntastica-queries for the tree-sitter queries. Choose one, and add it as a dependency next to syntastica itself.

The odd one out here is syntastica-parsers-dynamic, which unlike the others doesn't actually include any parsers but instead provides an interface to load them during runtime.

The other three parser collections all provide the same public API and have features for all supported languages, as well as the three feature groups some, most, and all. Take a look at the respective crate documentation for more information.

If you want to additionally use languages that are not in any of these parser collections or combine multiple sets, have a look at the Union type or the custom languages example.

• syntastica-parsers is probably the easiest to start with. It uses parsers from crates.io. This has the main benefit of being well integrated in the cargo ecosystem. However, many tree-sitter parsers do not get published to crates.io, and those that are, are usually very outdated. Thus, this collection is relatively limited.
• <a name="syntastica-parsers-git" href="https://crates.io/crates/syntastica-parsers-git"><code>syntastica-parsers-git</code></a> is probably the best choice overall. It contains all supported languages and is the only choice when targeting WebAssembly. It pulls pinned revisions of parser git repositories in the build script and links to the C and C++ parser sources. As such, it does not depend on the upstream parsers to have up-to-date Rust bindings. However, this way of fetching the parsers requires the git command to be accessible and internet access during compilation, which may not be desirable. Additionally, compilation can take very long unless you manually specify a cache directory that can be reused between builds. See the crate's docs for more information on that.
• syntastica-parsers-gitdep is a mix of both of the above. It uses cargo git dependencies to fetch the parser repositories and depends on a remote Rust binding (which is why not all parsers are included). The main disadvantages are that this collection cannot be published to crates.io, because it depends on crates that are not on crates.io (namely the parsers). This means, to use it you must also depend on it using a git dependency, which in turn forbids your crate to be published on crates.io. Unlike syntastica-parsers-git however, the parsers only need to be fetched once by cargo, and subsequent builds will be much faster.
• syntastica-parsers-dynamic doesn't include any parsers by itself but instead provides a LanguageSet implementation that can find and load parsers at runtime. This allows for behavior similar to what the tree-sitter CLI does, and opens up more possibilities for end-users, but also places more responsibilities on them, as the appropriate queries also need to be provided manually.

Theme collection

To render highlighted code to end users, a theme is needed, which specifies the colors to use for which theme key. The syntastica project comes with a separate crate containing a few default themes: syntastica-themes.

If you wish to create your own theme, have a look at the custom theme example and the documentation for the [theme!] macro.

Crates for internal use

The syntastica repository/workspace also includes some crates which are not meant for outside use, but are instead used internally. These are listed below.

Note: There are no guarantees about the public API of these crates! If, for any reason, you have to depend on one of them, then pin the exact version using <crate> = "=<version>".

• syntastica-core defines types, traits, constants, etc. which are used in multiple of the other crates. The main syntastica crate re-exports all those items transparently, so that external projects only need a dependency on that. The items are defined in syntastica-core however, to avoid cyclic (dev-)dependencies inside this workspace.
• syntastica-macros defines procedural macros for use exclusively inside this workspace. This crate allows the list of languages/parsers to be in one combined languages.toml file, and the different macros are used in the different places where this list needs to be referenced.
• syntastica-highlight is a fork of tree-sitter-highlight, which is adjusted and trimmed down for the use in syntastica. It contains the main highlighting logic.
• <a name="syntastica-queries" href="https://crates.io/crates/syntastica-queries"><code>syntastica-queries</code></a> is a collection of tree-sitter queries for all supported languages. It is marked as "for internal use", because all three parser collections depend on this crate and expose the queries through their implementation of LanguageSet. Unlike the previous crates in this list however, you may actually want to depend on this crate yourself, if you only need the queries.

General side-products

This list includes crates which were developed for syntastica but have no direct association with the main project and can be used completely separately.

• rsexpr is a generic S-expression parser with added support for square-brackets, strings, and comments. Additionally, the parsed S-expressions can be pretty-printed to provide a uniform formatting. See dprint-plugin-sexpr for more information on using this as a formatter. In syntastica this crate is used for parsing (and formatting) the tree-sitter queries in the queries directory. These are processed by cargo xtask codegen queries and result in the queries inside the generated_queries directory, which are the ones that are bundled with syntastica-queries.
• lua-pattern is a parser for Lua patterns. These are similar to regular expressions, but generally more limited. The crate also provides a best-effort conversion to regular expression strings. In syntastica this is used, as many of the source queries are forked from nvim-treesitter which makes heavy use of #lua-match? predicates for matching with Lua patterns. The official tree-sitter Rust bindings do not support Lua pa