CCSS is a preprocessor for CSS (Cascading Style Sheets), extending the language with arithmetic operations and variables
OCaml CSS Makefile
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
tests
.gitignore
.merlin
CHANGELOG
LICENSE
Makefile
README
_oasis
_tags
configure
myocamlbuild.ml
opam
setup.ml

README

=========================================================================
| README for CCSS                                                       |
|                                                                       |
| http://ccss.forge.ocamlcore.org/                                      |
|                                                                       |
| Dario Teixeira <dario.teixeira@nleyten.com>                           |
=========================================================================


1. Overview
===========

CCSS is a preprocessor/pretty-printer for CSS (Cascading Style Sheets).
It extends the CSS language with support for declaration of variables and
basic arithmetic operations (addition, subtraction, multiplication, division).
The programme is supposed to be used as a filter: it reads the CSS source
from stdin and outputs its result on stdout.


2. Features
===========

2.1. Variables for expressions and mixins
=========================================

With CCSS, you may declare and use variables in your CSS code (in fact, CCSS
variables are actually constants, since they are assigned upon declaration and
may not be changed).  Variable identifiers must begin with an uppercase letter,
and be followed by any combination of letters, numbers, and the characters
'-' (dash) and '_' (underscore).

There are two use cases for variables.  The first consists in assigning any
CSS expression (not only quantities) to a variable.  The assigned expression
can subsequently be referenced by the variable identifier.  The code below
demonstrates this situation:

Foo: 20em;
Bar: 1px solid black;

h1  {
    width: Foo;
    border: Bar;
    }


The second use of variables is to declare mixins, ie, declaration blocks
that can be included within subsequent declaration blocks.  The code below
illustrates the use of mixins:

Inverse_scheme:
    {
    color: #fff;
    background: #000;
    }

h1
    {
    Inverse_scheme;
    font-weight: bold;
    }


2.2. Arithmetic
===============

CCSS extends CSS expressions with basic arithmetic operations (addition,
subtraction, multiplication, and division).  The operands must be CSS
quantities (either dimensionless or with an attached unit), or other
expressions that ultimately resolve into a quantity.  Moreover, variables
whose value is a quantity (or an expression which resolves into a quantity)
may also be used as operands.

The operators are '+', '-', '*', and '÷'.  Note that multiplication and
division have precedence over addition and subtraction, but you may use
parentheses to group operations.  Consider thus the following input:

Left: 10em;
Right: 5em;
Total: Left + Right;

h1  {
    padding: (1.5em + 0.5em) * 2;
    width: 2 * Total;
    }


CCSS will produce the following output:

h1
    {
    padding: 4em;
    width: 30em;
    }


The reader will have noticed that CCSS must be unit-aware when performing
arithmetic.  As a matter of fact, the programme performs a basic sanity
check of units, and will complain if you try, for example, to add "1em" with
"10px".  By default, CCSS will not make any attempt to convert units even if
they are convertible, such "cm" and "mm".  If you wish for CCSS to attempt
unit conversion, please provide option "--convert" on the command line
(short version "-c").

Units can be grouped into four categories, and conversion is possible if the
units belong to the same category.  Upon conversion, the result will be the
same unit as the first operand.  The categories and corresponding units are
as follows:

     length: mm, cm, in, pt, pc
      angle: deg, grad, rad
       time: ms, s
  frequency: hz, khz

As an illustration of unit conversion, the result for all the following
arithmetic operations is the same, "2in":

h1
    {
    foo1: 1in + 1in;
    foo2: 1in + 2.54cm;
    foo3: 1in + 25.4mm;
    foo4: 1in + 72pt;
    foo5: 1in + 6pc;
    }


3. Dependencies
===============

Menhir is used as the parser generator [1], while scanning is done with Sedlex [2].
Other requirements are Batteries [3] and OCaml-re [4].


4. Building and installing
==========================

The build system is generated with OASIS.  Run 'configure' if you wish to modify
the default install destination. Enter 'make' and 'make install' to build and
install the binary executable.


5. License
==========

CCSS is distributed under the terms of the GNU GPL version 2.
See LICENSE file for full license text.


References
==========

[1] http://cristal.inria.fr/~fpottier/menhir/
[2] https://github.com/alainfrisch/sedlex
[3] http://batteries.forge.ocamlcore.org/
[4] https://github.com/ocaml/ocaml-re