FSA Description

This page describes the JSON format used to describe Finite State Automata.

Automata

The FSA is represented by a JSON object, with the following attributes:

fsa.states

A JSON object (required).

Its attributes are state names, and its values are state objects. It must contain one state named start, which will be the starting state.

fsa.max_noise

A non-negative integer (optional).

It indicates how many unrecognized events this automaton will accept before failing. If unspecified, the automaton will accept any amount of noise (provided that states themselves accept some noise).

fsa.max_duration

A positive integer (optional).

It indicates the maximum duration between the fisrt event and the last event of a match. If unspecified, the automaton will accept any duration.

fsa.allow_override

A boolean (optional).

If false (default value), the automaton will drop all pending matches whenever a match is found. If true, the automaton may yield overlapping matches, possibly involving the same events. See Greedy matches for more details.

fsa.state_defaults

A state object (optional).

It provides default values for all states of this automaton.

NB: it can not have transitions.

fsa.default_matcher

A string (optional).

If provided, it indicates the function used to compare incoming events to the condition. It must be a key present in fsa4streams.matcher.DIRECTORY.

If not provided, a simple matcher will be used, checking whether the event is equal to the transition.condition.

State

Every state is represented by a JSON object, with the following attributes:

state.transitions

A list of transition objects (optional).

Note that a state without any transitions must be terminal:attr`.

state.terminal

A boolean (optional).

If false (default value), this state can not yield any match. If true, this is a terminal state so it may yield matches (but may not do, if the automaton manages to progress to a further terminal state).

state.max_noise

A non-negative integer (optional).

It indicates how many unrecognized events this state will accept before failing. (in the limit imposed by fsa.max_noise). It defaults to 0, so by default automata are not noise-tolerant.

This attribute can not be set together with state.default_transition.

state.max_duration

A positive integer (optional).

It indicates the maximum in which the FSA will stay in this state. If no matching event occurs during this duration, the FSA will fail to match. It defaults to in infinity: if no max duration is specified, the FSA may stay an arbitrary long time in that state (in the limit imposed by fsa.max_duration).

state.default_transition

A transition object with some (optional).

It provides a transition to follow when an unrecognized event is encountered. This special transition can not have any condition or matcher.

This attribute can not be set together with state.max_noise.

Transition

Every transition is represented by a JSON object, with the following attributes:

transition.condition

Any JSON object (required).

The condition is compared to incoming events to check if the transition can be used. See also transition.matcher.

transition.target

A string (required).

This is the identifier (in fsa.states) of the target state of this transition.

transition.matcher

A string (optional).

If provided, it indicates the function used to compare incoming events to the condition. It must be a key present in fsa4streams.matcher.DIRECTORY.

If not provided, the default_matcher will be used.

transition.silent

A boolean (optional).

If it is set to false (default value), the event matching this transition will be included in the match. Otherwise, the transition will be used but the event will be simply discarded.

Example

{
    "allow_overlap": true,
    "states": {
        "start": {
            "max_noise": 0,
            "transitions": [
                {
                    "condition": "a",
                    "target": "start"
                },
                {
                    "condition": "a",
                    "target": "s1"
                },
                {
                    "condition": "d",
                    "target": "s2"
                }
            ]
        },
        "s1": {
            "transitions": [
                {
                    "condition": "b",
                    "target": "s1"
                },
                {
                    "condition": "c",
                    "target": "success"
                },
                {
                    "condition": "d",
                    "target": "error"
                }
            ]
        },
        "s2": {
            "max_noise": 4,
            "transitions": [
                {
                    "condition": "d",
                    "target": "success"
                }
            ]
        },
        "success": {
            "terminal": true
        },
        "error": {
            "terminal": true
        }
    }
}

Todo

May be also describe the format of the JSON files used to save tokens?...