SUIT Framework - Docs

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.

PHP

<?php
$rules = array
(
    '[lower]' => array
    (
        'close' => '[/lower]',
        'functions' => array
        (
            array
            (
                'class' => $class,
                'function' => 'lower'
            )
        )
    )
);
?>

Python

rules = {
    '[lower]':
    {
        'close': '[/lower]',
        'functions': [lower]
    }
}

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.

PHP

<?php
Class CLASS
{
    public function lower($params)
    {
        $params['string'] = $this->suit->walk($params['rules'], $params['tree'], $params['config']);
        $params['string'] = strtolower($params['string']);
        return $params;
    }
}
?>

Python

def lower(params):
    params['string'] = suit.walk(
        params['rules'],
        params['tree'],
        params['config']
    )
    params['string'] = params['string'].lower()
    return params