CSS::DOM - Document Object Model for Cascading Style Sheets

CSS-DOM documentation Contained in the CSS-DOM distribution.

Index

Code Index:

NAME

Top

CSS::DOM - Document Object Model for Cascading Style Sheets

VERSION

Top

Version 0.14

This is an alpha version. The API is still subject to change. Many features have not been implemented yet (but patches would be welcome :-).

The interface for feeding CSS code to CSS::DOM changed incompatibly in version 0.03.

SYNOPSIS

Top

  use CSS::DOM;

  my $sheet = CSS::DOM::parse( $css_source );

  use CSS::DOM::Style;
  my $style = CSS::DOM::Style::parse(
      'background: red; font-size: large'
  );

  my $other_sheet = new CSS::DOM; # empty
  $other_sheet->insertRule(
     'a{ text-decoration: none }',
      $other_sheet->cssRules->length,
  );
  # etc.

  # access DOM properties
  $other_sheet->cssRules->[0]->selectorText('p'); # change it
  $style->fontSize;          # returns 'large'
  $style->fontSize('small'); # change it

DESCRIPTION

Top

This set of modules provides the CSS-specific interfaces described in the W3C DOM recommendation.

The CSS::DOM class itself implements the StyleSheet and CSSStyleSheet DOM interfaces.

This set of modules has two modes:

1

It can validate property values, ignoring those that are invalid (just like a real web browser), and support shorthand properties. This means you can set font to '13px/15px My Font' and have the font-size, line-height, and font-family properties (among others) set automatically. Also, color: green; color: kakariki will assign 'green' to the color property, 'kakariki' not being a recognised color value.

2

It can blithely accept all property assignments as being valid. In the case of color: green; color kakariki, 'kakariki' will be assigned, since it overrides the previous assignment.

These two modes are controlled by the property_parser option to the constructors.

CONSTRUCTORS

Top

CSS::DOM::parse( $string )

This method parses the $string and returns a style sheet object. If you just have a CSS style declaration, e.g., from an HTML style attribute, see parse in CSS::DOM::Style.

new CSS::DOM

Creates a new, empty style sheet object. Use this only if you plan to build the style sheet piece by piece, instead of parsing a block of CSS code.

You can pass named arguments to both of those. parse accepts all of them; new understands only the first two, property_parser and url_fetcher.

property_parser

Set this to a PropertyParser object to specify which properties are supported and how they are parsed.

If this option is not specified or is set to undef, all property values are treated as valid.

See CSS::DOM::PropertyParser for more details.

url_fetcher

This has to be a code ref that returns the contents of the style sheet at the URL passed as the sole argument. E.g.,

  # Disclaimer: This does not work with relative URLs.
  use LWP::Simple;
  use CSS::DOM;
  $css = '@import "file.css"; /* other stuff ... ';
  $ss = CSS::DOM::parse $css, url_fetcher => sub { get shift };
  $ss->cssRules->[0]->styleSheet; # returns a style sheet object
                                  # corresponding to file.css

The subroutine can choose to return undef or an empty list, in which case the @import rule's styleSheet method will return null (empty list or undef), as it would if no url_fetcher were specified.

It can also return named items after the CSS code, like this:

  return $css_code, decode => 1, encoding_hint => 'iso-8859-1';

These correspond to the next two items:

decode

If this is specified and set to a true value, then CSS::DOM will treat the CSS code as a string of bytes, and try to decode it based on @charset rules and byte order marks.

By default it assumes that it is already in Unicode (i.e., decoded).

encoding_hint

Use this to provide a hint as to what the encoding might be.

If this is specified, and decode is not, then decode => 1 is assumed.

STYLE SHEET ENCODING

Top

See the options above. This section explains how and when you should use those options.

According to the CSS spec, any encoding specified in the 'charset' field on an HTTP Content-Type header, or the equivalent in other protocols, takes precedence. In such a case, since CSS::DOM doesn't deal with HTTP, you have to decode it yourself.

Otherwise, you should use decode => 1 to instruct CSS::DOM to use byte order marks or @charset rules.

If neither of those is present, then encoding data in the referencing document (e.g., <link charset="..."> or an HTML document's own encoding), if available/applicable, should be used. In this case, you should use the encoding_hint option, so that CSS::DOM has something to fall back to.

If you use decode => 1 with no encoding hint, and no BOM or @charset is to be found, UTF-8 is assumed.

SYNTAX ERRORS

Top

The two constructors above, and also CSS::DOM::Style::parse|CSS::DOM::Style/parse, set $@ to the empty string upon success. If they encounter a syntax error, they set $@ to the error and return an object that represents whatever was parsed up to that point.

Other methods that parse CSS code might die on encountering syntax errors, and should usually be wrapped in an eval.

The parser follows the 'future-compatible' syntax described in the CSS 2.1 specification, and also the spec's rules for handling parsing errors. Anything not handled by those two is a syntax error.

In other words, a syntax error is one of the following:

OBJECT METHODS

Top

Attributes

type

Returns the string 'text/css'.

disabled

Allows one to specify whether the style sheet is used. (This attribute is not actually used yet by CSS::DOM.) You can set it by passing an argument.

ownerNode

Returns the node that 'owns' this style sheet.

parentStyleSheet

If the style sheet belongs to an '@import' rule, this returns the style sheet containing that rule. Otherwise it returns an empty list.

href

Returns the style sheet's URI, if applicable.

title

Returns the value of the owner node's title attribute.

media

Returns the MediaList associated with the style sheet (or a plain list in list context). This defaults to an empty list. You can pass a comma-delimited string to the MediaList's mediaText method to initialise it.

(The medium information is not actually used [yet] by CSS::DOM, but you can put it there.)

ownerRule

If this style sheet was created by an @import rule, this returns the rule; otherwise it returns an empty list (or undef in scalar context).

cssRules

In scalar context, this returns a CSS::DOM::RuleList object (simply a blessed array reference) of CSS::DOM::Rule objects. In list context it returns a list.

Methods

insertRule ( $css_code, $index )

Parses the rule contained in the $css_code, inserting it in the style sheet's list of rules at the given $index.

deleteRule ( $index )

Deletes the rule at the given $index.

hasFeature ( $feature, $version )

You can call this either as an object or class method.

This is actually supposed to be a method of the 'DOMImplementation' object. (See, for instance, HTML::DOM::Interface's method of the same name, which delegates to this one.) This returns a boolean indicating whether a particular DOM module is implemented. Right now it returns true only for the 'CSS2' and 'StyleSheets' features (version '2.0').

Non-DOM Methods

set_ownerNode

This allows you to set the value of ownerNode. Passing an argument to ownerNode does nothing, because it is supposed to be read-only. But you have to be able to set it somehow, so that's why this method is here.

The style sheet will hold a weak reference to the object passed to this method.

set_href

Like set_ownerNode, but for href.

property_parser
url_fetcher

These two both return what was passed to the constructor. The second one, url_fetcher also allows an assignment, but this is not propagated to sub-rules and is intended mainly for internal use.

FUNCTIONS

Top

CSS::DOM::parse

See CONSTRUCTORS, above.

CSS::DOM::compute_style( %options )

Warning: This is still highly experimental and crawling with bugs.

This computes the style for a given HTML element. It does not yet calculate actual measurements (e.g., converting percentages to pixels), but simply applies the cascading rules and selectors. Pseudo-classes are not yet supported (but pseudo-elements are).

The precedence rules for normal vs important declarations in the CSS 2 specification are used. (CSS 2.1 is unclear.) The precedence is as follows, from lowest to highest:

 user agent normal declarations
 user normal declarations
 author normal     "
 user agent !important declarations
 author !important "
 user      "       "

The %options are as follows. They are all optional except for element.

ua_sheet

The user agent style sheet

user_sheet

The user style sheet

author_sheets

Array ref of style sheets that the HTML document defines or links to.

element

The element

pseudo

The pseudo-element (e.g., 'first-line'). This can be specified with no colons (the way Opera requires it) or with one or two colons (the way Firefox requires it).

medium
height
width
ppi

(To be implemented)

The

CLASSES AND DOM INTERFACES

Top

Here are the inheritance hierarchy of CSS::DOM's various classes and the DOM interfaces those classes implement. For brevity's sake, a simple '::' at the beginning of a class name in the left column is used for 'CSS::DOM::'. Items in brackets do not exist yet. (See also CSS::DOM::Interface for a machine-readable list of standard methods.)

  Class Inheritance Hierarchy  Interfaces
  ---------------------------  ----------

  CSS::DOM                     StyleSheet, CSSStyleSheet
  ::Array
      ::MediaList              MediaList
      ::StyleSheetList         StyleSheetList
      ::RuleList               CSSRuleList
  ::Rule                       CSSRule, CSSUnknownRule
      ::Rule::Style            CSSStyleRule
      ::Rule::Media            CSSMediaRule
      ::Rule::FontFace         CSSFontFaceRule
      ::Rule::Page             CSSPageRule
      ::Rule::Import           CSSImportRule
      ::Rule::Charset          CSSCharsetRule
  ::Style                      CSSStyleDeclaration, CSS2Properties
  ::Value                      CSSValue
  ::Value::Primitive           CSSPrimitiveValue, RGBColor, Rect
  ::Value::List                CSSValueList
 [::Counter                    Counter]

CSS::DOM does not implement the following interfaces (see HTML::DOM for these):

  LinkStyle
  DocumentStyle
  ViewCSS
  DocumentCSS
  DOMImplementationCSS
  ElementCSSInlineStyle

IMPLEMENTATION NOTES

Top

PREREQUISITES

Top

perl 5.8.2 or higher

Exporter 5.57 or later

Encode 2.10 or higher

Clone 0.09 or higher

BUGS

Top

The parser has not been updated to conform to the April 2009 revision of the CSS 2.1 candidate recommendation. Specifically, unexpected closing brackets are not ignored, but cause syntax errors; and @media rules containing unrecognised statements are themselves currently treated as unrecognised (the unrecognised inner statements should be ignored, rendering the outer @media rule itself valid).

If you create a custom property parser that defines 'list-style-type' to include multiple tokens, then counters will become CSS_CUSTOM CSSValue objects instead of CSS_COUNTER CSSPrimitiveValue objects.

If you change a property parser's property definitions such that a primitive value becomes a list, or vice versa, and then try to modify the cssText property of an existing value object belonging to that property, things will go awry.

Whitespace and comments are sometimes preserved in serialised CSS and sometimes not. Expect inconsistency.

To report bugs, please e-mail the author.

ACKNOWLEDGEMENTS

Top

Thanks to Ville Skyttä and Nicholas Bamber for their contributions.

AUTHOR & COPYRIGHT

Top

Copyright (C) 2007-10 Father Chrysostomos <sprout [at] cpan [dot] org>

This program is free software; you may redistribute it and/or modify it under the same terms as perl. The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

Top

All the classes listed above under CLASSES AND DOM INTERFACES.

CSS::SAC, CSS.pm and HTML::DOM

The DOM Level 2 Style specification at http://www.w3.org/TR/DOM-Level-2-Style

The CSS 2.1 specification at http://www.w3.org/TR/CSS21/

CSS-DOM documentation Contained in the CSS-DOM distribution. 
package CSS::DOM;

use 5.008002;

$VERSION = '0.14';

use   # to keep CPANTS happy :-)
   strict;
use   # same here
   warnings;

use CSS::DOM::Exception
	'SYNTAX_ERR' ,'HIERARCHY_REQUEST_ERR', 'INDEX_SIZE_ERR';
use CSS::DOM::Constants 'STYLE_RULE';
use Scalar::Util 'weaken';

require CSS::DOM::RuleList;

use constant 1.03 our $_constants = {
	ruls => 0,
	ownr => 1, # owner rule
	node => 2, # owner node
	dsbl => 3,
	hrfe => 4,
	medi => 5,
	fetc => 6, # url fetcher
	prsh => 7, # parent sheet
	prpp => 8, # property parser
};
{ no strict; delete @CSS::DOM::{_constants => keys %{our $_constants}} }


# NON-DOM METHODS

# classy method
sub new {
	my $self = bless[],shift;
	my %args = @_;
	if(defined(my $arg = delete $args{url_fetcher})) {
		$self->[fetc] = $arg;
	}
	$self->[prpp] = delete $args{property_parser};
	$self;
}

# objectionable methods
sub url_fetcher {
	my $old = (my$ self = shift)->[fetc];
	$ self -> [ fetc ] = shift if @ _ ;
	$old
}
sub property_parser { shift->[prpp] }


# FUNCTIONS

sub parse {
	require CSS::DOM::Parser;
	goto &CSS::DOM::Parser::parse;
}

sub compute_style {
	my %args = @_;
	# ~~~ for now we just ignore medium/height/width/ppi. We need to
	#     support those, too.

	require CSS::DOM::Style;
	my $style = new CSS::DOM::Style;

	my $elem = delete $args{element};
	my $pseudo = delete $args{pseudo};
	$pseudo && $pseudo =~ s/^::?//;
	
	# The specificity returned by the style rule is a three-character
	# string representing the number of id, attr, and elem selector
	# components (e.g., li.red.level gives "\0\2\1"). We prefix that
	# with two more chars, to make:
	#   XXXXX
	#   ||||`-- element
	#   |||`-- attribute
	#   ||`-- id
	#   |`-- style attribute
	#   `-- style sheet

	# ‘Style attribute’ is \1 or \0, indicating whether the CSS proper-
	# ties originate from a style attribute. ‘Style sheet’ is
	# as follows:
	#  "\0") user agent normal declarations
	#  "\1") user normal declarations
	#  "\2") author normal     "
	#  "\3") user agent !important declarations
	#  "\4") author !important "
	#  "\5") user      "       "

	# The individual properties are sorted according to this scheme.


	# ~~~ This isn’t the most efficient algorithm. Perhaps we can cache
	#     some of this.

	my %specificity; # per property

	my @normal_spec;
	my @important_spec;
	my @sheets;
	if(defined $args{ua_sheet}) {
		push @normal_spec, chr 0;
		push @important_spec, chr 3;
		push @sheets, delete $args{ua_sheet};
	}
	if(defined $args{user_sheet}) {
		push @normal_spec, chr 1;
		push @important_spec, chr 5;
		push @sheets, delete $args{user_sheet};
	}
	if(defined $args{author_sheets}) {
		my $s = delete $args{author_sheets};
		push @normal_spec, (chr 2) x @$s;
		push @important_spec, (chr 4) x @$s;
		push @sheets, @$s;
	}
	while(@sheets) {
		my $n = shift @normal_spec;
		my $i = shift @important_spec;
		my $s = shift @sheets;
		my @rules = $s->cssRules;
		while(@rules) {
			my $r = shift @rules;
			my $type = $r->type;
			if($type == STYLE_RULE) {
				next unless
				  my $specificity = $r->_selector_matches(
				    $elem, $pseudo
				  );
				my $sty = $r->style;
				for(0..$sty->length-1) {
					my $p = $sty->item($_);
					my $spec = (
					 $sty->getPropertyPriority($p)
					  =~
					 /^important\z/i
					 ? $i : $n
					) . "\0$specificity";
					no warnings 'uninitialized';
					$spec ge $specificity{$p} and
					  $style->setProperty(
					   $p, $sty->getPropertyValue($p)
					  ),
					  $specificity{$p} = $spec;
				}
			}
		}
	}
	
	my $sty = $elem->style;
	for(0..$sty->length-1) {
					my $p = $sty->item($_);
					my $spec = (
					 $sty->getPropertyPriority($p)
					  =~
					 /^important\z/i
					 ? "\4" : "\3"
					) . "\1\0\0\0";
					$spec ge $specificity{$p} and
					  $style->setProperty(
					   $p, $sty->getPropertyValue($p)
					  ),
					  $specificity{$p} = $spec;
	}

	return $style;
}


# DOM STUFF:

# StyleSheet interface:

sub type { 'text/css' }
sub disabled {
	my $old = (my $self = shift) ->[dsbl];
	@_ and $self->[dsbl] = shift;
	$old
};
sub ownerNode { defined $_[0][node]?$_[0][node]:() }
sub set_ownerNode { weaken($_[0]->[node] = $_[1]) }
sub parentStyleSheet { shift->[prsh]||() }
sub _set_parentStyleSheet { weaken($_[0]->[prsh] = $_[1]) }
sub href { shift->[hrfe] }
sub set_href { $_[0]->[hrfe] = $_[1] }
sub title { no warnings 'uninitialized';
           ''.(shift->ownerNode || return)->attr('title') }

# If you find a bug in here, Media.pm’s method probably also needs fixing.
sub media {
	wantarray ? @{$_[0]->[medi]||return} :
		($_[0]->[medi] ||= (
			require CSS::DOM::MediaList,
			CSS::DOM::MediaList->new
		))
}


# CSSStyleSheet interface:

sub ownerRule {
	shift->[ownr] || ()
}
sub _set_ownerRule {
	weaken($_[0]->[ownr] = $_[1]);
}

# If you find a bug in the following three methods, Media.pm’s methods
# probably also need fixing.
sub cssRules { 
	wantarray
		? @{shift->[ruls]||return}
		: (shift->[ruls]||=new CSS::DOM::RuleList);
}

sub insertRule { # This is supposed to raise an HIERARCHY_REQUEST_ERR if
                 # the rule cannot be inserted at the specified  index;
                 # e.g.,  if an  @import  rule is inserted after a stan-
                 # dard rule. But we don’t do that, in order to maintain
                 # future compatibility.
	my ($self, $rule_string, $index) = @_;
	
	require CSS::DOM::Parser;
	my ($at,$rule);
	{
		local *@;
		$rule = CSS::DOM::Parser::parse_statement(
		 $rule_string,$self
		);
		$at = $@
	}
	$at and die new CSS::DOM::Exception SYNTAX_ERR, $at;

#	$rule->_set_parentStyleSheet($self);

	my $list = $self->cssRules; # cssRules takes care of ||=
	splice @$list, $index, 0, $rule;

	$index < 0        ? $#$list + $index :
	$index <= $#$list ? $index           :
	                    $#$list
}

sub deleteRule {
	my ($self,$index) = @_;
	my $list = $self->[ruls];
	$index > $#$list and die CSS::DOM::Exception->new(
		INDEX_SIZE_ERR,
		"The index passed to deleteRule ($index) is too large"
	);
	splice @$list, $index, 1;
	return # nothing;
}



my %features = (
	stylesheets => { '2.0' => 1 },
#	css => { '2.0' => 1 },
	css2 => { '2.0' => 1 },
);

sub hasFeature {
	my($feature,$v) = (lc $_[1], $_[2]);
	exists $features{$feature} and
		!defined $v || exists $features{$feature}{$v};
}

                              !()__END__()!