intellicrack.core.template_manager

Template file management for the hex editor pattern system.

Manages template storage, loading, saving, and directory structure for both built-in and user-defined binary structure templates.

class TemplateInfo[source]

Bases: object

Metadata about a template file.

Variables:

name (str) – Template name.
description (str) – Human-readable description.
category (str) – Category grouping (e.g. PE, ELF, Custom).
is_builtin (bool) – Whether this is a built-in template.
json_path (Path) – Path to the JSON template file.
dsl_path (Path | None) – Path to the DSL source file, if available.

name: str

description: str

category: str

is_builtin: bool

json_path: Path

dsl_path: Path | None

__init__(name, description, category, is_builtin, json_path, dsl_path)

Parameters:

name (str)
description (str)
category (str)
is_builtin (bool)
json_path (Path)
dsl_path (Path | None)

Return type:

None

exception TemplateBootstrapError[source]

Bases: RuntimeError

Raised when built-in template bootstrap encounters failures.

Aggregates per-template failures encountered while exporting built-in templates or parsing template files so callers can react to or report them without losing information.

Variables:: failed_templates (Sequence[tuple[Path, str]]) – Sequence of (path, error_message) pairs describing each failure encountered during bootstrap.

__init__(message, failed_templates)[source]

Initialize the error with a message and failure details.

Parameters:

message (str) – Human-readable summary of the bootstrap failure.
failed_templates (Sequence[tuple[Path, str]]) – Sequence of (path, error_message) pairs for every template that failed to export or parse.

Return type:

None

failed_templates: Sequence[tuple[Path, str]]

class TemplateManager[source]

Bases: object

Manages template files on disk for the hex editor.

Maintains a directory structure under config_dir/templates/ with builtin and user subdirectories.

__init__(config_dir)[source]

Initialize the TemplateManager with a configuration directory.

Parameters:: config_dir (Path) – Base configuration directory.
Return type:: None

failed_templates: list[tuple[Path, str]]

ensure_directories()[source]

Create the template directory structure if it doesn’t exist.

Return type:: None

bootstrap_builtins(document)[source]

Export all built-in templates as JSON files.

Skips export only when every expected built-in template already exists in the registry on disk. Otherwise iterates over the document’s template list, exporting any missing entries via export_template_json and aggregating per-template failures. Failures are logged at warning and appended to self.failed_templates; if any failures occurred a TemplateBootstrapError is raised after all templates have been processed.

Parameters:: document (HexDocumentFull) – HexDocument instance exposing list_templates_detailed and export_template_json.
Raises:: TemplateBootstrapError – If one or more built-in templates failed to export, or if the document is missing the required template methods while bootstrap is still required.
Return type:: None

list_all_templates()[source]

List all available templates (built-in and user).

Returns:: List of template metadata sorted by name.
Return type:: list[TemplateInfo]

save_user_template(name, json_str, dsl_source=None)[source]

Save a user-defined template.

Writes the JSON template (and the optional DSL source) to disk and only emits user_template_file_written / user_template_dsl_file_written after the corresponding Path.write_text call returns successfully. Failures are logged at error as user_template_write_failed / user_template_dsl_write_failed and re-raised so callers can react.

Parameters:

name (str) – Template name.
json_str (str) – JSON template content.
dsl_source (str | None) – Optional DSL source to save alongside.

Returns:

Path to the saved JSON file.

Return type:

Path

Raises:

ValueError – If the name is empty or produces an empty filename.
OSError – If writing the JSON or DSL file fails.

static load_template(path)[source]

Load a template JSON from disk.

Parameters:: path (Path) – Path to the JSON template file.
Returns:: JSON content string.
Return type:: str
Raises:: FileNotFoundError – If the file does not exist.

delete_user_template(name)[source]

Delete a user-defined template.

Parameters:: name (str) – Template name.
Returns:: True if the template was deleted.
Return type:: bool
Raises:: ValueError – If the name is empty.

property patterns_dir: Path

The community .hexpat patterns directory.

Returns:: The vendor community patterns directory path.
Return type:: Path

get_pattern_registry()[source]

Get or create the PatternRegistry for .hexpat pattern discovery.

Returns:

A PatternRegistry instance, or None if: unavailable.

Return type:

PatternRegistry | None

list_hexpat_patterns()[source]

List all discovered .hexpat patterns with metadata.

Returns:

List of dicts with name, description,: category, and file_path keys.

Return type:

list[dict[str, str]]

list_hexpat_by_category()[source]

List .hexpat patterns grouped by category.

Returns:: Category name to list of pattern dicts.
Return type:: dict[str, list[dict[str, str]]]