CSS::Sass - Compile .scss files using libsass
# Object Oriented API use CSS::Sass; my $sass = CSS::Sass->new; my $css = $sass->compile(".something { color: red; }"); # Object Oriented API w/ options my $sass = CSS::Sass->new(include_paths => ['some/include/path'], image_path => 'base_url', output_style => SASS_STYLE_COMPRESSED, source_comments => 1, dont_die => 1, sass_functions => { 'my_sass_function($arg)' => sub { $_[0] } }); my $css = $sass->compile(".something { color: red; }"); if (!defined $css) { # $css can be undef because 'dont_die' was set warn $sass->last_error; } # Functional API use CSS::Sass qw(:Default sass_compile); my ($css, $err) = sass_compile(".something { color: red; }"); die $err if defined $err; # Functional API, simple, with no error messages my $css = sass_compile(".something { color: red; }"); die unless defined $css; # Functional API w/ options my ($css, $err) = sass_compile(".something { color: red; }", include_paths => ['some/include/path'], image_path => 'base_url', output_style => SASS_STYLE_NESTED, source_comments => 1);
CSS::Sass provides a perl interface to libsass, a fairly complete Sass compiler written in C. Despite its name, CSS::Sass can only compile the newer ".scss" files.
new
$sass = CSS::Sass->new(options)
Creates a Sass object with the specified options. Example:
$sass = CSS::Sass->new; # no options $sass = CSS::Sass->new(output_style => SASS_STYLE_NESTED);
compile(source_code)
$css = $sass->compile("source code");
This compiles the Sass string that is passed in the first parameter. If there is an error it will croak(), unless the dont_die option has been set. In that case, it will return undef.
croak()
dont_die
undef
last_error
$sass->last_error
Returns the error encountered by the most recent invocation of compile. This is really only useful if the dont_die option is set.
compile
libsass error messages are in the form ":$line:$column $error_message" so you can append them to the filename for a standard looking error message.
libsass
options
$sass->options->{dont_die} = 1;
Allows you to inspect or change the options after a call to new.
($css, $err) = sass_compile(source_code, options)
$css = sass_compile(source_code, options)
This compiles the Sass string that is passed in the first parameter. It returns both the CSS and the error in list context and just the CSS in scalar context. One of the returned values will always be undef, but never both.
output_style
SASS_STYLE_NESTED
SASS_STYLE_COMPRESSED
The default is SASS_STYLE_NESTED. Set to SASS_STYLE_COMPRESSED to eliminate all whitespace (for your production CSS).
source_comments
Set to 0 (the default) and no extra comments are output. Set to 1 and comments are output indicating what input line the code corresponds to.
0
1
include_paths
This is an arrayref that holds the list a of paths to search (in addition to the current directory) when following Sass @import directives.
@import
image_path
This is a string that holds the base URL. This is only used in the (non-standard) image-url() Sass function. For example, if image_path is set to 'file:///tmp/a/b/c', then the follwoing Sass code:
image-url()
'file:///tmp/a/b/c'
.something { background-image: image-url("my/path"); }
...will compile to this:
.something { background-image: url("file:///tmp/a/b/c/my/path"); }
This is only valid when used with the Object Oriented Interface. It is described in detail there.
sass_functions
This is a hash of Sass functions implemented in Perl. The key for each function should be the function's Sass signature and the value should be a Perl subroutine reference. This subroutine will be called whenever the function is used in the Sass being compiled. The arguments to the subroutine are CSS::Sass::Type objects and the return value must also be one of those types. It may also return undef which is just a shortcut for CSS::Sass::Type::String->new('').
The function is called with an eval statement so you may use "die" to throw errors back to libsass.
eval
A simple example:
sass_functions => { 'append_hello($str)' => sub { my ($str) = @_; die '$str should be a string' unless $str->isa("CSS::Sass::Type::String"); return CSS::Sass::Type::String->new($str->value . " hello"); } }
If this is encountered in the Sass:
some_rule: append_hello("Well,");
Then the ouput would be:
some_rule: Well, hello;
CSS::Sass::Type
The Sass Home Page
The libsass Home Page
The CSS::Sass Home Page
David Caldwell <david@porkrind.org>
Copyright (C) 2013 by David Caldwell
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.4 or, at your option, any later version of Perl 5 you may have available.
To install CSS::Sass, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CSS::Sass
CPAN shell
perl -MCPAN -e shell install CSS::Sass
For more information on module installation, please visit the detailed CPAN module installation guide.