docutils.statemachine.StateMachine

class documentation

class StateMachine(object):

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

View In Hierarchy

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}.
Instance Variable ​_stderr Wrapper around sys.stderr catching en-/decoding errors
def __init__(self, state_classes, initial_state, debug=False):

Initialize a StateMachine object; add state objects.

Parameters:

def abs_line_number(self):
Return line number of current line (counting from 1).
def abs_line_offset(self):
Return line offset of current line, from beginning of file.
def add_state(self, state_class):

Initialize & add a state_class (State subclass) object.

Exception: DuplicateStateError raised if state_class was already added.

def add_states(self, state_classes):
Add state_classes (a list of State subclasses).
def at_bof(self):
Return 1 if the input is at or before beginning-of-file.
def at_eof(self):
Return 1 if the input is at or past end-of-file.
def attach_observer(self, observer):
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):

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):

Undocumented

def error(self):
Report error details.
def get_source(self, line_offset):
Return source of line at absolute line offset line_offset.
def get_source_and_line(self, lineno=None):

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):

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):

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):
Jump to absolute line offset line_offset, load and return it.
def insert_input(self, input_lines, source):

Undocumented

def is_next_line_blank(self):
Return True if the next line is blank or non-existent.
def next_line(self, n=1):
Load self.line with the n'th next line and return it.
def notify_observers(self):

Undocumented

def previous_line(self, n=1):
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):
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:

def runtime_init(self):
Initialize self.states.
def unlink(self):
Remove circular references to objects no longer required.
current_state =
The name of the current state (key to self.states).
debug =
Debugging mode on/off.
initial_state =
The name of the initial state (key to self.states).
input_lines =
StringList of input lines (without newlines). Filled by self.run().
input_offset =
Offset of self.input_lines from the beginning of the file.
line =
Current input line.
line_offset =
Current input line offset from beginning of self.input_lines.
observers: list =
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 =
Mapping of {state_name: State_object}.
_stderr =
Wrapper around sys.stderr catching en-/decoding errors