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:

• parses your CSS into a node tree. Parsing doesn't use regular expression
• passes the tree to processors you set in order to process (edit) it
• passes the processed tree to your callback
• 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