docutils.statemachine.StateMachine

class documentation

class StateMachine: (source)

Known subclasses: docutils.statemachine.SearchStateMachine, docutils.statemachine.StateMachineWS

A finite state machine for text filters using regular expressions. The input is provided in the form of a list of one-line strings (no newlines). States are subclasses of the `State` class. Transitions consist of regular expression patterns and transition methods, and are defined in each state. The state machine is started with the `run()` method, which returns the results of processing in a list.

Method	`__init__`	Initialize a `StateMachine` object; add state objects.
Method	`abs_line_number`	Return line number of current line (counting from 1).
Method	`abs_line_offset`	Return line offset of current line, from beginning of file.
Method	`add_state`	Initialize & add a `state_class` (`State` subclass) object.
Method	`add_states`	Add `state_classes` (a list of `State` subclasses).
Method	`at_bof`	Return 1 if the input is at or before beginning-of-file.
Method	`at_eof`	Return 1 if the input is at or past end-of-file.
Method	`attach_observer`	The `observer` parameter is a function or bound method which takes two arguments, the source and offset of the current line.
Method	`check_line`	Examine one line of input for a transition match & execute its method.
Method	`detach_observer`	Undocumented
Method	`error`	Report error details.
Method	`get_source`	Return source of line at absolute line offset `line_offset`.
Method	`get_source_and_line`	Return (source, line) tuple for current or given line number.
Method	`get_state`	Return current state object; set it first if `next_state` given.
Method	`get_text_block`	Return a contiguous block of text.
Method	`goto_line`	Jump to absolute line offset `line_offset`, load and return it.
Method	`insert_input`	Undocumented
Method	`is_next_line_blank`	Return True if the next line is blank or non-existent.
Method	`next_line`	Load `self.line` with the `n`'th next line and return it.
Method	`notify_observers`	Undocumented
Method	`previous_line`	Load `self.line` with the `n`'th previous line and return it.
Method	`run`	Run the state machine on `input_lines`. Return results (a list).
Method	`runtime_init`	Initialize `self.states`.
Method	`unlink`	Remove circular references to objects no longer required.
Instance Variable	`current_state`	The name of the current state (key to `self.states`).
Instance Variable	`debug`	Debugging mode on/off.
Instance Variable	`initial_state`	The name of the initial state (key to `self.states`).
Instance Variable	`input_lines`	`StringList` of input lines (without newlines). Filled by `self.run()`.
Instance Variable	`input_offset`	Offset of `self.input_lines` from the beginning of the file.
Instance Variable	`line`	Current input line.
Instance Variable	`line_offset`	Current input line offset from beginning of `self.input_lines`.
Instance Variable	`observers`	List of bound methods or functions to call whenever the current line changes. Observers are called with one argument, ``self``. Cleared at the end of `run()`.
Instance Variable	`states`	Mapping of {state_name: State_object}.

def __init__(self, state_classes, initial_state, debug=False): (source)

Initialize a `StateMachine` object; add state objects. Parameters: - `state_classes`: a list of `State` (sub)classes. - `initial_state`: a string, the class name of the initial state. - `debug`: a boolean; produce verbose output if true (nonzero).

def abs_line_number(self): (source)

Return line number of current line (counting from 1).

def abs_line_offset(self): (source)

Return line offset of current line, from beginning of file.

def add_state(self, state_class): (source)

Initialize & add a `state_class` (`State` subclass) object. Exception: `DuplicateStateError` raised if `state_class` was already added.

def add_states(self, state_classes): (source)

Add `state_classes` (a list of `State` subclasses).

def at_bof(self): (source)

Return 1 if the input is at or before beginning-of-file.

def at_eof(self): (source)

Return 1 if the input is at or past end-of-file.

def attach_observer(self, observer): (source)

The `observer` parameter is a function or bound method which takes two arguments, the source and offset of the current line.

def check_line(self, context, state, transitions=None): (source)

Examine one line of input for a transition match & execute its method. Parameters: - `context`: application-dependent storage. - `state`: a `State` object, the current state. - `transitions`: an optional ordered list of transition names to try, instead of ``state.transition_order``. Return the values returned by the transition method: - context: possibly modified from the parameter `context`; - next state name (`State` subclass name); - the result output of the transition, a list. When there is no match, ``state.no_match()`` is called and its return value is returned.

def detach_observer(self, observer): (source)

Undocumented

def error(self): (source)

Report error details.

def get_source(self, line_offset): (source)

Return source of line at absolute line offset `line_offset`.

def get_source_and_line(self, lineno=None): (source)

Return (source, line) tuple for current or given line number. Looks up the source and line number in the `self.input_lines` StringList instance to count for included source files. If the optional argument `lineno` is given, convert it from an absolute line number to the corresponding (source, line) pair.

def get_state(self, next_state=None): (source)

Return current state object; set it first if `next_state` given. Parameter `next_state`: a string, the name of the next state. Exception: `UnknownStateError` raised if `next_state` unknown.

def get_text_block(self, flush_left=False): (source)

Return a contiguous block of text. If `flush_left` is true, raise `UnexpectedIndentationError` if an indented line is encountered before the text block ends (with a blank line).

def goto_line(self, line_offset): (source)

Jump to absolute line offset `line_offset`, load and return it.

def insert_input(self, input_lines, source): (source)

Undocumented

def is_next_line_blank(self): (source)

Return True if the next line is blank or non-existent.

def next_line(self, n=1): (source)

Load `self.line` with the `n`'th next line and return it.

def notify_observers(self): (source)

Undocumented

def previous_line(self, n=1): (source)

Load `self.line` with the `n`'th previous line and return it.

def run(self, input_lines, input_offset=0, context=None, input_source=None, initial_state=None): (source)

overridden in docutils.parsers.rst.states.NestedStateMachine, docutils.parsers.rst.states.RSTStateMachine

Run the state machine on `input_lines`. Return results (a list). Reset `self.line_offset` and `self.current_state`. Run the beginning-of-file transition. Input one line at a time and check for a matching transition. If a match is found, call the transition method and possibly change the state. Store the context returned by the transition method to be passed on to the next transition matched. Accumulate the results returned by the transition methods in a list. Run the end-of-file transition. Finally, return the accumulated results. Parameters: - `input_lines`: a list of strings without newlines, or `StringList`. - `input_offset`: the line offset of `input_lines` from the beginning of the file. - `context`: application-specific storage. - `input_source`: name or path of source of `input_lines`. - `initial_state`: name of initial state.

def runtime_init(self): (source)

Initialize `self.states`.

def unlink(self): (source)

Remove circular references to objects no longer required.

current_state = (source)

The name of the current state (key to `self.states`).

debug = (source)

Debugging mode on/off.

initial_state = (source)

The name of the initial state (key to `self.states`).

input_lines = (source)

`StringList` of input lines (without newlines). Filled by `self.run()`.

input_offset = (source)

Offset of `self.input_lines` from the beginning of the file.

line = (source)

Current input line.

line_offset = (source)

Current input line offset from beginning of `self.input_lines`.

observers: list = (source)

List of bound methods or functions to call whenever the current line changes. Observers are called with one argument, ``self``. Cleared at the end of `run()`.

states = (source)

Mapping of {state_name: State_object}.