coffeescript

<!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="pilwrap"> <a class="pilcrow" 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="pilwrap"> <a class="pilcrow" href="#section-2">¶</a> </div> Import the helpers we plan to use. </td> <td class="code"> <div class="highlight"><pre>{compact, flatten, extend, merge, del, starts, ends, last} = require './helpers' exports.extend = extend # for parser</pre></div> </td> </tr> <tr id="section-3"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-3">¶</a> </div> Constant functions for nodes that don't need customization. </td> <td class="code"> <div class="highlight"><pre>YES = -> yes NO = -> no THIS = -> this NEGATE = -> @negated = not @negated; this</pre></div> </td> </tr> <tr id="section-4"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-4">¶</a> </div> <h3>Base</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-5"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-5">¶</a> </div> The Base 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.Base = class Base</pre></div> </td> </tr> <tr id="section-6"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-6">¶</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). </td> <td class="code"> <div class="highlight"><pre> compile: (o, lvl) -> o = extend {}, o o.level = lvl if lvl node = @unfoldSoak(o) or this node.tab = o.indent if o.level is LEVEL_TOP or node.isPureStatement() or not node.isStatement(o) node.compileNode o else node.compileClosure o</pre></div> </td> </tr> <tr id="section-7"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-7">¶</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) -> if @containsPureStatement() throw SyntaxError 'cannot include a pure statement in an expression.' o.sharedScope = o.scope Closure.wrap(this).compileNode o</pre></div> </td> </tr> <tr id="section-8"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-8">¶</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. Pass a level to precompile. </td> <td class="code"> <div class="highlight"><pre> cache: (o, level, reused) -> unless @isComplex() ref = if level then @compile o, level else this [ref, ref] else ref = new Literal reused or o.scope.freeVariable 'ref' sub = new Assign ref, this if level then [sub.compile(o, level), ref.value] else [sub, ref]</pre></div> </td> </tr> <tr id="section-9"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-9">¶</a> </div> Compile to a source/variable pair suitable for looping. </td> <td class="code"> <div class="highlight"><pre> compileLoopReference: (o, name) -> src = tmp = @compile o, LEVEL_LIST unless -Infinity < +src < Infinity or IDENTIFIER.test(src) and o.scope.check(src, yes) src = "#{ tmp = o.scope.freeVariable name } = #{src}" [src, tmp]</pre></div> </td> </tr> <tr id="section-10"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-10">¶</a> </div> Construct a node that returns the current node's result. Note that this is overridden for smarter behavior for many statement nodes (e.g. If, For)... </td> <td class="code"> <div class="highlight"><pre> makeReturn: -> new Return this</pre></div> </td> </tr> <tr id="section-11"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-11">¶</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: (pred) -> contains = no @traverseChildren no, (node) -> if pred node contains = yes return no contains</pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-12">¶</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 (node) -> node instanceof type</pre></div> </td> </tr> <tr id="section-13"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-13">¶</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 (node) -> node.isPureStatement()</pre></div> </td> </tr> <tr id="section-14"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" 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 = '', name = @constructor.name) -> tree = '\n' + idt + name tree += '?' if @soak @eachChild (node) -> tree += node.toString idt + TAB tree</pre></div> </td> </tr> <tr id="section-15"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-15">¶</a> </div> Passes each child to a function, breaking when the function returns <code>false</code>. </td> <td class="code"> <div class="highlight"><pre> eachChild: (func) -> return this unless @children for attr in @children when @[attr] for child in flatten [@[attr]] return this if func(child) is false this traverseChildren: (crossScope, func) -> @eachChild (child) -> return false if func(child) is false child.traverseChildren crossScope, func invert: -> new Op '!', this unwrapAll: -> node = this continue until node is node = node.unwrap() node</pre></div> </td> </tr> <tr id="section-16"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-16">¶</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> children: [] isStatement : NO isPureStatement : NO isComplex : YES isChainable : NO isAssignable : NO unwrap : THIS unfoldSoak : NO</pre></div> </td> </tr> <tr id="section-17"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-17">¶</a> </div> Is this node used to assign a certain variable? </td> <td class="code"> <div class="highlight"><pre> assigns: NO</pre></div> </td> </tr> <tr id="section-18"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-18">¶</a> </div> <h3>Expressions</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-19"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-19">¶</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 Base constructor: (nodes) -> @expressions = compact flatten nodes or [] children: ['expressions']</pre></div> </td> </tr> <tr id="section-20"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-20">¶</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-21"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-21">¶</a> </div> Remove and return the last expression of this expression list. </td> <td class="code"> <div class="highlight"><pre> pop: -> @expressions.pop()</pre></div> </td> </tr> <tr id="section-22"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-22">¶</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-23"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-23">¶</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-24"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-24">¶</a> </div> Is this an empty block of code? </td> <td class="code"> <div class="highlight"><pre> isEmpty: -> not @expressions.length isStatement: (o) -> for exp in @expressions when exp.isPureStatement() or exp.isStatement o return yes no</pre></div> </td> </tr> <tr id="section-25"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-25">¶</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: -> len = @expressions.length while len-- expr = @expressions[len] if expr not instanceof Comment @expressions[len] = expr.makeReturn() break this</pre></div> </td> </tr> <tr id="section-26"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-26">¶</a> </div> An Expressions is the only node that can serve as the root. </td> <td class="code"> <div class="highlight"><pre> compile: (o = {}, level) -> if o.scope then super o, level else @compileRoot o</pre></div> </td> </tr> <tr id="section-27"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-27">¶</a> </div> Compile all expressions 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> compileNode: (o) -> @tab = o.indent top = o.level is LEVEL_TOP codes = [] for node in @expressions node = node.unwrapAll() node = (node.unfoldSoak(o) or node) if top node.front = true code = node.compile o codes.push if node.isStatement o then code else @tab + code + ';' else codes.push node.compile o, LEVEL_LIST return codes.join '\n' if top code = codes.join(', ') or 'void 0' if codes.length > 1 and o.level >= LEVEL_LIST then "(#{code})" else code</pre></div> </td> </tr> <tr id="section-28"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-28">¶</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.bare then '' else TAB o.scope = new Scope null, this, null o.level = LEVEL_TOP code = @compileWithDeclarations o code = code.replace TRAILING_WHITESPACE, '' if o.bare then code else "(function() {\n#{code}\n}).call(this);\n"</pre></div> </td> </tr> <tr id="section-29"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-29">¶</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 = post = '' for exp, i in @expressions exp = exp.unwrap() break unless exp instanceof Comment or exp instanceof Literal o.level = LEVEL_TOP if i rest = @expressions.splice i, @expressions.length code = @compileNode o @expressions = rest post = @compileNode o {scope} = o if not o.globals and o.scope.hasDeclarations this code += "#{@tab}var #{ scope.compiledDeclarations() };\n" if scope.hasAssignments this code += "#{@tab}var #{ multident scope.compiledAssignments(), @tab };\n" code + post</pre></div> </td> </tr> <tr id="section-30"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-30">¶</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> @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-31"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-31">¶</a> </div> <h3>Literal</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-32"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-32">¶</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.Literal = class Literal extends Base constructor: (@value) -> makeReturn: -> if @isPureStatement() then this else new Return this</pre></div> </td> </tr> <tr id="section-33"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-33">¶</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> isPureStatement: -> @value in ['break', 'continue', 'debugger'] isAssignable: -> IDENTIFIER.test @value isComplex: NO assigns: (name) -> name is @value compile: -> if @value.reserved then "\"#{@value}\"" else @value toString: -> ' "' + @value + '"'</pre></div> </td> </tr> <tr id="section-34"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-34">¶</a> </div> <h3>Return</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-35"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-35">¶</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.Return = class Return extends Base constructor: (@expression) -> children: ['expression'] isStatement: YES isPureStatement: YES makeReturn: THIS compile: (o, level) -> expr = @expression?.makeReturn() if expr and expr not instanceof Return then expr.compile o, level else super o, level compileNode: (o) -> o.level = LEVEL_PAREN @tab + "return#{ if @expression then ' ' + @expression.compile o else '' };"</pre></div> </td> </tr> <tr id="section-36"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-36">¶</a> </div> <h3>Value</h3> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-37"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-37">¶</a> </div> A value, variab