of_components ?source ?recover ?meta ?eof_loc cvs is a fresh cursor over cvs. Pass ?source so errors raised while consuming the cursor get a source-context snippet attached (matching of_string's behaviour). Pass ~recover:true to enable per-declaration recovery: validators that honour recover will catch a Parse_error on one declaration, push it to push_warning, and skip to the next ; instead of propagating. ?meta controls snippet construction and defaults to Loc.default_meta_level. ?eof_loc anchors end-of-input errors at a specific location.

sub ?eof_loc parent cvs is a fresh cursor over cvs that inherits parent's source, warnings list, recovery mode, and meta level. Pass ?eof_loc to anchor end-of-input errors at a specific location (e.g. the closing delimiter of a block); defaults to parent's own eof_loc.

func_sub fn parent is a sub-cursor over fn's arguments, anchored so an EOF error inside the function body points at the function's closing ')' rather than the end of the outer input.

recover t is the recovery mode t was built with. Validators that support declaration-level recovery check this to decide whether to catch and skip on a Parse_error or let it propagate.

meta t is the metadata level t was built with. At `Full errors carry source-context snippets; lower levels skip snippet construction.

source t is the preprocessed source text that produced t, when known.

push_warning t ~recovery e records e as a non-fatal warning on t, stamped with what the recovery did to the construct e is about. A validator in recovery mode catches a Parse_error, pushes it here, skips to a recovery point, and keeps going. Drained via drain_warnings.

drain_warnings t returns and clears the warnings accumulated on t in source order.

of_string ?meta ?unicode_ranges s lexes s into a Component.t list and wraps it. The trailing Eof token is dropped. unicode_ranges is passed to Lexer.of_reader, and only the value of a unicode-range descriptor sets it.

of_reader ?meta r consumes the rest of r's input as a component stream and wraps it.

peek t is the next component, or None at end of input. Skips any leading whitespace components.

next t consumes and returns the next component (or None at end of input). Skips any leading whitespace components.

skip t consumes the next component and discards it.

is_done t is true when only whitespace (or nothing) remains.

position t is the Loc.t of the next component, or Loc.dummy if is_done.

remaining t is the un-consumed tail (still includes whitespace).

string_of_components ?trim cvs serializes a component-value list. This is useful for at-rule preludes that must be split structurally before being preserved as raw CSS text.

string_of_components_verbatim cvs is string_of_components except that a whitespace run and an escaped token write back the text they were read from. A conditional group's prelude is the question the rendering browser is asked, so its spelling survives.

string_of_remaining t serializes the unconsumed tail without advancing t.

consume_remaining t is remaining, and also consumes the tail.

consume_remaining_as_string t serializes and consumes the unconsumed tail.

ws t drops any leading whitespace components. Usually a no-op since typed helpers skip whitespace for you; useful when a raw peek_raw or next_raw is about to run.

peek_raw t is the next component without skipping whitespace.

Head-shape classification of the next non-whitespace component, returned as a polymorphic variant constant so it carries no allocation.

peek_head_shape t classifies the next non-whitespace component, without boxing the component in Some _.

next_raw t consumes the next component without skipping whitespace.

skip_ws t consumes any leading whitespace and returns whether at least one whitespace component was skipped.

save t captures the current cursor position.

restore t s rewinds t to the position captured by s.

dropped_since t s construct is a dropped-construct recovery naming the source text from the first component t consumed since s to the last, whitespace at either end left out. A recovery point takes s before the item it gives up on and calls this once it has skipped that item, so the recovery names the whole construct the reader threw away rather than the point the read failed at. It names no text when t carries no source, when nothing but whitespace was consumed, or when s is no snapshot t advanced from.

atomic t f runs f () with a snapshot held; if f raises Parse_error, the cursor is restored before the exception propagates.

lookahead p t runs p t and then restores the cursor, returning the result.

try_typed_call typed t runs the typed reader typed when the next component is a Func. On success, returns Ok value. On Parse_error, restores the cursor, skips past the function call, and returns Error <captured-call> so callers can wrap it in their type's Invalid arm. When the next component isn't a Func the typed reader is run directly (errors propagate).

Alias for Error.Parse_error.

err ?loc ?got t msg raises Parse_error at the current position, or at loc when given. A reader that consumes the offending token before rejecting it passes the span it read: position has moved on to whatever follows by then, which at the end of a value is the terminator.

err_invalid t msg is err t ("invalid: " ^ msg).

err_eof t raises an "unexpected end of input" error.

err_expected t what raises with "expected what".

err_expected_but_eof t what raises when end of input is reached while expecting what.

err_unexpected t raises "unexpected token" at the current position.

condition_error t ~at_rule reason is the Error.kind.Bad_condition for at_rule anchored at the current position, with t's source attached. A reader that buffers a failure before deciding whether to recover from it builds the error here and raises it later.

err_condition t ~at_rule reason raises Parse_error carrying condition_error. An at-rule prelude reader raises through this so the caret lands on the slice of the condition that failed rather than on the enclosing rule.

with_context t label f annotates any Parse_error raised by f with label in the error path.

ident t consumes the next ident. keep_case defaults to true, the author's spelling, which is what an author-defined identifier is (CSS Values 4 sec. 4.2). ~keep_case:false lowercases it, which is what a keyword is (sec. 4.1).

custom_ident label t consumes a <custom-ident> in the author's spelling and raises on one sec. 4.2 excludes: a CSS-wide keyword or the reserved default. reserved names what the production excludes on top of those, such as none for a <counter-style-name>. Every exclusion is matched in all ASCII case permutations, and label names the production in the error.

is_reserved_custom_ident name is whether custom_ident refuses name, over the same exclusions and the same reserved extension. A printer asks it where a grammar spells the same name as an ident or a string, since a reserved name has no ident spelling and has to keep its quotes.

number t consumes the next numeric token.

int t consumes the next integer token.

hex t consumes a hash token and parses it as hex.

string t consumes a string literal.

url t consumes the body of a url(...) call (either a <url-token> or a function call with a quoted argument).

pct t consumes a percentage token. If ~clamp is set, the value is clamped to 0..100.

number_with_unit t consumes a dimension, percentage or number and returns the value and unit (if any).

number_repr_with_unit t is like number_with_unit, but also returns the authored numeric token representation.

bool t consumes true or false.

ident_opt t consumes and returns an identifier if present.

number_opt t consumes and returns a number token if present.

integer_opt t consumes and returns an integer-valued number if present.

percentage_opt t consumes and returns a percentage value if present.

dimension_opt t consumes and returns a dimension value and unit if present.

hash_opt t consumes and returns a hash token value if present.

string_opt t consumes and returns a string token if present.

string_with_quote_opt t consumes and returns a string token plus its quote character if present.

string_repr_with_quote_opt t is like string_with_quote_opt, but also returns the authored string token spelling when source text is available.

url_opt t consumes and returns a URL token if present.

delim_opt t consumes and returns a delimiter token if present.

peek_delim t is the char of the next component if it is a Delim token, without advancing the cursor.

peek_comma t is true iff the next component is a comma token.

peek_semicolon t is true iff the next component is a semicolon token.

peek_colon t is true iff the next component is a colon token.

peek_ident t is Some s when the next component is Ident s.

peek_keyword t is the next identifier folded to ASCII lower case, for matching against a keyword. CSS Values 4 sec. 4.1. Use peek_ident for an author-defined name, which sec. 4.2 keeps case-sensitive.

peek_hash t is Some s when the next component is Hash s.

peek_at_keyword t is Some s when the next component is At_keyword s.

peek_block t is Some bracket when the next component is a balanced block, returning its opening bracket kind.

at_keyword_opt t consumes the next component if it is an At_keyword token, returning the keyword name without the leading @.

expect_at_keyword name t consumes the @name token or raises. The name is a keyword, matched ASCII case-insensitively (CSS Values 4 sec. 4.1), so name is given lowercase.

drain_until_block t consumes components up to (but not including) the next block or semicolon, returning the drained components. Used for at-rule preludes.

Like drain_until_block, but serializes the drained components.

consume_until_semicolon t consumes and serializes components up to, but not including, the next semicolon.

skip_past_semicolon t consumes and discards components up to and including the next top-level semicolon, or up to end of input if none is left. A {} met on the way is one component value, not a stopping point, so this is the recovery step CSS Syntax 3 (ED) sec. 5.5.5 prescribes for a declaration that fails to parse.

consume_to_decl_end t consumes and serializes components up to, but not including, the next semicolon or top-level ! delimiter.

drain_to_decl_end t consumes components up to (but not including) the next semicolon or top-level ! delimiter, returning the drained list without serialising it.

decl_value_loc t is the span the declaration value ahead covers, without consuming it, or position when no value is left. A shorthand reader that takes the whole value before deciding it is bad reports against this, since the failure is the value's rather than that of the token after it.

declaration_value t consumes a declaration's value off t and is a cursor over it alone.

CSS Syntax 3 (ED) sec. 5.5.6 reads the value with <semicolon-token> as the stop token, then lifts a trailing ! important pair out of it into the declaration's important flag. A property grammar is handed what is left, which holds neither, so a reader whose grammar has an optional trailing component asks is_done and nothing more: the ; and the ! stay on t for the declaration consumer to finish. End-of-input errors on the value anchor at whichever of the two stopped it.

consume_to_slash_or_semicolon t consumes and serializes components up to, but not including, the next top-level slash delimiter or semicolon.

colon t consumes a ':' if next; true iff consumed.

semicolon t consumes a ';' if next; true iff consumed.

comma t consumes a ',' or raises.

comma_opt t consumes a ',' if next; true iff consumed.

slash t consumes a / delim or raises.

slash_opt t consumes a / delim if present and returns whether it was consumed.

consume_if c t consumes the next component if it is the delim c.

try_kind kind t consumes kind if it is next and returns whether it matched.

try_ident name t consumes the next component if it is the identifier name and returns whether it matched. The ident is a keyword, matched ASCII case-insensitively (CSS Values 4 sec. 4.1), so name is given lowercase.

try_kind_pair k1 k2 t consumes k1 followed by k2 if both are next and returns whether they matched.

looking_at t s is true iff the next component (after leading whitespace) starts with s - matches an ident, a function name followed by (, or a delim-based prefix. Idents and at-keywords match ASCII case-insensitively (CSS Values 4 sec. 4.1), so s is given lowercase.

looking_at_ident name t is true if the next component is identifier name, compared ASCII case-insensitively (CSS Values 4 sec. 4.1), so name is given lowercase.

looking_at_func name t is true if the next component is function name, compared ASCII case-insensitively (CSS Values 4 sec. 4.1), so name is given lowercase.

looking_at_calc t is true if the next component is calc() or the legacy -webkit-calc() spelling.

peek_function_name t is the name of the function call the cursor is on, lowercased (CSS Values 4 sec. 4.1), without consuming it. Use it where the caller decides on a set of names rather than on one.

expect c t consumes the delim c or raises.

expect_string s t consumes the ident s or raises. The ident is a keyword, matched ASCII case-insensitively (CSS Values 4 sec. 4.1), so s is given lowercase.

expect_eof t raises if any non-whitespace component remains.

parens f t consumes a (...) block and calls f with a fresh cursor over its contents. Raises if the next component is not a parenthesised block, or if f leaves any of the contents unconsumed: trailing content makes the value invalid, not truncated (CSS Syntax 3 (ED) sec. 5.4.1).

brackets t f consumes a [...] block similarly.

braces t f consumes a {...} block similarly.

call name t f consumes a name(...) function call and applies f to a cursor over its arguments. Raises if no such function is next, or if f leaves any of the arguments unconsumed: trailing content makes the value invalid, not truncated (CSS Syntax 3 (ED) sec. 5.4.1).

function_call name f t consumes a name(...) call and calls f over its arguments, raising if f leaves any of them unconsumed, as call does. Returns None without advancing if the next component is not a function with that name, compared ASCII case-insensitively (CSS Values 4 sec. 4.1), so name is given lowercase.

any_function_call f t consumes any function call and applies f to its name and argument cursor, raising if f leaves any argument unconsumed, as call does.

enum ?default label table t skips leading whitespace, consumes an ident, and looks it up in table. Falls back to default if provided, otherwise raises.

try_enum table t is like enum but returns None without raising. Keys are given lowercase.

enum_calls ?default table t skips leading whitespace, then dispatches on the name of the next function call. Each parser receives the raw cursor (still pointing at the function) and is expected to consume it.

enum_or_calls ?default label idents ?calls t skips leading whitespace, first tries to match idents (ident token), then calls (function call), and finally falls back to default. Raises if none apply and no default is given.

enum_or_var label idents ~var t is enum_or_calls specialised to the common case of "match a CSS keyword from idents, or read var(...) via var". Removes the boilerplate of writing the var entry in a calls list at every typed-property reader. var reads whatever the caller is reading, which for a reader called once per shorthand slot is that slot.

enum_or_whole_value_var is enum_or_var for a reader that owns the whole declaration value, where var stands for all of it. A var() with components after it is an operand of default's grammar rather than the value, so such a value goes to default.

option p t returns Some (p t) on success, None if p raises Parse_error (cursor is rewound).

one_of ps t tries each parser in order, rewinding on failure.

list ?sep ?at_least ?at_most item t parses items separated by sep (default: no separator). Lists require at least one item unless at_least is specified explicitly. A sep only commits once another item parses after it, so a trailing separator with nothing following it is left unconsumed for the caller rather than silently dropped. Enforces cardinality bounds. Too few items raise "expected at least N items (got M)", the wording Reader.list uses.

Like many but folds into an accumulator. Returns the final accumulator and the last error (if any).

many p t runs p repeatedly while it succeeds; returns the list of results and the last error message on failure (or None if the stream simply ran out).

pair ?sep a b t parses a followed by b, optionally separated by sep. Atomic: a failure in sep or b rewinds the cursor to where a started, so the caller can try another alternative.

triple ?sep a b c t parses a, b, and c, optionally separated by sep. Atomic like pair.

try_parse_err p t returns Ok v on success or Error msg on parse failure (cursor rewound).

try_parse_full_err p t is like try_parse_err, but also requires p to consume the cursor fully.