Docs - Rules
12/27/2015: SUIT Framework is no longer actively maintained.
What is a Rule?
A rule is used to tell SUIT how to transform a string. A collection of rules is called a Ruleset, and a Ruleset is used as a parameter in the execute, tokens, parse, and walk functions.
The syntax of a rule consists of an open and close string. Once these two strings are correctly matched, its contents are sent to user-defined functions which can transform them and return the final result. Rules can be nested and escaped.
Rule Structure
open | ||
---|---|---|
Key | Description | |
close | str: The close string. | |
create | str: The rule this rule creates if applicable. | |
functions | list: The functions to run when walking through a node created by this rule. | |
priority | int: Used to give the open and close strings of this rule priority over others. (Default: null. The strings will be prioritized by size) | |
skip | bool: Whether or not the parser should skip over the contents of the nodes created by this rule. | |
skipescape | bool: If skip is true, whether or not escaping the open or close strings should remove the escape strings. (Default: false) | |
var | mixed: A variable that the functions can use. This key could be named anything, and does not do anything by default. Conventionally, we use this key and have the functions copy it to params. |
Here's an example ruleset containing one rule, lower, which will be used to translate a string to lowercase.
Params Structure
When SUIT calls the functions provided by the rules, it sends a dict containing parameters. Here is the structure of these params:
Key | Description |
---|---|
config | dict: The config used for this walk function call. |
rules | dict: The rules used for this walk function call. |
string | str: The string built from these functions. |
tree | dict: This node. When walked through, it can be used to generate the string, and then the other functions could further transform it. |
As these parameters need to be sent between the various functions provided, have each function return these params so that SUIT can send them to the next function. The dict can be modified however the user wants.
Below is the lower function mentioned in the above configuration. See how it handles the params.