# css [![Build Status](https://travis-ci.org/reworkcss/css.svg?branch=master)](https://travis-ci.org/reworkcss/css)

CSS parser / stringifier.

## Installation

    $ npm install css

## Usage

```js
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

```js
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`](#stylesheet) node instead
of being thrown.

If you create any errors in plugins such as in
[rework](https://github.com/reworkcss/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:

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

Parse tree:

```json
{
  "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