view release on metacpan or  search on metacpan

lib/CSS/DOM.pm  view on Meta::CPAN

=item 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 C<undef> or an empty list, in which 
case the @import 
rule's C<styleSheet> method will return null (empty list or C<undef>), as
it would if no C<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:

=item 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).

=item encoding_hint

Use this to provide a hint as to what the encoding might be.

If this is specified, and C<decode> is not, then C<< decode => 1 >> is
assumed.

=back

=head1 STYLE SHEET ENCODING

See the options above. This section explains how and when you I<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 C<< 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
C<< encoding_hint >> option, so that CSS::DOM has something to fall back
to.

If you use C<< decode => 1 >> with no encoding hint, and no BOM or @charset
is to be found, UTF-8 is assumed.

=head1 SYNTAX ERRORS

The two constructors above, and also
L<C<CSS::DOM::Style::parse>|CSS::DOM::Style/parse>, set C<$@> to the empty 
string upon success. If 
they
encounter a syntax error, they set C<$@> 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 C<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:

=over 4

=item *

An unexpected closing bracket, as
in these examples

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

=item *

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

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

=item *

An extra C<@> keyword or semicolon where it doesn't belong; e.g.,

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

=back

=head1 OBJECT METHODS

=head2 Attributes

=over 4

=item type

Returns the string 'text/css'.

=item disabled