National Public Mania

    esprima-ast-utils

    0.0.7 • Public • Published

    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:traverse_fn]) -> 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: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 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: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 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: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 llafuente@noboxout.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.

    Install

    npm i esprima-ast-utils

    DownloadsWeekly Downloads

    1,285

    Version

    0.0.7

    License

    MIT

    Last publish

    Collaborators

    • jan
    • llafuente