gonzales-pe v4.3.0

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 git@github.com: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:

1. parse css string and get a parse tree in return;
2. modify tree nodes;
3. remove tree nodes;
4. add new nodes to the tree;
5. 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.