plucky (3) CSS::Tiny.3pm.gz

NAME

       CSS::Tiny - Read/Write .css files with as little code as possible

SYNOPSIS

           # In your .css file
           H1 { color: blue }
           H2 { color: red; font-family: Arial }
           .this, .that { color: yellow }

           # In your program
           use CSS::Tiny;

           # Create a CSS stylesheet
           my $CSS = CSS::Tiny->new();

           # Open a CSS stylesheet
           $CSS = CSS::Tiny->read( 'style.css' );

           # Reading properties
           my $header_color = $CSS->{H1}->{color};
           my $header2_hashref = $CSS->{H2};
           my $this_color = $CSS->{'.this'}->{color};
           my $that_color = $CSS->{'.that'}->{color};

           # Changing styles and properties
           $CSS->{'.newstyle'} = { color => '#FFFFFF' }; # Add a style
           $CSS->{H1}->{color} = 'black';                # Change a property
           delete $CSS->{H2};                            # Delete a style

           # Save a CSS stylesheet
           $CSS->write( 'style.css' );

           # Get the CSS as a <style>...</style> tag
           $CSS->html;

DESCRIPTION

       "CSS::Tiny" is a perl class to read and write .css stylesheets with as little code as possible, reducing
       load time and memory overhead. CSS.pm requires about 2.6 meg or ram to load, which is a large amount of
       overhead if you only want to do trivial things.  Memory usage is normally scoffed at in Perl, but in my
       opinion should be at least kept in mind.

       This module is primarily for reading and writing simple files, and anything we write shouldn't need to
       have documentation/comments. If you need something with more power, move up to CSS.pm. With the
       increasing complexity of CSS, this is becoming more common, but many situations can still live with
       simple CSS files.

   CSS Feature Support
       "CSS::Tiny" supports grouped styles of the form "this, that { color: blue }" correctly when reading,
       ungrouping them into the hash structure. However, it will not restore the grouping should you write the
       file back out. In this case, an entry in the original file of the form

           H1, H2 { color: blue }

       would become

           H1 { color: blue }
           H2 { color: blue }

       "CSS::Tiny" handles nested styles of the form "P EM { color: red }" in reads and writes correctly, making
       the property available in the form

           $CSS->{'P EM'}->{color}

       "CSS::Tiny" ignores comments of the form "/* comment */" on read correctly, however these comments will
       not be written back out to the file.

CSS FILE SYNTAX

       Files are written in a relatively human-orientated form, as follows:

           H1 {
               color: blue;
           }
           .this {
               color: red;
               font-size: 10px;
           }
           P EM {
               color: yellow;
           }

       When reading and writing, all property descriptors, for example "color" and "font-size" in the example
       above, are converted to lower case. As an example, take the following CSS.

           P {
               Font-Family: Verdana;
           }

       To get the value 'Verdana' from the object $CSS, you should reference the key "$CSS->{P}->{font-family}".

METHODS

   new
       The constructor "new" creates and returns an empty "CSS::Tiny" object.

   read $filename
       The "read" constructor reads a CSS stylesheet, and returns a new "CSS::Tiny" object containing the
       properties in the file.

       Returns the object on success, or "undef" on error.

   read_string $string
       The "read_string" constructor reads a CSS stylesheet from a string.

       Returns the object on success, or "undef" on error.

   clone
       The "clone" method creates an identical copy of an existing "CSS::Tiny" object.

   write_string
       Generates the stylesheet for the object and returns it as a string.

   write
       The "write $filename" generates the stylesheet for the properties, and writes it to disk. Returns true on
       success. Returns "undef" on error.

   html
       The "html" method generates the CSS, but wrapped in a "style" HTML tag, so that it can be dropped
       directly onto a HTML page.

   xhtml
       The "html" method generates the CSS, but wrapped in a "style" XHTML tag, so that it can be dropped
       directly onto an XHTML page.

   errstr
       When an error occurs, you can retrieve the error message either from the $CSS::Tiny::errstr variable, or
       using the "errstr" method.

CAVEATS

   CSS Rule Order
       While the order of rules in CSS is important, this is one of the features that is sacrificed to keep
       things small and dependency-free. If you need to preserve order yourself, we recommend that you upgrade
       to the more powerful CSS module.

       If this is not possible in your case, alternatively it can be done with the help of another module such
       as Tie::IxHash:

           my $css = CSS::Tiny->new;
           tie %$css, 'Tie::IxHash';
           $css->read('style.css');

       Note: You will also need to remember to add the additional dependency to your code or module in this
       case.

SUPPORT

       Bugs should be reported via the CPAN bug tracker at

       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CSS-Tiny>

       For other issues, or commercial enhancement or support, contact the author.

AUTHOR

       Adam Kennedy <adamk@cpan.org>

SEE ALSO

       CSS, <http://www.w3.org/TR/REC-CSS1>, Config::Tiny, <http://ali.as/>

COPYRIGHT

       Copyright 2002 - 2010 Adam Kennedy.

       This program is free software; you can redistribute it and/or modify it under the same terms as Perl
       itself.

       The full text of the license can be found in the LICENSE file included with this module.