Struct syntect::parsing::SyntaxSet

pub struct SyntaxSet {
    pub is_linked: bool,
    // some fields omitted
}

A syntax set holds a bunch of syntaxes and manages loading them and the crucial operation of linking.

Linking replaces the references between syntaxes with direct pointers. See link_syntaxes for more.

Re-linking— linking, adding more unlinked syntaxes with load_syntaxes, and then linking again—is allowed.

Fields

is_linked: bool

Methods

impl SyntaxSet

fn new() -> SyntaxSet

fn load_from_folder<P: AsRef<Path>>(
    folder: P
) -> Result<SyntaxSet, LoadingError>

Convenience constructor calling new and then load_syntaxes on the resulting set defaults to lines given not including newline characters, see the load_syntaxes method docs for an explanation as to why this might not be the best. It also links all the syntaxes together, see link_syntaxes for what that means.

fn load_syntaxes<P: AsRef<Path>>(
    &mut self,
    folder: P,
    lines_include_newline: bool
) -> Result<(), LoadingError>

Loads all the .sublime-syntax files in a folder into this syntax set. It does not link the syntaxes, in case you want to serialize this syntax set.

The lines_include_newline parameter is used to work around the fact that Sublime Text normally passes line strings including newline characters (\n) to its regex engine. This results in many syntaxes having regexes matching \n, which doesn't work if you don't pass in newlines. It is recommended that if you can you pass in lines with newlines if you can and pass true for this parameter. If that is inconvenient pass false and the loader will do some hacky find and replaces on the match regexes that seem to work for the default syntax set, but may not work for any other syntaxes.

In the future I might include a "slow mode" that copies the lines passed in and appends a newline if there isn't one. but in the interest of performance currently this hacky fix will have to do.

fn add_syntax(&mut self, syntax: SyntaxDefinition)

Add a syntax to the set. If the set was linked it is now only partially linked and you'll have to link it again for full linking.

fn syntaxes(&self) -> &[SyntaxDefinition]

The list of syntaxes in the set

fn load_plain_text_syntax(&mut self)

Rarely useful method that loads in a syntax with no highlighting rules for plain text. Exists mainly for adding the plain text syntax to syntax set dumps, because for some reason the default Sublime plain text syntax is still in .tmLanguage format.

fn find_syntax_by_scope(&self, scope: Scope) -> Option<&SyntaxDefinition>

Finds a syntax by its default scope, for example source.regexp finds the regex syntax. This and all similar methods below do a linear search of syntaxes, this should be fast because there aren't many syntaxes, but don't think you can call it a bajillion times per second.

fn find_syntax_by_name<'a>(&'a self, name: &str) -> Option<&'a SyntaxDefinition>

fn find_syntax_by_extension<'a>(
    &'a self,
    extension: &str
) -> Option<&'a SyntaxDefinition>

fn find_syntax_by_token<'a>(&'a self, s: &str) -> Option<&'a SyntaxDefinition>

Searches for a syntax first by extension and then by case-insensitive name useful for things like Github-flavoured-markdown code block highlighting where all you have to go on is a short token given by the user

fn find_syntax_by_first_line<'a>(
    &'a self,
    s: &str
) -> Option<&'a SyntaxDefinition>

Try to find the syntax for a file based on its first line. This uses regexes that come with some sublime syntax grammars for matching things like shebangs and mode lines like -*- Mode: C -*-

fn find_syntax_by_path<'a>(&'a self, path: &str) -> Option<&'a SyntaxDefinition>

Searches for a syntax by it's original file path when it was first loaded from disk primarily useful for syntax tests some may specify a Packages/PackageName/SyntaxName.sublime-syntax path others may just have SyntaxName.sublime-syntax this caters for these by matching the end of the path of the loaded syntax definition files

fn find_syntax_for_file<P: AsRef<Path>>(
    &self,
    path_obj: P
) -> Result<Option<&SyntaxDefinition>>

Convenience method that tries to find the syntax for a file path, first by extension and then by first line of the file if that doesn't work. May IO Error because it sometimes tries to read the first line of the file.

Examples

When determining how to highlight a file, use this in combination with a fallback to plain text:

use syntect::parsing::SyntaxSet;
let ss = SyntaxSet::load_defaults_nonewlines();
let syntax = ss.find_syntax_for_file("testdata/highlight_test.erb")
    .unwrap() // for IO errors, you may want to use try!() or another plain text fallback
    .unwrap_or_else(|| ss.find_syntax_plain_text());
assert_eq!(syntax.name, "HTML (Rails)");

fn find_syntax_plain_text(&self) -> &SyntaxDefinition

Finds a syntax for plain text, which usually has no highlighting rules. Good as a fallback when you can't find another syntax but you still want to use the same highlighting pipeline code.

This syntax should always be present, if not this method will panic. If the way you load syntaxes doesn't create one, use load_plain_text_syntax.

Examples

use syntect::parsing::SyntaxSet;
let mut ss = SyntaxSet::new();
ss.load_plain_text_syntax();
let syntax = ss.find_syntax_by_token("rs").unwrap_or_else(|| ss.find_syntax_plain_text());
assert_eq!(syntax.name, "Plain Text");

fn link_syntaxes(&mut self)

This links all the syntaxes in this set directly with pointers for performance purposes. It is necessary to do this before parsing anything with these syntaxes. However, it is not possible to serialize a syntax set that has been linked, which is why it isn't done by default, except by the load_from_folder constructor. This operation is idempotent, but takes time even on already linked syntax sets.

impl SyntaxSet

fn load_defaults_nonewlines() -> SyntaxSet

Instantiates a new syntax set from a binary dump of Sublime Text's default open source syntax definitions and then links it. These dumps are included in this library's binary for convenience.

This method loads the version for parsing line strings with no \n characters at the end. If you're able to efficiently include newlines at the end of strings, use load_defaults_newlines since it works better. See SyntaxSet#load_syntaxes for more info on this issue.

This is the recommended way of creating a syntax set for non-advanced use cases. It is also significantly faster than loading the YAML files.

Note that you can load additional syntaxes after doing this, you'll just have to link again. If you want you can even use the fact that SyntaxDefinitions are serializable with the bincode crate to cache dumps of additional syntaxes yourself.

fn load_defaults_newlines() -> SyntaxSet

Same as load_defaults_nonewlines but for parsing line strings with newlines at the end. These are separate methods because thanks to linker garbage collection, only the serialized dumps for the method(s) you call will be included in the binary (each is ~200kb for now).

Trait Implementations

impl Debug for SyntaxSet

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Default for SyntaxSet

fn default() -> Self

Returns the "default value" for a type.