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

NAME

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

VERSION

       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.

SYNOPSIS

         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

       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

       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

       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

       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:

       •   An unexpected closing bracket, as in these examples

             a { text-decoration: none )
             *[name=~'foo'} {}
             #thing { clip: rect( ]

       •   An HTML comment delimiter within a rule; e.g.,

             a { text-decoration : none <!-- /* Oops! */ }
             <!-- /*ok*/ @media --> /* bad! */ print { }

       •   An extra "@" keyword or semicolon where it doesn't belong; e.g.,

             @media @print { .... }
             @import "file.css" @print;
             td, @page { ... }
             #tabbar td; #tab1 { }

OBJECT METHODS

   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

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, as an HTML::DOM::Element object.

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

       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

       •   Attributes  of  objects  are  accessed  via methods of the same name. When the method is invoked, the
           current value is returned. If an argument is supplied, the attribute is set (unless it is  read-only)
           and its old value returned.

       •   Where the DOM spec. says to use null, undef or an empty list is used.

       •   Instead of UTF-16 strings, CSS::DOM uses Perl's Unicode strings.

       •   Each  method  that the specification says returns an array-like object (e.g., a RuleList) will return
           such an object in scalar context, or a simple list in list context. You can  use  the  object  as  an
           array ref in addition to calling its "item" and "length" methods.

PREREQUISITES

       perl 5.8.2 or higher

       Exporter 5.57 or later

       Encode 2.10 or higher

       Clone 0.09 or higher

BUGS

       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

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

AUTHOR & COPYRIGHT

       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.