Skip to content

Commit

Permalink
Merge branch 'master' of github.com:nzakas/parser-lib
Browse files Browse the repository at this point in the history
  • Loading branch information
@nzakas
nzakas committed Mar 9, 2013
2 parents 00c6859 + 5de9396 commit f549d14
Show file tree
Hide file tree
Showing 6 changed files with 339 additions and 333 deletions.
325 changes: 324 additions & 1 deletion README.md
View file
@@ -1,6 +1,329 @@

CSS Parser
==========

[![build status](https://secure.travis-ci.org/nzakas/parser-lib.png)](http://travis-ci.org/nzakas/parser-lib)
A collection of utilities, lexers, and parsers written in JavaScript.

* src - contains the JavaScript source code.
* build - contains the built files that are suitable for deployment.
* templates - files used as part of the build system.

Introduction
------------

The ParserLib CSS parser is a CSS3 SAX-inspired parser written in JavaScript. By default, the parser only deals with standard CSS syntax and doesn't do validation (checking of property names and values).

Adding to your project
----------------------

The CSS parser is intended for use primarily in command line JavaScript environments. The files you should use are in the `build` directory. Copy the files to an appropriate location for your usage.

### Node.js

To use the CSS parser in a Node.js script, include it at the beginning:

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

### Rhino

To use the CSS parser in a Rhino script, 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.

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
1. `line` - the line on which this token appeared
1. `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 style sheet");
});

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

### charset event

The `charset` event fires when the `@charset` directive is found in a style sheet. Since `@charset` is required to appear first in a style sheet, 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 style sheet. 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 style sheet. 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 style sheet. 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 `endfontface` 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 margin " + event.margin);
});

### startmedia and endmedia events

The `startmedia` event fires when `@media` is encountered and the `endmedia` event fires just after the closing right brace (`}`) is encountered after `@media`. The `event` object has one property, `media`, which is an array of `parserlib.css.MediaQuery` objects. Example:

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


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

### startkeyframes and endkeyframes events

The `startkeyframes` event fires when `@keyframes` (or any vendor prefixed version) is encountered and the `endkeyframes` event fires just after the closing right brace (`}`) is encountered after `@keyframes`. The `event` object has one property, `name`, which is the name of the animation. Example:

parser.addListener("startkeyframes", function(event){
console.log("Starting animation definition " + event.name);
});


parser.addListener("endkeyframes", function(event){
console.log("Ending animation definition " + event.name);
});

### startrule and endrule events

The `startrule` event fires just after all selectors on a rule have been parsed and the `endrule` event fires just after the closing right brace (`}`) is encountered for the rule. The `event` object has one additional property, `selectors`, which is an array of `parserlib.css.Selector` objects. Example:

parser.addListener("startrule", function(event){
console.log("Starting rule with " + event.selectors.length + " selector(s)");

for (var i=0,len=event.selectors.length; i < len; i++){
var selector = event.selectors[i];

console.log(" Selector #1 (" + selector.line + "," + selector.col + ")");

for (var j=0,count=selector.parts.length; j < count; j++){
console.log(" Unit #" + (j+1));

if (selector.parts[j] instanceof parserlib.css.SelectorPart){
console.log(" Element name: " + selector.parts[j].elementName);

for (var k=0; k < selector.parts[j].modifiers.length; k++){
console.log(" Modifier: " + selector.parts[j].modifiers[k]);
}
} else{
console.log(" Combinator: " + selector.parts[j]);
}


}


}

});

parser.addListener("endrule", function(event){
console.log("Ending rule with selectors [" + event.selectors + "]");
});


### property event

The `property` event fires whenever a CSS property (`name:value`) is encountered, which may be inside of a rule, a media block, a page block, etc. The `event` object has three additional properties: `property`, which is the name of the property as a `parserlib.css.PropertyName` object, `value`, which is an instance of `parserlib.css.PropertyValue`(both types inherit from `parserlib.util.SyntaxUnit`), and `important`, which is a Boolean value indicating if the property is flagged with `!important`. Example:

parser.addListener("property", function(event){
console.log("Property '" + event.property + "' has a value of '" + event.value + "' and " + (event.important ? "is" : "isn't") + " important. (" + event.property.line + "," + event.property.col + ")");
});

### error event

The `error` event fires whenever a recoverable error occurs during parsing. When in strict mode, this event does not fire. The `event` object contains three additional properties: `message`, which is the error message, `line`, which is the line on which the error occurred, and `col`, which is the column on that line in which the error occurred. Example:

parser.addListener("error", function(event){
console.log("Parse error: " + event.message + " (" + event.line + "," + event.col + ")", "error");
});

Error recovery
--------------

The CSS parser's goal is to be on-par with error recovery of CSS parsers in browsers. To that end, the following error recovery mechanisms are in place:

* **Properties** - a syntactically incorrect property definition will be skipped over completely. For instance, the second property below is dropped:

a:hover {
color: red;
font:: Helvetica; /*dropped!*/
text-decoration: underline;
}

* **Selectors** - if there's a syntax error in *any* selector, the entire rule is skipped over. For instance, the following rule is completely skipped:

a:hover, foo ... bar {
color: red;
font: Helvetica;
text-decoration: underline;
}

* **@ Rules** - there are certain @ rules that are only valid in certain contexts. The parser will skip over `@charset`, `@namespace`, and `@import` if they're found anywhere other than the beginning of the input.

* **Unknown @ Rules** - any @ rules that isn't recognized is automatically skipped, meaning the entire block after it is not parsed.

0 comments on commit f549d14

Please sign in to comment.