Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@jbalsas/gonzales-pe

Package Overview
Dependencies
Maintainers
1
Versions
1
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@jbalsas/gonzales-pe

Gonzales Preprocessor Edition (fast CSS parser)

  • 4.3.0
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
8.4K
increased by17.44%
Maintainers
1
Weekly downloads
 
Created
Source

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}optionsOptions 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}cssA string to parse.
{Object=}optionsOptional. 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}indexIndex 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}indexIndex of position where to insert the node.
{Object}nodeA 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}indexIndex 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.

FAQs

Package last updated on 28 Sep 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc