sfcode An Online Competing and Development Environment

css

CSS parser / stringifier.

# Installation

    $ npm install css

# Usage

var css = require('css');
var obj = css.parse('body { font-size: 12px; }', options);
css.stringify(obj, options);

# API

## css.parse(code, [options])

Accepts a CSS string and returns an AST `object`.

`options`:

- silent: silently fail on parse errors.
- source: the path to the file containing `css`. Makes errors and source maps more helpful, by letting them know where code comes from.

## css.stringify(object, [options])

Accepts an AST `object` (as `css.parse` produces) and returns a CSS string.

`options`:

- indent: the string used to indent the output. Defaults to two spaces.
- compress: omit comments and extraneous whitespace.
- sourcemap: return a sourcemap along with the CSS output. Using the `source` option of `css.parse` is strongly recommended when creating a source map. Specify ‘sourcemap: 'generator’` to return the SourceMapGenerator object instead of serializing the source map.
- inputSourcemaps: (enabled by default, specify `false` to disable) reads any source maps referenced by the input files when generating the output source map. When enabled, file system access may be required for reading the referenced source maps.

## Example

var ast = css.parse('body { font-size: 12px; }', { source: 'source.css' });
var css = css.stringify(ast);
var result = css.stringify(ast, { sourcemap: true });
result.code // string with CSS
result.map // source map object

## Errors

Errors thrown during parsing have the following properties:

- message: `String`. The full error message with the source position.
- reason: `String`. The error message without position.
- filename: `String` or `undefined`. The value of `options.source` if passed to `css.parse`. Otherwise `undefined`.
- line: `Integer`.
- column: `Integer`.
- source: `String`. The portion of code that couldn't be parsed.

When parsing with the `silent` option, errors are listed in the `parsingErrors` property of the `stylesheet` node instead of being thrown.

If you create any errors in plugins such as in rework, you must set the same properties for consistency.

# AST

Interactively explore the AST with http://iamdustan.com/reworkcss_ast_explorer/.

## Common properties

All nodes have the following properties.

### position

Information about the position in the source string that corresponds to the node.

`Object`:

- start: `Object`:
  - line: `Number`.
  - column: `Number`.
- end: `Object`:
  - line: `Number`.
  - column: `Number`.
- source: `String` or `undefined`. The value of `options.source` if passed to `css.parse`. Otherwise `undefined`.
- content: `String`. The full source string passed to `css.parse`.

The line and column numbers are 1-based: The first line is 1 and the first column of a line is 1 (not 0).

The `position` property lets you know from which source file the node comes from (if available), what that file contains, and what part of that file was parsed into the node.

### type

`String`. The possible values are the ones listed in the Types section below.

### parent

A reference to the parent node, or `null` if the node has no parent.

## Types

The available values of `node.type` are listed below, as well as the available properties of each node (other than the common properties listed above.)

### stylesheet

The root node returned by `css.parse`.

- stylesheet: `Object`:
  - rules: `Array` of nodes with the types `rule`, `comment` and any of the at-rule types.
  - parsingErrors: `Array` of `Error`s. Errors collected during parsing when option `silent` is true.

### rule

- selectors: `Array` of `String`s. The list of selectors of the rule, split on commas. Each selector is trimmed from whitespace and comments.
- declarations: `Array` of nodes with the types `declaration` and `comment`.

### declaration

- property: `String`. The property name, trimmed from whitespace and comments. May not be empty.
- value: `String`. The value of the property, trimmed from whitespace and comments. Empty values are allowed.

### comment

A rule-level or declaration-level comment. Comments inside selectors, properties and values etc. are lost.

- comment: `String`. The part between the starting `/*` and the ending `*/` of the comment, including whitespace.

### charset

The `@charset` at-rule.

- charset: `String`. The part following `@charset`.

### custom-media

The `@custom-media` at-rule.

- name: `String`. The `--`-prefixed name.
- media: `String`. The part following the name.

### document

The `@document` at-rule.

- document: `String`. The part following `@document`.
- vendor: `String` or `undefined`. The vendor prefix in `@document`, or `undefined` if there is none.
- rules: `Array` of nodes with the types `rule`, `comment` and any of the at-rule types.

### font-face

The `@font-face` at-rule.

- declarations: `Array` of nodes with the types `declaration` and `comment`.

### host

The `@host` at-rule.

- rules: `Array` of nodes with the types `rule`, `comment` and any of the at-rule types.

### import

The `@import` at-rule.

- import: `String`. The part following `@import`.

### keyframes

The `@keyframes` at-rule.

- name: `String`. The name of the keyframes rule.
- vendor: `String` or `undefined`. The vendor prefix in `@keyframes`, or `undefined` if there is none.
- keyframes: `Array` of nodes with the types `keyframe` and `comment`.

### keyframe

- values: `Array` of `String`s. The list of “selectors” of the keyframe rule, split on commas. Each “selector” is trimmed from whitespace.
- declarations: `Array` of nodes with the types `declaration` and `comment`.

### media

The `@media` at-rule.

- media: `String`. The part following `@media`.
- rules: `Array` of nodes with the types `rule`, `comment` and any of the at-rule types.

### namespace

The `@namespace` at-rule.

- namespace: `String`. The part following `@namespace`.

### page

The `@page` at-rule.

- selectors: `Array` of `String`s. The list of selectors of the rule, split on commas. Each selector is trimmed from whitespace and comments.
- declarations: `Array` of nodes with the types `declaration` and `comment`.

### supports

The `@supports` at-rule.

- supports: `String`. The part following `@supports`.
- rules: `Array` of nodes with the types `rule`, `comment` and any of the at-rule types.

## Example

CSS:

body {
background: #eee;
color: #888;
}

Parse tree:

{
"type": "stylesheet",
"stylesheet": {
"rules": [
{
"type": "rule",
"selectors": [
"body"
],
"declarations": [
{
"type": "declaration",
"property": "background",
"value": "#eee",
"position": {
"start": {
"line": 2,
"column": 3
},
"end": {
"line": 2,
"column": 19
}
}
},
{
"type": "declaration",
"property": "color",
"value": "#888",
"position": {
"start": {
"line": 3,
"column": 3
},
"end": {
"line": 3,
"column": 14
}
}
}
],
"position": {
"start": {
"line": 1,
"column": 1
},
"end": {
"line": 4,
"column": 2
}
}
}
]
}
}

# License

MIT