asciidisco.com/build/node_modules/css-tree/docs/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.

// 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):

• context
• atrule
• property
• positions
• tolerant
• onParseError
• filename
• offset
• line
• column
• parseAtrulePrelude
• parseRulePrelude
• parseValue
• parseCustomProperty

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.

property

Type: string or null
Default: null

Using for value context to apply property 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>
    }
}

tolerant

Type: boolean
Default: false

Enables tolerant mode, when parser does fail on invalid parts of input, but turns those parts into Raw nodes. onParseError option can be used to set a function to process errors.

onParseError

Type: function or null
Default: null

Function to process errors that occur on parsing. Make sense in tolerant mode only.

csstree.parse('example { foo; bar: 1! }', {
    tolerant: true,
    onParseError: function(error) {
        console.log(error.message);
    }
});
// Colon is expected
// Identifier is expected

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.

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).

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

csstree.parse('.foo {}', { parseRulePrelude: false });
// {
//     "type": "Rule",
//     "selector": {
//         "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.

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.

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"
//             }
//         ]
//     }
// }