Crate htmlp 

Strict, self-contained prompt files. The default library uses xmlparser and sha2; token counting is an injected TokenCounter. Enable tokens for CL100K, json for serialization, or cli for the standalone tool. Markup and the Rust API share one primitive: an Element with a name, an optional id, and budgets. Use Document::render to obtain immutable, validated text with per-element provenance. See the Rust guide.

let doc = htmlp::parse(r#"<htmlp max-tokens="10k" reason="Shared context."><task id="review">Review.</task></htmlp>"#)?;
assert_eq!(doc.get_element_by_id("review").unwrap().to_string(), "Review.");

Structs

Cl100k

Offline, exact CL100K token counting. Special-token-looking strings are ordinary text. This counts content, not any provider’s message framing overhead.

Diagnostic

Syntax, budget, tokenizer, or binding failure. No partial AST is returned.

Document

Portable AST. Use crate::parse or Document::new to create a document.

Element

A named grouping. Names and optional IDs have no provider role or trust meaning.

ElementOrigin

A containing element, including anonymous elements and their source position.

FileReport

A per-file report; files in a directory are never merged or inherited.

Limits

Limits are tokens, stored as expanded integers (1.5k becomes 1500).

Measurement

Per-element measurement. tokens is None and deferred is true when unbound variables prevent an exact count. Render to enforce those budgets.

Position

One-based Unicode-scalar line/column; zero-based UTF-8 byte offset. Zero line/column denotes an unknown location or an in-memory node.

RenderedDocument

Immutable output of a complete successful validation. No constructor or deserializer can fabricate checked output. Extracted text is ordinary text; modifying it does not preserve this object’s validation guarantee.

RenderedElement

One element’s rendered range, including empty and anonymous elements. These ranges may overlap; use spans for a non-overlapping partition.

RenderedSpan

Non-overlapping UTF-8 byte span in the final text. Element ancestry preserves nesting without counting a parent’s text a second time. Variables remain literal values and inherit their containing element’s attribution.

Report

TextMeasurement

A tokenizer-specific count of a complete rendered document, excluding provider message framing. Distinct from a runtime request estimate.

Variable

A named string slot: {{question}}. Variables have no limits.

Enums

ElementRef

A typed reference returned by ID lookup. Repeated variable names return the first reference in source order.

Node

Markdown stays literal text. These are the only content node kinds.

Traits

TokenCounter

Inject a tokenizer to keep the parser independent of large vocabulary tables. name must match the document’s tokenizer identifier. Implementations must count the supplied string as ordinary text, without interpreting special IDs.

Functions

budget_signature

First eight bytes of SHA-256 as lowercase hex. Covers normalized local limits and the decoded reason, not content, identity, or approval. Returns None when neither limit is declared. See the specification for the canonical byte encoding, allowing implementations in other languages.

check_path

Recursively check .htmlp files independently, in sorted order. Skip symlinks and .git, node_modules, target, dist, and vendor. An explicit file must have .htmlp extension. No matches is an error, avoiding empty CI passes.

lint

Check fully static subtrees exactly. Subtrees containing variables are reported as deferred, with no guessed count. Render to check their budgets.

parse

Parse strict HTML-inspired markup using a tested XML tokenizer. XML-only constructs, namespaces, invalid names, unknown attributes, and implicit repair are rejected. Empty elements may use self-closing tags. Markdown indentation is preserved, not inferred or rewritten.

parse_file

Read UTF-8 source with a 4 MiB cap before allocating the full input.

parse_limit

Parse an integer token budget or a decimal-k budget: 500, 10k, 1.5K. k means 1000. Fractional tokens, negatives, whitespace, and overflow fail.

parse_template

Parse Rust text interpolation into the same nodes as markup placeholders. Only {{name}} is special. Other text, including < and &, is literal; use Node::text for literal braces. HTML source decodes entities separately.

render

Validate static content, substitute inert strings, then check every final file and element budget. Variables have no separate limit. No output is returned on any error.

render_checked

Bind and validate the entire document, returning immutable text, exact tokenizer measurement, budget report, and non-overlapping element provenance.

sign_path

Sign all .htmlp files using the same traversal as check_path. All files are parsed before any writes. Changed files are replaced atomically, keeping permissions. Returns changed paths. An I/O failure can leave earlier files updated; a directory is not a transaction. Avoid concurrent source edits.

sign_source

Add or replace budget signatures without reformatting source. Existing quotes, Markdown, comments, line endings, and attribute order are preserved. Removes signatures from elements that no longer declare a local limit. Invalid syntax or missing reasons return an error without any output.

Type Aliases

Bindings

Runtime values are strings; never expressions or reparsed markup.