package cascade

  1. Overview
  2. Docs

Module Cascade.ErrorSource

Parse errors, sealed.

Every error is anchored to a Loc.t and labelled with the Sort.t of the IR node the parser was building when the failure occurred. The kind variant is closed: every CSS-syntax-level failure that the parser can emit is enumerated here.

Sourcetype kind =
  1. | Sort_mismatch of {
    1. expected : Sort.t;
    2. found : Sort.t;
    }
    (*

    Got a node of the wrong category, e.g. a component where a declaration was required.

    *)
  2. | Unexpected_token of Token.kind
    (*

    Hit a token that has no place in the current production.

    *)
  3. | Missing_token of string
    (*

    Expected a specific lexical thing, e.g. "';'" or "')'".

    *)
  4. | Bad_selector of string
    (*

    Selector parser rejected the prelude; payload is a short reason.

    *)
  5. | Bad_value of {
    1. property : string;
    2. reason : string;
    }
    (*

    Property value validator rejected the right-hand side.

    *)
  6. | Bad_condition of {
    1. at_rule : string;
    2. reason : string;
    }
    (*

    At-rule prelude (e.g. @supports) rejected by its condition grammar.

    *)
  7. | Unknown_at_rule of string
    (*

    At-keyword name has no registered handler.

    *)
  8. | Unterminated of Sort.t
    (*

    Hit EOF inside a Sort.t that needed a closing delimiter.

    *)
Sourcetype t = {
  1. loc : Loc.t;
  2. sort : Sort.t;
  3. path : string list;
  4. kind : kind;
  5. source : string option;
  6. filename : string option;
}

path is a breadcrumb trail from the outermost context down to the exact sub-production that failed, rendered with "/" separators. source carries the raw input string for materialising a snippet on demand via snippet.

Sourceval pp_kind : kind Pp.t

pp_kind renders just the reason, e.g. expected <ident> but found <delim '.'>.

Sourceval pp : t Pp.t

pp renders the located, sort-tagged error, e.g. expected <ident> but found <delim '.'> at [12-13] (in selector).

Sourceval to_string : t -> string

to_string error renders error as source text.

Construction and raising

Two flavours, Stdlib.failwith-style:

  • Value constructors (sort_mismatch, bad_selector, ...) build an t. Use when collecting non-fatal warnings, e.g. Parser.stylesheet.
  • Raising constructors (fail_sort_mismatch, fail_bad_selector, ...) build the same error and immediately raise Parse_error. Use at the point of failure inside a decoder.
Sourceexception Parse_error of t

Raised by parsers (and the Cursor helpers) on the first unrecoverable failure.

Sourceval fail : t -> 'a

Raises Parse_error with the given value.

Sourceval with_context : string -> (unit -> 'a) -> 'a

with_context label f runs f () and, on a raised Parse_error, prepends label to the error's context path. Compose on every descent into a named sub-production (:is(), [attr], nth-child, ...) to build breadcrumb paths like ":is()/.foo".

Sourceval v : ?path:Loc.Path.t -> ?source:string -> ?filename:string -> loc:Loc.t -> sort:Sort.t -> kind -> t

v ~loc ~sort kind builds an Error.t.

Sourceval with_filename : ?filename:string -> t -> t

with_filename ~filename t stamps filename onto t when t does not already carry one. Used by entry points that know the source filename to annotate warnings collected by inner readers.

Sourceval with_property : string -> t -> t

with_property property t fills in the property name of a Bad_value error raised without one - the typed value readers reject a right-hand side without knowing which property they serve, so the declaration parser stamps it back on. A non-Bad_value error, or one that already names a property, is returned unchanged.

Sourceval context : t -> Loc.Context.t

context t is the structured error context.

Sourceval snippet : t -> Loc.Context.snippet option

snippet t materialises the source-context snippet from t.source and t.loc. Returns None when no source was attached.

Value constructors

Sourceval sort_mismatch : Loc.t -> sort:Sort.t -> expected:Sort.t -> found:Sort.t -> t

sort_mismatch loc ~sort ~expected ~found flags a category mismatch.

Sourceval unexpected_token : Loc.t -> sort:Sort.t -> Token.kind -> t

unexpected_token loc ~sort k flags a stray token in a sort production.

Sourceval missing_token : Loc.t -> sort:Sort.t -> string -> t

missing_token loc ~sort what flags an expected lexeme that wasn't found.

Sourceval bad_selector : Loc.t -> string -> t

bad_selector loc reason flags a selector the validator rejected.

Sourceval bad_value : Loc.t -> property:string -> reason:string -> t

bad_value loc ~property ~reason flags a failed property value.

Sourceval bad_condition : Loc.t -> at_rule:string -> reason:string -> t

bad_condition loc ~at_rule ~reason flags a failed at-rule prelude.

Sourceval unknown_at_rule : Loc.t -> string -> t

unknown_at_rule loc name flags an \@name keyword with no handler.

Sourceval unterminated : Loc.t -> Sort.t -> t

unterminated loc s flags an EOF inside an unclosed node of sort s.

Raising constructors

fail_x args is fail (x args).

Sourceval fail_sort_mismatch : Loc.t -> sort:Sort.t -> expected:Sort.t -> found:Sort.t -> 'a

fail_sort_mismatch loc ~sort ~expected ~found raises sort_mismatch.

Sourceval fail_unexpected_token : Loc.t -> sort:Sort.t -> Token.kind -> 'a

fail_unexpected_token loc ~sort k raises unexpected_token.

Sourceval fail_missing_token : Loc.t -> sort:Sort.t -> string -> 'a

fail_missing_token loc ~sort what raises missing_token.

Sourceval fail_bad_selector : Loc.t -> string -> 'a

fail_bad_selector loc reason raises bad_selector.

Sourceval fail_bad_value : Loc.t -> property:string -> reason:string -> 'a

fail_bad_value loc ~property ~reason raises bad_value.

Sourceval fail_bad_condition : Loc.t -> at_rule:string -> reason:string -> 'a

fail_bad_condition loc ~at_rule ~reason raises bad_condition.

Sourceval fail_unknown_at_rule : Loc.t -> string -> 'a

fail_unknown_at_rule loc name raises unknown_at_rule.

Sourceval fail_unterminated : Loc.t -> Sort.t -> 'a

fail_unterminated loc s raises unterminated.