| CSS::DOM(3pm) | User Contributed Perl Documentation | CSS::DOM(3pm) |
CSS::DOM - Document Object Model for Cascading Style Sheets
Version 0.17
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.
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
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:
These two modes are controlled by the "property_parser" option to the constructors.
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".
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.
# 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:
By default it assumes that it is already in Unicode (i.e., decoded).
If this is specified, and "decode" is not, then "decode => 1" is assumed.
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.
The two constructors above, and also "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:
a { text-decoration: none )
*[name=~'foo'} {}
#thing { clip: rect( ]
a { text-decoration : none <!-- /* Oops! */ }
<!-- /*ok*/ @media --> /* bad! */ print { }
@media @print { .... }
@import "file.css" @print;
td, @page { ... }
#tabbar td; #tab1 { }
(The medium information is not actually used [yet] by CSS::DOM, but you can put it there.)
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').
The style sheet will hold a weak reference to the object passed to this method.
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".
The
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
perl 5.8.2 or higher
Exporter 5.57 or later
Encode 2.10 or higher
Clone 0.09 or higher
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.
Thanks to Ville Skyttä, Nicholas Bamber and Gregor Herrmann for their contributions.
Copyright (C) 2007-18 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.
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/>
| 2023-08-02 | perl v5.36.0 |