sl-esprima-ast-utils

collection for AST query/manipulation/transformation

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
sl-esprima-ast-utils
0.0.75 years ago5 years agoMinified + gzip package size for sl-esprima-ast-utils in KB

Readme

esprima-ast-utils Build Status
Node module to manipulate, transform, query and debug esprima ASTs.

Objective

When you edit esprima AST and go back to code with escodegen you lose too much information because primary you don't keep track of ranges, tokens, comments etc. esprima-ast-utils do this for you, so no escodegen is needed, you can edit the AST directly and code everything is in sync.

API

io

parse (String:str , Boolean:debug) -> Object
Parse given str
Parameters:
  • str

  • debug: display $id, $parent and $code in console.log (enumerable=true)

Returns:
  • Object

Note: location it's not supported, and won't sync with changes, range/rokens do.


parseWrap (String:str , Boolean:debug) -> Object
Wrap your code into a function and parse given str. Needed if your code contains a ReturnStatement at Program level.
Parameters:
  • str

  • debug: display $id, $parent and $code in console.log (enumerable=true)

Returns:
  • Object

Note: location it's not supported, and won't sync with changes, range/rokens do.


parseFile (String:file , Boolean:debug) -> Object
Parse given file
Parameters:
  • file: Path

  • debug: display $id, $parent and $code in console.log (enumerable=true)

Returns:
  • Object

Note: : NodeJS only


encode (Object:tree) -> String
Return tree.$code, just for API completeness.
Parameters:
  • tree

Returns:
  • String



walk

traverse (Object:node, Function:callback , Number:depth , Boolean:recursive)
traverse AST
Parameters:
  • node

  • callback: function(node, parent, property, index, depth)
You can return false to stop traverse
  • depth: (0) current depth

  • recursive: (true) recursively traverse



parentize (Object:root , Boolean:debug)
traverse AST and set $parent node
Parameters:
  • root

  • debug: display $parent in console.log (enumerable=true)



idze (Object:node , Boolean:debug)
traverse AST and set an unique $id to every node
Parameters:
  • node

  • debug: display $id in console.log (enumerable=true)



attachComments (Object:root)
Traverse the AST and add comments as nodes, so you can query them. Loop thought comments and find a proper place to inject (BlockStament or alike)
  • attach the comment to the before nearest children
  • if a children contains the comment it's considered invalid
  • push otherwise

Parameters:
  • root



filter (Object:node, Function:callback , Function:traversefn) -> Array
traverse and filter given AST based on given callback
Parameters:
  • node

  • callback

  • traverse_fn

Returns:
  • Array: Every match of the callback



getParent (Object:node, Function:callback) -> Object|NULL
Get parent node based on given callback, stops on true
Parameters:
  • node

  • callback

Returns:
  • Object|NULL



getRoot (Object:node) -> Object
get the root of the AST
Parameters:
  • node

Returns:
  • Object



clone (Object:node) -> Object
Recursive clone a node. Do no include "$" properties like $parent or $id If you want those, call parentize - idze after cloning
Parameters:
  • node

Returns:
  • Object



debug

debug_tree (Object:tree , Number:maxwidth , Boolean:displaycodeintree)
Show your tree in various ways to easy debug Big trees will be always a pain, so keep it small if possible
Parameters:
  • tree: Any node, if root tokens & source will be displayed

  • max_width: max tokens per line

  • display_code_in_tree: when display the tree attach the code on the right



query

getFunction (Object:node, String:fnname) -> Object|NULL
filter the AST and return the function with given name, null otherwise.
Parameters:
  • node

  • fn_name

Returns:
  • Object|NULL



getFunctionBlock (Object:node, String:fnname) -> Object|NULL
filter the AST and return the function > block with given name, null otherwise.
Parameters:
  • node

  • fn_name

Returns:
  • Object|NULL



isFunctionDeclared (Object:node, String:fnname) -> Boolean
shortcut
Parameters:
  • node

  • fn_name

Returns:
  • Boolean



hasVarDeclaration (Object:node, String:varname) -> Boolean
shortcut
Parameters:
  • node

  • var_name

Returns:
  • Boolean



isVarDeclared (Object:node, String:varname) -> Boolean
reverse from node to root and look for a Variable declaration
Parameters:
  • node

  • var_name

Returns:
  • Boolean

Note: It's not perfect because VariableDeclaration it's not hoisted


contains (Object:node, Object:subnode) -> Boolean
node constains subnode
Parameters:
  • node

  • subnode

Returns:
  • Boolean



hasBody (Object:node) -> Boolean
Has a body property, use to freely attach/detach
Parameters:
  • node

Returns:
  • Boolean



isComment (Object:node) -> Boolean
shortcut: Is a comment (Line or Block) and has text
Parameters:
  • node

Returns:
  • Boolean



getComment (Object:node, String:comment) -> Object
shortcut: search for a comment (trim it's content for maximum compatibility)
Parameters:
  • node

  • comment

Returns:
  • Object



getCode (Object:node) -> String
shortcut: Return node code
Parameters:
  • node

Returns:
  • String



getArgumentList (Object:node) -> Array
Return FunctionDeclaration arguments name as a list
Parameters:
  • node

Returns:
  • Array



getDefaultProperty (Object:node)
Parameters:
  • node



manipulations

attach (Object:node, String:property, Number|NULL:position, String|Object:str)
Attach Code/Program to given node.
Parameters:
  • node: node to attach

  • property: Where attach, could be an array or an object

  • position: index if an array is used as target property

  • str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram

Note: tokens are updated
Note: range is updated
Note: comments are not attached to root.comments (invalid-comments)


attachPunctuator (Object:tree, String:punctuator, Number:position) -> String
Attach a punctuator and keep the tree ranges sane. The Punctuator can be anything... be careful!
Parameters:
  • tree

  • punctuator

  • position

Returns:
  • String: detached code string

Note: The Punctuator is not parsed and could be assigned to nearest literal or alike.


detach (Object:node, String:property) -> String
Detach given node from it's parent
Parameters:
  • node

  • property

Returns:
  • String: detached code string

Note: node.$parent is set to null, remember to save it first if you need it.


attachAfter (Object:node, String|Object:str , String:property)
Attach after node, that means node.$parent.type is a BockStament
Parameters:
  • node

  • str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram

  • property: where to search node in the parent



attachBefore (Object:node, String|Object:str)
Attach before node, that means node.$parent.type is a BockStament
Parameters:
  • node

  • str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram



attachAfterComment (Object:node, String:comment, String|Object:str) -> Boolean
Shortcut: Search for given comment, and attachAfter
Parameters:
  • node

  • comment

  • str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram

Returns:
  • Boolean: success



replace (Object:node, String|Object:str)
Shortcut: detach/attach
Parameters:
  • node

  • str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram



replaceComment (Object:node, String:comment, String|Object:str)
Shortcut: Search for a comment and replace
Parameters:
  • node

  • comment

  • str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram



injectCode (Object:tree, Array:range, String|Object:str, Boolean:debug)
Inject code directly intro the given range. After the injection the code will be parsed again so original $id will be lost
Parameters:
  • tree

  • range

  • str: String is preferred if not possible remember that only Program can be attached, you may consider using toProgram

  • debug: display $id, $parent and $code in console.log (enumerable=true)

Note: this is dangerous and powerful


transformations

setIdentifier (Object:node, String:newname)
rename Identifier
Parameters:
  • node

  • new_name



renameProperty (Object:node, Object:replacements)
traverse and apply given replacements
Parameters:
  • node

  • replacements

Example:
renameProperty(node, {"old_var": "new_var", "much_older": "shinnig_new"})



renameVariable (Object:node, Object:replacements)
traverse and apply given replacements
Parameters:
  • node

  • replacements

Example:
renameVariable(node, {"old_var": "new_var", "much_older": "shinnig_new"})



renameFunction (Object:node, Object:replacements)
traverse and apply given replacements
Parameters:
  • node

  • replacements

Example:
renameFunction(node, {"old_var": "new_var", "much_older": "shinnig_new"})



toProgram (Object|Array:node)
Clone given node(s) and extract tokens & code from root to given you a Program-like attachable node
Parameters:
  • node: if array is provided will add all nodes to program.body



tokens

getToken (Object:tree, Number:start, Number:end) -> Object|NULL
Get token based on given range
Parameters:
  • tree

  • start

  • end

Returns:
  • Object|NULL



getTokens (Object:tree, Number:start, Number:end) -> Array|NULL
Get tokens in range
Parameters:
  • tree

  • start

  • end

Returns:
  • Array|NULL



pushTokens (Object:tree, Number:start, Number:amount)
Push tokens range from start
Parameters:
  • tree

  • start

  • amount

Note: Update nodes range


growTokens (Object:tree, Number:start, Number:end, Number:amount)
Grow tokens in given range
Parameters:
  • tree

  • start

  • end

  • amount

Note: Update nodes range


tokenAt (Object:tree, Number:start) -> Object
Get the first token
Parameters:
  • tree

  • start

Returns:
  • Object



addTokens (Object:dsttree, Object|Array:src, Number:start)
Add src tokens to dst since start (so keep the order)
Parameters:
  • dst_tree

  • src

  • start

Note: Remember to push src tokens before addTokens otherwise won't be synced


replaceCodeRange (Object:tree, Array:range, String:newtext)
Replace code range with given text.
Parameters:
  • tree

  • range

  • new_text



removeTokens (Object:tree, Number:start, Number:end)
Remove tokens in range and update ranges
Parameters:
  • tree

  • start

  • end

Note: Do not remove nodes.


LICENSE
(The MIT License)
Copyright (c) 2014 Luis Lafuente
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.