@swagger-api/apidom-ast

@swagger-api/apidom-ast

@swagger-api/apidom-ast contains tools necessary for parsing stage of ApiDOM, specifically for syntactic analysis. Syntactic analysis will take a stream of tokens and turn it into an AST representation. Using the information in the tokens, this phase will reformat them as an AST which represents the structure of input string in a way that makes it easier to work with.

@swagger-api/apidom-ast currently contains AST nodes for JSON and YAML 1.2 formats.

Installation

You can install this package via npm CLI by running the following command:

 $ npm install @swagger-api/apidom-ast

Base AST Nodes

Base AST nodes are nodes that are supplementary to any specific AST nodes. Having standardized AST of various formats (JSON/YAML) allows us to have common syntactic analysis or transformation algorithms. These nodes includes Error, Literal, Position, etc...

Along with base nodes there are predicates that can assert on these nodes.

JSON AST Nodes

Convenient for low lever CST parsers that don't come with it's onw AST nodes. You can find list of JSON AST nodes in this directory.

YAML AST Nodes

Convenient for low lever CST parsers that don't come with it's onw AST nodes. You can find list of YAML AST nodes in this directory. As YAML is very complex format, along with nodes we also expose implementation of YAML Failsafe and JSON schemas along with formatters for canonical block scalars.

Traversal

@swagger-api/apidom-ast comes with its own traversal algorithm convenient for traversing CST or AST.

visit

visit will walk through an CST/AST using a depth first traversal, calling the visitor's enter function at each node in the traversal, and calling the leave function after visiting that node and all of its child nodes.

By returning different values from the enter and leave functions, the behavior of the visitor can be altered, including skipping over a sub-tree of the Node (by returning false), editing the Node Tree by returning a value or null to remove the value, or to stop the whole traversal by returning BREAK.

When using visit to edit an Node Tree, the original Node Tree will not be modified, and a new version of the Node Tree with the changes applied will be returned from the visit function.

import { visit } from '@swagger-api/apidom-ast';

const tree = {
    type: 'root',
    children: [
      {
          type: 'child',
          value: 'this is child node',
          children: [],
      },
    ],
};

const keyMap = {
    root: ['children'],
};

const visitor = {
    child(node) {
        console.dir(node.value); // => 'this is child node'
    },
};

const newTree = visit(tree, visitor, { keyMap }); // => tree{...}

Notice how we used 3rd parameter to visit function. Actually it can consume number of configuration options which can change its behavior.

Configuration option	Type	Default	Description
keyMap	Object	null	Defines how nodes map to it's children.
state	Object	{}	Additional state that is provided to the visitor. State is merged inti visitor object in following manner: Object.assign(visitor, state)
breakSymbol	Object	{}	Defines a symbol that can break the traversal. Symbol is compared by strict equality (===).
visitFnGetter	Function	getVisitFn	Function that extract appropriate method from the visitor given specific Node type.
nodeTypeGetter	Function	getNodeType	Node type extractor function.
nodePredicate	Function	isNode	Predicate that checks if particular Node can be really considered a Node.
detectCycles	Boolean	true	If the structure that needs to be traversed is represented as directed cyclic graph, visit will skip Nodes that have already been traversed to avoid infinite recursion.

Changelog

0.81.0 (2023-10-30)

Features

• add OpenAPI 2.0 JSON parser adapter (#3333) (17d4ee1), closes #3099
• add OpenAPI 2.0 YAML 1.2 parser adapter (#3335) (62b5b07), closes #3098