Skip to content

Commit 9d50ca0

Browse files
mgretermgreter
committed
Updates documentation
1 parent 3567c89 commit 9d50ca0

File tree

4 files changed

+398
-35
lines changed

4 files changed

+398
-35
lines changed

‎README.md

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,10 @@ CSS::Sass
44
### Compile .scss and .sass files using libsass
55

66
CSS::Sass provides a perl interface to [libsass][1], a fairly complete
7-
Sass compiler written in C (approx. Ruby Sass 3.2).
7+
Sass compiler written in C++. It is currently somewhere around ruby sass
8+
3.2 feature parity. It can compile .scss and .sass files.
89

9-
[1]: https://github.com/hcatlin/libsass
10+
[1]: https://github.com/sass/libsass
1011

1112
Installation
1213
------------
@@ -21,7 +22,7 @@ To install this module type the following:
2122
./Build test verbose=1
2223
./Build install verbose=1
2324

24-
On windows you need to install [Strawberry Perl](http://strawberryperl.com/).
25+
On windows you may need to install [Strawberry Perl](http://strawberryperl.com/).
2526

2627
Documentation
2728
-------------
@@ -34,6 +35,10 @@ After installing:
3435

3536
man CSS::Sass
3637

38+
Or view [converted markdown version][1]
39+
40+
[1]: https://github.com/sass/perl-libsass/blob/master/lib/CSS/Sass.md
41+
3742
Dependencies
3843
------------
3944

@@ -42,6 +47,24 @@ This module requires these other modules and libraries:
4247
* Module::Build
4348
* Test::More
4449

50+
Command line utility
51+
--------------------
52+
53+
```
54+
psass [options] [ source | - ]
55+
```
56+
57+
```
58+
-v, --version print version
59+
-h, --help print this help
60+
-p, --precision precision for float output
61+
-t, --output-style=style output style [nested|compressed]
62+
-I, --include-path=path sass include path (repeatable)
63+
-c, --source-comments enable source debug comments
64+
-m, --source-map-file=file create and write source map to file
65+
--omit-source-map-url omit sourceMappingUrl from output
66+
```
67+
4568
Copyright And Licence
4669
---------------------
4770

‎lib/CSS/Sass.md

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
# NAME
2+
3+
CSS::Sass - Compile .scss files using libsass
4+
5+
# SYNOPSIS
6+
7+
# Object Oriented API
8+
use CSS::Sass;
9+
10+
# Call default constructor
11+
my $sass = CSS::Sass->new;
12+
# Manipulate options for compile calls
13+
$sass->options->{source_comments} = 1;
14+
# Call file compilation (may die on errors)
15+
my $css = $sass->compile_file('styles.scss');
16+
17+
# Add custom function to use inside your Sass code
18+
sub foobar { CSS::Sass::Type::String->new('blue') }
19+
$sass->options->{sass_functions}->{'foobar'} = \ &foobar;
20+
21+
# Compile string and get css output and source map json
22+
$sass->options->{source_map_file} = 'output.css.map';
23+
($css, $srcmap) = $sass->compile('A { color: foobar(); }');
24+
25+
26+
# Object Oriented API w/ options
27+
my $sass = CSS::Sass->new(include_paths => ['some/include/path'],
28+
image_path => 'base_url',
29+
output_style => SASS_STYLE_COMPRESSED,
30+
source_map_file => 'output.css.map',
31+
source_comments => 1,
32+
dont_die => 1,
33+
sass_functions => {
34+
'foobar($arg)' => sub { $_[0] }
35+
});
36+
37+
# Compile string and use the registered function
38+
my ($css, $srcmap) = $sass->compile('A { color: foobar(red); }');
39+
40+
# Result can be undef because 'dont_die' was set
41+
warn $sass->last_error unless (defined $css);
42+
43+
44+
# Functional API
45+
use CSS::Sass qw(:Default sass_compile);
46+
47+
# Functional API, with error messages and source map
48+
my ($css, $err, $srcmap) = sass_compile('A { color: red; }');
49+
die $err if defined $err;
50+
51+
# Functional API, simple, with no error messages
52+
my $css = sass_compile('A { color: red; }');
53+
die unless defined $css;
54+
55+
# Functional API w/ options
56+
my ($css, $err, $srcmap) = sass_compile('A { color: red; }',
57+
include_paths => ['some/include/path'],
58+
image_path => 'base_url',
59+
output_style => SASS_STYLE_NESTED,
60+
source_map_file => 'output.css.map');
61+
62+
# Import sass2scss function
63+
use CSS::Sass qw(sass2scss);
64+
65+
# convert indented syntax
66+
my $scss = sass2scss($sass);
67+
68+
# DESCRIPTION
69+
70+
CSS::Sass provides a perl interface to libsass, a fairly complete Sass
71+
compiler written in C++. It is currently somewhere around ruby sass 3.2
72+
feature parity. It can compile .scss and .sass files.
73+
74+
# OBJECT ORIENTED INTERFACE
75+
76+
- `new`
77+
78+
$sass = CSS::Sass->new(options)
79+
80+
Creates a Sass object with the specified options. Example:
81+
82+
$sass = CSS::Sass->new; # no options
83+
$sass = CSS::Sass->new(output_style => SASS_STYLE_NESTED);
84+
85+
- `compile(source_code)`
86+
87+
$css = $sass->compile("A { color: blue; }");
88+
89+
This compiles the Sass string that is passed in as the first parameter. It
90+
will `croak()` if there is an error, unless the `dont_die` option is set.
91+
It will return `undef` in that case.
92+
93+
- `last_error`
94+
95+
$sass->last_error
96+
97+
Returns the error encountered by the most recent invocation of
98+
`compile`. This is only useful if the `dont_die` option is set.
99+
100+
`libsass` error messages are in the form ":$line:$column $error\_message" so
101+
you can append them to the filename for a standard looking error message.
102+
103+
- `options`
104+
105+
$sass->options->{dont_die} = 1;
106+
107+
Allows you to inspect or change the options after a call to `new`.
108+
109+
# FUNCTIONAL INTERFACE
110+
111+
- `$css = sass_compile(source_code, options)`
112+
- `($css, $err, $srcmap) = sass_compile(source_code, options)`
113+
114+
This compiles the Sass string that is passed in the first parameter. It
115+
returns both the CSS and the error in list context and just the CSS in
116+
scalar context. One of the returned values will always be `undef`, but
117+
never both.
118+
119+
# OPTIONS
120+
121+
- `output_style`
122+
123+
- `SASS_STYLE_NESTED`
124+
- `SASS_STYLE_COMPRESSED`
125+
126+
The default is `SASS_STYLE_NESTED`. Set to `SASS_STYLE_COMPRESSED` to
127+
eliminate all whitespace (for your production CSS).
128+
129+
- `source_comments`
130+
131+
Set to `true` to get extra comments in the output, indicating what input
132+
line the code corresponds to.
133+
134+
- `source_map_file`
135+
136+
Setting this option enables the source map generating. The file will not
137+
actually be created, but its content will be returned to the caller. It
138+
will also enable sourceMappingUrl comment by default. See `omit_src_map_url`.
139+
140+
- `omit_src_map_url`
141+
142+
Set to `true` to omit the sourceMappingUrl comment from the output css.
143+
144+
- `include_paths`
145+
146+
This is an arrayref that holds the list a of paths to search (in addition to
147+
the current directory) when following Sass `@import` directives.
148+
149+
- `image_path`
150+
151+
This is a string that holds the base URL. This is only used in the
152+
(non-standard) `image-url()` Sass function. For example, if `image_path`
153+
is set to `'file:///tmp/a/b/c'`, then the follwoing Sass code:
154+
155+
.something { background-image: image-url("my/path"); }
156+
157+
...will compile to this:
158+
159+
.something { background-image: url("file:///tmp/a/b/c/my/path"); }
160+
161+
- `dont_die`
162+
163+
This is only valid when used with the [Object Oriented Interface](#object-oriented-interface). It is
164+
described in detail there.
165+
166+
- `sass_functions`
167+
168+
This is a hash of Sass functions implemented in Perl. The key for each
169+
function should be the function's Sass signature and the value should be a
170+
Perl subroutine reference. This subroutine will be called whenever the
171+
function is used in the Sass being compiled. The arguments to the subroutine
172+
are [CSS::Sass::Type](https://metacpan.org/pod/CSS::Sass::Type) objects and the return value _must_ also be one of
173+
those types. It may also return `undef` which is just a shortcut for
174+
CSS::Sass::Type::String->new('').
175+
176+
The function is called with an `eval` statement so you may use "die" to
177+
throw errors back to libsass.
178+
179+
A simple example:
180+
181+
sass_functions => {
182+
'append_hello($str)' => sub {
183+
my ($str) = @_;
184+
die '$str should be a string' unless $str->isa("CSS::Sass::Type::String");
185+
return CSS::Sass::Type::String->new($str->value . " hello");
186+
}
187+
}
188+
189+
If this is encountered in the Sass:
190+
191+
some_rule: append_hello("Well,");
192+
193+
Then the ouput would be:
194+
195+
some_rule: Well, hello;
196+
197+
# MISCELLANEOUS
198+
199+
- `SASS2SCSS_PRETTIFY_0`
200+
201+
Write everything on one line (minimized)
202+
203+
- `SASS2SCSS_PRETTIFY_1`
204+
205+
Add lf after opening bracket (lisp style)
206+
207+
- `SASS2SCSS_PRETTIFY_2`
208+
209+
Add lf after opening and before closing bracket (1TBS style)
210+
211+
- `SASS2SCSS_PRETTIFY_3`
212+
213+
Add lf before/after opening and before closing (allman style)
214+
215+
- `SASS2SCSS_KEEP_COMMENT`
216+
217+
Keep multi-line source code comments.
218+
Single-line comments are removed by default.
219+
220+
- `SASS2SCSS_STRIP_COMMENT`
221+
222+
Strip all source code (single- and multi-line) comments.
223+
224+
- `SASS2SCSS_CONVERT_COMMENT`
225+
226+
Convert single-line comments to mutli-line comments.
227+
228+
- `sass2scss`
229+
230+
We expose the `sass2scss` function, which can be used to convert indented sass
231+
syntax to the newer scss syntax. You may need this, since `libsass` will not
232+
automatically recognize the format of your string data.
233+
234+
my $options = SASS2SCSS_PRETTIFY_1;
235+
$options |= SASS2SCSS_CONVERT_COMMENT;
236+
my $scss = sass2scss($sass, $options);
237+
238+
# SEE ALSO
239+
240+
[CSS::Sass::Type](https://metacpan.org/pod/CSS::Sass::Type)
241+
242+
[The Sass Home Page](http://sass-lang.com/)
243+
244+
[The libsass Home Page](https://github.com/sass/libsass)
245+
246+
[The CSS::Sass Home Page](https://github.com/sass/perl-libsass)
247+
248+
# AUTHOR
249+
250+
David Caldwell <[email protected]>
251+
Marcel Greter <[email protected]>
252+
253+
# COPYRIGHT AND LICENSE
254+
255+
Copyright (C) 2013 by David Caldwell
256+
Copyright (C) 2014 by Marcel Greter
257+
258+
This library is free software; you can redistribute it and/or modify
259+
it under the same terms as Perl itself, either Perl version 5.12.4 or,
260+
at your option, any later version of Perl 5 you may have available.
261+
262+
# POD ERRORS
263+
264+
Hey! **The above document had some coding errors, which are explained below:**
265+
266+
- Around line 217:
267+
268+
'=item' outside of any '=over'

0 commit comments

Comments
 (0)