Skip to main content

Module keys

Module keys 

Source
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_X as it is taken (docs/plans/batch.md 2.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.
TemplateError
Why a template is refused.
TemplateKind
An output kind a template expands for.
TemplateRefusal
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_name refuses a segment to start with.
RESERVED_PREFIX
The key 2.3’s reserved_prefix refuses, 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 is too_long.

Functions§

check
The key, or the first rule of 2.3 it breaks (but prefix_conflict and archive_conflict, which phase 6 decides).
check_member
An archive member path’s check (4.7): check without reserved_prefix and reserved_name.
check_member_template
Checks an archive member’s path template of kind (1.7, 4.7): check_template without reserved_prefix and reserved_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 in scratch, at most STOP bytes of them, so a scratch of 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 first at bytes start a code point that src holds whole past at: none when at falls 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 is unnamed.
safe_into
safe of bytes written into out, at most room bytes of it: the same bytes as the first room of safe’s, made a code point at a time, with no copy of bytes. 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 . is unnamed.
tokens
The tokens of text, a template of kind, in order: the one reading of 2.1’s grammar, which Template::parse and check_template share. It allocates nothing but an error’s name, and ends after the first error. An empty text has no token (the grammar’s 1* is the caller’s).