Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CSS::DOM(3)	      User Contributed Perl Documentation	   CSS::DOM(3)

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:

       o   An unexpected closing bracket, as in	these examples

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

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

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

       o   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
       o   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.

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

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

       o   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 SkyttAx,	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.

SEE ALSO
       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/>

perl v5.32.0			  2018-01-29			   CSS::DOM(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CONSTRUCTORS | STYLE SHEET ENCODING | SYNTAX ERRORS | OBJECT METHODS | FUNCTIONS | CLASSES AND DOM INTERFACES | IMPLEMENTATION NOTES | PREREQUISITES | BUGS | ACKNOWLEDGEMENTS | AUTHOR & COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CSS::DOM&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help