@Wliu if you could just indulge me for this question, it would be very much appreciated. Given that I didn’t quite understand
injections when I first saw them, I just want to confirm I understand what everything listed below is for.
Properties of the grammar file observed by the
name: Aesthetic label for language selection menu
fileTypes: Array of file extensions used to help calculate the language score (for automatic selection)
scopeName: A root scope that gets applied to all text, regardless of further matches.
foldingStopMarker: A currently ignored property, potentially will be used for syntax based folding (instead of the current indentation folding).
foldingStartMarkeris not even looked for.
maxTokensPerLine: The maximum number of rule/pattern matches before tokenization of a line is stopped.
maxLineLength: The maximum line length, with longer ones being truncated to fit. It’s value in the grammar class can be
Infinity, but this results in an error when set directly in the file.
limitLineLength: Boolean, set to
GrammarRegistryset the value of
Infinitybefore converting to a grammar object.
injections: Explained in my other question. Basically, a way for the active grammar to insert rules based on scope instead of
includeing in other rules.
injectionSelector: Used to apply the grammar in file where it is not the active grammar. Based on the scope provided, which is converted into a
patterns: Converted into an ‘initial’ rule, which is then used to begin tokenization.
repository: Storage for rules based on name, which can be
included into other rules.
firstLineMatch: Used to help the score, like
Properties of an object in the
patterns array observed by the
name: Scope applied to text matched by the pattern.
contentName: Scope applied to text between the
endcaptures of a pattern.
match: A single line regex used to determine a match. I’m unsure of the implementation though, specifically the difference between
@regexSourcebecause of backreferences and the existence of an
endrule? Especially because I didn’t think
endwas supposed to be used with
if match if (end or @popRule) and @hasBackReferences ?= DigitRegex.test(match) @match = match else @regexSource = match
begin: Checked if
matchdoes not exist. If not, it is set up similarly to a
matchrule, but an end pattern is generated and turned into a rule with the other patterns.
end: Not required, but used to finish a
patterns: An array of objects which are part of the argument passed to
@grammar.createRule(). This in turn makes a new
Ruleobject, which passes each pattern to
@.grammar.createPattern(), which makes a new
Pattern. This recursive combination effectively processes every rule and pattern, no matter how deeply nested.
captures: Used to apply scopes to the captured
matchtext. Is alternatively used for
beginCapturesdoes not exist. Any
patternsarrays inside of the capture group objects are processed as described in the above point.
beginCaptures: Captures specifically meant for the
endCaptures: Captures specifically meant for the
endmatch. If it does not exist,
captureswill be tried instead.
applyEndPatternsLast: Getting more unsure here. The name seems straightforward; I would assume that by default the
endregex of the currently ‘active’ rule is always looked for first, before any internal pattern matches. Setting this to
truewould cause the reverse, where any internal patterns would try to be matched first.
include: The code for this is nice and straightforward. If it starts with a
#, the rule is looked for in the current repository. If it’s index is further in, the left side is considered the scope name of another grammar, and the right side the rule name in that grammar’s repository.
$baseget special handling. Otherwise, it is considered another grammar’s scope name, and it’s ‘initial’ rule is inserted.
I haven’t tested how it behaves if
patterns, etc. are also present, but that sounds like a bad thing to do.
popRule: Related to the
ruleStackvariable used in
tokenizeLine, I think. Seems to be automatically applied to
endpatterns, so I’m guessing it pops an entire rule, which is made from a
patternsarray. Are there any use cases where using it directly can help? I tested it now, and an error is thrown if it’s used to pop the
tokenizeLine. I don’t know why, but that amused me…
hasBackReferences: Automatically set if it doesn’t exist (tangent: the CoffeeScript
?=operator always confuses me). Used to determine if backreferences are present. If they are, they need to be replaced at some point.
Is there any reason to provide this property directly? Performance doesn’t seem like an issue, as it’s only done once when initialised.
AllDigitsRegexit uses doesn’t seem able to detect oniguruma backreferences (of the
\k<n>form). Using these throws an error though, and I can’t determine where from. It seems the be in the construction of a
disabled: A boolean only looked at by the
Ruleconstructor, which does what it says.