CSS::Sass(3)

📦 version 3.6.4, in opensuse-leap 16.0

🌸 NAME 🌸

hey bestie! welcome to the user-contributed perl documentation for the CSS::Sass(3) man page — this is the perl bindings for libsass, and the official name vibe is CSS::Sass — Compile .scss files using libsass. That's the whole NAME situation, no cap. 💖

✨ SYNOPSIS ✨

okay so here's the whole synopsis, copy-paste ready. every line is exactly what the man page says, so you can just steal it for your editor and go off:

# Object Oriented API
use CSS::Sass;

# Call default constructor
my $sass = CSS::Sass->new;
# Manipulate options for compile calls
$sass->options->{source_comments} = 1;
# Call file compilation (may die on errors)
my $css = $sass->compile_file('styles.scss');

# Add custom function to use inside your Sass code
sub foobar { CSS::Sass::Value::String->new('blue') }
$sass->options->{sass_functions}->{'foobar'} = \ &foobar;

# Compile string and get css output and source-map json
$sass->options->{source_map_file} = 'output.css.map';
($css, $stats) = $sass->compile('A { color: foobar(); }');

# Object Oriented API w/ options
my $sass = CSS::Sass->new(plugin_paths    => ['plugins'],
                          include_paths   => ['some/include/path'],
                          output_style    => SASS_STYLE_COMPRESSED,
                          source_map_file => 'output.css.map',
                          source_comments => 1,
                          dont_die        => 1,
                          sass_functions  => {
                            'foobar($arg)' => sub { $_[0] }
                          });

# Compile string and use the registered function
my ($css, $stats) = $sass->compile('A { color: foobar(red); }');

# Result can be undef because 'dont_die' was set
warn $sass->last_error unless (defined $css);

# Functional API
use CSS::Sass qw(:Default sass_compile);

# Functional API, with error messages and source-map
my ($css, $err, $stats) = sass_compile('A { color: red; }');
die $err if defined $err;

# Functional API, simple, with no error messages
my $css = sass_compile('A { color: red; }');
die unless defined $css;

# Functional API w/ options
my ($css, $err, $stats) = sass_compile('A { color: red; }',
                                       include_paths   => ['some/include/path'],
                                       output_style    => SASS_STYLE_NESTED,
                                       source_map_file => 'output.css.map');

# Import sass2scss function
use CSS::Sass qw(sass2scss);

# convert indented syntax
my $scss = sass2scss($sass);

# Import quoting functions
use CSS::Sass qw(quote unquote);

# Exchange quoted strings
my $string = unquote($from_sass);
my $to_sass = quote($string, '"');

🦋 DESCRIPTION 🦋

so what even is this? CSS::Sass provides a perl interface to libsass, which is a fairly complete Sass compiler written in C++. rn it's around ruby sass 3.3/3.4 feature parity and heading towards full 3.4 compatibility. it can compile .scss and .sass files. slay. 💅

👑 OBJECT ORIENTED INTERFACE 👑

this is the OO era, main character energy. you make an object, you poke its options, you compile stuff. iconic.

💅 new

$sass = CSS::Sass->new(options)

creates a Sass object with the specified options. example, bestie:

$sass = CSS::Sass->new; # no options
$sass = CSS::Sass->new(output_style => SASS_STYLE_NESTED);

🧚 compile(source_code)

$css = $sass->compile("A { color: blue; }");

this compiles the Sass string you pass in as the first parameter. it will croak() if there's an error, unless the dont_die option is set. in that case it will return undef. noted. 🫶

🫶 last_error

$sass->last_error

returns the error encountered by the most recent invocation of compile. this is only useful if the dont_die option is set.

the libsass error messages are in the form :$line:$column $error_message, so you can append them to the filename and get a standard-looking error message. lowkey handy.

🎀 options

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

lets you inspect or change the options after a call to new. yes, you can mess with it after the fact. 💖

🌈 FUNCTIONAL INTERFACE 🌈

no objects, just functions — still absolutely iconic:

$css = sass_compile(source_code, options)

($css, $err, $stats) = sass_compile(source_code, options)

compiles the sass code given by source_code. it returns CSS, error and a status object in list context, or just the CSS in scalar context. either CSS or error will be undef, but never both. periodt.

$css = sass_compile_file(input_path, options)

($css, $err, $stats) = sass_compile_file(input_path, options)

compiles the sass file given by input_path. it returns CSS, error and a status object in list context, or just the CSS in scalar context. either CSS or error will be undef, but never both. same energy, file edition. 🌸

📊 $stats status hash

the status hash holds usefull information after compilation:

  • error_status
  • output_string
  • included_files
  • source_map_string
  • error_line
  • error_column
  • error_src
  • error_file
  • error_text
  • error_message
  • error_json

✨ OPTIONS ✨

Okay bestie, this is the big one — every knob you can turn. Buckle up 💅

  • output_style — how your CSS comes out looking. Your choices are SASS_STYLE_NESTED, SASS_STYLE_COMPACT, SASS_STYLE_EXPANDED, and SASS_STYLE_COMPRESSED. The default is SASS_STYLE_NESTED. Set it to SASS_STYLE_COMPRESSED to eliminate all whitespace (that's the one for your production CSS, obvi 🫶).
  • precision — sets the floating point precision for output. Numbers gonna number.
  • linefeed — sets the linefeed string used for css output.
  • indent — sets the indentation string used for css output.
  • source_comments — set to true and you get extra comments in the output telling you what input line the code corresponds to. Very "who wrote this and where" of it 💖
  • source_map_file — setting this option enables the source-map generating. Lowkey important: the file will not actually be created, but its content will be returned to the caller. It will also enable the sourceMappingURL comment by default. See no_src_map_url.
  • source_map_file_urls — render source entries in the source map json as file urls (file:///).
  • source_map_root — a path (string) that is directly embedded in the source map as sourceRoot.
  • source_map_embed — embeds the complete source-map content into the sourceMappingURL, by using a base64 encoded data uri (sourceMappingURL=data:application/json;base64,XXXX). It's giving self-contained icon energy ✨
  • source_map_contents — embeds the content of each source inside a sourcesContent property in the source-map json. Setting this option along with source_map_embed allows for a completely self-contained source-map. Obsessed.
  • no_src_map_url — set to true to omit the sourceMappingURL comment from the output css. Heads up tho: setting this option makes source_map_embed useless 😭
  • include_paths — this is an arrayref that holds the list of paths to search (in addition to the current directory) when following Sass @import directives. Your import besties live here.
  • plugin_paths — this is an arrayref that holds a list of paths to search for third-party plugins. It will automatically load any <dll> or <so> library within that directory. Fair warning: this is currently a highly experimental libsass feature! 🧪
  • dont_die — this is only valid when used with the Object Oriented Interface. It is described in detail there. (Go read that section, bestie, it ate.)
  • 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::Value objects, which map to native perl types if possible. You can return either CSS::Sass::Value objects or supported native perl data structures. undef is an equivalent of CSS::Sass::Value::Null->new.

The function is called with an eval statement so you may use die to throw errors back to libsass (CSS::Sass::Value::Error).

A simple example:

sass_functions => {
    'append_hello($str)' => sub {
        my ($str) = @_;
        die '$str should be a string' unless $str->isa("CSS::Sass::Value::String");
        return CSS::Sass::Value::String->new($str->value . " hello");
        # equivalent to return $str->value . " hello";
    }
}

If this is encountered in the Sass:

some_rule: append_hello("Well,");

Then the output would be:

some_rule: Well, hello;

Literally so iconic of it 🌸

🛠️ Custom importer

This is a function implemented in Perl that gets called for every @import statement. Okay so — this feature is in an experimental stage and you have to be careful to return the expected structure. You can return multiple imports from one call to make it possible to implement globbing importers etc. If you omit $data, libsass will try to load the given path itself. It will go through the normal lookup algorithm as it would have if it had encountered the virtual import statement on its own. $scope holds the current import path. Imports in css are meant to be relative to the parent scope, so you can use it to create absolute urls or paths within the context you're working with.

A simple example:

importer => sub {
  my ($import, $scope) = @_;
  return [
    # [ $real_path ] or [ $virtual_path, $data ],
    [ "http://xyz/file", "div { color: red; }" ],
  ];
}

You may also return undef to skip the importer (useful if an importer only handles certain url protocols). With the latest libsass version, you can add multiple importers with a priority order to implement more complex scenarios (highly experimental). No cap, read that twice 🔥

🎀 Custom headers

Another highly experimental feature to prepend content on every compilation. It can be used to predefine mixins or other stuff. Internally the content is really just added to the top of the processed data. Custom headers have the same structure as importers. But all registered headers are called in the order given by the priority flag. Cute, consistent, iconic 👑

🧬 Sass_Value Types

Sass knows various Sass_Value types. We export the constants for completeness. Each type is mapped to a package inside the CSS::Sass::Value namespace.

# Value types
SASS_ERROR
SASS_NULL
SASS_BOOLEAN
SASS_NUMBER
SASS_STRING
SASS_COLOR
SASS_LIST
SASS_MAP
# List styles
SASS_COMMA
SASS_SPACE

🔮 Autodetection for value types returned by custom function

Many Sass_Value types can be mapped directly to perl data structures. maps and lists map directly to hashes and arrays. Scalars are mapped to string, number or null. You can directly return these native data types from your custom functions or use the data structures to access maps and lists.

undef; # same as CSS::Sass::Value::Null->new;
42; # same as CSS::Sass::Value::Number->new(42);
"foobar"; # same as CSS::Sass::Value::String->new("foobar");
[ 'foo', 'bar' ]; # same as CSS::Sass::Value::List->new('foo', 'bar');
{ key => 'value' }; # same as CSS::Sass::Value::Map->new(key => 'value');

We bless native return values from custom functions into the correct package. Yes bestie, it just knows 💅

# sub get-map { return { key: "value" } };
.class { content: map-get(get-map(), key); }

# sub get-list { return [ 'foo', 42, 'bar' ] };
.class { content: nth(get-list(), 2); }

🌈 MISCELLANEOUS 🌈

The little leftover gems. Slay.

  • SASS2SCSS_PRETTIFY_0 — write everything on one line (minimized)
  • SASS2SCSS_PRETTIFY_1 — add lf after opening bracket (lisp style)
  • SASS2SCSS_PRETTIFY_2 — add lf after opening and before closing bracket (1TBS style)
  • SASS2SCSS_PRETTIFY_3 — add lf before/after opening and before closing (allman style)
  • SASS2SCSS_KEEP_COMMENT — keep multi-line source code comments. Single-line comments are removed by default.
  • SASS2SCSS_STRIP_COMMENT — strip all source code (single- and multi-line) comments.
  • SASS2SCSS_CONVERT_COMMENT — convert single-line comments to multi-line comments.

🍓 sass2scss($sass, $options)

We expose the sass2scss function, which can be used to convert indented sass syntax to the newer scss syntax. You may need this, since libsass will not automatically recognize the format of your string data. Rude of it, honestly, but here we are 💀

my $options = SASS2SCSS_PRETTIFY_1;
$options |= SASS2SCSS_CONVERT_COMMENT;
my $scss = sass2scss($sass, $options);

👀 SEE ALSO

Go read the docs, bestie, they're free ✨

💖 AUTHOR

David Caldwell <david@porkrind.org> Marcel Greter <perl-libsass@ocbnet.ch>

Legends, both of them. Periodt.

📜 LICENSE

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

And that's the whole page, bestie 🫶 This one's from perl v5.42.0, dated 2021-05-22 — the CSS::Sass(3) era. Go forth and compile your little heart out 💜
📦 where this page comes from