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

CSS-Tiny documentation Contained in the CSS-Tiny distribution.

Index

Code Index:

NAME

Top

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

SYNOPSIS

Top

    # 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

Top

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

Top

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

Top

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

Top

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

Top

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

Top

Adam Kennedy <adamk@cpan.org>

SEE ALSO

Top

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

COPYRIGHT

Top

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.

CSS-Tiny documentation Contained in the CSS-Tiny distribution. 
package CSS::Tiny;

# See POD at end for docs

use strict;
BEGIN {
	require 5.004;
	$CSS::Tiny::VERSION = '1.19';
	$CSS::Tiny::errstr  = '';
}

# Create an empty object
sub new { bless {}, shift }

# Create an object from a file
sub read {
	my $class = shift;

	# Check the file
	my $file = shift or return $class->_error( 'You did not specify a file name' );
	return $class->_error( "The file '$file' does not exist" )          unless -e $file;
	return $class->_error( "'$file' is a directory, not a file" )       unless -f _;
	return $class->_error( "Insufficient permissions to read '$file'" ) unless -r _;

	# Read the file
	local $/ = undef;
	open( CSS, $file ) or return $class->_error( "Failed to open file '$file': $!" );
	my $contents = <CSS>;
	close( CSS );

	$class->read_string( $contents )
}

# Create an object from a string
sub read_string {
	my $self = ref $_[0] ? shift : bless {}, shift;

	# Flatten whitespace and remove /* comment */ style comments
	my $string = shift;
	$string =~ tr/\n\t/  /;
	$string =~ s!/\*.*?\*\/!!g;

	# Split into styles
	foreach ( grep { /\S/ } split /(?<=\})/, $string ) {
		unless ( /^\s*([^{]+?)\s*\{(.*)\}\s*$/ ) {
			return $self->_error( "Invalid or unexpected style data '$_'" );
		}

		# Split in such a way as to support grouped styles
		my $style      = $1;
		my $properties = $2;
		$style =~ s/\s{2,}/ /g;
		my @styles = grep { s/\s+/ /g; 1; } grep { /\S/ } split /\s*,\s*/, $style;
		foreach ( @styles ) { $self->{$_} ||= {} }

		# Split into properties
		foreach ( grep { /\S/ } split /\;/, $properties ) {
			unless ( /^\s*([\w._-]+)\s*:\s*(.*?)\s*$/ ) {
				return $self->_error( "Invalid or unexpected property '$_' in style '$style'" );
			}
			foreach ( @styles ) { $self->{$_}->{lc $1} = $2 }
		}
	}

	$self
}

# Copy an object, using Clone.pm if available
BEGIN { local $@; eval "use Clone 'clone';"; eval <<'END_PERL' if $@; }
sub clone {
	my $self = shift;
	my $copy = ref($self)->new;
	foreach my $key ( keys %$self ) {
		my $section = $self->{$key};
		$copy->{$key} = {};
		foreach ( keys %$section ) {
			$copy->{$key}->{$_} = $section->{$_};
		}
	}
	$copy;
}
END_PERL

# Save an object to a file
sub write {
	my $self = shift;
	my $file = shift or return $self->_error( 'No file name provided' );

	# Write the file
	open( CSS, '>'. $file ) or return $self->_error( "Failed to open file '$file' for writing: $!" );
	print CSS $self->write_string;
	close( CSS );
}

# Save an object to a string
sub write_string {
	my $self = shift;

	# Iterate over the styles
	# Note: We use 'reverse' in the sort to avoid a special case related
	# to A:hover even though the file ends up backwards and looks funny.
	# See http://www.w3.org/TR/CSS2/selector.html#dynamic-pseudo-classes
	my $contents = '';
	foreach my $style ( reverse sort keys %$self ) {
		$contents .= "$style {\n";
		foreach ( sort keys %{ $self->{$style} } ) {
			$contents .= "\t" . lc($_) . ": $self->{$style}->{$_};\n";
		}
		$contents .= "}\n";
	}

	return $contents;
}

# Generate a HTML fragment for the CSS
sub html {
	my $css = $_[0]->write_string or return '';
	return "<style type=\"text/css\">\n<!--\n${css}-->\n</style>";
}

# Generate an xhtml fragment for the CSS
sub xhtml {
	my $css = $_[0]->write_string or return '';
	return "<style type=\"text/css\">\n/* <![CDATA[ */\n${css}/* ]]> */\n</style>";
}

# Error handling
sub errstr { $CSS::Tiny::errstr }
sub _error { $CSS::Tiny::errstr = $_[1]; undef }

1;

__END__