everycss

#EveryCSS

Framework for CSS post and/or pre proccessors.

EveryCSS parses CSS with pre-processors in mind. It parses regular CSS but also non regular CSS like nested rules. By doing this it let you process your css in a pre, post or both ways.

##Caution

EveryCSS is not yet production ready. It actually works but the API is subject to change.

##How it works

EveryCSS:

1. parses your CSS into a node tree. Parsing doesn't use regular expression
2. passes the tree to processors you set in order to process (edit) it
3. passes the processed tree to your callback
4. you cound stringify the tree using the toString method

var EveryCSS    = require('everycss'),

    // load processors you want to use
    importer    = require('everycss-import'),
    rem         = require('everycss-rem'),
    nestedRule  = require('everycss-nested'),
    charset     = require('everycss-charset'),

    everycss;

// instantiate EveryCSS
everycss = new EveryCSS;
everycss
  // add processors
  .use(importer.processor)
  .use(rem.processor)
  .use(nestedRule.processor)
  .use(charset.processor)
  // process
  .processFile('demo/demo.css', function (root) {
    // output result
    console.log(root.toString());
  });

##What is a processor?

A processor is a function which take node tree as parameter and edit it. You can write your own processors and/or use existing ones:

• everycss-charset: help dealing with @charset rule
• everycss-import: add support for @import and @import-once
• everycss-nested: add support for nested rules
• everycss-rem: add pixel fallback for rem values

##The EveryCSS object

To create your own pre/post processor, instantiate an EveryCSS object and add processors:

var EveryCSS = require('everycss'),
    ecss;

ecss  = new EveryCSS;
ecss.use(function (root) {
  // process

  // call next processor
  this.next();
});

Then process a string with process method or a file with processFile:

ecss.processFile('somefile.ecss', function (processed) {
	console.log(processed.toString());
});

###use(processor [, options ])

Add a processor to your EveryCSS instance.

• processor: function processing an EveryCSS tree
• options: object with options used by the processor

ecssRem = require('everycss/lib/processors/rem');
ecss.use(ecssRem, {size: 10});

###process(string [, success [, error ]])

Parse and process a string.

• string: string to process
• success: function called when process succeeds
• error: function called when process fails

ecss.process('foo { height: 2rem; }',
  function (processed) {
    // process succeed
    console.log(processed.toString());
  },
  function (error) {
    // process failed
    console.log(error);
  });

###processFile(filename [, success [, error ]])

Parse and process a file.

• filename: file to process
• success: function called when process succeeds
• error: function called when process fails

ecss.process('somefile.ecss',
  function (processed) {
    // process succeed
    console.log(processed.toString());
  },
  function (error) {
    // process failed
    console.log(error);
  });

##The tree

The EveryCSS tree is compound of different types of nodes:

• at-rule
• color
• comment
• declaration
• function
• identifier
• list
• number
• operator
• root
• rule
• string
• whitespace

They have common methods and attributes but some types of nodes have their own too. Node methods return the current instance by default.

###Common attributes

• type: type of the node (readonly)
• iBlock: if the node could have children (readonly)
• parent: the parent node or null (readonly)
• children: array of children node (readonly)
• length: number of children node (readonly)
• depth: depth of the node in the tree (readonly)

###Common methods

####children([ type ])

Return node's children. If a type is provided, only nodes with corresponding type will be returned.

• type: type of node to return

####after(node)

Insert a node after this in the parent node.

• node: the node to insert

####append(node)

Insert a node after the last one.

• node: the node to insert

####before(node)

Insert a node before the current node in the parent.

• node: the node to insert

####copy([ overlay ])

Return a copy of the current node.

• overlay: object of properties to replace in the copy

####detach()

Remove the current node from it's parent.

####each([ type,][ limit,] callback)

Loop through node's descendant eventually filtered by a type and limited in depth.

• type: type of node to loop through. Loop through all types by default
• limit: descending levels allowed. A limit of 0 will loop through direct children. -1 correspond to no limit.
• callback: callback called on each node. Receives the node and a loop object as argument.

root.each(function (node, loop) {});
root.each(0, function (node, loop) {});
root.each('at-rule', function (rule, loop) {});
root.each('at-rule', 0, function (rule, loop) {});

The callback is executed in the context of the node on which you called each (the parent node). The callback receives two argument, a descendant node and a loop object containing these attributes:

• cursor: global index of the node, depth agnostic
• depth: relative depth of the node
• index: index of the node at the current depth
• descent: set to true by default. Defining it to false will prevent from looping on current node's children.

####insertAt(node, index)

Insert a node at the given index.

• node: the node to insert
• index: the new position of the node

####prepend(node)

Insert a node before the first one.

• node: the node to insert

####remove(node)

Remove the node from the children list.

• node: the node to remove