@xinminlabs/gonzales-pe
v1.1.0
Published
Gonzales Preprocessor Edition (fast CSS parser)
Downloads
3,972
Readme
Gonzales PE @dev
Gonzales PE is a CSS parser which plays nicely with preprocessors.
Currently those are supported: SCSS, Sass, LESS.
Try out Gonzales PE online: Gonzales PE Playground.
Install
(1) To install command-line tool globally:
npm install -g git://github.com/tonyganch/gonzales-pe.git#dev
(2) To install parser as a project dependency:
npm install --save git://github.com/tonyganch/gonzales-pe.git#dev
(3) If for some reason you want to build files yourself:
# Clone the repo.
git clone [email protected]:tonyganch/gonzales-pe.git
# Go to dev branch.
git checkout dev
# Install project dependencies.
npm install
# Install git hooks and build files.
npm run init
API
Basically there are a few things you can do:
- parse css string and get a parse tree in return;
- modify tree nodes;
- remove tree nodes;
- add new nodes to the tree;
- convert modified tree back to a string.
The different type of tree nodes can be found in docs/node-types.md.
In examples below I assume that gonzales
is a parser module and parseTree
is some parsed css:
let gonzales = require('gonzales-pe');
let parseTree = gonzales.parse(css);
gonzales.createNode(options)
Description
Creates a new node. Useful when you need to add something to a tree.
Parameters
Returns
Examples
let css = 'a {color: tomato}';
let parseTree = gonzales.parse(css);
let node = gonzales.createNode({ type: 'animal', content: 'panda' });
parseTree.content.push(node);
gonzales.parse(css[, options])
Description
Parses a css string.
Parameters
Returns
Examples
let css = 'a {color: tomato}';
let parseTree = gonzales.parse(css);
let less = 'a {$color: tomato}';
let parseTree = gonzales.parse(less, {syntax: 'less'});
let less = '$color: tomato';
let parseTree = gonzales.parse(less, {syntax: 'less', rule: 'declaration'});
parseTree.contains(type)
Description
Checks whether there is a child node of given type.
Parameters
Returns
Examples
if (parseTree.contains('space')) {
doSomething();
}
parseTree.content
Returns
parseTree.eachFor([type, ]callback)
Description
Calls a function for every child node in tree. If type
parameter is passed,
calls a function only for child nodes of a given type. The main difference from
parseTree.forEach()
is that this method loops through node list from the end
to beginning.
Parameters
Examples
parseTree.eachFor(function(childNode) {
doSomething(childNode);
});
// Remove all child spaces.
parseTree.eachFor('space', function(spaceNode, i) {
parseTree.removeChild(i);
});
parseTree.end
Returns
parseTree.first([type])
Description
Gets the first child node. If type
parameter is passed, gets the first child
node of a given type. If no node has been found, returns null
.
Parameters
Returns
Examples
let node = parseTree.first();
node.content = 'panda';
let node = parseTree.first('multilineComment');
node.content = 'panda';
parseTree.forEach([type, ]callback)
Description
Calls a function for every child node in tree. If type
parameter is passed,
calls a function only for child nodes of a given type. The main difference from
parseTree.eachFor()
is that this method loops through node list from the
beginnig to end.
Parameters
Examples
parseTree.forEach(function(childNode) {
doSomething();
});
parseTree.forEach('space', function(spaceNode) {
doSomething();
});
parseTree.get(index)
Description
Gets nth child of the parseTree
. If no node has been found, returns null
.
Parameters
Returns
Examples
var node = parseTree.get(2);
doSomething(node);
parseTree.insert(index, node)
Description
Inserts a node to a given position in parseTree
.
Parameters
Examples
let node = gonzales.createNode({type: 'animal', content: 'panda'});
parseTree.insert(2, node);
parseTree.is(type)
Description
Checks whether the node is of given type.
Parameters
Returns
Examples
if (node.is('space')) {
node.content = '';
}
parseTree.last(type)
Gets the last child node. If type
parameter is passed, gets the last child
node of a given type. If no node has been found, returns null
.
Parameters
Returns
Examples
let node = parseTree.last();
node.content = 'panda';
let node = parseTree.last('multilineComment');
node.content = 'panda';
parseTree.length
Returns
parseTree.removeChild(index)
Description
Removes a child node at a given position.
Parameters
Returns
// Swap nodes.
var node = parseTree.removeChild(1);
parseTree.insert(0, node);
parseTree.start
Returns
parseTree.syntax
Returns
parseTree.toJson()
Description
Converts parse tree to JSON. Useful for printing.
Returns
parseTree.toString()
Description
Converts parse tree back to string according to original syntax.
Returns
Examples
let css = parseTree.toString();
parseTree.traverse(callback)
Description
Calls the function for every node in a tree including parseTree
itself.
Parameters
Examples
parseTree.traverse(function(node, index, parent) {
if (node.is('multilineComment')) {
parent.removeChild(index);
} else if (node.is('space')) {
node.content = ' ';
}
});
parseTree.traverseByType(type, callback)
Description
This method should be called for a root node, because calling it for a child
will be more time consuming.
Calls the function for every node of a given type. This means not just child
nodes, but grandchilds and so on.
Parameters
Examples
// Remove all comments.
parseTree.traverseByType('multilineComment', function(node, index, parent) {
parent.removeChild(index);
});
parseTree.traverseByTypes(types, callback)
Description
This method should be called for a root node, because calling it for a child
will be more time consuming.
Calls the function for every node of given types. This means not just child
nodes, but grandchilds and so on.
Parameters
Examples
// Remove all comments and spaces.
let types = ['multilineComment', 'space'];
parseTree.traverseByTypes(types, function(node, index, parent) {
parent.removeChild(index);
});
parseTree.type
Returns
Test
To run tests:
npm test
This command will build library files from sources and run tests on all files in syntax directories.
Every test has 3 files: source stylesheet, expected parse tree and expected string compiled back from parse tree to css.
If some tests fail, you can find information in test logs:
log/test.log
contains all information from stdout;log/expected.txt
contains only expected text;log/result.txt
contains only result text.
The last two are made for your convenience: you can use any diff app to see the defference between them.
If you want to test one specific string or get a general idea of how Gonzales
works, you can use test/ast.js
file.
Simply change the first two strings (css
and syntax
vars) and run:
node test/single-test.js
Report
If you find a bug or want to add a feature, welcome to Issues.
If you are shy but have a question, feel free to drop me a line.