Scanner

StateScanner(patterns, first_state, engine=None)

Bases: Generic[S]

Single-pass scanner for state transitions.

This class orchestrates the scanning of a byte buffer or file to identify transitions between different states based on predefined patterns. It uses a ScanEngine to perform the actual pattern matching.

Type variables

S: An Enum type representing the possible states a file can be in.

Initializes the StateScanner.

PARAMETER	DESCRIPTION
patterns	A dictionary where keys are state Enum members and values are lists of byte patterns (regex or literal) that signify a transition to that state. TYPE: dict[S, list[bytes]]
first_state	The initial state of the file, which is used to begin the scanning process. TYPE: S
engine	An optional ScanEngine instance to use for pattern matching. If None, StdRegexEngine will be used by default. TYPE: ScanEngine[S] | None DEFAULT: None

engine = engine

first_state = first_state

patterns

Returns the compiled patterns used by the internal scan engine.

This property provides access to the patterns that the scanner is configured to detect.

RETURNS	DESCRIPTION
	The underlying patterns from the scan engine.

scan(buf)

Single-pass scan of bytes to identify states and their transitions.

This method iterates through the provided byte buffer, identifying all occurrences of predefined patterns that indicate a change in state. It constructs a list of StateTransition objects, each detailing the from_state, to_state, and byte start_pos/end_pos of each identified region.

PARAMETER	DESCRIPTION
buf	The byte buffer to be scanned for state transitions. TYPE: bytes

RETURNS	DESCRIPTION
list[StateTransition]	A list of StateTransition objects, ordered by their appearance in the buffer, representing the sequence of states and their corresponding byte ranges.