NativeElixirPdfUtilities.HtmlToPdf.CssParser (native_elixir_pdf_utilities v1.1.0)

View Source

Strict CSS parser for the native HTML-to-PDF renderer.

The parser accepts the document-oriented selector subset used by the style cascade: element, class, id, attribute operators and case flags, descendant, child, supported positional, initial :enabled/:disabled/:checked/:popover-open and negation pseudo-classes, ::before, ::after, and comma groups. Bare @page { ... } and simple @font-face rules are accepted outside the style cascade, and @media print rules are included in the active print cascade. Page selectors, named-page preludes, and misspelled @page at-rules are rejected. Declarations are kept as normalized property/value pairs so the style layer can validate values against the renderer's supported property set.

Summary

Functions

Extracts active local font declarations from @font-face rules.

Extracts renderer page defaults from bare @page { ... } rules.

Parses a CSS stylesheet into strict renderer rules.

Parses a CSS declaration block into normalized property/value pairs.

Parses a CSS declaration block and returns source-location details on failure.

Parses a CSS stylesheet and returns source-location details when parsing fails.

Removes CSS comments while preserving token boundaries, quoted strings and escapes.

Removes CSS comments using an explicit separator, preserving quoted strings and escapes.

Types

attribute_operator()

@type attribute_operator() ::
  :equals | :includes | :dash_match | :prefix | :suffix | :substring

declaration()

@type declaration() :: {String.t(), String.t()} | {String.t(), String.t(), :important}

font_face()

@type font_face() :: %{
  family: String.t(),
  sources: [String.t()],
  weight: 100..900,
  style: :normal | :italic
}

page_option()

rule()

@type rule() :: %{
  selectors: [selector()],
  declarations: [declaration()],
  order: non_neg_integer()
}

selector()

@type selector() :: %{
  :parts => [selector_part()],
  :specificity => {non_neg_integer(), non_neg_integer(), non_neg_integer()},
  optional(:language_dependent) => true
}

selector_part()

@type selector_part() :: %{
  :tag => String.t() | nil,
  :id => String.t() | nil,
  :classes => [String.t()],
  :attributes => [
    {:present, String.t()}
    | {attribute_operator(), String.t(), String.t()}
    | {attribute_operator(), String.t(), String.t(), :sensitive | :insensitive}
  ],
  :pseudo_classes => [
    :first_child
    | :last_child
    | :first_of_type
    | :last_of_type
    | :only_child
    | :only_of_type
    | :root
    | :enabled
    | :disabled
    | :checked
    | :required
    | :optional
    | :read_only
    | :read_write
    | :popover_open
    | {:lang, [[String.t()]]}
    | {:nth_child | :nth_last_child | :nth_of_type | :nth_last_of_type,
       integer() | :odd | :even | {integer(), integer()}}
  ],
  :negations => [selector_part()],
  :pseudo_element => nil | :before | :after | :picker_icon,
  :combinator => nil | :descendant | :child,
  optional(:language_dependent) => true
}

stylesheet()

@type stylesheet() :: [rule()]

Functions

font_faces(css)

@spec font_faces(String.t()) ::
  {:ok, [font_face()]}
  | {:error, :invalid_css}
  | {:error, {:resource_limit_exceeded, map()}}

Extracts active local font declarations from @font-face rules.

Sources must use url(...) with a TrueType or OpenType source. Remote URLs, data URIs, WOFF/WOFF2 sources, and unsupported descriptors are rejected. Relative paths are returned unchanged for the style layer to resolve against the stylesheet location or renderer :base_url. Supported sources retain their declared order so loading can fall back when an earlier file is unavailable or invalid.

page_options(css)

@spec page_options(String.t()) ::
  {:ok, [page_option()]}
  | {:error, :invalid_css}
  | {:error, {:resource_limit_exceeded, map()}}

Extracts renderer page defaults from bare @page { ... } rules.

Valid page-context properties are accepted even when the renderer does not apply them yet. Rendering consumes accepted named and explicit two-length size values, portrait and landscape orientations, one-to-four-value margin shorthands, and the four margin longhands. Malformed declarations, unknown properties, invalid paged-media descriptor values, page selectors, named-page preludes, and misspelled @page at-rules return {:error, :invalid_css}.

parse(css)

@spec parse(String.t()) ::
  {:ok, stylesheet()}
  | {:error, :invalid_css | :not_implemented | :resource_limit_exceeded}

Parses a CSS stylesheet into strict renderer rules.

parse_declarations(css)

@spec parse_declarations(String.t()) ::
  {:ok, [declaration()]}
  | {:error, :invalid_css | :not_implemented | :resource_limit_exceeded}

Parses a CSS declaration block into normalized property/value pairs.

This is used for both stylesheet blocks and inline style attributes.

parse_declarations_detailed(css)

@spec parse_declarations_detailed(String.t()) ::
  {:ok, [declaration()]}
  | {:error,
     {:invalid_css | :not_implemented | :resource_limit_exceeded, map()}}

Parses a CSS declaration block and returns source-location details on failure.

parse_detailed(css)

@spec parse_detailed(String.t()) ::
  {:ok, stylesheet()}
  | {:error,
     {:invalid_css | :not_implemented | :resource_limit_exceeded, map()}}

Parses a CSS stylesheet and returns source-location details when parsing fails.

strip_comments(css)

@spec strip_comments(String.t()) :: String.t()

Removes CSS comments while preserving token boundaries, quoted strings and escapes.

strip_comments(css, separator)

@spec strip_comments(String.t(), String.t()) :: String.t()

Removes CSS comments using an explicit separator, preserving quoted strings and escapes.