1CSS::DOM(3) User Contributed Perl Documentation CSS::DOM(3)
2
6 CSS::DOM - Document Object Model for Cascading Style Sheets
7
9 Version 0.17
10 This is an alpha version. The API is still subject to change. Many
12 features have not been implemented yet (but patches would be welcome
13 :-).
14 The interface for feeding CSS code to CSS::DOM changed incompatibly in
16 version 0.03.
17
19 use CSS::DOM;
20 my $sheet = CSS::DOM::parse( $css_source );
22 use CSS::DOM::Style;
24 my $style = CSS::DOM::Style::parse(
25 'background: red; font-size: large'
26 );
27 my $other_sheet = new CSS::DOM; # empty
29 $other_sheet->insertRule(
30 'a{ text-decoration: none }',
31 $other_sheet->cssRules->length,
32 );
33 # etc.
34 # access DOM properties
36 $other_sheet->cssRules->[0]->selectorText('p'); # change it
37 $style->fontSize; # returns 'large'
38 $style->fontSize('small'); # change it
39
41 This set of modules provides the CSS-specific interfaces described in
42 the W3C DOM recommendation.
43 The CSS::DOM class itself implements the StyleSheet and CSSStyleSheet
45 DOM interfaces.
46 This set of modules has two modes:
48 1. It can validate property values, ignoring those that are invalid
50 (just like a real web browser), and support shorthand properties.
51 This means you can set font to '13px/15px My Font' and have the
52 font-size, line-height, and font-family properties (among others)
53 set automatically. Also, "color: green; color: kakariki" will
54 assign 'green' to the color property, 'kakariki' not being a
55 recognised color value.
56 2. It can blithely accept all property assignments as being valid. In
58 the case of "color: green; color: kakariki", 'kakariki' will be
59 assigned, since it overrides the previous assignment.
60 These two modes are controlled by the "property_parser" option to the
62 constructors.
63
65 CSS::DOM::parse( $string )
66 This method parses the $string and returns a style sheet object. If
67 you just have a CSS style declaration, e.g., from an HTML "style"
68 attribute, see "parse" in CSS::DOM::Style.
69 new CSS::DOM
71 Creates a new, empty style sheet object. Use this only if you plan
72 to build the style sheet piece by piece, instead of parsing a block
73 of CSS code.
74 You can pass named arguments to both of those. "parse" accepts all of
76 them; "new" understands only the first two, "property_parser" and
77 "url_fetcher".
78 property_parser
80 Set this to a PropertyParser object to specify which properties are
81 supported and how they are parsed.
82 If this option is not specified or is set to "undef", all property
84 values are treated as valid.
85 See CSS::DOM::PropertyParser for more details.
87 url_fetcher
89 This has to be a code ref that returns the contents of the style
90 sheet at the URL passed as the sole argument. E.g.,
91 # Disclaimer: This does not work with relative URLs.
93 use LWP::Simple;
94 use CSS::DOM;
95 $css = '@import "file.css"; /* other stuff ... ';
96 $ss = CSS::DOM::parse $css, url_fetcher => sub { get shift };
97 $ss->cssRules->[0]->styleSheet; # returns a style sheet object
98 # corresponding to file.css
99 The subroutine can choose to return "undef" or an empty list, in
101 which case the @import rule's "styleSheet" method will return null
102 (empty list or "undef"), as it would if no "url_fetcher" were
103 specified.
104 It can also return named items after the CSS code, like this:
106 return $css_code, decode => 1, encoding_hint => 'iso-8859-1';
108 These correspond to the next two items:
110 decode
112 If this is specified and set to a true value, then CSS::DOM will
113 treat the CSS code as a string of bytes, and try to decode it based
114 on @charset rules and byte order marks.
115 By default it assumes that it is already in Unicode (i.e.,
117 decoded).
118 encoding_hint
120 Use this to provide a hint as to what the encoding might be.
121 If this is specified, and "decode" is not, then "decode => 1" is
123 assumed.
124
126 See the options above. This section explains how and when you should
127 use those options.
128 According to the CSS spec, any encoding specified in the 'charset'
130 field on an HTTP Content-Type header, or the equivalent in other
131 protocols, takes precedence. In such a case, since CSS::DOM doesn't
132 deal with HTTP, you have to decode it yourself.
133 Otherwise, you should use "decode => 1" to instruct CSS::DOM to use
135 byte order marks or @charset rules.
136 If neither of those is present, then encoding data in the referencing
138 document (e.g., <link charset="..."> or an HTML document's own
139 encoding), if available/applicable, should be used. In this case, you
140 should use the "encoding_hint" option, so that CSS::DOM has something
141 to fall back to.
142 If you use "decode => 1" with no encoding hint, and no BOM or @charset
144 is to be found, UTF-8 is assumed.
145
147 The two constructors above, and also "CSS::DOM::Style::parse", set $@
148 to the empty string upon success. If they encounter a syntax error,
149 they set $@ to the error and return an object that represents whatever
150 was parsed up to that point.
151 Other methods that parse CSS code might die on encountering syntax
153 errors, and should usually be wrapped in an "eval".
154 The parser follows the 'future-compatible' syntax described in the CSS
156 2.1 specification, and also the spec's rules for handling parsing
157 errors. Anything not handled by those two is a syntax error.
158 In other words, a syntax error is one of the following:
160 • An unexpected closing bracket, as in these examples
162 a { text-decoration: none )
164 *[name=~'foo'} {}
165 #thing { clip: rect( ]
166 • An HTML comment delimiter within a rule; e.g.,
168 a { text-decoration : none <!-- /* Oops! */ }
170 <!-- /*ok*/ @media --> /* bad! */ print { }
171 • An extra "@" keyword or semicolon where it doesn't belong; e.g.,
173 @media @print { .... }
175 @import "file.css" @print;
176 td, @page { ... }
177 #tabbar td; #tab1 { }
178
180 Attributes
181 type
182 Returns the string 'text/css'.
183 disabled
185 Allows one to specify whether the style sheet is used. (This
186 attribute is not actually used yet by CSS::DOM.) You can set it by
187 passing an argument.
188 ownerNode
190 Returns the node that 'owns' this style sheet.
191 parentStyleSheet
193 If the style sheet belongs to an '@import' rule, this returns the
194 style sheet containing that rule. Otherwise it returns an empty
195 list.
196 href
198 Returns the style sheet's URI, if applicable.
199 title
201 Returns the value of the owner node's title attribute.
202 media
204 Returns the MediaList associated with the style sheet (or a plain
205 list in list context). This defaults to an empty list. You can pass
206 a comma-delimited string to the MediaList's "mediaText" method to
207 initialise it.
208 (The medium information is not actually used [yet] by CSS::DOM, but
210 you can put it there.)
211 ownerRule
213 If this style sheet was created by an @import rule, this returns
214 the rule; otherwise it returns an empty list (or undef in scalar
215 context).
216 cssRules
218 In scalar context, this returns a CSS::DOM::RuleList object (simply
219 a blessed array reference) of CSS::DOM::Rule objects. In list
220 context it returns a list.
221 Methods
223 insertRule ( $css_code, $index )
224 Parses the rule contained in the $css_code, inserting it in the
225 style sheet's list of rules at the given $index.
226 deleteRule ( $index )
228 Deletes the rule at the given $index.
229 hasFeature ( $feature, $version )
231 You can call this either as an object or class method.
232 This is actually supposed to be a method of the 'DOMImplementation'
234 object. (See, for instance, HTML::DOM::Interface's method of the
235 same name, which delegates to this one.) This returns a boolean
236 indicating whether a particular DOM module is implemented. Right
237 now it returns true only for the 'CSS2' and 'StyleSheets' features
238 (version '2.0').
239 Non-DOM Methods
241 set_ownerNode
242 This allows you to set the value of "ownerNode". Passing an
243 argument to "ownerNode" does nothing, because it is supposed to be
244 read-only. But you have to be able to set it somehow, so that's why
245 this method is here.
246 The style sheet will hold a weak reference to the object passed to
248 this method.
249 set_href
251 Like "set_ownerNode", but for "href".
252 property_parser
254 url_fetcher
255 These two both return what was passed to the constructor. The
256 second one, "url_fetcher" also allows an assignment, but this is
257 not propagated to sub-rules and is intended mainly for internal
258 use.
259
261 CSS::DOM::parse
262 See "CONSTRUCTORS", above.
263 CSS::DOM::compute_style( %options )
265 Warning: This is still highly experimental and crawling with bugs.
266 This computes the style for a given HTML element. It does not yet
268 calculate actual measurements (e.g., converting percentages to
269 pixels), but simply applies the cascading rules and selectors.
270 Pseudo-classes are not yet supported (but pseudo-elements are).
271 The precedence rules for normal vs important declarations in the
273 CSS 2 specification are used. (CSS 2.1 is unclear.) The precedence
274 is as follows, from lowest to highest:
275 user agent normal declarations
277 user normal declarations
278 author normal "
279 user agent !important declarations
280 author !important "
281 user " "
282 The %options are as follows. They are all optional except for
284 "element".
285 ua_sheet
287 The user agent style sheet
288 user_sheet
290 The user style sheet
291 author_sheets
293 Array ref of style sheets that the HTML document defines or
294 links to.
295 element
297 The element, as an HTML::DOM::Element object.
298 pseudo
300 The pseudo-element (e.g., 'first-line'). This can be specified
301 with no colons (the way Opera requires it) or with one or two
302 colons (the way Firefox requires it).
303 medium
305 height
306 width
307 ppi (To be implemented)
308 The
310
312 Here are the inheritance hierarchy of CSS::DOM's various classes and
313 the DOM interfaces those classes implement. For brevity's sake, a
314 simple '::' at the beginning of a class name in the left column is used
315 for 'CSS::DOM::'. Items in brackets do not exist yet. (See also
316 CSS::DOM::Interface for a machine-readable list of standard methods.)
317 Class Inheritance Hierarchy Interfaces
319 --------------------------- ----------
320 CSS::DOM StyleSheet, CSSStyleSheet
322 ::Array
323 ::MediaList MediaList
324 ::StyleSheetList StyleSheetList
325 ::RuleList CSSRuleList
326 ::Rule CSSRule, CSSUnknownRule
327 ::Rule::Style CSSStyleRule
328 ::Rule::Media CSSMediaRule
329 ::Rule::FontFace CSSFontFaceRule
330 ::Rule::Page CSSPageRule
331 ::Rule::Import CSSImportRule
332 ::Rule::Charset CSSCharsetRule
333 ::Style CSSStyleDeclaration, CSS2Properties
334 ::Value CSSValue
335 ::Value::Primitive CSSPrimitiveValue, RGBColor, Rect
336 ::Value::List CSSValueList
337 [::Counter Counter]
338 CSS::DOM does not implement the following interfaces (see HTML::DOM for
340 these):
341 LinkStyle
343 DocumentStyle
344 ViewCSS
345 DocumentCSS
346 DOMImplementationCSS
347 ElementCSSInlineStyle
348
350 • Attributes of objects are accessed via methods of the same name.
351 When the method is invoked, the current value is returned. If an
352 argument is supplied, the attribute is set (unless it is read-only)
353 and its old value returned.
354 • Where the DOM spec. says to use null, undef or an empty list is
356 used.
357 • Instead of UTF-16 strings, CSS::DOM uses Perl's Unicode strings.
359 • Each method that the specification says returns an array-like
361 object (e.g., a RuleList) will return such an object in scalar
362 context, or a simple list in list context. You can use the object
363 as an array ref in addition to calling its "item" and "length"
364 methods.
365
367 perl 5.8.2 or higher
368 Exporter 5.57 or later
370 Encode 2.10 or higher
372 Clone 0.09 or higher
374
376 The parser has not been updated to conform to the April 2009 revision
377 of the CSS 2.1 candidate recommendation. Specifically, unexpected
378 closing brackets are not ignored, but cause syntax errors; and @media
379 rules containing unrecognised statements are themselves currently
380 treated as unrecognised (the unrecognised inner statements should be
381 ignored, rendering the outer @media rule itself valid).
382 If you create a custom property parser that defines 'list-style-type'
384 to include multiple tokens, then counters will become "CSS_CUSTOM"
385 CSSValue objects instead of "CSS_COUNTER" CSSPrimitiveValue objects.
386 If you change a property parser's property definitions such that a
388 primitive value becomes a list, or vice versa, and then try to modify
389 the "cssText" property of an existing value object belonging to that
390 property, things will go awry.
391 Whitespace and comments are sometimes preserved in serialised CSS and
393 sometimes not. Expect inconsistency.
394 To report bugs, please e-mail the author.
396
398 Thanks to Ville Skyttä, Nicholas Bamber and Gregor Herrmann for their
399 contributions.
400
402 Copyright (C) 2007-18 Father Chrysostomos <sprout [at] cpan [dot] org>
403 This program is free software; you may redistribute it and/or modify it
405 under the same terms as perl. The full text of the license can be found
406 in the LICENSE file included with this module.
407
409 All the classes listed above under "CLASSES AND DOM INTERFACES".
410 CSS::SAC, CSS.pm and HTML::DOM
412 The DOM Level 2 Style specification at
414 <http://www.w3.org/TR/DOM-Level-2-Style>
415 The CSS 2.1 specification at <http://www.w3.org/TR/CSS21/>
417perl v5.36.0 2022-07-22 CSS::DOM(3)