Skip to content

Latest commit

 

History

History
322 lines (259 loc) · 8.27 KB

parsing.md

File metadata and controls

322 lines (259 loc) · 8.27 KB

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 '@eslint/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.

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