From 9814fc2e1c84ee471e5f0bc7600af2f58cf9253e Mon Sep 17 00:00:00 2001 From: Jeremy Ashkenas Date: Sat, 17 Jul 2010 10:28:06 -0400 Subject: [PATCH] Updating documentation with endtime's suggestions. --- Rakefile | 2 +- documentation/coffee/block_comment.coffee | 4 + documentation/coffee/cake_tasks.coffee | 12 +- documentation/index.html.erb | 41 +++--- documentation/js/block_comment.js | 6 + documentation/js/cake_tasks.js | 21 ++- documentation/js/classes.js | 3 - documentation/js/expressions.js | 6 +- documentation/js/expressions_comprehension.js | 5 +- documentation/js/intro.js | 7 - documentation/js/object_comprehensions.js | 5 +- documentation/js/punctuation.js | 8 -- documentation/js/soaks.js | 4 +- index.html | 124 ++++++++++-------- 14 files changed, 132 insertions(+), 116 deletions(-) create mode 100644 documentation/coffee/block_comment.coffee create mode 100644 documentation/js/block_comment.js delete mode 100644 documentation/js/intro.js delete mode 100644 documentation/js/punctuation.js diff --git a/Rakefile b/Rakefile index c9ccf5ed..8c6b8fc8 100644 --- a/Rakefile +++ b/Rakefile @@ -17,7 +17,7 @@ EOS desc "Build the documentation page" task :doc do source = 'documentation/index.html.erb' - child = fork { exec "bin/coffee -c documentation/coffee/*.coffee -o documentation/js -w" } + child = fork { exec "bin/coffee -cw -o documentation/js documentation/coffee/*.coffee" } at_exit { Process.kill("INT", child) } Signal.trap("INT") { exit } loop do diff --git a/documentation/coffee/block_comment.coffee b/documentation/coffee/block_comment.coffee new file mode 100644 index 00000000..85cae37f --- /dev/null +++ b/documentation/coffee/block_comment.coffee @@ -0,0 +1,4 @@ +### +CoffeeScript Compiler v0.7.2 +Released under the MIT License +### \ No newline at end of file diff --git a/documentation/coffee/cake_tasks.coffee b/documentation/coffee/cake_tasks.coffee index 811e3487..f4d125e3 100644 --- a/documentation/coffee/cake_tasks.coffee +++ b/documentation/coffee/cake_tasks.coffee @@ -1,3 +1,9 @@ -task 'test', 'run each of the unit tests', -> - for test in files - fs.readFile test, (err, code) -> eval coffee.compile code +fs: require 'fs' + +option '-o', '--output [DIR]', 'directory for compiled code' + +task 'build:parser', 'rebuild the Jison parser', -> + require 'jison' + code: require('./lib/grammar').parser.generate() + dir: options.output or 'lib' + fs.writeFile "$dir/parser.js", code \ No newline at end of file diff --git a/documentation/index.html.erb b/documentation/index.html.erb index 5d3128fb..075eda48 100644 --- a/documentation/index.html.erb +++ b/documentation/index.html.erb @@ -59,7 +59,7 @@ Try/Catch/Finally Chained Comparisons String and RegExp Interpolation - Multiline Strings and Heredocs + Multiline Strings, Heredocs, and Block Comments Cake, and Cakefiles "text/coffeescript" Script Tags Resources @@ -184,11 +184,11 @@ alert reverse '.eeffoC yrT' sudo bin/cake install

- Alternatively, if you already have the + Alternatively, if you already have the Node Package Manager installed, you can use that to grab the latest CoffeeScript:

- + 
 sudo npm install coffee-script
@@ -389,7 +389,7 @@ coffee --print app/scripts/*.coffee > concatenation.js <%= code_for('objects_and_arrays', 'song.join(",")') %>

In JavaScript, you can't use reserved words, like class, as properties - of an object, without quoting them as strings. CoffeeScript notices and quotes + of an object, without quoting them as strings. CoffeeScript notices and quotes them for you, so you don't have to worry about it (say, when using jQuery).

<%= code_for('objects_reserved') %> @@ -486,7 +486,7 @@ coffee --print app/scripts/*.coffee > concatenation.js As a shortcut for this.property, you can use @property.

- You can use in to test for array presence, and of to + You can use in to test for array presence, and of to test for JavaScript object-key presence.

<%= code_for('aliases') %> @@ -778,7 +778,7 @@ coffee --print app/scripts/*.coffee > concatenation.js

- Multiline Strings and Heredocs + Multiline Strings, Heredocs, and Block Comments Multiline strings are allowed in CoffeeScript.

<%= code_for('strings', 'mobyDick') %> @@ -792,6 +792,13 @@ coffee --print app/scripts/*.coffee > concatenation.js

Double-quoted heredocs, like double-quoted strings, allow interpolation.

+

+ Sometimes you'd like to pass a block comment through to the generated + JavaScript. For example, when you need to embed a licensing header at + the top of a file. Block comments, which mirror the synax for heredocs, + are preserved in the generated code. +

+ <%= code_for('block_comment') %>

@@ -799,18 +806,22 @@ coffee --print app/scripts/*.coffee > concatenation.js

- CoffeeScript includes a simple build system similar to Make and Rake. Naturally, + CoffeeScript includes a simple build system similar to + Make and + Rake. Naturally, it's called Cake, and is used for the build and test tasks for the CoffeeScript language itself. Tasks are defined in a file named Cakefile, and can be invoked by running cake taskname from within the directory. - To print a list of all the tasks, just run cake. + To print a list of all the tasks and options, just run cake.

Task definitions are written in CoffeeScript, so you can put arbitrary code in your Cakefile. Define a task with a name, a long description, and the - function to invoke when the task is run. Here's a hypothetical task - that uses the Node.js API. + function to invoke when the task is run. If your task takes a command-line + option, you can define the option with short and long flags, and it will + be made available in the options object. Here's a task that uses + the Node.js API to rebuild CoffeeScript's parser:

<%= code_for('cake_tasks') %> @@ -924,7 +935,7 @@ coffee --print app/scripts/*.coffee > concatenation.js
  • jashkenas's Docco - — A quick-and-dirty literate-programming-style documentation generator + — A quick-and-dirty literate-programming-style documentation generator for CoffeeScript. Used to produce the annotated source.
    • @@ -948,13 +959,13 @@ coffee --print app/scripts/*.coffee > concatenation.js Change Log - +

    0.7.2 Quick bugfix (right after 0.7.1) for a problem that prevented coffee command-line options from being parsed in some circumstances.

    - +

    0.7.1 Block-style comments are now passed through and printed as JavaScript block @@ -962,13 +973,13 @@ coffee --print app/scripts/*.coffee > concatenation.js support for running coffee scripts standalone via hashbangs. Improved syntax errors for tokens that are not in the grammar.

    - +

    0.7.0 Official CoffeeScript variable style is now camelCase, as in JavaScript. Reserved words are now allowed as object keys, and will be quoted for you. Range comprehensions now generate cleaner code, but you have to specify by -1 - if you'd like to iterate downward. Reporting of syntax errors is greatly + if you'd like to iterate downward. Reporting of syntax errors is greatly improved from the previous release. Running coffee with no arguments now launches the REPL, with Readline support. The <- bind operator has been removed from CoffeeScript. The loop keyword was added, diff --git a/documentation/js/block_comment.js b/documentation/js/block_comment.js new file mode 100644 index 00000000..c7c89d61 --- /dev/null +++ b/documentation/js/block_comment.js @@ -0,0 +1,6 @@ +(function(){ + /* + CoffeeScript Compiler v0.7.2 + Released under the MIT License + */ +})(); diff --git a/documentation/js/cake_tasks.js b/documentation/js/cake_tasks.js index d2d41f68..d53e9e86 100644 --- a/documentation/js/cake_tasks.js +++ b/documentation/js/cake_tasks.js @@ -1,15 +1,12 @@ (function(){ - task('test', 'run each of the unit tests', function() { - var _a, _b, _c, _d; - _a = []; _c = files; - for (_b = 0, _d = _c.length; _b < _d; _b++) { - (function() { - var test = _c[_b]; - return _a.push(fs.readFile(test, function(err, code) { - return eval(coffee.compile(code)); - })); - })(); - } - return _a; + var fs; + fs = require('fs'); + option('-o', '--output [DIR]', 'directory for compiled code'); + task('build:parser', 'rebuild the Jison parser', function() { + var code, dir; + require('jison'); + code = require('./lib/grammar').parser.generate(); + dir = options.output || 'lib'; + return fs.writeFile(("" + dir + "/parser.js"), code); }); })(); diff --git a/documentation/js/classes.js b/documentation/js/classes.js index fe6507cc..1f5ca1dd 100644 --- a/documentation/js/classes.js +++ b/documentation/js/classes.js @@ -11,7 +11,6 @@ Animal.prototype.move = function(meters) { return alert(this.name + " moved " + meters + "m."); }; - Snake = function(name) { this.name = name; return this; @@ -21,7 +20,6 @@ alert("Slithering..."); return Snake.__superClass__.move.call(this, 5); }; - Horse = function(name) { this.name = name; return this; @@ -31,7 +29,6 @@ alert("Galloping..."); return Horse.__superClass__.move.call(this, 45); }; - sam = new Snake("Sammy the Python"); tom = new Horse("Tommy the Palomino"); sam.move(); diff --git a/documentation/js/expressions.js b/documentation/js/expressions.js index 8753add2..2e21f24a 100644 --- a/documentation/js/expressions.js +++ b/documentation/js/expressions.js @@ -4,11 +4,7 @@ if (student.excellentWork) { return "A+"; } else if (student.okayStuff) { - if (student.triedHard) { - return "B"; - } else { - return "B-"; - } + return student.triedHard ? "B" : "B-"; } else { return "C"; } diff --git a/documentation/js/expressions_comprehension.js b/documentation/js/expressions_comprehension.js index e176dfe2..5f15e5f4 100644 --- a/documentation/js/expressions_comprehension.js +++ b/documentation/js/expressions_comprehension.js @@ -3,9 +3,10 @@ var __hasProp = Object.prototype.hasOwnProperty; globals = (function() { _a = []; _b = window; - for (name in _b) { if (__hasProp.call(_b, name)) { + for (name in _b) { + if (!__hasProp.call(_b, name)) continue; _a.push(name); - }} + } return _a; })().slice(0, 10); })(); diff --git a/documentation/js/intro.js b/documentation/js/intro.js deleted file mode 100644 index 8ffe3ee2..00000000 --- a/documentation/js/intro.js +++ /dev/null @@ -1,7 +0,0 @@ -(function(){ - - // CoffeeScript on the left, JS on the right. - var square = function(x) { - return x * x; - }; -})(); \ No newline at end of file diff --git a/documentation/js/object_comprehensions.js b/documentation/js/object_comprehensions.js index 78f02527..bd637117 100644 --- a/documentation/js/object_comprehensions.js +++ b/documentation/js/object_comprehensions.js @@ -8,10 +8,11 @@ }; ages = (function() { _a = []; _b = yearsOld; - for (child in _b) { if (__hasProp.call(_b, child)) { + for (child in _b) { + if (!__hasProp.call(_b, child)) continue; age = _b[child]; _a.push(child + " is " + age); - }} + } return _a; })(); })(); diff --git a/documentation/js/punctuation.js b/documentation/js/punctuation.js deleted file mode 100644 index de6a556d..00000000 --- a/documentation/js/punctuation.js +++ /dev/null @@ -1,8 +0,0 @@ -(function(){ - - // Comments start with hash marks. Periods mark the end of a block. - var left_hand = raining ? umbrella : parasol; - // To signal the beginning of the next expression, - // use "then", or a newline. - left_hand = raining ? umbrella : parasol; -})(); \ No newline at end of file diff --git a/documentation/js/soaks.js b/documentation/js/soaks.js index 062366da..7baf2ce8 100644 --- a/documentation/js/soaks.js +++ b/documentation/js/soaks.js @@ -1,4 +1,4 @@ (function(){ - var _a; - typeof (_a = (lottery.drawWinner())) === "undefined" || _a == undefined ? undefined : _a.address == undefined ? undefined : _a.address.zipcode; + var _a, _b; + (_b = (typeof (_a = (lottery.drawWinner())) === "undefined" || _a == undefined ? undefined : _a.address)) == undefined ? undefined : _b.zipcode; })(); diff --git a/index.html b/index.html index ae5e02d8..966fc6a4 100644 --- a/index.html +++ b/index.html @@ -45,7 +45,7 @@ Try/Catch/Finally Chained Comparisons String and RegExp Interpolation - Multiline Strings and Heredocs + Multiline Strings, Heredocs, and Block Comments Cake, and Cakefiles "text/coffeescript" Script Tags Resources @@ -269,11 +269,11 @@ cubes = (function() { sudo bin/cake install

    - Alternatively, if you already have the + Alternatively, if you already have the Node Package Manager installed, you can use that to grab the latest CoffeeScript:

    - + 
     sudo npm install coffee-script
    @@ -527,7 +527,7 @@ matrix = [1, 0, 1, 0, 0, 1, 1, 1, 0]; ;alert(song.join(","));'>run: song.join(",")

    In JavaScript, you can't use reserved words, like class, as properties - of an object, without quoting them as strings. CoffeeScript notices and quotes + of an object, without quoting them as strings. CoffeeScript notices and quotes them for you, so you don't have to worry about it (say, when using jQuery). 

    $('.account').css {class: 'active'}
@@ -670,7 +670,7 @@ options = options || d
       As a shortcut for this.property, you can use @property.
     
    
     
    
-      You can use in to test for array presence, and of to 
+      You can use in to test for array presence, and of to
       test for JavaScript object-key presence.
     
    
     
    launch() if ignition is on
@@ -942,10 +942,11 @@ yearsOld = {
 };
 ages = (function() {
   _a = []; _b = yearsOld;
-  for (child in _b) { if (__hasProp.call(_b, child)) {
+  for (child in _b) {
+    if (!__hasProp.call(_b, child)) continue;
     age = _b[child];
     _a.push(child + " is " + age);
-  }}
+  }
   return _a;
 })();
 

    
@@ -1031,11 +1033,7 @@ eldest: if if (student.excellentWork) {
     return "A+";
   } else if (student.okayStuff) {
-    if (student.triedHard) {
-      return "B";
-    } else {
-      return "B-";
-    }
+    return student.triedHard ? "B" : "B-";
   } else {
     return "C";
   }
@@ -1046,11 +1044,7 @@ grade = function(student) {
   if (student.excellentWork) {
     return "A+";
   } else if (student.okayStuff) {
-    if (student.triedHard) {
-      return "B";
-    } else {
-      return "B-";
-    }
+    return student.triedHard ? "B" : "B-";
   } else {
     return "C";
   }
@@ -1085,18 +1079,20 @@ globals: (name for nam
 var __hasProp = Object.prototype.hasOwnProperty;
 globals = (function() {
   _a = []; _b = window;
-  for (name in _b) { if (__hasProp.call(_b, name)) {
+  for (name in _b) {
+    if (!__hasProp.call(_b, name)) continue;
     _a.push(name);
-  }}
+  }
   return _a;
 })().slice(0, 10);

    @@ -1173,8 +1169,8 @@ speed = (typeof speed !== "undefined" && speed !== null) ? speed : 140; the TypeError that would be raised otherwise. 

    lottery.drawWinner()?.address?.zipcode
-
    var _a;
-typeof (_a = (lottery.drawWinner())) === "undefined" || _a == undefined ? undefined : _a.address == undefined ? undefined : _a.address.zipcode;
+
    var _a, _b;
+(_b = (typeof (_a = (lottery.drawWinner())) === "undefined" || _a == undefined ? undefined : _a.address)) == undefined ? undefined : _b.zipcode;

    Soaking up nulls is similar to Ruby's @@ -1245,7 +1241,6 @@ tom.move() Animal.prototype.move = function(meters) { return alert(this.name + " moved " + meters + "m."); }; - Snake = function(name) { this.name = name; return this; @@ -1255,7 +1250,6 @@ __extends(Snake, Animal); alert("Slithering..."); return Snake.__superClass__.move.call(this, 5); }; - Horse = function(name) { this.name = name; return this; @@ -1265,7 +1259,6 @@ __extends(Horse, Animal); alert("Galloping..."); return Horse.__superClass__.move.call(this, 45); }; - sam = new Snake("Sammy the Python"); tom = new Horse("Tommy the Palomino"); sam.move(); @@ -1282,7 +1275,6 @@ Animal = function() { }; Animal.prototype.move = function(meters) { return alert(this.name + " moved " + meters + "m."); }; - Snake = function(name) { this.name = name; return this; @@ -1292,7 +1284,6 @@ Snake.prototype.move = function() { alert("Slithering..."); return Snake.__superClass__.move.call(this, 5); }; - Horse = function(name) { this.name = name; return this; @@ -1302,7 +1293,6 @@ Horse.prototype.move = function() { alert("Galloping..."); return Horse.__superClass__.move.call(this, 45); }; - sam = new Snake("Sammy the Python"); tom = new Horse("Tommy the Palomino"); sam.move(); @@ -1649,7 +1639,7 @@ dates = (new RegExp(("\\d+" + sep + "\\d+" + sep + "\\d+"), "g"));

    - Multiline Strings and Heredocs + Multiline Strings, Heredocs, and Block Comments Multiline strings are allowed in CoffeeScript. 

    mobyDick: "Call me Ishmael. Some years ago --
@@ -1692,6 +1682,21 @@ html = '<
     
    
       Double-quoted heredocs, like double-quoted strings, allow interpolation.
     
    
+    
    
+      Sometimes you'd like to pass a block comment through to the generated 
+      JavaScript. For example, when you need to embed a licensing header at 
+      the top of a file. Block comments, which mirror the synax for heredocs, 
+      are preserved in the generated code.
+    
    
+    
    ###
+CoffeeScript Compiler v0.7.2
+Released under the MIT License
+###
+
    /*
+CoffeeScript Compiler v0.7.2
+Released under the MIT License
+*/
+

    
 
     
    
       
@@ -1699,34 +1704,41 @@ html = '<
     
    
 
     
    
-      CoffeeScript includes a simple build system similar to Make and Rake. Naturally,
+      CoffeeScript includes a simple build system similar to 
+      Make and 
+      Rake. Naturally,
       it's called Cake, and is used for the build and test tasks for the CoffeeScript
       language itself. Tasks are defined in a file named Cakefile, and
       can be invoked by running cake taskname from within the directory.
-      To print a list of all the tasks, just run cake.
+      To print a list of all the tasks and options, just run cake.
     
    
 
     
    
       Task definitions are written in CoffeeScript, so you can put arbitrary code
       in your Cakefile. Define a task with a name, a long description, and the
-      function to invoke when the task is run. Here's a hypothetical task
-      that uses the Node.js API.
+      function to invoke when the task is run. If your task takes a command-line
+      option, you can define the option with short and long flags, and it will
+      be made available in the options object. Here's a task that uses
+      the Node.js API to rebuild CoffeeScript's parser:
     
    
-    
    task 'test', 'run each of the unit tests', ->
-  for test in files
-    fs.readFile test, (err, code) -> eval coffee.compile code
-
    task('test', 'run each of the unit tests', function() {
-  var _a, _b, _c, _d;
-  _a = []; _c = files;
-  for (_b = 0, _d = _c.length; _b < _d; _b++) {
-    (function() {
-      var test = _c[_b];
-      return _a.push(fs.readFile(test, function(err, code) {
-        return eval(coffee.compile(code));
-      }));
-    })();
-  }
-  return _a;
+    
    fs: require 'fs'
+
+option '-o', '--output [DIR]', 'directory for compiled code'
+
+task 'build:parser', 'rebuild the Jison parser', ->
+  require 'jison'
+  code:   require('./lib/grammar').parser.generate()
+  dir:    options.output or 'lib'
+  fs.writeFile "$dir/parser.js", code
+
    var fs;
+fs = require('fs');
+option('-o', '--output [DIR]', 'directory for compiled code');
+task('build:parser', 'rebuild the Jison parser', function() {
+  var code, dir;
+  require('jison');
+  code = require('./lib/grammar').parser.generate();
+  dir = options.output || 'lib';
+  return fs.writeFile(("" + dir + "/parser.js"), code);
 });
 

    
 
@@ -1840,7 +1852,7 @@ html = '<
       
       
  • 
         jashkenas's Docco
-        — A quick-and-dirty literate-programming-style documentation generator 
+        — A quick-and-dirty literate-programming-style documentation generator
         for CoffeeScript. Used to produce the annotated source.
       
    • 
     
@@ -1864,13 +1876,13 @@ html = '<
       
       Change Log
     
-    
+
     
    
       0.7.2
       Quick bugfix (right after 0.7.1) for a problem that prevented coffee
       command-line options from being parsed in some circumstances.
     
    
-    
+
     
    
       0.7.1
       Block-style comments are now passed through and printed as JavaScript block
@@ -1878,13 +1890,13 @@ html = '<
       support for running coffee scripts standalone via hashbangs.
       Improved syntax errors for tokens that are not in the grammar.
     
    
-    
+
     
    
       0.7.0
       Official CoffeeScript variable style is now camelCase, as in JavaScript.
       Reserved words are now allowed as object keys, and will be quoted for you.
       Range comprehensions now generate cleaner code, but you have to specify by -1
-      if you'd like to iterate downward. Reporting of syntax errors is greatly 
+      if you'd like to iterate downward. Reporting of syntax errors is greatly
       improved from the previous release. Running coffee with no arguments
       now launches the REPL, with Readline support. The <- bind operator
       has been removed from CoffeeScript. The loop keyword was added,