Legislators¶
As most people know, legislators make the rules. This applies in Lilt, too.
A legislator takes a bit of code and returns a rule based on it.
Literal¶
One of the simplest legislators is the literal legislator, which returns a rule only matching exactly the given text.
Literal legislators begin and end with a double quote or single quote. Inbetween these two double quotes lies the content the resultant rule will match.
For instance, "banana" will match any text beginning with “banana”. Matching this text, it will consume 6 characters (the length of the word “banana”) and return the text “banana”. If the text doesn’t start with “banana”, the rule will fail.
Escape Sequences¶
Literals may contain the following escape sequences
| Key | Mapping |
|---|---|
\\ |
Literal backslash |
\t |
Tab |
\r |
Carriage return |
\c |
Carriage return |
\l |
Linefeed |
\a |
Alert |
\b |
Backspace |
\e |
ESC |
\' |
Literal ‘ |
\" |
Literal “ |
\> |
Literal > |
\xHH |
Character with given hex value |
Set¶
Set legislators return a rule which matches any single character in the set.
Set legislators begin with a < and end with a >. Contained within are all the characters in the set.
For instance <abcdef> will match “a”, “b”, “c”, “d”, “e”, or “f”. If it matches, it will consume the a single character and return it. If the text doesn’t match, it will fail.
Sets have the same escape sequences as literals.
Sequence¶
Sequence legislators are comprised of several rules in a row. Sequence legislators match text that matches all of the contained rules in order.
For instance, "word" " " "another" is equivalent to "word another".
Slighyly more usefully, <ab> <?!> matches “a?”, “a!”, “b?”, and “b!”.
Sequences always return text, concatenating together the text return values of their contined rules. Sequences will fail if any of the contained rules fail.
Choice¶
Choice legislators are also comprised of several rules. Choices return the return value of the first contained rule which matches the given text. The matching rule will also consume code, and possibly mutate the current state.
Choices are comprised of a sequence of rules, each separated by a pipe (|). Both a leading and a trailing pipe is allowed.
For instance, "firstname" | "lastname" matches “firstname” and “lastname” only.
Choices will only fail if the given text matches none of the contained rules.
Ambiguous choices are allowed. For instance, "abc" | "abc" is ambiguous – does the text “abc” match the first rule, or the second? To solve this, the choice defers to the first matching rule.
Optional¶
Optional legislators optionally match their contained rule. If the contained rule matches, the optional returns the value.
If the inner rule doesn’t match, and would have returned a node, the optional returns nothing.
If the inner rule doesn’t match, and would have returned text, the optional returns “”.
If the inner rule doesn’t match, and would have return a list of nodes, the optiional returns [].
Optionals begin with a ? and are followed by a rule.
For instance, ?"fruit!" applied to “fruit!” returns “fruit!” and applied to “NOT FRUIT” returns “”.
Oneplus¶
Oneplus legislators match their contained rule once or more.
They begin with + and are followed by a rule.
If the inner rule returns text, the oneplus will return all the text returned by the inner rule concatenated together, similarly to a sequence.
For instance, *"a" applied to “aaaaa” returns “aaaaa”.
If the inner rule returns a node, the oneplus will similarly return a list of nodes.
Oneplus rules will only fail if the inner rule is not matched at least once.
Zeroplus¶
Zeroplus legislators are like oneplus legislators, but match the inner rule zero or more times.
Zeroplus’ begin with a * and are followed by a rule.
*rule is actually expanded to ?+rule; zeroplus legislators are macros.
Lambdas & States¶
Lambda legislators contain a rule and posses a mutable state.
They begin and end with { and }, containing the sequence/choice in between.
If the lambda doesn’t contain any adjoinments, properties, or extensions, it will return the value of the contained rule.
Otherwise, the lambda will return the state, which can be text, a node, or a list of nodes, after the inner rule has run. As it runs, the state will be mutated.
For instance, { *&"i" } applied to “iiii” will return “iiii”, just as *"i" would. Though effectively the same, the two are semantically different. The former reads like: zero or more times, append the text “i” to the state, returning it when complete; the latter reads like: match zero or more “i”s and return the consumed value.
Result¶
Result legislators modify the current state, setting it to the value of the result’s inner rule.
Results begin with a # and are followed by any rule that doesn’t return nothing.
For instance, _ #"banana" _ will match the text ” banana “, returning “banana”.
Results return nothing and fail when their inner rule fails.
Adjoinment¶
Adjoinment legislators modify the current state, appending the text of the adjoinment’s inner rule.
Adjoinments begin with a $ and are followed by a text-returning rule.
For instance, $"banana" matches the text “banana”, but instead of returning it, mutates the current state, appending the text “banana”. This distinction is covered in the description of lambdas.
Adjoinments return nothing and fail when the inner rule fails.
Property¶
Property legislators modify the current state, setting an attribute of the property’s inner rule.
Properties consist of an identifier followed by a = and a node-returning, text-returning, or node-list-returning rule.
For instance, fruit="grapes" will match the text “grapes”, setting the attribute “fruit” of the current state to the value “grapes”.
Properties return nothing and fail when the inner rule fails.
Extension¶
Extension legislators modify the current state, appending a node.
Extensions being with a & and are followed by a node-returning rule.
For instance, if node is a rule which matches the text “peach” and returns a node with the property {fruit: "peach"}, &node will match the text “peach”, appending the resultant node to the state.
Extensions return nothing and fail when the inner rule fails.