Skip to content

Latest commit

 

History

History
314 lines (254 loc) · 7.83 KB

parsing.md

File metadata and controls

314 lines (254 loc) · 7.83 KB
Raw

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.

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

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

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 will be null until positions option is set to true.

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 an 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": "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).

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.

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.

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