Struct Rule

Source

pub struct Rule(/* private fields */);

Expand description

One entry of a pattern list: what the tokenizer tries at each position.

A rule is one of:

a Match: one regular expression, scoped as a whole and by capture group ("match" in the JSON);
a BeginEnd: a region from a begin match to an end match, with its own patterns inside ("begin"/"end");
a BeginWhile: a region that starts at a begin match and continues on each following line while a while pattern matches at its start ("begin"/"while"), as Markdown block quotes do;
an include of a repository entry, the grammar itself, the base grammar, or another grammar ("include");
a list of rules tried together (Rule::patterns).

Match, BeginEnd, and BeginWhile convert into a Rule with into(), and every method that takes a rule accepts them directly.

§Examples

use textmate_lang::{BeginEnd, Grammar, Match, Rule};

let json = Grammar::new("source.demo")
    .pattern(Rule::include("comments"))
    .pattern(Match::new(r"\b(let|fn)\b").scope("keyword.other.demo"))
    .repository(
        "comments",
        Rule::patterns([
            Match::new("//.*$").scope("comment.line.double-slash.demo").into(),
            BeginEnd::new(r"/\*", r"\*/").scope("comment.block.demo").into(),
        ]),
    )
    .to_json()?;
assert!(json.contains(r##""include": "#comments""##));

Implementations§

Source §

impl Rule

Source

pub fn include(name: impl Into<Cow<'static, str>>) -> Rule

Includes the repository entry called name ("include": "#name").

The entry must exist (Error::UndefinedInclude), checked when the grammar is emitted. The entry’s patterns are tried as if they were written in place of the include.

Parameter	Meaning
`name`	A repository entry’s name, without the `#`.

§Examples

use textmate_lang::{Grammar, Match, Rule};

let json = Grammar::new("source.demo")
    .pattern(Rule::include("numbers"))
    .repository("numbers", Match::new(r"\d+").scope("constant.numeric.demo"))
    .to_json()?;
assert!(json.contains(r##""include": "#numbers""##));

Source

Includes the base grammar’s top-level patterns ("include": "$base"): the grammar of the file being highlighted. That is this grammar, unless this one is embedded in another (a SQL grammar inside a host language’s strings, say), in which case it is the host.

§Examples

use textmate_lang::{BeginEnd, Grammar, Rule};

let json = Grammar::new("source.demo")
    .pattern(BeginEnd::new(r"\(", r"\)").pattern(Rule::include_base()))
    .to_json()?;
assert!(json.contains(r#""include": "$base""#));

Source

pub fn include_scope(scope: impl Into<Cow<'static, str>>) -> Rule

Includes another grammar’s top-level patterns by its scope name ("include": "source.js"), to embed one language in another.

The other grammar is not available here, so only the scope name’s syntax is checked. Naming this grammar’s own scope is the same as include_self.

Parameter	Meaning
`scope`	The other grammar’s `scopeName`.

§Examples

use textmate_lang::{BeginEnd, Grammar, Rule};

let json = Grammar::new("text.html.demo")
    .pattern(
        BeginEnd::new("<script>", "</script>")
            .content_scope("source.js.embedded.demo")
            .pattern(Rule::include_scope("source.js")),
    )
    .to_json()?;
assert!(json.contains(r#""include": "source.js""#));

Source

pub fn include_scope_entry( scope: impl Into<Cow<'static, str>>, name: impl Into<Cow<'static, str>>, ) -> Rule

Includes one repository entry of another grammar ("include": "source.js#expression").

Only the syntax is checked, unless scope is this grammar’s own scope name: then the entry must exist, as for include.

Parameter	Meaning
`scope`	The other grammar’s `scopeName`.
`name`	The entry in that grammar’s repository.

§Examples

use textmate_lang::{Grammar, Rule};

let json = Grammar::new("source.demo")
    .pattern(Rule::include_scope_entry("source.js", "expression"))
    .to_json()?;
assert!(json.contains(r#""include": "source.js#expression""#));

Source

pub fn patterns(rules: impl IntoIterator<Item = Rule>) -> Rule

A list of rules tried together, as one rule ({"patterns": [...]}).

The usual body of a repository entry that groups related rules, so that one include pulls in all of them. The rules are tried in order; at each position the earliest match wins, and the first rule in the list wins a tie.

Parameter	Meaning
`rules`	The rules, in priority order.

§Examples

use textmate_lang::{Grammar, Match, Rule};

let literals = Rule::patterns([
    Match::new(r"\b(true|false)\b").scope("constant.language.demo").into(),
    Match::new(r"\b\d+\b").scope("constant.numeric.demo").into(),
]);
let json = Grammar::new("source.demo")
    .pattern(Rule::include("literals"))
    .repository("literals", literals)
    .to_json_compact()?;
assert!(json.contains(r#""literals":{"patterns":[{"name":"constant.language.demo""#));