parsing.md

# Parsing CSS into AST

> NOTE: Currenly parser omits redundant separators, spaces and comments (except exclamation comments, i.e. `/*! comment */`) on AST build.

## parse(source[, options])

Parses CSS into AST.

```js
// simple parsing with no options
var ast = csstree.parse('.example { color: red }');

// parse with options
var ast = csstree.parse('.foo.bar', {
    context: 'selector',
    positions: true
});
```

Options (optional):

<!-- MarkdownTOC -->

- [context](#context)
- [atrule](#atrule)
- [positions](#positions)
- [onParseError](#onparseerror)
- [filename](#filename)
- [offset](#offset)
- [line](#line)
- [column](#column)
- [parseAtrulePrelude](#parseatruleprelude)
- [parseRulePrelude](#parseruleprelude)
- [parseValue](#parsevalue)
- [parseCustomProperty](#parsecustomproperty)

<!-- /MarkdownTOC -->

### context

Type: `string`  
Default: `'stylesheet'`

Defines what part of CSS is parsing.

Contexts:

- `stylesheet` (default) – regular stylesheet, should be suitable in most cases
- `atrule` – at-rule (e.g. `@media screen, print { ... }`)
- `atrulePrelude` – at-rule prelude (`screen, print` for example above)
- `mediaQueryList` – used to parse comma separated media query list
- `mediaQuery` – used to parse media query
- `rule` – rule (e.g. `.foo, .bar:hover { color: red; border: 1px solid black; }`)
- `selectorList` – selector group (`.foo, .bar:hover` for rule example)
- `selector` – selector (`.foo` or `.bar:hover` for rule example)
- `block` – block with curly braces (`{ color: red; border: 1px solid black; }` for rule example)
- `declarationList` – block content w/o curly braces (`color: red; border: 1px solid black;` for rule example), useful for parsing HTML `style` attribute value
- `declaration` – declaration (`color: red` or `border: 1px solid black` for rule example)
- `value` – declaration value (`red` or `1px solid black` for rule example)

### atrule

Type: `string` or `null`  
Default: `null`

Using for `atrulePrelude` context to apply atrule specific parse rules.

### positions

Type: `boolean`  
Default: `false`

Specify to store locations of node content in original source. Location is storing as `loc` field of nodes. `loc` property is always `null` when option is `false`. The structure of `loc`:

```
loc: {
    source: 'value of `filename` option or `<unknown>`',
    start: {
        offset: <number>,
        line: <number>,
        column: <number>
    },
    end: {
        offset: <number>,
        line: <number>,
        column: <number>
    }
}
```

### onParseError

Type: `function(error, fallbackNode)` or `null`  
Default: `null`

Parsing is tolerant by default, i.e. any text may to be parsed with no an raised exception. However, mistakes in CSS may make it imposible to parse some part, e.g. a selector or declaration. In that case bad content is wrapping into a `Raw` node and `onParseError` is invoking.

```js
csstree.parse('example { foo; bar: 1! }', {
    onParseError: function(error) {
        console.log(error.formattedMessage);
    }
});
// Parse error: Colon is expected
//     1 |example { foo; bar: 1! }
// --------------------^
// Parse error: Identifier is expected
//     1 |example { foo; bar: 1! }
// ------------------------------^
```

### filename

Type: `string`  
Default: `'<unknown>'`

Filename of source. This value adds to `loc` as `source` property when `positions` option is `true`. Using for source map generation.

### offset

Type: `number`  
Default: `0`

Start offset. Useful when parsing a fragment of CSS to store a correct positions for node's `loc` property.

### line

Type: `number`  
Default: `1`

Start line number. Useful when parsing fragment of CSS to store correct positions in node's `loc` property.

### column

Type: `number`  
Default: `1`

Start column number. Useful when parsing fragment of CSS to store correct positions in node's `loc` property.

### parseAtrulePrelude

Type: `boolean`  
Default: `true`

Defines to parse a at-rule prelude in details (represents as `AtruleExpresion`, `MediaQueryList` or `SelectorList` if any). Otherwise represents prelude as `Raw` node.

```js
csstree.parse('@example 1 2;');
// {
//     "type": "Atrule",
//     "prelude": {
//         "type": "AtrulePrelude",
//         "children": [
//             { "type": "Number", "value": "1" },
//             { "type": "WhiteSpace", "value": " " },
//             { "type": "Number", "value": "2" }
//         ]
//     },
//     "block": null
// }

csstree.parse('@example 1 2;', { parseAtrulePrelude: false });
// {
//     "type": "Atrule",
//     "prelude": {
//         "type": "Raw",
//         "value": "1 2"
//     },
//     "block": null
// }
```

### parseRulePrelude

Type: `boolean`  
Default: `true`

Defines to parse a rule prelude in details or left unparsed (represents as `Raw` node).

```js
csstree.parse('.foo {}');
// {
//     "type": "Rule",
//     "prelude": {
//         "type": "SelectorList",
//         "children": [
//             {
//                 "type": "Selector",
//                 "children": [
//                     { "type": "ClassSelector", "name": "foo" }
//                 ]
//             }
//         ]
//     },
//     "block": {
//         "type": "Block",
//         "children": []
//     }
// }

csstree.parse('.foo {}', { parseRulePrelude: false });
// {
//     "type": "Rule",
//     "prelude": {
//         "type": "Raw",
//         "value": ".foo"
//     },
//     "block": {
//         "type": "Block",
//         "children": []
//     }
// }
```

### parseValue

Type: `boolean`  
Default: `true`

Defines to parse a declaration value in details (represents as `Value`). Otherwise represents value as `Raw` node.

```js
csstree.parse('color: #aabbcc', { context: 'declaration' });
// {
//     "type": "Declaration",
//     "important": false,
//     "property": "color",
//     "value": {
//         "type": "Value",
//         "children": [
//             {
//                 "type": "HexColor",
//                 "value": "aabbcc"
//             }
//         ]
//     }
// }

csstree.parse('color: #aabbcc', { context: 'declaration', parseValue: false });
// {
//     "type": "Declaration",
//     "important": false,
//     "property": "color",
//     "value": {
//         "type": "Raw",
//         "value": " #aabbcc"
//     }
// }
```

### parseCustomProperty

Type: `boolean`  
Default: `false`

Defines to parse a custom property value and a `var()` fallback in details (represents as `Value`). Otherwise represents value as `Raw` node.

```js
csstree.parse('--custom: #aabbcc', { context: 'declaration' });
// {
//     "type": "Declaration",
//     "important": false,
//     "property": "--custom",
//     "value": {
//         "type": "Raw",
//         "value": " #aabbcc"
//     }
// }

csstree.parse('--custom: #aabbcc', { context: 'declaration', parseCustomProperty: true });
// {
//     "type": "Declaration",
//     "important": false,
//     "property": "--custom",
//     "value": {
//         "type": "Value",
//         "children": [
//             {
//                 "type": "HexColor",
//                 "value": "aabbcc"
//             }
//         ]
//     }
// }
```