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

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

:book: Usage

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

const parsed = calcAstParser.parse("calc(100%/3 - 21em - 21px)")
`

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

`json
{
"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

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

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

$3

Parse the given source code.

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

$3

Stringifies the given node.

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

$3

Get the resolved type of the given math expression.
> https://www.w3.org/TR/css3-values/#calc-type-checking

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

$3

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

`ts

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
`

$3

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

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