Style Conventions

Naming

The convention is to use snake_case for all identifiers.

Abbreviations are encouraged in classes and feature names which are expected to be used frequently to allow writing rules on one line as much as possible. For example, the recommended names for vowel and consonant classes are vow and cons respectively.

Bindings should use short (1-3 character) identifiers to keep rules compact and follow one of the following patterns:

When using only one binding in a rule, denoting the type of binding:
- @i for index bindings.
- @s for content bindings.
- @f for feature bindings.
When the order of bindings is of primary interest, numbered bindings such as @_1, @_2, etc.
When the matcher that created, initials indicating the matcher, such as vow@v or cons@c. This may include type-based names if binding type is different between matchers.

Indentation

Use 2 or 4 spaces for indentation. Rules should be written on one line if possible, and lines should be kept under 100 characters.

Splitting Rules

If a rule is too long, it should first be separated from the declaration onto a separate indented line:

rule this_rule_is_long_and_has_a_long_name =
    'a' /* lots of matchers */ -> () in /* lots of environments */;

If it is still too long and has multiple environments, the environments should be split in one of two ways. The in, or, and except keywords should always be aligned under the first in when splitting environments across lines. The start of environments may be either on the same line as the rule itself or on a new indented line. Avoid multiple environments on one line if environments are split.

// variant 1
rule long_rule =
    'a' -> () in _ /* environment 1 */
              or _ /* environment 2 */
              except _ /* exception 1 */
              or _ /* exception 2 */;

// variant 2
rule long_rule_2 =
    'a' -> ()
        in _ /* environment 1 */
        or _ /* environment 2 */
        except _ /* exception 1 */
        or _ /* exception 2 */;

Finally, if the core rule is too long, it may be split at the -> operator.

rule long_rule_2 =
    'a' /* long matcher */
        -> 'b' /* long replacer */ 
        in _ /* environment 1 */
        or _ /* environment 2 */
        except _ /* exception 1 */
        or _ /* exception 2 */;

Compound Rules

Annotations

If sufficiently short, annotated rules may be written on a single line.

rule ann_short = #{converging} 'a' -> 'b' in _ 'b';

If the rule is longer, keep the annotation on the previous line.

rule ann_long = #{word}
    'a' /* long matcher */ -> 'b';

When long filter or scope annotations are present, keep the annotation keyword on the first line with the opening brace and indent the content on a separate line. Also, place the rule in braces and on an indented line.

rule long_ann = #{with
    config validate_symbols = true;
} {
    'a' -> 'b';
}

Combinators

If possible, use operator precedence to group rules. Place each rule and operator on a separate line.

When grouping rules with braces, prefer enclosing both sides of operators even if one side is a single rule. Place closing brace, operator, and next opening brace on the same line.

rule precedence = {
    'a' -> 'b';
    'c' -> 'd';
    then
    'e' -> 'f';
    'g' -> 'h';
}

rule complex = {
    {
        {
            'a' -> 'b';
            then
            'c' -> 'd';
        } else {
            'e' -> 'f';
        }
    } {
        'g' -> 'h';
        then
        'i' -> 'j';
    }
}