postcss-calc-ast-parser

postcss-calc-ast-parser

Parse the calc() function defined in CSS and convert it to AST.

Why?

There are already various parsers of CSS and values ​​defined in CSS. However, these parser do not have the information of calc function AST. Also, it may not be possible to use it combination with SCSS or Less. postcss-calc-ast-parser is a parser specialized for the calc() (max, min and clamp) functions. We are aiming to work even when used in combination with SCSS or Less.

:cd: Installation

npm install --save-dev postcss-calc-ast-parser

:book: Usage

const calcAstParser = require("postcss-calc-ast-parser")

const parsed = calcAstParser.parse("calc(100%/3 - 2*1em - 2*1px)")

For example, parsing the value calc(100%/3 - 2*1em - 2*1px) will return the following:

{
    "type": "Root",
    "nodes": [
        {
            "type": "Function",
            "name": "calc",
            "nodes": [
                {
                    "type": "MathExpression",
                    "left": {
                        "type": "MathExpression",
                        "left": {
                            "type": "Percentage",
                            "value": 100,
                            "unit": "%"
                        },
                        "operator": "/",
                        "right": {
                            "type": "Number",
                            "value": 3
                        }
                    },
                    "operator": "-",
                    "right": {
                        "type": "MathExpression",
                        "left": {
                            "type": "MathExpression",
                            "left": {
                                "type": "Number",
                                "value": 2
                            },
                            "operator": "*",
                            "right": {
                                "type": "Length",
                                "value": 1,
                                "unit": "em"
                            }
                        },
                        "operator": "-",
                        "right": {
                            "type": "MathExpression",
                            "left": {
                                "type": "Number",
                                "value": 2
                            },
                            "operator": "*",
                            "right": {
                                "type": "Length",
                                "value": 1,
                                "unit": "px"
                            }
                        }
                    }
                }
            ]
        }
    ]
}

To know more about certain nodes in produced AST, please go AST docs.

API

const calcAstParser = require("postcss-calc-ast-parser")

const parsed = calcAstParser.parse("calc(100% - 20px)")

calcAstParser.parse(code, options)

Parse the given source code.

calcAstParser.parse(
    code: string,
    options?: {
        /**
         * Allow inline comments. default `true`
         */
        allowInlineCommnets: boolean
    }
): AST.Root

calcAstParser.stringify(node)

Stringifies the given node.

calcAstParser.stringify(node: AST.Node): string

calcAstParser.getResolvedType(expr)

Get the resolved type of the given math expression.

https://www.w3.org/TR/css3-values/#calc-type-checking

calcAstParser.getResolvedType(expr: AST.MathExpression):
    | "Number" | "Length" | "Angle" | "Time" | "Frequency" | "Resolution" | "Percentage" | "Flex"
    | "Unknown" // Is includes unknown values and SCSS interpolation etc.
    | "invalid" // Type can not be resolved.

calcAstParser.reduceExpression(expr)

Returns the calculated value of MathExpression. Returns null if it can not be resolved.

calcAstParser.reduceExpression(expr:
    | AST.MathExpression
    | AST.Root
    | AST.FunctionNode
    | AST.NumberValue
    | AST.LengthValue
    | AST.AngleValue
    | AST.TimeValue
    | AST.FrequencyValue
    | AST.ResolutionValue
    | AST.PercentageValue
    | AST.FlexValue
):
    | {
        value: number,
        type: "Number" | "Length" | "Angle" | "Time" | "Frequency" | "Resolution" | "Percentage" | "Flex",
        unit?: string
    }
    | null

parsed.walk(type, callback)

Walks each node of the given type inside parsed.nodes.

parsed.walk(type: string | RegExp, callback: (node) => boolean | void): boolean | void