Current Version: 1.0.10
Project Name: csspp
CSS Preprocessor @-keywords

Table of Contents

@charset "utf-8";

The csspp compiler accepts the @charset keyword, but only if it specifies UTF-8. At this time the compiler does not check whether the @charset was appearing at the very beginning of the file. Also, the specification is not kept in the compiled tree so it does not get output either.

If the string following the @charset is not UTF-8 (in any case) then an error is generated. If the syntax is invalid, an error is also generated (i.e. the @charset must be followed by a string.)

@debug <string> ;

Print out a debug message (i.e. <string>). By default a system should not display debug messages. The csspp command line tool shows debug messages only if the –debug command line option is used.

If the message is somehow empty, then a default message is printed.

@else { code }

The @else command offers a way to run code when all @if and @else if preceeding this @else have a false expression.

The precense of an @else somewhere else than after an @if or an @else if is an error.

@if $pseudo_name = "nth-child" {
// do something if nth-child
}
@else if $pseudo_name = "first-child" {
// do something if first-child
}
@else {
@error "we do not know what to do then...";
}

@else if <expression> { code }

The @else if command offers a way to verify another expression and execute code only if all previous @if and @else if were all false and this @else if expression is true.

The precense of an @else if somewhere else than after an @if or another @else if is an error. In particular, an @else if cannot appear after an @else.

@if $pseudo_name = "nth-child" {
// do something if nth-child
}
@else if $pseudo_name = "first-child" {
// do something if first-child
}

@error <string> ;

Print out an error message (i.e. <string>). If the message is somehow empty, print out a default error message.

The error is counted just like any other errors, so a tool, such as the csspp compiler, will return with an exit code of 1.

@if <expression> { code }

The @if command adds the possibility to write code that gets compiled only when the expression is true.

An @if command can be followed by an @else if or an @else.

For example, validation code generally checks various values such as strings and generate an error if the values are not considered valid:

@if $pseudo_name != "nth-child" {
@error $pseudo_name + " is not a known pseudo function.";
}

@import <string> ;

The @import command includes another .scss or .css file in place. This allows you to create libraries of CSS rules that you can reuse in various places.

The @import is ignored if the specified path or URL points to a file that cannot be loaded. If the URL specify a domain name then the compiler ignores it and the @import is left alone.

At this point the @import conditions are completely ignored if present.

If a file can be loaded, then the @import is removed from the source and replaced by the contents of the file.

There is no depth limit to the @import, however, the compiler will do its best to avoid loops (importing A which imports B and in turn attempts to re-import A.)

@import "extensions/colorful.scss";

An imported file can include anything. For example, the system/version.scss file only includes a set of variables representing the version of the compiler.

Note
There is also an @include command, which is used to include complex variables when the simple $<varname> is not going to work right.

@include <identifier> ;

This @include is used to insert a variable in place. In some circumstance you may want to insert a rather complex variable and this will generally make it work.

This is particularly useful in case you want to insert a variable representing fields. That being said, the csspp way is to use the null field name:

@mixin complex { color: red; }
// this works as is since we are defining 'background-color: red'
body { background: $complex }
// however, to define the text color we have a problem which
// can be resolved these ways:
p { -csspp-null: $complex }
span { @include complex; }

Of course, the @include itself gets removed from the resulting CSS file.

Note that the @include can also be used to insert a variable function:

@mixin colorful($color, $border-width: 1px) {
color: $color;
border: $border-width solid black;
}
p.error { @include colorful(red, 3px); }

The final output will look like:

p.error {
color: red;
border: 3px solid black;
}
Note
If you wanted to include another CSS or SCSS file in your SCSS file, you were looking for @import and not the @include.

@message <string> ; or @info <string> ;

Print out an informational message (i.e. <string>). If the message is empty, then a default message gets written.

The error and warning counters do not get touched when an informational message is output.

@mixin <identifer> { ... }

The @mixin comes from SASS. It is a way to declare a complex variable. Although csspp does not require it, we have it to be a little more compatible to SASS.

The name of the variable is specified right after the @mixin keyword. It may be an identifier or a function declaration. The code inside the curly brackets is what represents the value of the variable.

@mixin red-color { color: #f00 }
@mixin your-color($color) { color: $color }

Just like other variables, @mixin can be inserted using the name of the variable:

border { -csspp-null: $red-color; }
border { -csspp-null: $your-color(#0f1598); }

To be more SASS compatible, we also support the @include.

@return <expression> ;

When defining <identifer> { ... } functions, the result of the function can be returned using the @return keyword.

The @return keyword is expected to be used last in the list of commands in the function block. It immediately ends the processing of the function and makes the final expression the returned result to the caller.

The call is like an internal function. System defined functions are found in the scripts/system/functions.scss. For example, the opacity() function is an overload of the alpha() function. We define it as an external function as follow:

@mixin opacity($color)
{
@return alpha($color);
}

One can use the opacity() function in a rule such as:

div { z-index: opacity($color); }

@warning <string> ;

Print out a warning message (i.e. <string>). If the message is somehow empty, print out a default warning message.

The warning is counted just like any other warnings and if the user requested that warnings be managed like errors, an error is printed and counted as expected.

Documentation of CSS Preprocessor.

This document is part of the Snap! Websites Project.

Copyright by Made to Order Software Corp.