NAME

CSS::Sass - Compile .scss files using libsass

SYNOPSIS

  # 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);

DESCRIPTION

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.

OBJECT ORIENTED INTERFACE

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.

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.

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.

options

  $sass->options->{dont_die} = 1;

Allows you to inspect or change the options after a call to new.

FUNCTIONAL INTERFACE

($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.

OPTIONS

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.

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.

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:

  .something { background-image: image-url("my/path"); }

...will compile to this:

  .something { background-image: url("file:///tmp/a/b/c/my/path"); }

dont_die

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.

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;

SEE ALSO

CSS::Sass::Type

The Sass Home Page

The libsass Home Page

The CSS::Sass Home Page

AUTHOR

David Caldwell <david@porkrind.org>

COPYRIGHT AND LICENSE

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.