Expand description
Key templates, safe() and the key rules (docs/BATCH_SPEC.md 2.1 to
2.3; docs/plans/extract.md E27, E28).
A Template is parsed once, refusing an unknown variable or one its
kind does not allow (validation’s refusal, exit 78, is the engine’s). Its
expansion is bytes, a plain variable written verbatim (a name’s stored
bytes) and a safe_ one through safe_into; check then names the
first rule of 2.3 the key breaks, or gives it back as UTF-8, and
check_prefixed checks it again after the sink’s prefix, as 2.3 says.
An expansion stops at STOP bytes (docs/plans/batch.md 2.6 step 5),
written into a buffer of that capacity the caller charged, each value
read only as far as the room left (review round 2’s S3), so a key past
KEY_MAX is read no further and check decides it on what it holds
(2.3’s rule for a key past its bound). prefix_conflict and
archive_conflict are phase 6’s (4.6). KeyTable is the attempt’s one
key table, charged to M_X.
Structs§
- KeyTable
- The attempt’s key table (4.4 step 3): one for every kind’s stage, the
engine’s to make and hand to each attempt, every key charged to
M_Xas it is taken (docs/plans/batch.md2.6 step 5): its string, and the set’s buckets before they grow ([Set]). - Template
- A parsed template.
- Tokens
tokens’ iterator.
Enums§
- KeyRule
- The rules of 2.3 an attempt checks, in the table’s order, which their order as values keeps.
- Template
Error - Why a template is refused.
- Template
Kind - An output kind a template expands for.
- Template
Refusal - Why validation refuses a template: rule
template(section 10). - Token
- A piece of a template’s text as 2.1’s grammar reads it, borrowed from
the text: a run of literal characters, the one brace
{{or}}writes, or a variable. - Var
- A template variable (2.1’s table).
Constants§
- KEY_MAX
- The longest key.
- RESERVED_
NAME - What 2.3’s
reserved_namerefuses a segment to start with. - RESERVED_
PREFIX - The key 2.3’s
reserved_prefixrefuses, and every key under it. - SEGMENT_
MAX - The longest segment (
NAME_MAX). - STOP
- Where an expansion stops: one byte past
KEY_MAX, which is enough to know the key istoo_long.
Functions§
- check
- The key, or the first rule of 2.3 it breaks (but
prefix_conflictandarchive_conflict, which phase 6 decides). - check_
member - An archive member path’s check (4.7):
checkwithoutreserved_prefixandreserved_name. - check_
member_ template - Checks an archive member’s path template of
kind(1.7, 4.7):check_templatewithoutreserved_prefixandreserved_name. - check_
prefixed - 2.3’s two checks: the key as given, then after
prefix(the sink’s), the first rule either breaks naming the refusal. The two are joined inscratch, at mostSTOPbytes of them, so ascratchof that capacity allocates nothing. - check_
template - Checks a key template of
kind(an output’s key, 2.1): it parses, and its literals pass 2.3’s rules as 2.1 says. - cut_
tail - How many of
src’s firstatbytes start a code point thatsrcholds whole pastat: none whenatfalls on a code point boundary, or the bytes there are no valid code point’s start. - entry_
cost - What one key costs its table beside the table’s buckets: the string,
at
heap_cost. - safe
safe()(2.2): per code point, an invalid UTF-8 byte counting as one, every one outside[A-Za-z0-9._-]becomes_; then every leading and trailing.is stripped; an empty result isunnamed.- safe_
into safeofbyteswritten intoout, at mostroombytes of it: the same bytes as the firstroomofsafe’s, made a code point at a time, with no copy ofbytes. A run of.is written only once a code point other than.follows it (a trailing run is stripped), and a value of nothing but.isunnamed.- tokens
- The tokens of
text, a template ofkind, in order: the one reading of 2.1’s grammar, whichTemplate::parseandcheck_templateshare. It allocates nothing but an error’s name, and ends after the first error. An empty text has no token (the grammar’s1*is the caller’s).