intellicrack.core.hexpat

HexPat .hexpat pattern language interpreter package.

Provides a full interpreter for HexPat’s pattern language that executes .hexpat files against binary data and outputs ParsedField-compatible dicts for display in the hex editor template tree.

exception HexPatError[source]

Bases: Exception

Base error for the HexPat interpreter.

__init__(message, line=0, column=0, file='')[source]

Initialize the HexPatError with location and message details.

Parameters:

message (str) – Human-readable error description.
line (int) – Source line number where the error occurred.
column (int) – Source column number where the error occurred.
file (str) – Source file path where the error occurred.

Return type:

None

class HexPatInterpreter[source]

Bases: object

Full .hexpat pattern interpreter.

Orchestrates the complete pipeline: preprocessor -> lexer -> parser -> type registration -> evaluator. Outputs ParsedField-compatible dicts that plug directly into the existing hex editor UI.

__init__(include_paths=None, std_lib_path=None, print_sink=None)[source]

Initialize the HexPatInterpreter with include search paths.

Parameters:

include_paths (list[Path] | None) – Additional directories to search for included files.
std_lib_path (Path | None) – Override path for the standard library directory.
print_sink (Callable[[str], None] | None) – Optional sink invoked with each formatted message produced by std::print. The sink is registered via stdlib.set_print_sink() for the lifetime of every execute* call originating from this instance.

Return type:

None

property last_type_registry: TypeRegistry | None

The TypeRegistry produced by the most recent successful execution.

The registry exposes user-declared struct, union, enum, bitfield, and alias names via TypeRegistry.user_type_names(), allowing IDE-style helpers (autocomplete, validators) to incorporate the identifiers declared by the most recently run pattern.

Returns:

The registry from the last successful: execute / execute_bytes call, or None when no execution has succeeded yet.

Return type:

TypeRegistry | None

set_print_sink(sink)[source]

Replace the std::print output sink for subsequent executions.

Parameters:: sink (Callable[[str], None] | None) – Callable receiving each formatted std::print payload, or None to clear any previously installed sink.
Return type:: None

execute(source, document, offset=0, file_path=None)[source]

Execute a .hexpat pattern against binary data.

Parameters:

source (str) – The .hexpat source code to interpret.
document (HexDocumentLike) – A HexDocument PyO3 object or any object with read(offset, length) -> list[int] and length() -> int.
offset (int) – Base offset in the binary data to start parsing.
file_path (Path | None) – Path to the source file for #include resolution and error messages.

Returns:

A list of ParsedField-compatible dicts with keys: name, offset, size, raw_bytes, display_value, children, color, validation_passed, description.

Return type:

list[dict[str, Any]]

execute_file(pattern_path, document, offset=0)[source]

Execute a .hexpat file against binary data.

Parameters:

pattern_path (Path) – Path to the .hexpat file to execute.
document (HexDocumentLike) – A HexDocument PyO3 object.
offset (int) – Base offset in the binary data.

Returns:

A list of ParsedField-compatible dicts.

Return type:

list[dict[str, Any]]

execute_bytes(source, data, offset=0, file_path=None)[source]

Execute a .hexpat pattern against raw bytes.

Convenience method for testing without a HexDocument.

Parameters:

source (str) – The .hexpat source code.
data (bytes) – Raw binary data to parse.
offset (int) – Base offset in the data.
file_path (Path | None) – Optional source file path.

Returns:

A list of ParsedField-compatible dicts.

Return type:

list[dict[str, Any]]

can_compile_to_json(source)[source]

Check if a pattern can be compiled to JSON for the fast Rust path.

A pattern is eligible for JSON compilation if it contains only static struct/union/enum/bitfield declarations with no functions, loops, match statements, or runtime-computed expressions.

Parameters:: source (str) – The .hexpat source code to check.
Returns:: True if the pattern can be compiled to JSON.
Return type:: bool

static compile_to_json(source)[source]

Compile a simple pattern to JSON for the Rust evaluator.

Delegates to the existing HexPatCompiler for patterns that pass can_compile_to_json(). Native HexPatError instances propagate unchanged so callers preserve precise diagnostic information (parse vs. type vs. runtime errors). Only an unrelated ImportError from the helper module is wrapped, since the compiler module is treated as an integration boundary rather than a runtime defect path.

Parameters:: source (str) – The .hexpat source code.
Returns:: JSON string representing the template.
Return type:: str
Raises:: HexPatError – If the underlying compiler module cannot be imported. Native HexPatError subclasses raised by the compiler propagate unchanged.

exception HexPatRuntimeError[source]

Bases: HexPatError

Error during pattern evaluation against binary data.

__init__(message, line=0, column=0, file='', offset=0, end_offset=None)[source]

Initialize the HexPatRuntimeError with location, message, and data span.

Parameters:

message (str) – Human-readable error description.
line (int) – Source line number where the error occurred.
column (int) – Source column number where the error occurred.
file (str) – Source file path where the error occurred.
offset (int) – Byte offset in the binary data.
end_offset (int | None) – Optional end byte offset for the error data span.

Return type:

None

property data_span: tuple[int, int] | None

The byte range for the runtime error if available.

Returns:: A tuple (offset, end_offset) when both start and end byte offsets are known, otherwise None.
Return type:: tuple[int, int] | None

class PatternMetadata[source]

Bases: object

Metadata extracted from a .hexpat pattern file.

Variables:

name (str) – The pattern name derived from the filename.
file_path (Path) – Absolute path to the .hexpat file.
description (str | None) – Human-readable description from #pragma description.
author (str | None) – Pattern author from #pragma author.
mime_types (tuple[str, ...]) – MIME types this pattern handles from #pragma MIME.
magic_bytes (tuple[tuple[int, bytes], ...]) – Magic byte patterns for detection, as (offset, bytes) pairs.
category (str) – Category derived from the parent directory name.

name: str

file_path: Path

description: str | None

author: str | None

mime_types: tuple[str, ...]

magic_bytes: tuple[tuple[int, bytes], ...]

category: str

__init__(name, file_path, description, author, mime_types, magic_bytes, category)

Parameters:

name (str)
file_path (Path)
description (str | None)
author (str | None)
mime_types (tuple[str, ...])
magic_bytes (tuple[tuple[int, bytes], ...])
category (str)

Return type:

None

class PatternRegistry[source]

Bases: object

Discovers, indexes, and matches .hexpat pattern files.

Scans specified directories for .hexpat files, extracts metadata from #pragma directives, and provides file-format matching via magic bytes.

__init__(pattern_dirs=None)[source]

Initialize the PatternRegistry with directories to scan.

Parameters:: pattern_dirs (list[Path] | None) – Directories to scan for .hexpat files.
Return type:: None

scan()[source]

Scan all configured directories for .hexpat files.

Reads the first ~80 lines of each file to extract #pragma metadata. Results are cached until scan() is called again.

Return type:: None

list_patterns()[source]

List all discovered patterns.

Returns:: A list of PatternMetadata for all indexed .hexpat files, sorted by name.
Return type:: list[PatternMetadata]

list_by_category()[source]

List patterns grouped by category.

Returns:: A dict mapping category names to lists of PatternMetadata.
Return type:: dict[str, list[PatternMetadata]]

get_pattern(name)[source]

Look up a pattern by name.

Parameters:: name (str) – The pattern name to look up.
Returns:: The PatternMetadata if found, None otherwise.
Return type:: PatternMetadata | None

match_file(data_reader)[source]

Find patterns whose magic bytes match the given binary data.

Reads the first 1024 bytes and checks each indexed pattern’s magic_bytes against the data.

Parameters:: data_reader (DataReader) – DataReader wrapping the binary data to match.
Returns:: A list of matching PatternMetadata, sorted by specificity (longer magic sequences first).
Return type:: list[PatternMetadata]

static load_source(metadata)[source]

Load the full source code of a pattern file.

Parameters:: metadata (PatternMetadata) – The pattern metadata with the file path.
Returns:: The full .hexpat source code as a string.
Return type:: str
Raises:: OSError – If the file cannot be read.

Submodules

`ast_nodes`	AST node dataclasses for the HexPat .hexpat pattern language parser.
`completer`	Type-name completion source for the HexPat pattern editor.
`data_reader`	Byte-access abstraction over HexDocument or raw bytes for the .hexpat interpreter.
`errors`	Error types for the HexPat pattern language interpreter pipeline.
`evaluator`	Core tree-walking evaluator for the HexPat .hexpat pattern language.
`interpreter`	Top-level orchestrator for the .hexpat pattern language interpreter.
`lexer`	Lexer for the HexPat pattern language.
`parse_helpers`	Shared parsing helpers for the hexpat runtime.
`parser`	Recursive-descent parser with Pratt-style operator precedence for the HexPat pattern language.
`pattern_registry`	Pattern registry for discovering, indexing, and matching .hexpat files.
`pragma`	Shared PragmaInfo dataclass for the HexPat interpreter pipeline.
`preprocessor`	Preprocessor for HexPat .hexpat pattern files.
`stdlib`	Python implementations of builtin:: namespace functions.
`tokens`	Token types and Token dataclass for the HexPat pattern language lexer.
`type_system`	Runtime type registry for the HexPat pattern language evaluator.