Abstract Syntax Tree (AST) Data Structure
npm install asty
ASTy
====
Abstract Syntax Tree (AST) Data Structure




Installation
------------
``shell`
$ npm install asty
About
-----
ASTy is a Abstract Syntax Tree (AST) Data Structure library for JavaScript,
i.e., it provides a hierarchical data structure for holding the syntax
abstraction of an arbitrary formal language. It is usually used
in combination with a parser generator like PEG.js
(and then especially with its utility class PEGUtil)
to carry the results of the parsing step and to provide the vehicle
for further processing those results.
Usage
-----
ASTy provides a context (ASTYCtx below) for the creation of AST nodeASTYNode
( below). The tree of AST nodes is formed by linking childASTY
AST nodes into a parent AST node. The ASTy API, here assumed to be
exposed through the variable , provides the following methods (in
a notation somewhat resembling TypeScript type definitions):
- new ASTY(): ASTYCtx:ASTYNode
Create a new instance of the ASTy context.
It internally captures the prototype () of the AST nodes to be created.
- ASTYCtx#version(): { major: Number, minor: Number, micro: Number, date: Number }:YYYYMMDD
Return the ASTy version detals. The date is in numeric format .
- ASTYCtx#extend(object: { [methodName: String]: [methodFunc: Function] }): ASTYCtx:ASTYCtx#create
Extend the internal ASTYNode prototype with additional methods which are then available on each
ASTYNode instance when created with . This should be used by ASTy extension modules only.
- ASTYCtx#create(type: String, attrs?: {[name: String]: [value: Object]}, childs?: ASTY[]): ASTYNode:type
Create a new ASTYNode instance of and optionally already set attributes and add child nodes.
- ASTYCtx#isA(object: Object): Boolean:object
Check whether is an ASTYNode instance.
- static ASTYCtx::serialize(node: ASTYNode): String:
Serializes (formats) ASTy nodes to JSON string. Use this for exporting an AST.
- static ASTYCtx::unserialize(json: String): ASTYNode:
Unserializes (parses) JSON string to ASTy nodes. Use this for importing an AST.
- ASTYNode#create(type: String, attrs?: {[name: String]: [value: Object]}, childs?: ASTY[]): ASTYNode:type
Create a new ASTYNode instance of and optionally already set attributes and add child nodes.
- ASTYNode#merge(node: Node, takePos?: Boolean, attrMap?: {[from: String]: [to: (String|null)})): ASTYNode:null
Merge attributes, childs and optionally the position of a node.
The attributes can be renamed or skipped (if mapped onto ).
- ASTYNode#type(type: String): Boolean:ASTYNode#type(): String
:
Set or get type of node.
- ASTYNode#pos(line: Number, column: Number, offset: Number): ASTYNode:ASTYNode#pos(): { line: Number, column: Number, offset: Number }
:
Set or get the position for the node.
- ASTYNode#set(name: String, value: Object): ASTYNode:ASTYNode#set({ [String]: Object }): ASTYNode
:name
Set a single attribute to value or set multiple
attributes to their corresponding value.
- ASTYNode#unset(name: String): ASTYNode:ASTYNode#unset(names: String[]): ASTYNode
:name
Unset a single attribute or unset multiple attributes.
- ASTYNode#set({ [name: String]: [value: Object] }): ASTYNode:
Set multiple attributes, each consisting of name and value pairs.
- ASTYNode#get(name: String): Object:ASTYNode#get(names: String[]): Object[]
:name
Get value of a particular attribute ,names
or get array of values corresponding to each name in .
- ASTYNode#attrs(): String[]:
Get names of all node attributes.
- ASTYNode#nth(): Number:
Get position among sibling nodes in parent's child node list.
The positions start at 0.
- ASTYNode#ins(pos: Number, childs: ASTYNode[]): ASTYNode:pos
Add one or more childs to a node, at a fixed position . The array childspos
can either contain ASTYNode objects or even arrays of ASTYNode objects.
If is negative it counts from the end of child list,-1
with the position after the last existing child.
- ASTYNode#add(childs: ASTYNode[]): ASTYNode:childs
Add one or more childs to a node, at the end of the child list. The array
can either contain ASTYNode objects or even arrays of ASTYNode objects.
- ASTYNode#del(childs: ASTYNode[]): ASTYNode:
Delete one or more childs from a node.
- ASTYNode#childs(begin?: Number, end?: Number): ASTYNode[]:begin
Get a nodes list of all or some childs. The and end parametersArray::slice
are passed-through to . If the range from begin to end is
out of range, an empty array is returned.
- ASTYNode#child(pos: Number): ASTYNode:pos
Get a particular child node. If is out of range, null is returned.
- ASTYNode#parent(): ASTYNode:
Get parent node.
- ASTYNode#walk(callback: (node: ASTYNode, depth: Number, parent: ASTYNode, when: String) => Void, when?: String): ASTYNode:callback
Recursively walk the AST starting at this node (at depth 0). For
each visited node the function is called with thewhen
current node, the current node's tree depth, the current node's
parent node and the current walking situation. By default (and
if is either downward or both), the callback is calledwhen
in the downward phase, i.e., before(!) all child nodes will be
visited, and with set to downward. If when is set toupward
or both, the callback is called in the upward phase,when
i.e., after(!) all child nodes were visited, and with setupward
to .
- ASTYNode#dump(maxDepth?: Number, colorize?: (type: String, text: String) => String, unicode?: Boolean): String:maxDepth
Returns a textual dump of the AST starting at the current node. By
default is Infinity and this way the whole AST below themaxDepth
current node is dumped. If is 0 only the current node ismaxDepth
dumped. If is 1 the current node and all its direct childcolorize
nodes are dumped. The parameter is an optional callback function,text
intended to colorize the output fragments according to their type.type
The following strings are supported: tree, type, parenthesis, comma,key
, colon, value, position, bracket, line, slash, and column.unicode
If is set to false, ASCII substitution characters are used
for the tree structure.
- ASTYNode#serialize(): String:
Recursively serializes the AST node to JSON.
Use this for exporting.
Implementation Notice
---------------------
Although ASTy is written in ECMAScript 2018, it is transpiled to older
environments and this way runs in really all current (as of 2018)
JavaScript environments, of course.
Additionally, there are two transpilation results: first, there is a
compressed asty.browser.js for Browser environments. Second, there isasty.node.js` for Node.js environments.
an uncompressed
Alternatives
------------
A few decent alternatives to ASTy exist:
- UniST and UniST Builder
- estree
- AST-Types
License
-------
Copyright © 2014-2024 Dr. Ralf S. Engelschall (http://engelschall.com/)
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.