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. Enable runtime for attributed model requests and token usage accounting, independently of prompt files or provider SDKs. Use render_checked to obtain immutable, validated text and section provenance before constructing a runtime fragment. See the Rust guide.

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

Modules

runtime

Typed model requests and runtime accounting, independent of any provider SDK. Every fragment requires a source and role. Estimates, tokenizer-measured document budgets, and reported usage are distinct; none implies the others.

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.

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.

RenderedPrompt

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.

RenderedSpan

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

Report

Section

A semantic grouping. IDs have no provider-specific role or trust meaning.

SectionOrigin

A containing section, including unnamed sections and their source position.

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, unknown names, 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.

render

Validate static content, substitute inert strings, then check every final file and section 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 section 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.