CSS Parser

Introduction

The ParserLib CSS parser is a CSS3 SAX-inspired parser written in JavaScript. It handles standard CSS syntax as well as validation (checking of property names and values) although it is not guaranteed to thoroughly validate all possible CSS properties.

Adding to your project

The CSS parser is built for a number of different JavaScript environments. The most recently released version of the parser can be found in the dist directory when you check out the repository; run npm run build to regenerate them from the latest sources.

Node.js

You can use the CSS parser in a Node.js script via the standard npm package manager as the parserlib package (npm install parserlib):

var parserlib = require("parserlib");

var parser = new parserlib.css.Parser();

Alternatively, you can copy a single file version of the parser from dist/node-parserlib.js to your own project, and use it as follows:

var parserlib = require("./node-parserlib");

Rhino

To use the CSS parser in a Rhino script, copy the file dist/parserlib.js to your project and then include it at the beginning:

load("parserlib.js");

HTML page

To use the CSS parser on an HTML page, you can either include the entire library on your page:

<script src="parserlib.js"></script>

Or include it as its component parts, the ParserLib core and the CSS parser:

<script src="parserlib-core.js"></script>
<script src="parserlib-css.js"></script>

Note that parsing large JavaScript files may cause the browser to become unresponsive. All three of these files are located in the dist directory.

Basic usage

You can create a new instance of the parser by using the following code:

var parser = new parserlib.css.Parser();

The constructor accepts an options object that specifies additional features the parser should use. The available options are:

• starHack - set to true to treat properties with a leading asterisk as if the asterisk wasn't there. Default is false.
• underscoreHack - set to true to treat properties with a leading underscore as if the underscore wasn't there. Default is false.
• ieFilters - set to true to accept IE < 8 style filter properties. Default is false.
• strict - set to true to disable error recovery and stop on the first syntax error. Default is false.

Here's an example with some options set:

var parser = new parserlib.css.Parser({ starHack: true, underscoreHack: true });

You can then parse a string of CSS code by passing into the parse() method:

parser.parse(someCSSText);

The parse() method throws an error if a non-recoverable syntax error occurs, otherwise it finishes silently. This method does not return a value nor does it build up an abstract syntax tree (AST) for you, it simply parses the CSS text and fires events at important moments along the parse.

Note: The parseStyleSheet() method is provided for compatibility with SAC-based APIs but does the exact same thing as parse().

Understanding syntax units

The CSS parser defines several types that inherit from parserlib.util.SyntaxUnit. These types are designed to give you easy access to all relevant parts of the CSS syntax.

Media Queries

The parserlib.css.MediaFeature type represents a specific media feature in a media query, such as (orientation: portrait) or (color). Essentially, this type of object represents anything enclosed in parentheses in a media query. Object of this type have the following properties:

• name - the name of the media feature such as "orientation"
• value - the value of the media feature (may be null)

The parserlib.css.MediaQuery type represents all parts of a media query. Each instance has the following properties:

• modifier - either "not" or "only"
• mediaType - the actual media type such as "print"
• features - an array of parserlib.css.MediaFeature objects

For example, consider the following media query:

only screen and (max-device-width: 768px) and (orientation: portrait)

A corresponding object would have the following values:

• modifier = "only"
• mediaType = "screen"
• features = array of (name="max-device-width", value="768px") and (name="orientation", value="portrait")

Properties

The parserlib.css.PropertyName type represents a property name. Each instance has the following properties:

• hack - if star or underscore hacks are allowed, either * or _ if present (null if not present or hacks are not allowed)

When star hacks are allowed, the text property becomes the actual property name, so *width has hack equal to * and text equal to "width". If no hacks are allowed, then *width causes a syntax error while _width has hack equal to null and text equal to _width.

The parserlib.css.PropertyValue type represents a property value. Since property values in CSS are complex, this type of object wraps the various parts into a single interface. Each instance has the following properties:

• parts - array of PropertyValuePart objects

The parts array always has at least one item.

The parserlib.css.PropertyValuePart type represents an individual part of a property value. Each instance has the following properties:

• type - the type of value part ("unknown", "dimension", "percentage", "integer", "number", "color", "uri", "string", "identifier" or "operator")

A part is considered any atomic piece of a property value not including white space. Consider the following:

font: 1em/1.5em "Times New Roman", Times, serif;

The PropertyName is "font" and the PropertyValue represents everything after the colon. The parts are "1em" (dimension), "/" (operator), "1.5em" (dimension), "Times New Roman" (string), "," (operator), "Times" (identifier), "," (operator), and "serif" (identifier).

Selectors

The parserlib.css.Selector type represents a single selector. Each instance has a parts property, which is an array of parserlib.css.SelectorPart objects, which represent atomic parts of the selector, and parserlib.css.Combinator objects, which represent combinators in the selector. Consider the following selector:

li.selected > a:hover

This selector has three parts: li.selected, >, and a:hover. The first part is a SelectorPart, the second is a Combinator, and the third is a SelectorPart. Each SelectorPart is made up of an optional element name followed by an ID, class, attribute condition, pseudo class, and/or pseudo element.

Each instance of parserlib.css.SelectorPart has an elementName property, which represents the element name as a parserlib.css.SelectorSubPart object or null if there isn't one, and a modifiers property, which is an array of parserlib.css.SelectorSubPart objects. Each SelectorSubPart object represents the smallest individual piece of a selector and has a type property indicating the type of subpart, "elementName", "class", "attribute", "pseudo", "id", "not". If the type is "not", then the args property contains an array of SelectorPart arguments that were passed to not().

Each instance of parserlib.css.Combinator has an additional type property that indicates the type of combinator: "descendant", "child", "sibling", or "adjacent-sibling".

Using events

The CSS parser fires events as it parses text. The events correspond to important parts of the parsing algorithm and are designed to provide developers with all of the information necessary to create lint checkers, ASTs, and other data structures.

For many events, the event object contains additional information. This additional information is most frequently in the form of a parserlib.util.SyntaxUnit object, which has three properties:

1. text - the string value
2. line - the line on which this token appeared
3. col - the column within the line at which this token appeared

The toString() method for these objects is overridden to be the same value as text, so that you can treat the object as a string for comparison and concatenation purposes.

You should assign your event handlers before calling the parse() method.

startstylesheet and endstylesheet events

The startstylesheet event fires just before parsing of the CSS text begins and the endstylesheet event fires just after all of the CSS text has been parsed. There is no additional information provided for these events. Example:

parser.addListener("startstylesheet", function() {
    console.log("Starting to parse stylesheet");
});

parser.addListener("endstylesheet", function() {
    console.log("Finished parsing stylesheet");
});

charset event

The charset event fires when the @charset directive is found in a stylesheet. Since @charset is required to appear first in a stylesheet, any other occurances cause a syntax error. The charset event provides an event object with a property called charset, which contains the name of the character set for the stylesheet. Example:

parser.addListener("charset", function(event) {
    console.log("Character set is " + event.charset);
});

namespace event

The namespace event fires when the @namespace directive is found in a stylesheet. The namespace event provides an event object with two properties: prefix, which is the namespace prefix, and uri, which is the namespace URI. Example:

parser.addListener("namespace", function(event) {
    console.log("Namespace with prefix=" + event.prefix + " and URI=" + event.uri);
});

import event

The import event fires when the @import directive is found in a stylesheet. The import event provides an event object with two properties: uri, which is the URI to import, and media, which is an array of media queries for which this URI applies. The media array contains zero or more parserlib.css.MediaQuery objects. Example:

parser.addListener("import", function(event) {
    console.log("Importing " + event.uri + " for media types [" + event.media + "]");
});

startfontface and endfontface events

The startfontface event fires when @font-face is encountered and the endfontface event fires just after the closing right brace (}) is encountered after @font-face. There is no additional information available on the event object. Example:

parser.addListener("startfontface", function(event) {
    console.log("Starting font face");
});

parser.addListener("endfontface", function(event) {
    console.log("Ending font face");
});

startpage and endpage events

The startpage event fires when @page is encountered and the endpage event fires just after the closing right brace (}) is encountered after @page. The event object has two properties: id, which is the page ID, and pseudo, which is the page pseudo class. Example:

parser.addListener("startpage", function(event) {
    console.log("Starting page with ID=" + event.id + " and pseudo=" + event.pseudo);
});

parser.addListener("endpage", function(event) {
    console.log("Ending page with ID=" + event.id + " and pseudo=" + event.pseudo);
});

startpagemargin and endpagemargin events

The startpagemargin event fires when a page margin directive (such as @top-left) is encountered and the endfontface event fires just after the closing right brace (}) is encountered after the page margin. The event object has a margin property, which contains the actual page margin encountered. Example:

parser.addListener("startpagemargin", function(event) {
    console.log("Starting page margin " + event.margin);
});

parser.addListener("endpagemargin", function(event) {
    console.log("Ending page marg