.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "CSS::DOM 3pm"
.TH CSS::DOM 3pm "2018-02-12" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CSS::DOM \- Document Object Model for Cascading Style Sheets
.SH "VERSION"
.IX Header "VERSION"
Version 0.17
.PP
This is an alpha version. The \s-1API\s0 is still subject to change. Many features
have not been implemented yet (but patches would be welcome :\-).
.PP
The interface for feeding \s-1CSS\s0 code to \s-1CSS::DOM\s0 changed incompatibly in
version 0.03.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use CSS::DOM;
\&
\&  my $sheet = CSS::DOM::parse( $css_source );
\&
\&  use CSS::DOM::Style;
\&  my $style = CSS::DOM::Style::parse(
\&      \*(Aqbackground: red; font\-size: large\*(Aq
\&  );
\&
\&  my $other_sheet = new CSS::DOM; # empty
\&  $other_sheet\->insertRule(
\&     \*(Aqa{ text\-decoration: none }\*(Aq,
\&      $other_sheet\->cssRules\->length,
\&  );
\&  # etc.
\&  
\&  # access DOM properties
\&  $other_sheet\->cssRules\->[0]\->selectorText(\*(Aqp\*(Aq); # change it
\&  $style\->fontSize;          # returns \*(Aqlarge\*(Aq
\&  $style\->fontSize(\*(Aqsmall\*(Aq); # change it
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This set of modules provides the CSS-specific interfaces described in the
W3C \s-1DOM\s0
recommendation.
.PP
The \s-1CSS::DOM\s0 class itself implements the StyleSheet and CSSStyleSheet \s-1DOM\s0
interfaces.
.PP
This set of modules has two modes:
.IP "1." 4
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, \f(CW\*(C`color: green; color: kakariki\*(C'\fR will assign 'green' 
to the color
property, 'kakariki' not being a recognised color value.
.IP "2." 4
It can
blithely accept all property assignments as being valid. In the case of
\&\f(CW\*(C`color: green; color: kakariki\*(C'\fR, 'kakariki' will be assigned, since it overrides the previous
assignment.
.PP
These two modes are controlled by the \f(CW\*(C`property_parser\*(C'\fR option to the
constructors.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.ie n .IP "CSS::DOM::parse( $string )" 4
.el .IP "CSS::DOM::parse( \f(CW$string\fR )" 4
.IX Item "CSS::DOM::parse( $string )"
This method parses the \f(CW$string\fR and returns a style sheet object. If you
just have a \s-1CSS\s0 style declaration, e.g., from an \s-1HTML\s0 \f(CW\*(C`style\*(C'\fR attribute,
see \*(L"parse\*(R" in CSS::DOM::Style.
.IP "new \s-1CSS::DOM\s0" 4
.IX Item "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 \s-1CSS\s0 code.
.PP
You can pass named arguments to both of those. \f(CW\*(C`parse\*(C'\fR accepts all of
them; \f(CW\*(C`new\*(C'\fR understands only the first two, \f(CW\*(C`property_parser\*(C'\fR and
\&\f(CW\*(C`url_fetcher\*(C'\fR.
.IP "property_parser" 4
.IX Item "property_parser"
Set this to a PropertyParser object to specify
which properties are supported and how they are parsed.
.Sp
If this option is not specified or is set to \f(CW\*(C`undef\*(C'\fR, all property
values are treated as valid.
.Sp
See CSS::DOM::PropertyParser for more details.
.IP "url_fetcher" 4
.IX Item "url_fetcher"
This has to be a code ref that returns the contents
of the style sheet at the \s-1URL\s0 passed as the sole argument. E.g.,
.Sp
.Vb 7
\&  # Disclaimer: This does not work with relative URLs.
\&  use LWP::Simple;
\&  use CSS::DOM;
\&  $css = \*(Aq@import "file.css"; /* other stuff ... \*(Aq;
\&  $ss = CSS::DOM::parse $css, url_fetcher => sub { get shift };
\&  $ss\->cssRules\->[0]\->styleSheet; # returns a style sheet object
\&                                  # corresponding to file.css
.Ve
.Sp
The subroutine can choose to return \f(CW\*(C`undef\*(C'\fR or an empty list, in which 
case the \f(CW@import\fR 
rule's \f(CW\*(C`styleSheet\*(C'\fR method will return null (empty list or \f(CW\*(C`undef\*(C'\fR), as
it would if no \f(CW\*(C`url_fetcher\*(C'\fR were specified.
.Sp
It can also return named items after the \s-1CSS\s0 code, like this:
.Sp
.Vb 1
\&  return $css_code, decode => 1, encoding_hint => \*(Aqiso\-8859\-1\*(Aq;
.Ve
.Sp
These correspond to the next two items:
.IP "decode" 4
.IX Item "decode"
If this is specified and set to a true value, then \s-1CSS::DOM\s0 will treat the
\&\s-1CSS\s0 code as a string of bytes, and try to decode it based on \f(CW@charset\fR rules
and byte order marks.
.Sp
By default it assumes that it is already in Unicode (i.e., decoded).
.IP "encoding_hint" 4
.IX Item "encoding_hint"
Use this to provide a hint as to what the encoding might be.
.Sp
If this is specified, and \f(CW\*(C`decode\*(C'\fR is not, then \f(CW\*(C`decode => 1\*(C'\fR is
assumed.
.SH "STYLE SHEET ENCODING"
.IX Header "STYLE SHEET ENCODING"
See the options above. This section explains how and when you \fIshould\fR use
those options.
.PP
According to the \s-1CSS\s0 spec, any encoding specified in the 'charset' field on
an \s-1HTTP\s0 Content-Type header, or the equivalent in other protocols, takes
precedence. In such a case, since \s-1CSS::DOM\s0 doesn't deal with \s-1HTTP,\s0 you have
to decode it yourself.
.PP
Otherwise, you should use \f(CW\*(C`decode => 1\*(C'\fR to instruct \s-1CSS::DOM\s0 to use
byte order marks or \f(CW@charset\fR rules.
.PP
If neither of those is present, then encoding data in the referencing
document (e.g., <link charset=\*(L"...\*(R"> or an \s-1HTML\s0 document's own encoding),
if available/applicable, should be used. In this case, you should use the
\&\f(CW\*(C`encoding_hint\*(C'\fR option, so that \s-1CSS::DOM\s0 has something to fall back
to.
.PP
If you use \f(CW\*(C`decode => 1\*(C'\fR with no encoding hint, and no \s-1BOM\s0 or \f(CW@charset\fR
is to be found, \s-1UTF\-8\s0 is assumed.
.SH "SYNTAX ERRORS"
.IX Header "SYNTAX ERRORS"
The two constructors above, and also
\&\f(CW\*(C`CSS::DOM::Style::parse\*(C'\fR, set \f(CW$@\fR to the empty 
string upon success. If 
they
encounter a syntax error, they set \f(CW$@\fR to the error and return an object
that represents whatever was parsed up to that point.
.PP
Other methods that parse \s-1CSS\s0 code might die on encountering
syntax errors, and should usually be wrapped in an \f(CW\*(C`eval\*(C'\fR.
.PP
The parser follows the 'future\-compatible' syntax described in the \s-1CSS 2.1\s0
specification, and also the spec's rules for handling parsing errors.
Anything not handled by those two is a syntax error.
.PP
In other words, a syntax error is one of the following:
.IP "\(bu" 4
An unexpected closing bracket, as
in these examples
.Sp
.Vb 3
\&  a { text\-decoration: none )
\&  *[name=~\*(Aqfoo\*(Aq} {}
\&  #thing { clip: rect( ]
.Ve
.IP "\(bu" 4
An \s-1HTML\s0 comment delimiter within a rule; e.g.,
.Sp
.Vb 2
\&  a { text\-decoration : none <!\-\- /* Oops! */ }
\&  <!\-\- /*ok*/ @media \-\-> /* bad! */ print { }
.Ve
.IP "\(bu" 4
An extra \f(CW\*(C`@\*(C'\fR keyword or semicolon where it doesn't belong; e.g.,
.Sp
.Vb 4
\&  @media @print { .... }
\&  @import "file.css" @print;
\&  td, @page { ... }
\&  #tabbar td; #tab1 { }
.Ve
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
.SS "Attributes"
.IX Subsection "Attributes"
.IP "type" 4
.IX Item "type"
Returns the string 'text/css'.
.IP "disabled" 4
.IX Item "disabled"
Allows one to specify whether the style sheet is used. (This attribute is
not actually used yet by \s-1CSS::DOM.\s0) You can set it by passing an argument.
.IP "ownerNode" 4
.IX Item "ownerNode"
Returns the node that 'owns' this style sheet.
.IP "parentStyleSheet" 4
.IX Item "parentStyleSheet"
If the style sheet belongs to an '@import' rule, this returns the style
sheet containing that rule. Otherwise it returns an empty list.
.IP "href" 4
.IX Item "href"
Returns the style sheet's \s-1URI,\s0 if applicable.
.IP "title" 4
.IX Item "title"
Returns the value of the owner node's title attribute.
.IP "media" 4
.IX Item "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
\&\f(CW\*(C`mediaText\*(C'\fR method to initialise it.
.Sp
(The medium information is not actually used [yet] by \s-1CSS::DOM,\s0 but you
can put it there.)
.IP "ownerRule" 4
.IX Item "ownerRule"
If this style sheet was created by an \f(CW@import\fR rule, this returns the rule;
otherwise it returns an empty list (or undef in scalar context).
.IP "cssRules" 4
.IX Item "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.
.SS "Methods"
.IX Subsection "Methods"
.ie n .IP "insertRule ( $css_code, $index )" 4
.el .IP "insertRule ( \f(CW$css_code\fR, \f(CW$index\fR )" 4
.IX Item "insertRule ( $css_code, $index )"
Parses the rule contained in the \f(CW$css_code\fR, inserting it in the style
sheet's list of rules at the given \f(CW$index\fR.
.ie n .IP "deleteRule ( $index )" 4
.el .IP "deleteRule ( \f(CW$index\fR )" 4
.IX Item "deleteRule ( $index )"
Deletes the rule at the given \f(CW$index\fR.
.ie n .IP "hasFeature ( $feature, $version )" 4
.el .IP "hasFeature ( \f(CW$feature\fR, \f(CW$version\fR )" 4
.IX Item "hasFeature ( $feature, $version )"
You can call this either as an object or class method.
.Sp
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 \s-1DOM\s0 module is implemented. Right now it returns true only for
the '\s-1CSS2\s0' and 'StyleSheets' features (version '2.0').
.SS "Non-DOM Methods"
.IX Subsection "Non-DOM Methods"
.IP "set_ownerNode" 4
.IX Item "set_ownerNode"
This allows you to set the value of \f(CW\*(C`ownerNode\*(C'\fR. Passing an argument to
\&\f(CW\*(C`ownerNode\*(C'\fR 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.
.Sp
The style sheet will hold a weak reference to the object passed to this
method.
.IP "set_href" 4
.IX Item "set_href"
Like \f(CW\*(C`set_ownerNode\*(C'\fR, but for \f(CW\*(C`href\*(C'\fR.
.IP "property_parser" 4
.IX Item "property_parser"
.PD 0
.IP "url_fetcher" 4
.IX Item "url_fetcher"
.PD
These two both return what was passed to the constructor. The second one,
\&\f(CW\*(C`url_fetcher\*(C'\fR also allows an assignment, but this is not propagated to
sub-rules and is intended mainly for internal use.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "CSS::DOM::parse" 4
.IX Item "CSS::DOM::parse"
See \*(L"\s-1CONSTRUCTORS\*(R"\s0, above.
.ie n .IP "CSS::DOM::compute_style( %options )" 4
.el .IP "CSS::DOM::compute_style( \f(CW%options\fR )" 4
.IX Item "CSS::DOM::compute_style( %options )"
\&\fBWarning:\fR This is still highly experimental and crawling with bugs.
.Sp
This computes the style for a given \s-1HTML\s0 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).
.Sp
The precedence rules for normal vs important declarations in the \s-1CSS 2\s0 
specification are used. (\s-1CSS 2.1\s0 is unclear.) The precedence is as follows,
from lowest to highest:
.Sp
.Vb 6
\& user agent normal declarations
\& user normal declarations
\& author normal     "
\& user agent !important declarations
\& author !important "
\& user      "       "
.Ve
.Sp
The \f(CW%options\fR are as follows. They are all optional except for 
\&\f(CW\*(C`element\*(C'\fR.
.RS 4
.IP "ua_sheet" 4
.IX Item "ua_sheet"
The user agent style sheet
.IP "user_sheet" 4
.IX Item "user_sheet"
The user style sheet
.IP "author_sheets" 4
.IX Item "author_sheets"
Array ref of style sheets that the \s-1HTML\s0 document defines or links to.
.IP "element" 4
.IX Item "element"
The element, as an HTML::DOM::Element object.
.IP "pseudo" 4
.IX Item "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).
.IP "medium" 4
.IX Item "medium"
.PD 0
.IP "height" 4
.IX Item "height"
.IP "width" 4
.IX Item "width"
.IP "ppi" 4
.IX Item "ppi"
.PD
(To be implemented)
.RE
.RS 4
.Sp
The
.RE
.SH "CLASSES AND DOM INTERFACES"
.IX Header "CLASSES AND DOM INTERFACES"
Here are the inheritance hierarchy of \s-1CSS::DOM\s0's various classes and the
\&\s-1DOM\s0 interfaces those classes implement. For brevity's sake, a simple '::'
at the beginning of a class name in the left column is used for
\&'\s-1CSS::DOM::\s0'. Items in brackets do not exist yet. (See also 
CSS::DOM::Interface for a
machine-readable list of standard methods.)
.PP
.Vb 2
\&  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]
.Ve
.PP
\&\s-1CSS::DOM\s0 does not implement the following interfaces (see \s-1HTML::DOM\s0 for
these):
.PP
.Vb 6
\&  LinkStyle
\&  DocumentStyle
\&  ViewCSS
\&  DocumentCSS
\&  DOMImplementationCSS
\&  ElementCSSInlineStyle
.Ve
.SH "IMPLEMENTATION NOTES"
.IX Header "IMPLEMENTATION NOTES"
.IP "\(bu" 4
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.
.IP "\(bu" 4
Where the \s-1DOM\s0 spec. says to use null, undef or an empty list is used.
.IP "\(bu" 4
Instead of \s-1UTF\-16\s0 strings, \s-1CSS::DOM\s0 uses Perl's Unicode strings.
.IP "\(bu" 4
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 \f(CW\*(C`item\*(C'\fR and 
\&\f(CW\*(C`length\*(C'\fR methods.
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
perl 5.8.2 or higher
.PP
Exporter 5.57 or later
.PP
Encode 2.10 or higher
.PP
Clone 0.09 or higher
.SH "BUGS"
.IX Header "BUGS"
The parser has not been updated to conform to the April 2009 revision of 
the \s-1CSS 2.1\s0 candidate recommendation. Specifically, unexpected closing 
brackets are not ignored, but cause syntax errors; and \f(CW@media\fR rules 
containing unrecognised statements are themselves currently treated as 
unrecognised (the unrecognised inner statements should be ignored, 
rendering the outer \f(CW@media\fR rule itself valid).
.PP
If you create a custom property parser that defines
\&'list\-style\-type' to include multiple tokens, then counters will become
\&\f(CW\*(C`CSS_CUSTOM\*(C'\fR CSSValue objects instead of \f(CW\*(C`CSS_COUNTER\*(C'\fR CSSPrimitiveValue
objects.
.PP
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
\&\f(CW\*(C`cssText\*(C'\fR property of an existing value object belonging to that property,
things will go awry.
.PP
Whitespace and comments are sometimes preserved in serialised \s-1CSS\s0 and 
sometimes not.
Expect inconsistency.
.PP
To report bugs, please e\-mail the author.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Thanks to Ville Skyttä, Nicholas Bamber and Gregor Herrmann for their
contributions.
.SH "AUTHOR & COPYRIGHT"
.IX Header "AUTHOR & COPYRIGHT"
Copyright (C) 2007\-18 Father Chrysostomos <sprout [at] cpan
[dot] org>
.PP
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 \s-1LICENSE\s0 file included with this module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
All the classes listed above under \*(L"\s-1CLASSES AND DOM INTERFACES\*(R"\s0.
.PP
\&\s-1CSS::SAC\s0, \s-1CSS\s0.pm and \s-1HTML::DOM\s0
.PP
The \s-1DOM\s0 Level 2 Style specification at
<http://www.w3.org/TR/DOM\-Level\-2\-Style>
.PP
The \s-1CSS 2.1\s0 specification at <http://www.w3.org/TR/CSS21/>