package cascade

  1. Overview
  2. Docs
package cascade
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module Cascade.StylesheetSource

CSS stylesheet interface.

This module models stylesheet syntax and CSS-file-local structure: construction, parsing, printing, traversal helpers, and context-free cascade ordering helpers. Operations that need information beyond stylesheet text should take an explicit closed context record from a dedicated module, such as Context.

include module type of Stylesheet_intf

Core Types

Import Rule

Sourcetype import_rule = {
  1. url : string;
    (*

    URL or string to import

    *)
  2. layer : string option;
    (*

    Optional layer name

    *)
  3. supports : Supports.t option;
    (*

    Optional supports condition

    *)
  4. media : Media.t option;
    (*

    Optional media query

    *)
}

A CSS \@import rule

Property Rule

Sourcetype 'a property_rule = {
  1. name : string;
  2. syntax : 'a Variables.syntax;
  3. inherits : bool;
  4. initial_value : 'a option;
}

Type-safe CSS @property rule with typed syntax and initial value

Cascade Origins

Sourcetype cascade_origin =
  1. | User_agent
  2. | User
  3. | Author_presentational_hint
  4. | Author
  5. | Animation
  6. | Transition
    (*

    Cascade origins from CSS Cascading and Inheritance. Animation and Transition represent generated virtual rules.

    *)
Sourcetype cascade_layer_candidate = {
  1. layer : string option;
    (*

    Explicit layer name, or None for the implicit unlayered layer.

    *)
  2. important : bool;
    (*

    Whether this candidate comes from an important declaration.

    *)
  3. source_order : int;
    (*

    Later source-order values win after layer precedence ties.

    *)
  4. value : string;
    (*

    Test/API payload representing the cascaded value.

    *)
}

A minimal same-origin/same-specificity cascade candidate used to model the layer and source-order parts of the cascade sorting order.

Sourcetype cascade_origin_candidate = {
  1. origin : cascade_origin;
    (*

    Origin bucket that contributes this same-property candidate.

    *)
  2. important : bool;
    (*

    Whether this candidate comes from an important declaration.

    *)
  3. source_order : int;
    (*

    Later source-order values win after origin/importance ties.

    *)
  4. value : string;
    (*

    Test/API payload representing the cascaded value.

    *)
}

A minimal same-specificity cascade candidate used to model origin, importance, and source-order sorting.

Sourcetype declared_value = {
  1. property : string;
  2. value : string;
  3. important : bool;
  4. source_order : int;
}

A declared value contributed by one property declaration before cascade sorting. The value is the declaration's minified CSS value string.

Sourcetype value_source =
  1. | Cascaded
  2. | Initial_default
  3. | Inherited_default
  4. | Initial_keyword
  5. | Inherit_keyword
  6. | Unset_initial
  7. | Unset_inherited
    (*

    Why a specified value was selected during defaulting.

    *)
Sourcetype value = {
  1. value : string;
  2. value_source : value_source;
}

Result of applying the non-layout parts of specified-value defaulting.

Sourcetype value_processing_stage =
  1. | Declared_value
  2. | Cascaded_value
  3. | Specified_value
  4. | Computed_value
  5. | Used_value
  6. | Actual_value
    (*

    CSS Cascade value-processing stages.

    *)
Sourcetype url_form =
  1. | Bare
  2. | Quoted of char

@namespace prelude URI form. CSS Namespaces 3 1: <string> and url(<string>) are spec-equivalent; url_form further distinguishes whether the url() body itself quoted its argument so the pretty-printer can round-trip the source spelling. Under --minify the printer collapses every form to the bare quoted string (the shortest spelling).

Sourcetype namespace_url =
  1. | Url of string * url_form
  2. | Quoted of string
Sourcetype cascade_candidate = {
  1. origin : cascade_origin;
  2. layer : string option;
  3. important : bool;
  4. specificity : int;
  5. scope_hops : int option;
  6. source_order : int;
  7. value : string;
}

A same-property cascade candidate covering the cascade ordering criteria this library can model without a DOM: origin/importance, layer, specificity, scoping proximity, and source order.

Basic Rules

Sourcetype rule = {
  1. selector : Selector.t;
  2. declarations : Declaration.declaration list;
  3. nested : statement list;
  4. merge_key : string option;
}

A CSS rule with a selector, declarations, optional nested rules/at-rules, and an optional merge key for combining rules with identical declarations. When merge_key is Some key, rules with the same key and identical declarations can be combined into a single rule with a selector list.

Statements and Blocks

Sourceand statement =
  1. | Rule of rule
  2. | Declarations of Declaration.declaration list
    (*

    Bare declarations for CSS nesting (no selector)

    *)
  3. | Bang_comment of string
    (*

    Preserved /*! ... */ comment (license header convention). The body excludes the surrounding /*! / */ delimiters.

    *)
  4. | Charset of string
    (*

    @charset "UTF-8";

    *)
  5. | Import of import_rule
    (*

    @import url(...) layer(...) supports(...);

    *)
  6. | Namespace of string option * namespace_url
    (*

    @namespace prefix? url;

    *)
  7. | Property : 'a property_rule -> statement
    (*

    @property --name { ... }

    *)
  8. | Layer_decl of string list
    (*

    @layer theme, base, utilities;

    *)
  9. | Layer of string option * block
    (*

    @layer name? { ... }

    *)
  10. | Media of Media.t * block
    (*

    @media (...) { ... }

    *)
  11. | Container of string option * Container.t option * block
    (*

    @container name? (...) { ... }

    *)
  12. | Supports of Supports.t * block
    (*

    @supports (...) { ... }

    *)
  13. | Moz_document of moz_document_condition list * block
    (*

    @-moz-document url-prefix(...) { ... }

    *)
  14. | Starting_style of block
    (*

    @starting-style { ... }

    *)
  15. | When of conditional * block
    (*

    @when media(...) { ... }

    *)
  16. | Else of conditional option * block
    (*

    @else supports(...)? { ... }

    *)
  17. | Supports_condition of string * Declaration.declaration list
    (*

    @supports-condition --name { ... }

    *)
  18. | Origin of cascade_origin * block
    (*

    API-level wrapper recording the cascade origin of a stylesheet block. It has no CSS surface syntax, but lets optimizers and tests preserve origin boundaries.

    *)
  19. | Scope of Selector.t option * Selector.t option * block
    (*

    @scope (start)? to (end)? { ... }

    *)
  20. | Keyframes of string * keyframe list
    (*

    @keyframes name { ... }

    *)
  21. | Webkit_keyframes of string * keyframe list
    (*

    @-webkit-keyframes name { ... }

    *)
  22. | Moz_keyframes of string * keyframe list
    (*

    @-moz-keyframes name { ... }

    *)
  23. | Font_face of font_face_descriptor list
    (*

    @font-face { ... }

    *)
  24. | Counter_style of string * counter_style_descriptor list
    (*

    @counter-style name { ... }

    *)
  25. | Page of page_selector list * Declaration.declaration list
    (*

    @page :first { ... }; empty list is a bare @page

    *)
  26. | Page_with_margins of page_selector list * page_descriptor list * page_margin_rule list
    (*

    @page :first { margin: 1cm; @top-left { content: ... } }

    *)
  27. | Font_palette_values of string * font_palette_descriptor list
    (*

    @font-palette-values --name { ... }

    *)
  28. | Font_feature_values of Properties.font_family list * font_feature_values_block list
    (*

    @font-feature-values <family-name># { @styleset { nice: 1 } }

    *)
  29. | View_transition of view_transition_descriptor list
    (*

    @view-transition { navigation: auto }

    *)
  30. | Position_try of string * Declaration.declaration list
    (*

    @position-try --name { top: anchor(...) }

    *)
  31. | Viewport of viewport_prefix * viewport_descriptor list
    (*

    @viewport { ... } / @-ms-viewport { ... } (CSS Device Adaptation 1, deprecated but still emitted by minifiers for legacy IE).

    *)
  32. | Unknown_at_rule of {
    1. name : string;
    2. prelude : string;
    3. block : string option;
    }
    (*

    CSS Syntax 3 sec. 5.4.2 "consume an at-rule" preserves any unrecognised at-rule as raw text so authors can ship unknown vendor or future at-rules without dropping the whole stylesheet.

    *)

A CSS statement - either a rule or an at-rule

Sourceand block = statement list

A block contains a list of statements

Sourceand conditional =
  1. | Media_condition of Media.t
  2. | Supports_condition_test of Supports.t
  3. | And of conditional * conditional
  4. | Or of conditional * conditional
Sourceand moz_document_condition =
  1. | Url_prefix of string option
Sourceand viewport_prefix =
  1. | Standard
  2. | Ms_prefixed
Sourceand viewport_descriptor = {
  1. name : string;
  2. value : string;
}

Raw <name>:<value> pair inside @viewport / @-ms-viewport; viewport descriptors share names with regular CSS properties (e.g., width) but take a viewport-specific value grammar that includes device-width, device-height, so they aren't typed against the property reader.

Sourceand keyframe = {
  1. selector : Keyframe.selector;
    (*

    e.g., From, To, Percent 50.

    *)
  2. declarations : Declaration.declaration list;
}

A single keyframe within \@keyframes

Sourceand page_pseudo =
  1. | First
  2. | Left
  3. | Right
  4. | Blank
Sourceand page_selector = {
  1. name : string option;
  2. pseudos : page_pseudo list;
}

@page selector: an optional page name and zero or more pseudo-pages, e.g. invoice:blank:first

Sourceand page_descriptor = Declaration.declaration
Sourceand font_palette_base =
  1. | Light
  2. | Dark
  3. | Index of int
  4. | Palette_ident of string
Sourceand font_palette_descriptor =
  1. | Palette_font_family of Properties.font_family list
  2. | Base_palette of font_palette_base
  3. | Override_colors of (int * Values.color) list
Sourceand font_feature_values_block = string * (string * int list) list
Sourceand counter_style_system =
  1. | Cyclic
  2. | Numeric
  3. | Alphabetic
  4. | Symbolic
  5. | Fixed of int option
  6. | Additive
  7. | Extends of string
Sourceand counter_style_descriptor =
  1. | System of counter_style_system
  2. | Symbols of string list
  3. | Suffix of string
  4. | Prefix of string
  5. | Fallback of string
  6. | Range of string
  7. | Pad of string
  8. | Negative of string
  9. | Additive_symbols of string
  10. | Speak_as of string
Sourceand view_transition_descriptor =
  1. | Navigation of [ `Auto | `None ]
  2. | Types of string list option
Sourceand font_variant_descriptor =
  1. | Normal
  2. | None
  3. | Values of font_variant_descriptor_value list
Sourceand font_variant_descriptor_value =
  1. | Ligature of Properties.font_variant_ligature
  2. | Caps of Properties.font_variant_caps
  3. | Numeric of Properties.font_variant_numeric_token
  4. | East_asian of Properties.east_asian_feature
Sourceand page_margin_rule = {
  1. name : string;
  2. descriptors : Declaration.declaration list;
}

CSS page margin at-rule inside @page.

Sourceand font_face_descriptor =
  1. | Font_family of Properties.font_family list
    (*

    Font family name

    *)
  2. | Src of Font_face.src
    (*

    Font source (url(), local(), etc.)

    *)
  3. | Font_style of Properties.font_style
    (*

    normal, italic, oblique

    *)
  4. | Font_style_range of Properties.font_style * Properties.font_style
    (*

    variable font style range, e.g. normal italic

    *)
  5. | Font_weight of Properties.font_weight
    (*

    normal, bold, 100-900

    *)
  6. | Font_weight_range of Properties.font_weight * Properties.font_weight
    (*

    variable font weight range, e.g. 100 900

    *)
  7. | Font_stretch of Properties.font_stretch
    (*

    normal, condensed, expanded, etc.

    *)
  8. | Font_stretch_range of string
    (*

    variable font stretch range

    *)
  9. | Font_display of Properties.font_display
    (*

    auto, block, swap, fallback, optional

    *)
  10. | Unicode_range of Properties.unicode_range list
    (*

    CSS Fonts 4 sec. 4.5 comma-separated unicode-range list.

    *)
  11. | Font_variant of font_variant_descriptor
    (*

    font-variant descriptor

    *)
  12. | Font_feature_settings of Properties.font_feature_settings
    (*

    OpenType feature settings

    *)
  13. | Font_variation_settings of Properties.font_variation_settings
    (*

    Variable font settings

    *)
  14. | Font_tech of string
    (*

    font-tech descriptor

    *)
  15. | Size_adjust of Font_face.size_adjust
    (*

    Size adjustment percentage

    *)
  16. | Ascent_override of Font_face.metric_override
    (*

    Ascent metric override

    *)
  17. | Descent_override of Font_face.metric_override
    (*

    Descent metric override

    *)
  18. | Line_gap_override of Font_face.metric_override
    (*

    Line gap metric override

    *)

Font-face descriptors per CSS Fonts spec

Stylesheet Structure

Sourcetype stylesheet = statement list

A CSS stylesheet is a list of statements

Rendering

Sourcetype mode =
  1. | Variables
  2. | Inline
    (*

    Rendering mode for CSS output

    *)
Sourceval equal_cascade_origin : cascade_origin -> cascade_origin -> bool
Sourceval equal : stylesheet -> stylesheet -> bool

Stylesheet value type.

Construction Functions

Sourceval rule : selector:Selector.t -> ?nested:statement list -> ?merge_key:string -> Declaration.declaration list -> rule

rule ~selector ?nested ?merge_key declarations creates a CSS rule with optional nested rules/at-rules and an optional merge key for combining rules with identical declarations.

Sourceval property : syntax:'a Variables.syntax -> ?initial_value:'a -> ?inherits:bool -> string -> statement

property ~syntax ?initial_value ?inherits name creates a @property rule with typed syntax and initial value.

Sourceval layer_decl : string list -> statement

layer_decl names creates a layer declaration statement.

Sourceval layer : ?name:string -> block -> statement

layer ?name content creates a @layer rule.

Sourceval media : condition:Media.t -> block -> statement

media ~condition content creates a @media rule.

Sourceval media_nested : condition:Media.t -> Declaration.declaration list -> statement

media_nested ~condition declarations creates a @media rule for CSS nesting, containing bare declarations (no selector). Used inside rules where the selector is inherited from the parent.

Sourceval container : ?name:string -> ?condition:Container.t -> block -> statement

container ?name ~condition content creates a @container rule.

Sourceval supports : condition:Supports.t -> block -> statement

supports ~condition content creates a @supports rule.

Sourceval starting_style : block -> statement

starting_style content creates a @starting-style rule.

Sourceval with_origin : cascade_origin -> block -> statement

with_origin cascade_origin content records the cascade origin for a stylesheet block. This is an API-level wrapper with no CSS syntax.

Sourceval origin_importance_rank : important:bool -> cascade_origin -> int

origin_importance_rank ~important origin returns the cascade precedence rank for the origin/importance criterion. Larger ranks have higher precedence.

Sourceval import_layer_name : import_rule -> string option

import_layer_name rule returns the layer name declared by an @import rule: None means the import does not declare a layer, Some "" means the import declares an anonymous layer, and Some name is the declared layer name.

Sourceval layer_block_name : statement -> string option

layer_block_name stmt returns the declared name for an @layer block rule. It returns Some "" for anonymous layer blocks, Some name for named layer blocks, and None for non-layer-block statements. The returned name is the at-rule's own declared name, not a parent-prefixed name.

Sourceval layer_statement_name_list : statement -> string list option

layer_statement_name_list stmt returns the declared name list for statement-form @layer rules.

Sourceval cascade_layer_precedence_rank : layer_order:string list -> important:bool -> string option -> int

cascade_layer_precedence_rank ~layer_order ~important layer returns the same-origin layer precedence rank. For normal declarations, later explicit layers and then the implicit unlayered layer rank higher. For important declarations, that order is reversed, with important unlayered declarations ranked below important explicit layers.

Sourceval compare_cascade_layer_candidate : layer_order:string list -> cascade_layer_candidate -> cascade_layer_candidate -> int

compare_cascade_layer_candidate compares same-origin/same-specificity candidates by importance, layer precedence, then source order.

Sourceval winning_cascade_layer_candidate : layer_order:string list -> cascade_layer_candidate list -> cascade_layer_candidate option

winning_cascade_layer_candidate returns the winning candidate using compare_cascade_layer_candidate.

Sourceval cascade_revert_layer_candidates : layer_order:string list -> important:bool -> current_layer:string option -> cascade_layer_candidate list -> cascade_layer_candidate list

cascade_revert_layer_candidates returns the same-importance candidates in lower-priority layers than current_layer, modeling the candidate set used after revert-layer removes declarations from the current layer.

Sourceval compare_cascade_origin_candidate : cascade_origin_candidate -> cascade_origin_candidate -> int

compare_cascade_origin_candidate compares same-specificity candidates by origin/importance precedence, then source order.

Sourceval winning_cascade_origin_candidate : cascade_origin_candidate list -> cascade_origin_candidate option

winning_cascade_origin_candidate returns the winning candidate using compare_cascade_origin_candidate.

Sourceval cascade_revert_origin_candidates : important:bool -> current_origin:cascade_origin -> cascade_origin_candidate list -> cascade_origin_candidate list

cascade_revert_origin_candidates returns same-importance candidates in the origins exposed by a revert declaration from current_origin.

Sourceval declared_values : ?property:string -> Declaration.declaration list -> declared_value list

declared_values ?property declarations returns the declared values contributed by declarations, preserving declaration source order. When property is supplied, only declarations for that property are returned.

Sourceval cascaded_value : cascade_origin_candidate list -> string option

cascaded_value candidates returns the winning cascaded value payload, or None when no candidate contributes a value.

Sourceval compare_cascade_candidate : layer_order:string list -> cascade_candidate -> cascade_candidate -> int

compare_cascade_candidate ~layer_order a b compares full same-property cascade candidates by origin/importance, layer, specificity, scoping proximity, and source order.

Sourceval winning_cascade_candidate : layer_order:string list -> cascade_candidate list -> cascade_candidate option

winning_cascade_candidate ~layer_order candidates returns the highest priority full cascade candidate.

Sourceval value : inherits:bool -> initial:string -> inherited:string option -> cascaded:string option -> value

value ~inherits ~initial ~inherited ~cascaded models the defaulting step that produces a specified value from a cascaded value for initial, inherit, and unset. inherited = None means the element has no parent value and falls back to initial.

Sourceval specified_value_after_revert : inherits:bool -> initial:string -> inherited:string option -> cascade_origin_candidate list -> value

specified_value_after_revert resolves a chain of revert winners by rolling back to the next-lower origin until a non-revert candidate (or none) survives, then defaults the result. The rollback context is taken from each winning candidate, so callers do not need to pass current_origin.

Sourceval specified_value_after_revert_layer : inherits:bool -> initial:string -> inherited:string option -> layer_order:string list -> cascade_layer_candidate list -> value

specified_value_after_revert_layer is the revert-layer analogue of specified_value_after_revert: chains rollback through the lower-priority layers until a non-revert-layer winner remains.

Sourceval value_processing_requires_document_context : value_processing_stage -> bool

value_processing_requires_document_context stage is true for stages this parser/serializer cannot compute from CSS text alone without caller-supplied document, inheritance, layout, rendering, or device context.

Sourceval starting_style_nested : Declaration.declaration list -> statement

starting_style_nested declarations creates a @starting-style rule for CSS nesting, containing bare declarations (no selector). Used inside rules where the selector is inherited from the parent.

Sourceval keyframes : string -> keyframe list -> statement

keyframes name frames creates a @keyframes animation rule.

Sourceval v : statement list -> stylesheet

v statements creates a stylesheet from a list of statements.

Sourceval empty_stylesheet : stylesheet

empty_stylesheet is an empty stylesheet.

Accessors

Sourceval selector : rule -> Selector.t

selector rule returns the selector of a rule.

Sourceval declarations : rule -> Declaration.declaration list

declarations rule returns the declarations of a rule.

Sourceval nested : rule -> statement list

nested rule returns the nested statements of a rule.

Sourceval statement_children : statement -> block

statement_children stmt is the block stmt wraps: a rule's nested statements, the body of a grouping at-rule (@media, @supports, @container, @layer, @scope, @starting-style, @when, @else, @-moz-document, and the Origin wrapper), and [] for a statement that holds no statements of its own. It is the one place that knows which at-rules nest, so a traversal written on top of it cannot miss one: the match is exhaustive, and a block at-rule added to the AST later does not compile until it is listed here.

Reading/Parsing

Sourceval read_rule : ?nested:bool -> Cursor.t -> rule

read_rule r reads a CSS rule from the reader. With ~nested:true the prelude is parsed as a CSS Nesting <relative-selector-list>, so it may start with a combinator (> .bar) taken relative to the parent &.

Sourceval read_block : Cursor.t -> block

read_block r reads a CSS block from the reader.

Sourceval read_stylesheet : Cursor.t -> stylesheet

read_stylesheet r reads a complete CSS stylesheet from the reader. Raises Cursor.Parse_error on the first validator failure; use parse_stylesheet_partial to get the recovered sheet with warnings instead.

Sourceval read_stylesheet_of_rules : ?source:string -> ?meta:Loc.meta_level -> Component.rule list -> stylesheet * Error.t list

read_stylesheet_of_rules ?source ?meta rules validates each Parser- recovered Component.rule to a typed statement independently. A validator failure on one rule is captured as a warning and the rule is dropped; the remaining rules are returned. Pass ?source (and keep ?meta at its default `Full) so dropped-rule warnings carry source- context snippets.

Sourceval parse_stylesheet_partial : ?meta:Loc.meta_level -> ?enforce_spec:bool -> string -> stylesheet * Error.t list

parse_stylesheet_partial ?meta source runs section 5.3 recovery via Parser.stylesheet and then typed-validates each recovered rule via read_stylesheet_of_rules. Warnings from both stages are combined in source order.

Pretty Printing

Sourceval pp_rule : rule Pp.t

pp_rule pretty-prints CSS rules.

Sourceval pp_stylesheet : stylesheet Pp.t

pp_stylesheet pretty-prints CSS stylesheets.

Variable Extraction

Sourceval vars_of_stylesheet : stylesheet -> Variables.any_var list

vars_of_stylesheet ss extracts all variables referenced in a stylesheet.

Rendering

Sourceval to_string : ?minify:bool -> ?indent:int -> ?lossless:bool -> ?enforce_spec:bool -> t -> string

to_string ?minify ?indent stylesheet serialises a stylesheet to CSS. Pure formatter - no optimisation, no theme resolution.

Sourceval pp : ?minify:bool -> ?indent:int -> ?lossless:bool -> ?enforce_spec:bool -> t -> string

pp is to_string.

Sourceval inline_style_of_declarations : ?minify:bool -> ?mode:mode -> Declaration.declaration list -> string

inline_style_of_declarations declarations converts declarations to inline style string.

Legacy Compatibility

Sourceval empty : t

empty is an empty stylesheet.

Sourceval rules : t -> rule list

rules t returns the top-level rules from the stylesheet.

Sourceval layers : t -> string list

layers t returns the layer names from the stylesheet.

Sourceval media_queries : t -> (Media.t * rule list) list

media_queries t returns the media queries from the stylesheet.

Sourceval container_queries : t -> (string option * Container.t option * rule list) list

container_queries t returns the container queries from the stylesheet.

Parsing and Pretty-printing

Sourceval read : Cursor.t -> t

read r parses a stylesheet from the reader.

Sourceval pp_import_rule : import_rule Pp.t

pp_import_rule pretty-prints an import rule.

Sourceval read_import_rule : Cursor.t -> import_rule

read_import_rule r parses an import rule.

Sourceval rule_hash : rule -> int

rule_hash r is a cheap hash that discriminates rules by their cached declaration hashes. Equal rules hash equally; unequal rules may collide, so callers still confirm with structural equality.