boreas v1.0.3

Boreas: A CSS Parser in TypeScript

Boreas is a CSS parser written in TypeScript (which compiles to JavaScript). It can be used both in node.js projects and in the browser (work in progress).

The project was done because we needed a reliable, robust CSS parser for our synchronized Web testing tool Ghostlab.

This project comprises

• a W3C compliant tokenizer (cf. the W3C CSS syntax module, http://www.w3.org/TR/css3-syntax),
• a parser that can serialize the AST to an output identical to the input (i.e., it preserves non-significant whitespaces and comments) and can parse "disabled" properties (i.e., properties that are commented out),
• AST classes allowing easy AST manipulations and AST construction,
• AST classes and tokens that contain information about their occurrence within the source code,
• AST traversal (tree walking).

Installation

To install Boreas, simply type

npm install boreas

Building

You only need to build Boreas if you want to change the code or if you got the package by cloning the git repository; i.e., if you're just planning to use it from the installed version, there is no need to build it.

Build Boreas by typing

npm install
grunt

on the command line. The modules will be compiled into the lib directory.

Usage

All examples here are written in plain JavaScript (as are the examples in the project).

Parsing

var Parser = require('boreas/lib/parser');

// some CSS source you want to parse
var src = '* { color: blue; }';

// parse the CSS
var ast = Parser.parse(src);

// do any AST manipulations/tree walkling...

// unparse the AST to stdout
console.log(ast.toString());

The parser offers a set of static convenience methods to parse different types of CSS structures:

All the parse functions take, apart from the mandatory CSS source as first argument, an optional "options" argument, which is a hash with the following (optional) properties:

Unparsing

Every AST class and tokens have a toString() method, which returns the a string identical to the corresponding part of the input.

AST Manipulations

Given an AST structure, the AST objects have methods by means of which the AST can be manipulated. E.g., RuleLists or SelectorLists or DeclarationLists have methods to insert or delete rules, selectors, or declarations, respectively.

Example:

var AST = require('../lib/ast');

// construct an AST structure by parsing or constructing it programmatically
var ast = ...;

// insert a new rule
ast.insertRule(new AST.Rule(
    new AST.SelectorList([
        new AST.Selector('h1')
    ]),
    new AST.DeclarationList([
        new AST.Declaration('color', 'blue')
    ])
));

// insert a new selector at the first position of the first rule
ast.getRules()[0].getSelectors().insertSelector(new AST.Selector('tr.odd'), 0);

// insert a new declaration (property)
ast.getRules()[0].getDeclarations().insertDeclaration(new AST.Declaration('border', '1px solid gray'));

AST Construction

All the AST classes have convenience constructors which allow easy programmatic construction of an AST structure.

Example:

var AST = require('../lib/ast');

var styleSheet = new AST.StyleSheet(
    new AST.RuleList([
        new AST.AtImport('import.css'),
        new AST.Rule(
            new AST.SelectorList([
                new AST.Selector('html'),
                new AST.Selector('h1 + p')
            ]),
            new AST.DeclarationList([
                new AST.Declaration('color', 'blue'),
                new AST.Declaration('border', '1px solid purple', true),
                new AST.Declaration('padding', '1em', false, true)
            ])
        ),
        new AST.AtMedia(
            'screen and (max-width: 1000px)',
            new AST.RuleList([
                new AST.SelectorList([ new AST.Selector('body') ]),
                new AST.DeclarationList([
                    new AST.Declaration('background-color', 'pink')
                ])
            ])
        )
    ])
);
console.log(styleSheet.toString());

AST Walking

Tokenizer and Parser Reference

Tokenizer

ITokenizerOptions is a hash which can have the following properties:

Parser

AST Class Reference

Types

INode

This is a TypeScript interface which all AST classes and the Token class implement. It has the following members:

Defined in types.ts.

IComponentValue

Extends INode.

ISourceRange

Defined in types.ts.

EToken

This enum defines the token types. The following enum values are defined (in accordance with the W3C specification):

Defined in tokenizer.ts.

IASTWalker

AST Classes

Token

This class represents a single token.

Defined in tokenizer.ts.

ASTNode

This is the base class for all AST classes described below. It implements INode.

All the AST classes are defined in ast.ts.

ASTNodeList\<U extends INode>

Extends ASTNode.

This is a generic class for encapsulating lists of AST nodes. It provides the base functionality for manipulating (replacing, inserting, deleting) its child nodes and a forEach method for iterating over its children.

StyleSheet

Extends ASTNode.

AbstractRule

Extends ASTNode.

This class is the base class for Rule and AtRule.

RuleList

Extends ASTNodeList<AbstractRule>.

Rule

A qualified rule.

Extends AbstractRule.

SelectorList

Extends ASTNodeList<Selector>.

Selector

Extends ComponentValueList.

SelectorCombinator

Extends ComponentValue.

SimpleSelector\<U extends INode>

Extends ASTNode, implements IComponentValue.

This class is the base class for the specialized selector classes described below.

TypeSelector

Extends SimpleSelector<Token>.

UniversalSelector

Extends SimpleSelector<Token>.

AttributeSelector

Extends SimpleSelector<BlockComponentValue>.

ClassSelector

Extends SimpleSelector<Token>.

IDSelector

Extends SimpleSelector<Token>.

PseudoClass

Extends ASTNode, implements IComponentValue.

DeclarationList

Extends ASTNodeList<Declaration>.

This class encapsulates a list of declaration, optionally enclosed in curly braces.

Declaration

Extends ASTNode.

This class encapsulates a declaration (e.g., a CSS propery).

Example:

h1 {
	color: red;
	border: 1px solid yellow !important;
	/* padding: 0; */
}

In this example, "color: red;" and "border: 1px solid yellow !important;" are represented by Declarations.

The parser also supports disabled declarations, i.e., declarations which are commented out like "/ padding: 0; /" in the example. I.e., the parser will also parse such declarations and set the "disabled" flag to true.

DeclarationValue

Extends ComponentValueList.

This class encapsulates the value part of a declaration (e.g., a property).

Example:

h1 {
	color: red;
	border: 1px solid yellow !important;
}

In this example, "red" and "1px solid yellow !important" are represented by DeclarationValues.

AtRule

Extends AtRule.

This class encapsulates a generic @rule and is the base class for all the specialized @rule classes described below.

AtCharset

Extends AtRule.

This class represents an @charset rule.

Example:

@charset 'utf-8';

AtCustomMedia

Extends AtRule.

This class represents an @custom-media rule.

Example:

AtDocument

Extends AtRule.

This class represents an @document rule.

Example:

@-moz-document url(http://localhost), domain(localhost), regexp("https:.*") {
	body {
		background: yellow;
	}
}

In this example, the CSS rules within the @document rule applies to

• the page "http://www.w3.org/",
• any page whose URL begins with "http://www.w3.org/Style/",
• any page whose URL's host is "mozilla.org" or ends with ".mozilla.org",
• any page whose URL starts with "https:".

AtFontFace

Extends AtRule.

This class represents an @font-face rule.

Example:

@font-face {
	font-family: MyHelvetica;
	src: local("Helvetica Neue Bold"),
	local("HelveticaNeue-Bold"),
	url(MgOpenModernaBold.ttf);
	font-weight: bold;
}

AtHost

Extends AtRule.

This class represents an @host rule.

Example:

AtImport

Extends AtRule.

This class represents an @import rule.

Example:

@import url('style1.css');
@import url('style2.css') screen and (min-width: 600px);

AtKeyframes

Extends AtRule.

This class represents an @keyframes rule.

Example:

@-webkit-keyframes moving-image {
	0%   { background-position: 0; }
	50%  { background-position: 100%; }
	100% { background-position: 0; }
}

@-moz-keyframes moving-image {
	0%   { background-position: 0; }
	50%  { background-position: 100%; }
	100% { background-position: 0; }
}

AtMedia

Extends AtRule.

This class represents an @media rule.

Example:

@media screen and (min-width: 800px) {
	body {
		padding: 1em
	}
}

AtNamespace

Extends AtRule.

This class represents an @namespace rule.

Example:

@namespace svg "http://www.w3.org/2000/svg";

In this example, "svg" is the (optional) namespace prefix, followed by the namespace URL.

AtPage

Extends AtRule.

This class represents an @page rule.

Example:

@page {
	margin: 5cm;
}

@page :first {
	margin-left: 0.5cm;
}

AtSupports

Extends AtRule.

This class represents an @supports rule.

Example:

@supports (display: flexbox) {
	body {
		display: flex;
	}
}

In this example, (display: flexbox) is the prelude part of the rule, which is followed by a list of rules enclosed in curly braces.

ComponentValue

Extends ASTNode.

This class encapsulates a single token. ComponentValues are used as generic AST nodes when a token isn't further specialized by the parser.

ComponentValueList

Extends ASTNodeList.

This class encapsulates a sequence of ComponentValues.

BlockComponentValue

Extends ComponentValueList.

This class encapsulates a generic block, i.e., a portion of code starting with a opening parenthesis/square bracket/curly brace and ending with a closing parenthesis/square bracket/curly brace.

FunctionComponentValue

Extends BlockComponentValue.

This class encapsulates a function invocation, e.g., rgb(10, 20, 30).

FunctionArgumentValue

Extends ComponentValueList.

This class represents an argument to a function, such as 10, , in rgb(10, 20, 30). Note that it also comprises the comma separator if there is one following the actual argument.

ImportantComponentValue

Extends ASTNode.

This class represents the !important part of a property value.

License

MIT

Copyright (C) by Vanamco AG