Skip to content

DOCS.md

Latest commit

 

History

History
437 lines (256 loc) · 8.25 KB

DOCS.md

File metadata and controls

437 lines (256 loc) · 8.25 KB

build-ast documentation

Usage

const Builder = require('@helpdotcom/build-ast')
const ast = Builder.ast

Builder()

Creates a new Builder object. The Builder object will be used to generate AST nodes. All of the methods on Builder.prototype can be chained together:

Builder()
  .use('strict')
  .module('Test')

The static methods on Builder will return a <Object>.

Builder().and(...args)

Takes a variable amount of arguments that should all be an <Object>. This joins two expressions using the && operator.

Builder().array(items)

Creates an array of items.

Builder().array([
  Builder.string('a')
, Builder.string('b')
])
// will be the ast for
['a', 'b']

Builder().assign(left, right, operator)

Assign the object-path <String> left to the right value.

  • left <String> A dot notated string that can represent a nested object
  • right Any The value
  • operator <String> The operator to use (=, *=, etc.)
Builder().assign('Event.VERSION', Builder.string('1.0.0'))
// will build the ast for
Event.VERSION = '1.0.0'

Builder().block(body)

Creates a new BlockStatement node and pushes it onto the current Builder's body.

Builder().build()

Returns the builder's body.

Builder().callFunction(name, args)

Calls a function with name with the args

  • name <String> The function name, a dot notated string that can represent a nested object
  • args <Array> Array of AST Nodes

Builder().declare(type, name, val)

Declare a variable.

Example:

Builder().declare('const', 'http', Builder.require('http'))
// will build the ast for
const http = require('http')

Builder().equals(left, right)

Builder().function(name, args, body)

Creates a <Function>

  • name <String> The function name
  • args <Array> An array of arguments. These should be strings.
  • body <Array> The function body. This will be wrapped in a BlockStatement
Builder().function('test', ['t'], [])
// will build the ast for
function test(t) {

}

Builder().if(test, block, alt)

Creates an IfStatement

  • test AST Node
  • block The consequent block. Should be wrapped in a BlockStatement
  • alt The alternate block. Should be wrapped in a BlockStatement
Builder().if(
  Builder.not(Builder.instanceOf(
    Builder.this(), Builder.id('Event')
  ))
, Builder.block(
    Builder.returns(Builder.new('Event', ['buffer']))
  )
)
// will build the ast for
if (!(this instanceof Event)) {
  return new Event(buffer)
}

Builder().ifNot(test, block, alt)

Shortcut for the following:

Builder().if(Builder.not(test), consequent, alternate)

Builder().instanceOf(left, right)

Creates an instanceof check.

  • left AST Node
  • right AST Node

Builder().module(name)

Adds a module.exports statement.

  • name <String> The function name to export

Builder().new(name, args)

Calls new on the name as a constructor.

  • name <String> The constructor name to call
  • args <Array> The arguments to pass to the constructor. In the event an item of args is a string, it will be returned as an Identifier.

Builder().not(expr)

Negates the expr by wrapping it in a UnaryExpression with ! as the operator.

Builder().notEquals(left, right)

Note: uses strict equality (!==)

Builder().number(n)

Creates a raw number.

  • n <Number> The number. Will be coerced to a number.

The following will both return a node for the same value:

Builder().number(3)
Builder().number('3')
// => 3

Builder().object(properties)

Creates an array of properties.

  • properties <Object> An object mapping properties to values
Builder().object({
  foo: Builder.number('42')
, bar: Builder.string('baz')
})
// will be the ast for
{ foo: 42, bar: 'baz' }

Builder().or(...args)

Takes a variable amount of arguments that should all be an <Object>. This joins two expressions using the || operator.

Builder().regex(re)

Creates a regular expression.

Must start with a slash (/).

Builder().require(str, prop)

Adds a require statement.

  • str <String> The module to require
  • prop <String> A dot notated string that can represent a nested object
// To get require('path').join
Builder().require('path', 'join')

// To get require('path').posix.join
Builder().require('path', 'posix.join')

Builder().reset()

Clears the Builder's body and resets the state.

Builder().returns(arg)

Creates a ReturnStatement.

  • arg AST Node
Builder().returns(ast.literal(true))
// will create the ast for
return true

Builder().string(str)

Creates a raw string.

  • str <String> The string. If not a string, it will be coerced.
Builder().string('Hi!')

Builder().ternary(test, block, alt)

Creates a ConditionalStatement

  • test AST Node
  • block The consequent block.
  • alt The alternate block.
Builder().ternary(
  Builder.objectPath('isActive')
, Builder.string('User is active')
, Builder.string('User is offline')
)
// will build the ast for
isActive ? 'User is active' : 'User is offline'

Builder().throws(arg)

Creates a ThrowStatement throwing the given arg.

Builder().use(str)

Adds a use directive ('use strict' or 'use asm').

Builder().use('strict')

Builder().program()

Marks the builder as a program.

Additional static methods

Builder.objectPath(str)

Returns a member expression for the given dot notated object path.

  • str <String> Dot notated string (ex. 'admin.id')

Note: To explicitly mark a segment as a computed property, prefix the segment with a ^. Ex: admin.^i would represent admin[i].

Builder.Error(msg)

Returns the representation of an <Error> object.

If msg is a string, it will be properly wrapped. Otherwise, it will be unmodified.

Builder.TypeError(msg)

Returns the representation of a <TypeError> object.

If msg is a string, it will be properly wrapped. Otherwise, it will be unmodified.

Builder.RangeError(msg)

Returns the representation of a <RangeError> object.

If msg is a string, it will be properly wrapped. Otherwise, it will be unmodified.

Builder.class()

Returns a prototype to create a new class.

Class.declaration(name, superClass)

Forces the class to be a ClassDeclaration.

Returns this

Class.expression(name, superClass)

Forces the class to be a ClassExpression.

Returns this

Class.ctor(args, body)

Define the constructor of the class.

  • args <Array> The function arguments
  • body <Array> The function body block

Returns this

Class.method(name, args, body, options)

Define a method of the class.

Returns this

Class.build()

Builds the class into either a ClassExpression or a ClassDeclaration.

Returns an <Object>