jade

<!DOCTYPE html> <html> <head> <title>nodes.coffee</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div id="container"> <div id="background"></div> <div id="jump_to"> Jump To … <div id="jump_wrapper"> <div id="jump_page"> <a class="source" href="browser.html"> browser.coffee </a> <a class="source" href="cake.html"> cake.coffee </a> <a class="source" href="coffee-script.html"> coffee-script.coffee </a> <a class="source" href="command.html"> command.coffee </a> <a class="source" href="grammar.html"> grammar.coffee </a> <a class="source" href="helpers.html"> helpers.coffee </a> <a class="source" href="index.html"> index.coffee </a> <a class="source" href="lexer.html"> lexer.coffee </a> <a class="source" href="nodes.html"> nodes.coffee </a> <a class="source" href="optparse.html"> optparse.coffee </a> <a class="source" href="repl.html"> repl.coffee </a> <a class="source" href="rewriter.html"> rewriter.coffee </a> <a class="source" href="scope.html"> scope.coffee </a> </div> </div> </div> <table cellpadding="0" cellspacing="0"> <thead> <tr> <th class="docs"> <h1> nodes.coffee </h1> </th> <th class="code"> </th> </tr> </thead> <tbody> <tr id="section-1"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-1">#</a> </div> <code>nodes.coffee</code> contains all of the node classes for the syntax tree. Most nodes are created as the result of actions in the <a href="grammar.html">grammar</a>, but some are created by other nodes as a method of code generation. To convert the syntax tree into a string of JavaScript code, call <code>compile()</code> on the root. </td> <td class="code"> <div class="highlight"><pre>{Scope} = require './scope'</pre></div> </td> </tr> <tr id="section-2"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-2">#</a> </div> Import the helpers we plan to use. </td> <td class="code"> <div class="highlight"><pre>{compact, flatten, merge, del, include, indexOf, starts, ends} = require('./helpers').helpers</pre></div> </td> </tr> <tr id="section-3"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-3">#</a> </div> <h3>BaseNode</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-4"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-4">#</a> </div> The BaseNode is the abstract base class for all nodes in the syntax tree. Each subclass implements the <code>compileNode</code> method, which performs the code generation for that node. To compile a node to JavaScript, call <code>compile</code> on it, which wraps <code>compileNode</code> in some generic extra smarts, to know when the generated code needs to be wrapped up in a closure. An options hash is passed and cloned throughout, containing information about the environment from higher in the tree (such as if a returned value is being requested by the surrounding function), information about the current scope, and indentation level. </td> <td class="code"> <div class="highlight"><pre>exports.BaseNode = class BaseNode constructor: -> @tags = {}</pre></div> </td> </tr> <tr id="section-5"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-5">#</a> </div> Common logic for determining whether to wrap this node in a closure before compiling it, or to compile directly. We need to wrap if this node is a statement, and it's not a pureStatement, and we're not at the top level of a block (which would be unnecessary), and we haven't already been asked to return the result (because statements know how to return results). If a Node is topSensitive, that means that it needs to compile differently depending on whether it's being used as part of a larger expression, or is a top-level statement within the function body. </td> <td class="code"> <div class="highlight"><pre> compile: (o) -> @options = merge o or {} @tab = o.indent del @options, 'chainRoot' unless this instanceof AccessorNode or this instanceof IndexNode top = if @topSensitive() then @options.top else del @options, 'top' closure = @isStatement(o) and not @isPureStatement() and not top and not @options.asStatement and this not instanceof CommentNode and not @containsPureStatement() o.scope.startLevel() if not o.keepLevel code = if closure then @compileClosure(@options) else @compileNode(@options) o.scope.endLevel() if not o.keepLevel code</pre></div> </td> </tr> <tr id="section-6"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-6">#</a> </div> Statements converted into expressions via closure-wrapping share a scope object with their parent closure, to preserve the expected lexical scope. </td> <td class="code"> <div class="highlight"><pre> compileClosure: (o) -> @tab = o.indent o.sharedScope = o.scope ClosureNode.wrap(this).compile o</pre></div> </td> </tr> <tr id="section-7"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-7">#</a> </div> If the code generation wishes to use the result of a complex expression in multiple places, ensure that the expression is only ever evaluated once, by assigning it to a temporary variable. </td> <td class="code"> <div class="highlight"><pre> compileReference: (o, options) -> options or= {} pair = if not (@containsType(CallNode) or (this instanceof ValueNode and (not (@base instanceof LiteralNode) or @hasProperties()))) [this, this] else if this instanceof ValueNode and options.assignment this.cacheIndexes(o) else reference = literal o.scope.freeVariable 'ref' compiled = new AssignNode reference, this [compiled, reference] return [pair[0].compile(o), pair[1].compile(o)] if options.precompile pair</pre></div> </td> </tr> <tr id="section-8"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-8">#</a> </div> Convenience method to grab the current indentation level, plus tabbing in. </td> <td class="code"> <div class="highlight"><pre> idt: (tabs) -> idt = @tab or '' num = (tabs or 0) + 1 idt += TAB while num -= 1 idt</pre></div> </td> </tr> <tr id="section-9"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-9">#</a> </div> Construct a node that returns the current node's result. Note that this is overridden for smarter behavior for many statement nodes (eg IfNode, ForNode)... </td> <td class="code"> <div class="highlight"><pre> makeReturn: -> new ReturnNode this</pre></div> </td> </tr> <tr id="section-10"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-10">#</a> </div> Does this node, or any of its children, contain a node of a certain kind? Recursively traverses down the children of the nodes, yielding to a block and returning true when the block finds a match. <code>contains</code> does not cross scope boundaries. </td> <td class="code"> <div class="highlight"><pre> contains: (block) -> contains = false @traverseChildren false, (node) -> if block(node) contains = true return false contains</pre></div> </td> </tr> <tr id="section-11"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-11">#</a> </div> Is this node of a certain type, or does it contain the type? </td> <td class="code"> <div class="highlight"><pre> containsType: (type) -> this instanceof type or @contains (n) -> n instanceof type</pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-12">#</a> </div> Convenience for the most common use of contains. Does the node contain a pure statement? </td> <td class="code"> <div class="highlight"><pre> containsPureStatement: -> @isPureStatement() or @contains (n) -> n.isPureStatement and n.isPureStatement()</pre></div> </td> </tr> <tr id="section-13"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-13">#</a> </div> Perform an in-order traversal of the AST. Crosses scope boundaries. </td> <td class="code"> <div class="highlight"><pre> traverse: (block) -> @traverseChildren true, block</pre></div> </td> </tr> <tr id="section-14"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-14">#</a> </div> <code>toString</code> representation of the node, for inspecting the parse tree. This is what <code>coffee --nodes</code> prints out. </td> <td class="code"> <div class="highlight"><pre> toString: (idt, override) -> idt or= '' children = (child.toString idt + TAB for child in @collectChildren()).join('') '\n' + idt + (override or @class) + children eachChild: (func) -> return unless @children for attr in @children when this[attr] for child in flatten [this[attr]] return if func(child) is false collectChildren: -> nodes = [] @eachChild (node) -> nodes.push node nodes traverseChildren: (crossScope, func) -> @eachChild (child) -> func.apply(this, arguments) child.traverseChildren(crossScope, func) if child instanceof BaseNode</pre></div> </td> </tr> <tr id="section-15"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-15">#</a> </div> Default implementations of the common node properties and methods. Nodes will override these with custom logic, if needed. </td> <td class="code"> <div class="highlight"><pre> class: 'BaseNode' children: [] unwrap : -> this isStatement : -> no isPureStatement : -> no topSensitive : -> no</pre></div> </td> </tr> <tr id="section-16"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-16">#</a> </div> <h3>Expressions</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-17"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-17">#</a> </div> The expressions body is the list of expressions that forms the body of an indented block of code -- the implementation of a function, a clause in an <code>if</code>, <code>switch</code>, or <code>try</code>, and so on... </td> <td class="code"> <div class="highlight"><pre>exports.Expressions = class Expressions extends BaseNode class: 'Expressions' children: ['expressions'] isStatement: -> yes constructor: (nodes) -> super() @expressions = compact flatten nodes or []</pre></div> </td> </tr> <tr id="section-18"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-18">#</a> </div> Tack an expression on to the end of this expression list. </td> <td class="code"> <div class="highlight"><pre> push: (node) -> @expressions.push(node) this</pre></div> </td> </tr> <tr id="section-19"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-19">#</a> </div> Add an expression at the beginning of this expression list. </td> <td class="code"> <div class="highlight"><pre> unshift: (node) -> @expressions.unshift(node) this</pre></div> </td> </tr> <tr id="section-20"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-20">#</a> </div> If this Expressions consists of just a single node, unwrap it by pulling it back out. </td> <td class="code"> <div class="highlight"><pre> unwrap: -> if @expressions.length is 1 then @expressions[0] else this</pre></div> </td> </tr> <tr id="section-21"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-21">#</a> </div> Is this an empty block of code? </td> <td class="code"> <div class="highlight"><pre> empty: -> @expressions.length is 0</pre></div> </td> </tr> <tr id="section-22"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-22">#</a> </div> An Expressions node does not return its entire body, rather it ensures that the final expression is returned. </td> <td class="code"> <div class="highlight"><pre> makeReturn: -> idx = @expressions.length - 1 last = @expressions[idx] last = @expressions[idx -= 1] if last instanceof CommentNode return this if not last or last instanceof ReturnNode @expressions[idx] = last.makeReturn() this</pre></div> </td> </tr> <tr id="section-23"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-23">#</a> </div> An Expressions is the only node that can serve as the root. </td> <td class="code"> <div class="highlight"><pre> compile: (o) -> o or= {} if o.scope then super(o) else @compileRoot(o) compileNode: (o) -> (@compileExpression(node, merge(o)) for node in @expressions).join("\n")</pre></div> </td> </tr> <tr id="section-24"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-24">#</a> </div> If we happen to be the top-level Expressions, wrap everything in a safety closure, unless requested not to. It would be better not to generate them in the first place, but for now, clean up obvious double-parentheses. </td> <td class="code"> <div class="highlight"><pre> compileRoot: (o) -> o.indent = @tab = if o.noWrap then '' else TAB o.scope = new Scope(null, this, null) code = @compileWithDeclarations(o) code = code.replace(TRAILING_WHITESPACE, '') if o.noWrap then code else "(function() {\n#{code}\n}).call(this);\n"</pre></div> </td> </tr> <tr id="section-25"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-25">#</a> </div> Compile the expressions body for the contents of a function, with declarations of all inner variables pushed up to the top. </td> <td class="code"> <div class="highlight"><pre> compileWithDeclarations: (o) -> code = @compileNode(o) code = "#{@tab}var #{o.scope.compiledAssignments()};\n#{code}" if o.scope.hasAssignments(this) code = "#{@tab}var #{o.scope.compiledDeclarations()};\n#{code}" if not o.globals and o.scope.hasDeclarations(this) code</pre></div> </td> </tr> <tr id="section-26"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-26">#</a> </div> Compiles a single expression within the expressions body. If we need to return the result, and it's an expression, simply return it. If it's a statement, ask the statement to do so. </td> <td class="code"> <div class="highlight"><pre> compileExpression: (node, o) -> @tab = o.indent compiledNode = node.compile merge o, top: true if node.isStatement(o) then compiledNode else "#{@idt()}#{compiledNode};"</pre></div> </td> </tr> <tr id="section-27"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-27">#</a> </div> Wrap up the given nodes as an Expressions, unless it already happens to be one. </td> <td class="code"> <div class="highlight"><pre>Expressions.wrap = (nodes) -> return nodes[0] if nodes.length is 1 and nodes[0] instanceof Expressions new Expressions(nodes)</pre></div> </td> </tr> <tr id="section-28"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-28">#</a> </div> <h3>LiteralNode</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-29"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-29">#</a> </div> Literals are static values that can be passed through directly into JavaScript without translation, such as: strings, numbers, <code>true</code>, <code>false</code>, <code>null</code>... </td> <td class="code"> <div class="highlight"><pre>exports.LiteralNode = class LiteralNode extends BaseNode class: 'LiteralNode' constructor: (@value) -> super() makeReturn: -> if @isStatement() then this else super()</pre></div> </td> </tr> <tr id="section-30"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-30">#</a> </div> Break and continue must be treated as pure statements -- they lose their meaning when wrapped in a closure. </td> <td class="code"> <div class="highlight"><pre> isStatement: -> @value is 'break' or @value is 'continue' or @value is 'debugger' isPureStatement: LiteralNode::isStatement compileNode: (o) -> idt = if @isStatement(o) then @idt() else '' end = if @isStatement(o) then ';' else '' idt + @value + end toString: (idt) -> '"' + @value + '"'</pre></div> </td> </tr> <tr id="section-31"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-31">#</a> </div> <h3>ReturnNode</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-32"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-32">#</a> </div> A <code>return</code> is a pureStatement -- wrapping it in a closure wouldn't make sense. </td> <td class="code"> <div class="highlight"><pre>exports.ReturnNode = class ReturnNode extends BaseNode class: 'ReturnNode' isStatement: -> yes isPureStatement: -> yes children: ['expression'] constructor: (@expression) -> super() makeReturn: -> this compile: (o) -> expr = @expression.makeReturn() return expr.compile o unless expr instanceof ReturnNode super o compileNode: (o) -> o.asStatement = true if @expression.isStatement(o) "#{@tab}return #{@expression.compile(o)};"</pre></div> </td> </tr> <tr id="section-33"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-33">#</a> </div> <h3>ValueNode</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-34"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-34">#</a> </div> A value, variable or literal or parenthesized, indexed or dotted into, or vanilla. </td> <td class="code"> <div class="highlight"><pre>exports.ValueNode = class ValueNode extends BaseNode class: 'ValueNode' children: ['base', 'properties']</pre></div> </td> </tr> <tr id="section-35"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-35">#</a> </div> A ValueNode has a base and a list of property accesses. </td> <td class="code"> <div class="highlight"><pre> constructor: (@base, @properties) -> super() @properties or= []</pre></div> </td> </tr> <tr id="section-36"> <td class="docs"> <div class="octowrap"> <a class="octothorpe" href="#section-36">#</a> </div> <