Inheritance diagram for docutils.statemachine.StateMachine:

Public Member Functions
	__init__ (self, state_classes, initial_state, debug=False)

	unlink (self)

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

	get_state (self, next_state=None)

	next_line (self, n=1)

	is_next_line_blank (self)

	at_eof (self)

	at_bof (self)

	previous_line (self, n=1)

	goto_line (self, line_offset)

	get_source (self, line_offset)

	abs_line_offset (self)

	abs_line_number (self)

	get_source_and_line (self, lineno=None)

	insert_input (self, input_lines, source)

	get_text_block (self, flush_left=False)

	check_line (self, context, state, transitions=None)

	add_state (self, state_class)

	add_states (self, state_classes)

	runtime_init (self)

	error (self)

	attach_observer (self, observer)

	detach_observer (self, observer)

	notify_observers (self)

Public Attributes
	input_lines

	input_offset

	line

	line_offset

	debug

	initial_state

	current_state

	states

	observers

Detailed Description

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.

Constructor & Destructor Documentation

◆ init()

docutils.statemachine.StateMachine.__init__	(	self,
		state_classes,
		initial_state,
		debug = `False`
	)

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

Member Function Documentation

◆ abs_line_number()

docutils.statemachine.StateMachine.abs_line_number ( self )

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

◆ abs_line_offset()

docutils.statemachine.StateMachine.abs_line_offset ( self )

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

◆ add_state()

docutils.statemachine.StateMachine.add_state	(	self,
		state_class
	)

Initialize & add a `state_class` (`State` subclass) object.

Exception: `DuplicateStateError` raised if `state_class` was already
added.

◆ add_states()

docutils.statemachine.StateMachine.add_states	(	self,
		state_classes
	)

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

◆ at_bof()

docutils.statemachine.StateMachine.at_bof ( self )

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

◆ at_eof()

docutils.statemachine.StateMachine.at_eof ( self )

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

◆ attach_observer()

docutils.statemachine.StateMachine.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.

◆ check_line()

docutils.statemachine.StateMachine.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.

◆ error()

docutils.statemachine.StateMachine.error ( self )

Report error details.

◆ get_source()

docutils.statemachine.StateMachine.get_source	(	self,
		line_offset
	)

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

◆ get_source_and_line()

docutils.statemachine.StateMachine.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.

◆ get_state()

docutils.statemachine.StateMachine.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.

◆ get_text_block()

docutils.statemachine.StateMachine.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).

◆ goto_line()

docutils.statemachine.StateMachine.goto_line	(	self,
		line_offset
	)

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

◆ is_next_line_blank()

docutils.statemachine.StateMachine.is_next_line_blank ( self )

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

◆ next_line()

docutils.statemachine.StateMachine.next_line	(	self,
		n = `1`
	)

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

◆ previous_line()

docutils.statemachine.StateMachine.previous_line	(	self,
		n = `1`
	)

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

◆ run()

docutils.statemachine.StateMachine.run	(	self,
		input_lines,
		input_offset = `0`,
		context = `None`,
		input_source = `None`,
		initial_state = `None`
	)

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.

Reimplemented in docutils.parsers.rst.states.RSTStateMachine, and docutils.parsers.rst.states.NestedStateMachine.

◆ runtime_init()

docutils.statemachine.StateMachine.runtime_init ( self )

Initialize `self.states`.

◆ unlink()

docutils.statemachine.StateMachine.unlink ( self )

Remove circular references to objects no longer required.

The documentation for this class was generated from the following file:

docs/help/help-venv/lib/python3.12/site-packages/docutils/statemachine.py

Public Member Functions

Public Attributes