gonzales-pe
Gonzales Preprocessor Edition (fast CSS parser)
Last updated 9 years ago by tonyganch .
MIT · Repository · Bugs · Original npm · Tarball · package.json 
$ npm install gonzales-pe
SYNC missed versions from official npm registry.

Gonzales PE @dev

NPM version Build Status AppVeyor Build Status

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
{Object} options Options to pass to a `Node` constructor.
Returns
{Object} A new node.
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
{string} css A string to parse.
{Object=} options Optional. Additional options:
  • {string} syntax — any of the following: css, less, sass, scss. Default one is css.
  • {string} context — root node's type. For a list of available values see "Node types". Default one is stylesheet.
  • {number} tabSize — size of a tab character in spaces. Default one is 1.
Returns
{Object} Parse tree.
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
{string} type Node type we're looking for. For a list of available values see "Node types".
Returns
{boolean} true if a tree contains a child node of a given type, false otherwise.
Examples
if (parseTree.contains('space')) {
  doSomething();
}

parseTree.content

Returns
{string|Array} Node's content (child nodes or a string).

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
{string=} type Optional. A node type by which to filter child nodes before applying a callback function. For a list of available values see "Node types".
{Function} callback Function to call for every child node. Accepts following parameters:
  • {Object} — a child node;
  • {number} — index of the child node in node list;
  • {Object} — parent node (equals to parseTree).
Examples
parseTree.eachFor(function(childNode) {
  doSomething(childNode);
});

// Remove all child spaces.
parseTree.eachFor('space', function(spaceNode, i) {
  parseTree.removeChild(i);
});

parseTree.end

Returns
{Object} End position of the node. Contains following info:
  • {number} line — last symbol's line number (1-based index);
  • {number} column — last symbol's column number (1-based index).

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
{string=} type Optional. Node type to look for. For a list of available values see "Node types".
Returns
{?Object} A node.
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
{string=} type Optional. A node type by which to filter child nodes before applying a callback function. For a list of available values see "Node types".
{Function} callback Function to call for every child node. Accepts following parameters:
  • {Object} — a child node;
  • {number} — index of the child node in node list;
  • {Object} — parent node (equals to parseTree).
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
{number} index Index number of node which we're looking for.
Returns
{?Object} A node.
Examples
var node = parseTree.get(2);
doSomething(node);

parseTree.insert(index, node)

Description

Inserts a node to a given position in parseTree.

Parameters
{number} index Index of position where to insert the node.
{Object} node A node to insert.
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
{string} type A node type against which to check type of parseTree. For a list of available values see "Node types".
Returns
{boolean} true if types are equal, false otherwise.
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
{string=} type Optional. Node type to look for. For a list of available values see "Node types".
Returns
{?Object} A node.
Examples
let node = parseTree.last();
node.content = 'panda';

let node = parseTree.last('multilineComment');
node.content = 'panda';

parseTree.length

Returns
{number} Number of child nodes.

parseTree.removeChild(index)

Description

Removes a child node at a given position.

Parameters
{number} index Index of a child node we need to remove.
Returns
{Object} Removed node.
##### Examples 
// Swap nodes.
var node = parseTree.removeChild(1);
parseTree.insert(0, node);

parseTree.start

Returns
{Object} Start position of the node. Contains following info:
  • {number} line — first symbol's line number (1-based index);
  • {number} column — first symbol's column number (1-based index).

parseTree.syntax

Returns
{string} Syntax of original parsed string.

parseTree.toJson()

Description

Converts parse tree to JSON. Useful for printing.

Returns
{Object} Parse tree in JSON

parseTree.toString()

Description

Converts parse tree back to string according to original syntax.

Returns
{string} A compiled string.
Examples
let css = parseTree.toString();

parseTree.traverse(callback)

Description

Calls the function for every node in a tree including parseTree itself.

Parameters
{Function} callback Function to apply to every node. Accepts following parameters:
  • {Object} — a node to which we apply callback;
  • {number} — node's index number inside its parent;
  • {Object} — a node's parent;
  • {number} — node's nesting level relative to its parent.
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
{string} type Node type. For a list of available values please see "Node types".
{Function} callback Function to apply to every node of a given type. Accepts following parameters:
  • {Object} — a node to which we apply callback;
  • {number} — node's index number inside its parent;
  • {Object} — a node's parent.
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
{Array.string} types List of node types. For a list of available values please see "Node types".
{Function} callback Function to apply to every node of given types. Accepts following parameters:
  • {Object} — a node to which we apply callback;
  • {number} — node's index number inside its parent;
  • {Object} — a node's parent.
Examples
// Remove all comments and spaces.
let types = ['multilineComment', 'space'];
parseTree.traverseByTypes(types, function(node, index, parent) {
  parent.removeChild(index);
});

parseTree.type

Returns
{string} Node type. For a list of available values see "Node types".

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.

Current Tags

  • 3.2.2                                ...           dev (9 years ago)
  • 4.3.0                                ...           latest (5 years ago)
  • 3.2.5-dev2                                ...           tg (9 years ago)

69 Versions

  • 4.3.0                                ...           5 years ago
  • 4.2.4                                ...           6 years ago
  • 4.2.3                                ...           7 years ago
  • 4.2.2                                ...           7 years ago
  • 4.1.1                                ...           7 years ago
  • 4.0.3                                ...           8 years ago
  • 4.0.2                                ...           8 years ago
  • 4.0.1                                ...           8 years ago
  • 4.0.0                                ...           8 years ago
  • 3.4.7                                ...           8 years ago
  • 3.4.6                                ...           8 years ago
  • 3.4.5                                ...           8 years ago
  • 3.4.4                                ...           8 years ago
  • 3.4.3                                ...           8 years ago
  • 3.4.2                                ...           8 years ago
  • 3.4.1                                ...           8 years ago
  • 3.4.0                                ...           8 years ago
  • 3.3.6                                ...           8 years ago
  • 3.3.5                                ...           9 years ago
  • 3.3.4                                ...           9 years ago
  • 3.3.3                                ...           9 years ago
  • 3.3.2                                ...           9 years ago
  • 3.3.1                                ...           9 years ago
  • 3.2.7                                ...           9 years ago
  • 3.2.6                                ...           9 years ago
  • 3.2.5-dev2                                ...           9 years ago
  • 3.2.5-dev1                                ...           9 years ago
  • 3.2.5                                ...           9 years ago
  • 3.2.4                                ...           9 years ago
  • 3.2.3                                ...           9 years ago
  • 3.2.2                                ...           9 years ago
  • 3.2.1                                ...           9 years ago
  • 3.2.0                                ...           9 years ago
  • 3.1.1                                ...           9 years ago
  • 3.1.0                                ...           9 years ago
  • 3.0.3                                ...           9 years ago
  • 3.0.2                                ...           9 years ago
  • 3.0.1                                ...           9 years ago
  • 3.0.0                                ...           9 years ago
  • 3.0.0-beta                                ...           9 years ago
  • 3.0.0-31                                ...           10 years ago
  • 3.0.0-30                                ...           10 years ago
  • 3.0.0-29                                ...           10 years ago
  • 3.0.0-28                                ...           10 years ago
  • 3.0.0-27                                ...           10 years ago
  • 3.0.0-26                                ...           10 years ago
  • 3.0.0-16                                ...           10 years ago
  • 3.0.0-15                                ...           10 years ago
  • 3.0.0-14                                ...           10 years ago
  • 3.0.0-13                                ...           10 years ago
  • 3.0.0-12                                ...           10 years ago
  • 3.0.0-11                                ...           10 years ago
  • 3.0.0-10                                ...           10 years ago
  • 3.0.0-9                                ...           10 years ago
  • 3.0.0-8                                ...           10 years ago
  • 3.0.0-7                                ...           10 years ago
  • 3.0.0-6                                ...           10 years ago
  • 3.0.0-5                                ...           11 years ago
  • 3.0.0-4                                ...           11 years ago
  • 3.0.0-3                                ...           11 years ago
  • 3.0.0-2                                ...           11 years ago
  • 3.0.0-1                                ...           11 years ago
  • 2.0.2                                ...           11 years ago
  • 2.0.1                                ...           11 years ago
  • 2.0.0                                ...           11 years ago
  • 2.0.0-rc1                                ...           11 years ago
  • 2.0.0-rc0                                ...           11 years ago
  • 2.0.0-beta                                ...           11 years ago
  • 2.0.0-alpha                                ...           11 years ago
Maintainers (1)
tonyganch
Downloads
Total 0
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (1)
Dev Dependencies (7)
Dependents (9)

© 2010 - cnpmjs.org x YWFE | Home | YWFE