# Parsing CSS into AST

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

## parse(source[, options])

Parses CSS into AST.

```js
import { parse } from 'css-tree';

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

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

Options (optional):

<!-- MarkdownTOC -->

- [context](#context)
- [atrule](#atrule)
- [positions](#positions)
- [onComment](#oncomment)
- [onToken](#ontoken)
- [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 this option is `false`. See structure of [`loc`](ast.md#loc) in AST format description.

### 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(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! }
// ------------------------------^
```

### onComment

Type: `function(value, loc)` or `null`  
Default: `null`

A handler to call for every comment in parsing source. Value is passing without surrounding `/*` and `*/`. [`loc`](ast.md#loc) will be `null` until `positions` option is set to `true`.

### onToken

Type: `function(type, start, end, index)` or `Array` or `null`  
Default: `null`

When a function, `onToken` is a handler to call for every token in the parsing source. The arguments are the numeric type of the token, the start offset, the end offset, and the token index. When an array, `onToken` is populated with objects containing the numeric type of the token (`type`), the start offset (`start`), and the end offset (`end`).

### filename

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

Filename of source. This value adds to [`loc`](ast.md#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`](ast.md#loc) property.

### line

Type: `number`  
Default: `1`

Start line number. Useful when parsing fragment of CSS to store correct positions in node's [`loc`](ast.md#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 an 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": "StyleSheet",
//     "children": [
//         {
//             "type": "Atrule",
//             "name": "example",
//             "prelude": {
//                 "type": "AtrulePrelude",
//                 "children": [
//                     { "type": "Number", "value": "1" },
//                     { "type": "Number", "value": "2" }
//                 ]
//             },
//             "block": null
//         }
//     ]
// }

csstree.parse('@example 1 2;', {
    parseAtrulePrelude: false
});
// {
//     "type": "StyleSheet",
//     "children": [
//         {
//             "type": "Atrule",
//             "name": "example",
//             "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": "StyleSheet",
//     "children": [
//         {
//             "type": "Rule",
//             "prelude": {
//                 "type": "SelectorList",
//                 "children": [
//                     {
//                         "type": "Selector",
//                         "children": [
//                             { "type": "ClassSelector", "name": "foo" }
//                         ]
//                     }
//                 ]
//             },
//             "block": {
//                 "type": "Block",
//                 "children": []
//             }
//         }
//     ]
// }

csstree.parse('.foo {}', {
    parseRulePrelude: false
});
// {
//     "type": "StyleSheet",
//     "children": [
//         {
//             "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": "Hash",
//                 "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": "Hash",
//                 "value": "aabbcc"
//             }
//         ]
//     }
// }
```