esprima-ast-utils
v0.0.7
Published
collection for AST query/manipulation/transformation
Downloads
2,230
Readme
esprima-ast-utils
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
: Pathdebug
: 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 returnfalse
to stop traversedepth
: (0) current depthrecursive
: (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:traverse_fn]) -> Array
traverse
and filter
given AST based on given callback
Parameters:
node
callback
traverse_fn
Returns:
Array
: Every match of thecallback
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:max_width] [, Boolean:display_code_in_tree])
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 displayedmax_width
: max tokens per linedisplay_code_in_tree
: when display the tree attach the code on the right
query
getFunction
(Object:node, String:fn_name) -> 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:fn_name) -> 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:fn_name) -> Boolean
shortcut
Parameters:
node
fn_name
Returns:
Boolean
hasVarDeclaration
(Object:node, String:var_name) -> Boolean
shortcut
Parameters:
node
var_name
Returns:
Boolean
isVarDeclared
(Object:node, String:var_name) -> 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 attachproperty
: Where attach, could be an array or an objectposition
: index if an array is used as target propertystr
: String is preferred if not possible remember that only Program can be attached, you may consider usingtoProgram
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 usingtoProgram
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 usingtoProgram
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 usingtoProgram
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 usingtoProgram
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 usingtoProgram
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 usingtoProgram
debug
: display $id, $parent and $code in console.log (enumerable=true)
Note: this is dangerous and powerful
transformations
setIdentifier
(Object:node, String:new_name)
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:dst_tree, 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:new_text)
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 [email protected]
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.