Package atessera.markup

Class TextStateParser<M>

java.lang.Object

atessera.markup.TextStateParser<M>

Type Parameters:

M - the type of the model object populated during parsing

Direct Known Subclasses:

PresentationParser

public class TextStateParser<M>
extends Object

A generic two-phase line-by-line text parser based on a state machine pattern.

This parser processes a list of strings (typically lines of a text file) in two sequential phases:

1. Headers phase: The parser iterates over lines at the beginning of the input and passes each non-empty trimmed line to a set of TextStateParser.HeaderLine matchers. As long as at least one matcher accepts the line, the parser stays in this phase. The first line that is not accepted by any header matcher ends the headers phase, and this same line is immediately handed over to the next phase without being discarded.
2. States phase: Each line (starting from the one that terminated the headers phase) is checked against a set of TextStateParser.NewStateLine matchers to detect state boundaries. If a matcher returns a new TextStateParser.State, the previous state is committed and the new state becomes active. Otherwise, the line is dispatched to onLine of the current state.

After all lines are processed, the last active state is committed.

The generic type parameter <M> represents the model object that accumulates parsing results. It is passed to all callbacks and is expected to be mutated during parsing. The same model instance is shared across all phases, states, and matchers.

See Also:

• TextStateParser.HeaderLine
• TextStateParser.NewStateLine
• TextStateParser.State

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	TextStateParser.HeaderLine<M>	Matches a line as a header entry during the headers phase.
static interface	TextStateParser.NewStateLine<M>	Detects a state boundary and creates the corresponding TextStateParser.State.
static interface	TextStateParser.State<M>	Represents a parsing state that processes lines belonging to a specific section of the input.

Constructor Summary

Constructors

Constructor	Description
TextStateParser(M model, TextStateParser.State<M> initialState, List<TextStateParser.HeaderLine<M>> headerLines, List<TextStateParser.NewStateLine<M>> newStateLines)	Creates a new parser.

Method Summary

Modifier and Type	Method	Description
void	parse(List<String> lines)	Executes the two-phase parsing over the given list of lines.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

TextStateParser

public TextStateParser(M model,
 TextStateParser.State<M> initialState,
 List<TextStateParser.HeaderLine<M>> headerLines,
 List<TextStateParser.NewStateLine<M>> newStateLines)

Creates a new parser.

Parameters:

model - the model to populate during parsing, must not be null

initialState - the initial state to use before any transition occurs, must not be null

headerLines - the list of header matchers; if null, an empty list is used

newStateLines - the list of state-boundary matchers; if null, an empty list is used

Throws:

NullPointerException - if model or initialState is null

Method Details

parse

public void parse(List<String> lines)

Executes the two-phase parsing over the given list of lines.

The method first enters the headers phase: non-empty trimmed lines are offered to TextStateParser.HeaderLine matchers. The first line not recognised as a header terminates the headers phase and is immediately processed in the states phase.

During the states phase, each trimmed line is checked against TextStateParser.NewStateLine matchers. If a matcher returns a new TextStateParser.State, the current state is committed and the new state becomes active. Otherwise, the original (untrimmed) line is dispatched to the current state via onLine. After all lines are exhausted, the last active state is committed.

Parameters:

lines - the lines to parse