coffeescript

<!DOCTYPE html> <html> <head> <title>grammar.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> grammar.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> The CoffeeScript parser is generated by <a href="http://github.com/zaach/jison">Jison</a> from this grammar file. Jison is a bottom-up parser generator, similar in style to <a href="http://www.gnu.org/software/bison">Bison</a>, implemented in JavaScript. It can recognize <a href="http://en.wikipedia.org/wiki/LR_grammar">LALR(1), LR(0), SLR(1), and LR(1)</a> type grammars. To create the Jison parser, we list the pattern to match on the left-hand side, and the action to take (usually the creation of syntax tree nodes) on the right. As the parser runs, it shifts tokens from our token stream, from left to right, and <a href="http://en.wikipedia.org/wiki/Bottom-up_parsing">attempts to match</a> the token sequence against the rules below. When a match can be made, it reduces into the <a href="http://en.wikipedia.org/wiki/Terminal_and_nonterminal_symbols">nonterminal</a> (the enclosing name at the top), and we proceed from there. If you run the <code>cake build:parser</code> command, Jison constructs a parse table from our rules and saves it into <code>lib/parser.js</code>. </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-2"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-2">¶</a> </div> The only dependency is on the Jison.Parser. </td> <td class="code"> <div class="highlight"><pre>{Parser} = require 'jison'</pre></div> </td> </tr> <tr id="section-3"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-3">¶</a> </div> <h2>Jison DSL</h2> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-4"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-4">¶</a> </div> Since we're going to be wrapped in a function by Jison in any case, if our action immediately returns a value, we can optimize by removing the function wrapper and just returning the value directly. </td> <td class="code"> <div class="highlight"><pre>unwrap = /^function\s*\s*\{\s*return\s*([\s\S]*);\s*\}/</pre></div> </td> </tr> <tr id="section-5"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-5">¶</a> </div> Our handy DSL for Jison grammar generation, thanks to <a href="http://github.com/creationix">Tim Caswell</a>. For every rule in the grammar, we pass the pattern-defining string, the action to run, and extra options, optionally. If no action is specified, we simply pass the value of the previous nonterminal. </td> <td class="code"> <div class="highlight"><pre>o = (patternString, action, options) -> patternString = patternString.replace /\s{2,}/g, ' ' return [patternString, '$$ = $1;', options] unless action action = if match = unwrap.exec action then match[1] else "(#{action}())" action = action.replace /\bnew /g, '$&yy.' action = action.replace /\b(?:Expressions\.wrap|extend)\b/g, 'yy.$&' [patternString, "$$ = #{action};", options]</pre></div> </td> </tr> <tr id="section-6"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-6">¶</a> </div> <h2>Grammatical Rules</h2> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-7"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-7">¶</a> </div> In all of the rules that follow, you'll see the name of the nonterminal as the key to a list of alternative matches. With each match's action, the dollar-sign variables are provided by Jison as references to the value of their numeric position, so in this rule: <pre><code>"Expression UNLESS Expression" </code></pre> <code>$1</code> would be the value of the first <code>Expression</code>, <code>$2</code> would be the token for the <code>UNLESS</code> terminal, and <code>$3</code> would be the value of the second <code>Expression</code>. </td> <td class="code"> <div class="highlight"><pre>grammar =</pre></div> </td> </tr> <tr id="section-8"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-8">¶</a> </div> The Root is the top-level node in the syntax tree. Since we parse bottom-up, all parsing must end here. </td> <td class="code"> <div class="highlight"><pre> Root: [ o '', -> new Expressions o 'Body' o 'Block TERMINATOR' ]</pre></div> </td> </tr> <tr id="section-9"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-9">¶</a> </div> Any list of statements and expressions, separated by line breaks or semicolons. </td> <td class="code"> <div class="highlight"><pre> Body: [ o 'Line', -> Expressions.wrap [$1] o 'Body TERMINATOR Line', -> $1.push $3 o 'Body TERMINATOR' ]</pre></div> </td> </tr> <tr id="section-10"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-10">¶</a> </div> Expressions and statements, which make up a line in a body. </td> <td class="code"> <div class="highlight"><pre> Line: [ o 'Expression' o 'Statement' ]</pre></div> </td> </tr> <tr id="section-11"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-11">¶</a> </div> Pure statements which cannot be expressions. </td> <td class="code"> <div class="highlight"><pre> Statement: [ o 'Return' o 'Throw' o 'Comment' o 'STATEMENT', -> new Literal $1 ]</pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-12">¶</a> </div> All the different types of expressions in our language. The basic unit of CoffeeScript is the Expression -- everything that can be an expression is one. Expressions serve as the building blocks of many other rules, making them somewhat circular. </td> <td class="code"> <div class="highlight"><pre> Expression: [ o 'Value' o 'Invocation' o 'Code' o 'Operation' o 'Assign' o 'If' o 'Try' o 'While' o 'For' o 'Switch' o 'Class' ]</pre></div> </td> </tr> <tr id="section-13"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-13">¶</a> </div> An indented block of expressions. Note that the <a href="rewriter.html">Rewriter</a> will convert some postfix forms into blocks for us, by adjusting the token stream. </td> <td class="code"> <div class="highlight"><pre> Block: [ o 'INDENT Body OUTDENT', -> $2 o 'INDENT OUTDENT', -> new Expressions ]</pre></div> </td> </tr> <tr id="section-14"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-14">¶</a> </div> A literal identifier, a variable name or property. </td> <td class="code"> <div class="highlight"><pre> Identifier: [ o 'IDENTIFIER', -> new Literal $1 ]</pre></div> </td> </tr> <tr id="section-15"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-15">¶</a> </div> Alphanumerics are separated from the other Literal matchers because they can also serve as keys in object literals. </td> <td class="code"> <div class="highlight"><pre> AlphaNumeric: [ o 'NUMBER', -> new Literal $1 o 'STRING', -> new Literal $1 ]</pre></div> </td> </tr> <tr id="section-16"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-16">¶</a> </div> All of our immediate values. These can (in general), be passed straight through and printed to JavaScript. </td> <td class="code"> <div class="highlight"><pre> Literal: [ o 'AlphaNumeric' o 'JS', -> new Literal $1 o 'REGEX', -> new Literal $1 o 'BOOL', -> new Literal if $1 is 'undefined' then 'void 0' else $1 ]</pre></div> </td> </tr> <tr id="section-17"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-17">¶</a> </div> Assignment of a variable, property, or index to a value. </td> <td class="code"> <div class="highlight"><pre> Assign: [ o 'Assignable = Expression', -> new Assign $1, $3 o 'Assignable = INDENT Expression OUTDENT', -> new Assign $1, $4 ]</pre></div> </td> </tr> <tr id="section-18"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-18">¶</a> </div> Assignment when it happens within an object literal. The difference from the ordinary Assign is that these allow numbers and strings as keys. </td> <td class="code"> <div class="highlight"><pre> AssignObj: [ o 'ObjAssignable', -> new Value $1 o 'ObjAssignable : Expression', -> new Assign new Value($1), $3, 'object' o 'ObjAssignable : INDENT Expression OUTDENT', -> new Assign new Value($1), $4, 'object' o 'Comment' ] ObjAssignable: [ o 'Identifier' o 'AlphaNumeric' o 'Parenthetical' o 'ThisProperty' ]</pre></div> </td> </tr> <tr id="section-19"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-19">¶</a> </div> A return statement from a function body. </td> <td class="code"> <div class="highlight"><pre> Return: [ o 'RETURN Expression', -> new Return $2 o 'RETURN', -> new Return ]</pre></div> </td> </tr> <tr id="section-20"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-20">¶</a> </div> A block comment. </td> <td class="code"> <div class="highlight"><pre> Comment: [ o 'HERECOMMENT', -> new Comment $1 ]</pre></div> </td> </tr> <tr id="section-21"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-21">¶</a> </div> The Code node is the function literal. It's defined by an indented block of Expressions preceded by a function arrow, with an optional parameter list. </td> <td class="code"> <div class="highlight"><pre> Code: [ o 'PARAM_START ParamList PARAM_END FuncGlyph Block', -> new Code $2, $5, $4 o 'FuncGlyph Block', -> new Code [], $2, $1 ]</pre></div> </td> </tr> <tr id="section-22"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-22">¶</a> </div> CoffeeScript has two different symbols for functions. <code>-></code> is for ordinary functions, and <code>=></code> is for functions bound to the current value of this. </td> <td class="code"> <div class="highlight"><pre> FuncGlyph: [ o '->', -> 'func' o '=>', -> 'boundfunc' ]</pre></div> </td> </tr> <tr id="section-23"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-23">¶</a> </div> An optional, trailing comma. </td> <td class="code"> <div class="highlight"><pre> OptComma: [ o '' o ',' ]</pre></div> </td> </tr> <tr id="section-24"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-24">¶</a> </div> The list of parameters that a function accepts can be of any length. </td> <td class="code"> <div class="highlight"><pre> ParamList: [ o '', -> [] o 'Param', -> [$1] o 'ParamList , Param', -> $1.concat $3 ]</pre></div> </td> </tr> <tr id="section-25"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-25">¶</a> </div> A single parameter in a function definition can be ordinary, or a splat that hoovers up the remaining arguments. </td> <td class="code"> <div class="highlight"><pre> Param: [ o 'ParamVar', -> new Param $1 o 'ParamVar ...', -> new Param $1, null, on o 'ParamVar = Expression', -> new Param $1, $3 ] ParamVar: [ o 'Identifier' o 'ThisProperty' o 'Array' o 'Object' ]</pre></div> </td> </tr> <tr id="section-26"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-26">¶</a> </div> A splat that occurs outside of a parameter list. </td> <td class="code"> <div class="highlight"><pre> Splat: [ o 'Expression ...', -> new Splat $1 ]</pre></div> </td> </tr> <tr id="section-27"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-27">¶</a> </div> Variables and properties that can be assigned to. </td> <td class="code"> <div class="highlight"><pre> SimpleAssignable: [ o 'Identifier', -> new Value $1 o 'Value Accessor', -> $1.push $2 o 'Invocation Accessor', -> new Value $1, [$2] o 'ThisProperty' ]</pre></div> </td> </tr> <tr id="section-28"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-28">¶</a> </div> Everything that can be assigned to. </td> <td class="code"> <div class="highlight"><pre> Assignable: [ o 'SimpleAssignable' o 'Array', -> new Value $1 o 'Object', -> new Value $1 ]</pre></div> </td> </tr> <tr id="section-29"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-29">¶</a> </div> The types of things that can be treated as values -- assigned to, invoked as functions, indexed into, named as a class, etc. </td> <td class="code"> <div class="highlight"><pre> Value: [ o 'Assignable' o 'Literal', -> new Value $1 o 'Parenthetical', -> new Value $1 o 'Range', -> new Value $1 o 'This' ]</pre></div> </td> </tr> <tr id="section-30"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-30">¶</a> </div> The general group of accessors into an object, by property, by prototype or by array index or slice. </td> <td class="code"> <div class="highlight"><pre> Accessor: [ o '. Identifier', -> new Access $2 o '?. Identifier', -> new Access $2, 'soak' o ':: Identifier', -> new Access $2, 'proto' o '::', -> new Access new Literal 'prototype' o 'Index' o 'Slice', -> new Slice $1 ]</pre></div> </td> </tr> <tr id="section-31"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-31">¶</a> </div> Indexing into an object or array using bracket notation. </td> <td class="code"> <div class="highlight"><pre> Index: [ o 'INDEX_START Expression INDEX_END', -> new Index $2 o 'INDEX_SOAK Index', -> extend $2, soak : yes o 'INDEX_PROTO Index', -> extend $2, proto: yes ]</pre></div> </td> </tr> <tr id="section-32"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-32">¶</a> </div> In CoffeeScript, an object literal is simply a list of assignments. </td> <td class="code"> <div class="highlight"><pre> Object: [ o '{ AssignList OptComma }', -> new Obj $2, $1.generated ]</pre></div> </td> </tr> <tr id="section-33"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-33">¶</a> </div> Assignment of properties within an object literal can be separated by comma, as in JavaScript, or simply by newline. </td> <td class="code"> <div class="highlight"><pre> AssignList: [ o '', -> [] o 'AssignObj', -> [$1] o 'AssignList , AssignObj', -> $1.concat $3 o 'AssignList OptComma TERMINATOR AssignObj', -> $1.concat $4 o 'AssignList OptComma INDENT AssignList OptComma OUTDENT', -> $1.concat $4 ]</pre></div> </td> </tr> <tr id="section-34"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-34">¶</a> </div> Class definitions have optional bodies of prototype property assignments, and optional references to the superclass. </td> <td class="code"> <div class="highlight"><pre> Class: [ o 'CLASS', -> new Class o 'CLASS Block', -> new Class null, null, $2 o 'CLASS EXTENDS Value', -> new Class null, $3 o 'CLASS EXTENDS Value Block', -> new Class null, $3, $4 o 'CLASS SimpleAssignable', -> new Class $2 o 'CLASS SimpleAssignable Block', -> new Class $2, null, $3 o 'CLASS SimpleAssignable EXTENDS Value', -> new Class $2, $4 o 'CLASS SimpleAssignable EXTENDS Value Block', -> new Class $2, $4, $5 ]</pre></div> </td> </tr> <tr id="section-35"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-35">¶</a> </div> Ordinary function invocation, or a chained series of calls. </td> <td class="code"> <div class="highlight"><pre> Invocation: [ o 'Value OptFuncExist Arguments', -> new Call $1, $3, $2 o 'Invocation OptFuncExist Arguments', -> new Call $1, $3, $2 o 'SUPER', -> new Call 'super', [new Splat new Literal 'arguments'] o 'SUPER Arguments', -> new Call 'super', $2 ]</pre></div> </td> </tr> <tr id="section-36"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-36">¶</a> </div> An optional existence check on a function. </td> <td class="code"> <div class="highlight"><pre> OptFuncExist: [ o '', -> no o 'FUNC_EXIST', -> yes ]</pre></div> </td> </tr> <tr id="section-37"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-37">¶</a> </div> The list of arguments to a function call. </td> <td class="code"> <div class="highlight"><pre> Arguments: [ o 'CALL_START CALL_END', -> [] o 'CALL_START ArgList OptComma CALL_END', -> $2 ]</pre></div> </td> </tr> <tr id="section-38"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-38">¶</a> </div> A reference to the this current object. </td> <td class="code"> <div class="highlight"><pre> This: [ o 'THIS', -> new Value new Literal 'this' o '@', -> new Value new Literal 'this' ]</pre></div> </td> </tr> <tr id="section-39"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-39">¶</a> </div> A reference to a property on this. </td> <td class="code"> <div class="highlight"><pre> ThisProperty: [ o '@ Identifier', -> new Value new Literal(<span