Module: Cataract

Defined in:

lib/cataract.rb,
lib/cataract.rb,
lib/cataract/pure.rb,
lib/cataract/rule.rb,
lib/cataract/error.rb,
lib/cataract/at_rule.rb,
lib/cataract/version.rb,
lib/cataract/constants.rb,
lib/cataract/stylesheet.rb,
lib/cataract/declaration.rb,
lib/cataract/media_query.rb,
lib/cataract/pure/parser.rb,
lib/cataract/declarations.rb,
lib/cataract/pure/flatten.rb,
lib/cataract/import_resolver.rb,
lib/cataract/pure/serializer.rb,
lib/cataract/import_statement.rb,
lib/cataract/pure/specificity.rb,
lib/cataract/stylesheet_scope.rb,
lib/cataract/pure/declarations.rb,
lib/cataract/pure/byte_constants.rb,
ext/cataract/cataract.c

Overview

Pure Ruby CSS parser - Byte constants for fast parsing Using getbyte() instead of String#[] to avoid allocating millions of string objects

Defined Under Namespace

Modules: Backends, ImportResolver Classes: AtRule, ColorConversionError, Declaration, Declarations, DepthError, Error, ImportError, ImportStatement, MediaQuery, ParseError, Rule, SizeError, Stylesheet, StylesheetScope

Constant Summary

IMPLEMENTATION =

backend_const_holder::IMPLEMENTATION

COMPILE_FLAGS =

backend_const_holder::COMPILE_FLAGS

NATIVE_EXTENSION_LOADED =

true

PURE_RUBY_LOADED =

true

VERSION =

'0.4.0'

DEFAULT_URI_RESOLVER =

Default URI resolver proc for converting relative URLs to absolute Uses Ruby's URI stdlib to merge base and relative URIs

lambda { |base, relative|
  require 'uri'
  URI.parse(base).merge(relative).to_s
}.freeze

Class Method Summary

• .flatten(stylesheet_or_css) ⇒ Stylesheet

  Flatten CSS rules according to CSS cascade rules.

• .parse_css(css, **options) ⇒ Stylesheet

  Parse a CSS string into a Stylesheet object.

Class Method Details

.flatten(stylesheet_or_css) ⇒ Stylesheet

Note:

This is a module-level convenience method. The same functionality is available as an instance method: stylesheet.flatten

Flatten CSS rules according to CSS cascade rules.

Takes a Stylesheet or CSS string and flattens all rules according to CSS cascade precedence rules. Returns a new Stylesheet with flattened rules containing the final computed declarations.

Flatten rules (in order of precedence):

1. !important declarations win over non-important
2. Higher specificity wins
3. Later declarations with same specificity and importance win
4. Shorthand properties are created from longhand when possible (e.g., margin-* -> margin)

Examples:

Flatten a stylesheet

sheet = Cataract.parse_css(".test { color: red; } #test { color: blue; }")
flattened = Cataract.flatten(sheet)
flattened.rules.first.declarations #=> [#<Declaration property="color" value="blue" important=false>]

Flatten with !important

sheet = Cataract.parse_css(".test { color: red !important; } #test { color: blue; }")
flattened = Cataract.flatten(sheet)
flattened.rules.first.declarations #=> [#<Declaration property="color" value="red" important=true>]

Shorthand creation

css = ".test { margin-top: 10px; margin-right: 10px; margin-bottom: 10px; margin-left: 10px; }"
flattened = Cataract.flatten(Cataract.parse_css(css))
# flattened contains single "margin: 10px" declaration instead of four longhand properties

Parameters:

• stylesheet_or_css (Stylesheet, String) —

  The stylesheet to flatten, or a CSS string to parse and flatten

Returns:

• (Stylesheet) —

  A new Stylesheet with flattened rules

See Also:

• Cataract::Stylesheet#flatten

# File 'lib/cataract.rb', line 127

def flatten(stylesheet_or_css)
  stylesheet_or_css = Stylesheet.parse(stylesheet_or_css) if stylesheet_or_css.is_a?(String)
  stylesheet_or_css.flatten
end

.parse_css(css, **options) ⇒ Stylesheet

Parse a CSS string into a Stylesheet object.

This is the main entry point for parsing CSS. It returns a Stylesheet object that can be queried, modified, and serialized.

Examples:

Parse simple CSS

sheet = Cataract.parse_css("body { color: red; }")
sheet.size #=> 1

Parse with imports

sheet = Cataract.parse_css("@import 'style.css';", imports: true)

Parse with import options

sheet = Cataract.parse_css(css, imports: {
  allowed_schemes: ['https', 'file'],
  base_path: '/path/to/css'
})

Parameters:

• css (String) —

  The CSS string to parse

• imports (Boolean, Hash) —

  Whether to resolve @import statements. Pass true to enable with defaults, or a hash with options:

  • allowed_schemes: Array of allowed URI schemes (default: ['https'])
  • extensions: Array of allowed file extensions (default: ['css'])
  • max_depth: Maximum import nesting depth (default: 5)
  • base_path: Base directory for resolving relative imports

Returns:

• (Stylesheet) —

  A new Stylesheet containing the parsed CSS rules

Raises:

• (IOError) —

  If import resolution fails and io_exceptions option is enabled

See Also:

• Cataract::Stylesheet.parse
• Cataract::Stylesheet.parse

# File 'lib/cataract.rb', line 89

def parse_css(css, **options)
  Stylesheet.parse(css, **options)
end