Skip to content

tonyganch/gonzales-pe

dev
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
bin
 
 
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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.