gonzales-pe

What is gonzales-pe?

The gonzales-pe npm package is a CSS parser that can parse CSS, SCSS, LESS, and other CSS-like syntaxes. It is useful for tasks such as linting, formatting, and transforming stylesheets.

What are gonzales-pe's main functionalities?

Parsing CSS

This feature allows you to parse CSS code into an Abstract Syntax Tree (AST). The code sample demonstrates how to parse a simple CSS string and convert it into a JSON representation of the AST.

const gonzales = require('gonzales-pe');
const ast = gonzales.parse('.class { color: red; }', { syntax: 'css' });
console.log(ast.toJson());

Parsing SCSS

This feature allows you to parse SCSS code into an AST. The code sample shows how to parse a simple SCSS string and convert it into a JSON representation of the AST.

const gonzales = require('gonzales-pe');
const ast = gonzales.parse('.class { color: red; }', { syntax: 'scss' });
console.log(ast.toJson());

Parsing LESS

This feature allows you to parse LESS code into an AST. The code sample demonstrates how to parse a simple LESS string and convert it into a JSON representation of the AST.

const gonzales = require('gonzales-pe');
const ast = gonzales.parse('.class { color: red; }', { syntax: 'less' });
console.log(ast.toJson());

Transforming AST

This feature allows you to traverse and transform the AST. The code sample shows how to change the color property from 'red' to 'blue' in a CSS AST.

const gonzales = require('gonzales-pe');
let ast = gonzales.parse('.class { color: red; }', { syntax: 'css' });
ast.traverse(function(node) {
  if (node.type === 'declaration' && node.content[0].content === 'color') {
    node.content[1].content = 'blue';
  }
});
console.log(ast.toString());

Other packages similar to gonzales-pe

postcss

PostCSS is a tool for transforming CSS with JavaScript plugins. It is more versatile and has a larger ecosystem of plugins compared to gonzales-pe. PostCSS can be used for linting, autoprefixing, and many other CSS transformations.

csstree

CSSTree is a tool for working with CSS, including parsing, generating, and analyzing CSS. It provides a more detailed and accurate AST compared to gonzales-pe and includes utilities for working with the AST.

rework

Rework is a plugin framework for CSS preprocessing. It allows you to transform CSS with plugins, similar to PostCSS. Rework is simpler and less feature-rich compared to PostCSS but can be easier to use for basic transformations.

README

API

gonzales.createNode(options)

Creates a new node.

Parameters:

• {{type: String, content: String|Array}} options

Returns:

• {Object} node

Example:

    var css = 'a {color: tomato}';
    var ast = gonzales.parse(css);
    var node = gonzales.createNode({ type: 'animal', content: 'panda' });
    ast.content.push(node);

gonzales.parse(css, options)

Parse CSS.

Parameters:

• {String} css
• {{syntax: String, rule: String}} options

Returns:

• {Object} ast.

Example:

    var css = 'a {color: tomato}';
    var ast = gonzales.parse(css);

Example:

    var less = 'a {$color: tomato}';
    var ast = gonzales.parse(less, {syntax: 'less'});

Example:

    var less = '$color: tomato';
    var ast = gonzales.parse(less, {syntax: 'less', rule: 'declaration'});

ast.contains(type)

Checks whether there is a child node of given type.

Parameters:

• {String} type

Returns:

• {Boolean}

Example:

    if (ast.contains('panda'))
        doSomething();

ast.content

ast.eachFor(type, callback)

ast.end

ast.first(type)

Returns the first child node of given type.

Parameters:

• {String=} type

Returns:

• {Node} node

Example:

    var node = ast.first();
    node.content = 'panda';

Example:

    var node = ast.first('commentML');
    node.content = 'panda';

ast.forEach(type, function)

Calls the function for every child node of given type.

Parameters:

• {String=} type
• {Function} function

Example:

    ast.forEach('commentML', function(node) {
        node.content = 'panda';
    });

ast.get(index)

ast.indexHasChanged

ast.insert(index, node)

ast.is(type)

Checks whether the node is of given type.

Parameters:

• {String} type

Returns:

• {Boolean}

Example:

    if (ast.is('s'))
        ast.content = '';

ast.last(type)

Returns the last child node of given type.

Parameters:

• {String=} type

Returns:

• {Node} node

Example:

    var node = ast.last()
    node.content = 'panda';

Example:

    var node = ast.last('commentML');
    node.content = 'panda';

ast.length

ast.remove(index)

ast.start

ast.syntax

ast.toJson()

ast.toString()

Converts AST to code.

Parameters:

• {String} syntax

Returns:

• {String} css

Example:

    var css = ast.toCSS('css');
    var less = ast.toCSS('less');

ast.traverse(function)

Calls the function for every node in a tree. Modifies the tree!

Parameters:

• {Function} function

Example:

    ast.map(function(node) {
        if (node.type === 'commentML') node.content = 'panda';
    });

ast.traverseByType(type, callback)

ast.traverseByTypes(types, callback)

ast.type

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 AST and expected string compiled back from AST 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.

Changelog

05.10.2015, version 3.0.0-beta

CLI

:star: Added --simple flag for printing a simplified tree structure.
:green_apple: CLI now prints parse tree to stdout.

API

:japanese_ogre: Parse tree is now represented as objects, not arrays.
:japanese_ogre: Renamed gonzales.srcToAST() to gonzales.parse(). See Readme.
:japanese_ogre: Renamed gonzales.astToSrc() to parseTree.toString(). See Readme.
:japanese_ogre: Renamed gonzales.astToString() to parseTree.toJson(). See Readme.
:star: Added information about column number to nodes.
:star: Added information about end position to nodes.
:green_apple: Made empty strings to be parsed as empty nodes.

Node types

:japanese_ogre: In Sass renamed interpolatedVariable to interpolation.
:japanese_ogre: Separated include and extend nodes.
:japanese_ogre: Replaced filter with declaration.
:japanese_ogre: Replaced braces with brackets and parentheses.
:japanese_ogre: Replaced atrulers with block.
:japanese_ogre: Renamed nthSelector to pseudoClass.
:japanese_ogre: Renamed atrules, atruler and atruleb to atrule.
:japanese_ogre: Renamed functionBody to arguments.
:japanese_ogre: Renamed functionExpression to expression.
:japanese_ogre: Renamed attrib to attributeSelector.
:japanese_ogre: Renamed attrselector to attributeMatch.
:japanese_ogre: Renamed commentSL to singlelineComment.
:japanese_ogre: Renamed commentML to multilineComment.
:japanese_ogre: Renamed declDelim to declarationDelimiter.
:japanese_ogre: Renamed delim to delimiter.
:japanese_ogre: Renamed propertyDelim to propertyDelimiter.
:japanese_ogre: Renamed pseudoc to pseudoClass.
:japanese_ogre: Renamed pseudoe to pseudoElement.
:japanese_ogre: Renamed s to space.
:japanese_ogre: Renamed shash to color.
:japanese_ogre: Renamed vhash to id.
:japanese_ogre: Removed atrulerq, unary and unknown.
:star: Added attributeFlags.
:star: Added attributeName.
:star: Added attributeValue.
:star: Added conditionalStatement.
:star: Added namePrefix.
:star: Added namespacePrefix.
:star: Added namespaceSeparator.
:star: Added typeSelector.

Parsing rules

:japanese_ogre: Spaces that separate two nodes are now put between those nodes in parse tree.
:star: Added support for extend nodes in Less.
:star: Added support for equality and inequality signs in Sass and SCSS.
:star: Added support for /deep/ combinator.
:star: Added support for !optional and !global in Sass and SCSS.
:green_apple: Fixed parsing of interpolations in Sass and SCSS.
:green_apple: Fixed parsing of arguments in Sass, SCSS and Less.
:green_apple: Fixed parsing of declaration delimiters in Sass.
:green_apple: Fixed the issue when pseudo-classes were parsed like declarations.
:green_apple: Fixed parsing of selectors on multiple lines in Sass.
:green_apple: Fixed parsing of percent sign as operator in SCSS.
:green_apple: Fixed parsing of pseudo-elements as selectors in Sass.

Misc

:star: Added Babel to build source files.
:star: Used mocha for tests.
:star: Added helper scripts.
:star: Added Travis config.
:rocket: Improved tests structure.
:rocket: Separated log and test scripts.
:rocket: Improved error messages.
:rocket: Removed benchmark tests.
:rocket: Moved source files from lib to src directory.
:rocket: Made package availbale for install from GitHub.