From 1778177195639ee9a13622c41d089adb1537bbed Mon Sep 17 00:00:00 2001 From: Jeremy Ashkenas Date: Sun, 21 Nov 2010 19:53:31 -0500 Subject: [PATCH] continuing to document the homepage for 0.9.5 ... removing an optimization for local variables within loops. --- documentation/coffee/objects_reserved.coffee | 4 +- documentation/css/docs.css | 15 +- documentation/index.html.erb | 184 +++++++++------ documentation/js/array_comprehensions.js | 12 +- documentation/js/expressions_comprehension.js | 7 +- documentation/js/objects_reserved.js | 3 +- index.html | 213 ++++++++++-------- lib/cake.js | 7 +- lib/command.js | 7 +- lib/nodes.js | 4 +- src/nodes.coffee | 3 +- 11 files changed, 268 insertions(+), 191 deletions(-) diff --git a/documentation/coffee/objects_reserved.coffee b/documentation/coffee/objects_reserved.coffee index 588c366c..31830139 100644 --- a/documentation/coffee/objects_reserved.coffee +++ b/documentation/coffee/objects_reserved.coffee @@ -1 +1,3 @@ -$('.account').attr class: 'active' \ No newline at end of file +$('.account').attr class: 'active' + +log object.class \ No newline at end of file diff --git a/documentation/css/docs.css b/documentation/css/docs.css index ce9ea0ce..4f8a9e93 100644 --- a/documentation/css/docs.css +++ b/documentation/css/docs.css @@ -44,6 +44,15 @@ table { td { padding: 9px 15px 9px 0; } +table.definitions { + width: auto; + margin: 30px 0; + border-left: 6px solid #ccccdd; +} + table.definitions td { + text-align: center; + padding: 5px 20px; + } code, pre, tt, textarea { font-family: Monaco, Consolas, "Lucida Console", monospace; font-size: 12px; @@ -55,12 +64,10 @@ code, pre, tt, textarea { tt { background: #f8f8ff; border: 1px solid #dedede; - font-size: 85%; padding: 0px 0.2em; } pre { - border-left: 6px solid #222255; - margin-left: 13px; + border-left: 6px solid #ccccdd; padding: 3px 0 3px 12px; font-size: 12px; } @@ -73,7 +80,7 @@ div.code { position: relative; border: 1px solid #cacaca; background: #fafaff; - padding: 11px 3px; + padding: 7px 0 10px 0; -moz-border-radius: 5px; -webkit-border-radius: 5px; border-radius: 5px; -webkit-box-shadow: 0px 0px 7px #cacaca; zoom: 1; diff --git a/documentation/index.html.erb b/documentation/index.html.erb index a6bfe080..1d7e0141 100644 --- a/documentation/index.html.erb +++ b/documentation/index.html.erb @@ -34,7 +34,7 @@ Table of Contents
- Mini Overview + Overview Installation and Usage Language Reference Significant Whitespace @@ -59,6 +59,7 @@ Multiline Strings, Heredocs, and Block Comments Cake, and Cakefiles "text/coffeescript" Script Tags + Examples Resources Web Chat (IRC) Change Log @@ -133,63 +134,47 @@ <%= code_for('overview', 'cubes') %> -

- For a longer CoffeeScript example, check out - Underscore.coffee, a port - of the Underscore.js - library of helper functions. Underscore.coffee can pass the entire Underscore.js - test suite. The CoffeeScript version is faster than the original for a number - of methods (in general, due to the speed of CoffeeScript's array comprehensions), and - after being minified and gzipped, is only 241 bytes larger than the original - JavaScript version. - Additional examples are included in the source repository, inside the - examples folder. -

-

Installation and Usage

- The CoffeeScript compiler is written in pure CoffeeScript, using a - small DSL - on top of the Jison parser generator, and is available - as a Node.js utility. The core compiler however, - does not depend on Node, and can be run in other server-side-JavaScript environments, - or in the browser (see "Try CoffeeScript", above). + The CoffeeScript compiler + is itself written in CoffeeScript, + using the Jison parser generator. The command-line + version of coffee is available as a Node.js utility. + The core compiler however, does not depend on Node, and can be run in any + JavaScript environment, or in the browser (see "Try CoffeeScript", above).

To install, first make sure you have a working copy of the latest tagged version of - Node.js, currently 0.1.102 or higher. - Then clone the CoffeeScript - source repository - from GitHub, or download the latest - release: 0.9.5. - To install the CoffeeScript compiler system-wide - under /usr/local, open the directory and run: -

- - 
-sudo bin/cake install
- -

- Alternatively, if you already have the - Node Package Manager installed, - you can use that to grab the latest CoffeeScript: + Node.js, and NPM + (the Node Package Manager). You can then install CoffeeScript with NPM: 

 npm install coffee-script
+

+ If you'd prefer to install the latest master version of CoffeeScript, you + can clone the CoffeeScript + source repository + from GitHub, or download + the source directly. + To install the CoffeeScript compiler system-wide + under /usr/local, open the directory and run: +

+ + 
+sudo bin/cake install
+

- Both of these provide the coffee command, which will execute CoffeeScripts - under Node.js by default, but is also used to compile CoffeeScript - .coffee files into JavaScript, or to run an an interactive REPL. - When compiling to JavaScript, coffee writes the output - as .js files in the same directory by default, but output - can be customized with the following options: + Both of these provide the coffee command, which can execute + coffee scripts, compile .coffee files into .js, and + provides an interactive REPL. The coffee command takes the + following options:

@@ -297,10 +282,10 @@ Expressions 

-coffee -c path/to/script.coffee
-coffee --interactive
+coffee -o lib/ -c src/
 coffee --watch --lint experimental.coffee
-coffee --print app/scripts/*.coffee > concatenation.js
+coffee --print app/scripts/*.coffee > concatenation.js +coffee --bare --print --stdio

@@ -338,20 +323,17 @@ coffee --print app/scripts/*.coffee > concatenation.js

You don't need to use parentheses to invoke a function if you're passing - arguments:
print "coffee". Implicit parentheses wrap forwards - to the end of the line, or block expression. + arguments:
print "coffee". The implicit call wraps forward + to the end of the line or block expression.

- +

- You can use newlines to break up your expression into smaller pieces, - as long as CoffeeScript can determine that the line hasn't finished yet, - because it ends with an operator or a dot ... seen most commonly - in jQuery-chaining style JavaScript. + Within object literals, indentation can be used to create nested objects.

- Functions and Invocation + Functions Functions are defined by a list of parameters, an arrow, and the function body. The empty function looks like this: ->

@@ -361,15 +343,16 @@ coffee --print app/scripts/*.coffee > concatenation.js Objects and Arrays Object and Array literals look very similar to their JavaScript cousins. - When you spread out each property on a separate line, the commas are - optional. Implicit objects may be created with indentation instead of - brackets, winding up looking quite similar to YAML. + When each property is listed on its own line, the commas are + optional. Objects may be created using indentation instead of + explicit braces, similar to YAML.

<%= 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 - them for you, so you don't have to worry about it (say, when using jQuery). + of an object, without quoting them as strings. CoffeeScript notices reserved words + used as keys in objects and quotes them for you, so you don't have to worry + about it (say, when using jQuery).

<%= code_for('objects_reserved') %> @@ -408,7 +391,7 @@ coffee --print app/scripts/*.coffee > concatenation.js attach them as properties on window, or on the exports object in CommonJS. The existential operator (covered below), gives you a reliable way to figure out where to add them, if you're targeting both - CommonJS and the browser: root = exports ? this + CommonJS and the browser: exports ? this

@@ -423,7 +406,7 @@ coffee --print app/scripts/*.coffee > concatenation.js CoffeeScript can compile if statements into JavaScript expressions, using the ternary operator when possible, and closure wrapping otherwise. There is no explicit ternary statement in CoffeeScript — you simply use - a regular if statement inline. + a regular if statement on a single line.

<%= code_for('conditionals') %> @@ -463,6 +446,25 @@ coffee --print app/scripts/*.coffee > concatenation.js You can use in to test for array presence, and of to test for JavaScript object-key presence.

+ +

+ All together now: +

+ +

+ + + + + + + + + + + +
CoffeeScriptJavaScript
is===
isnt!==
not!
and&&
or||
true, yes, ontrue
false, no, offfalse
@, thisthis
ofin
in(no JS equivalent)
+ <%= code_for('aliases') %>

@@ -818,6 +820,40 @@ coffee --print app/scripts/*.coffee > concatenation.js run within a closure wrapper, so if you want to expose global variables or functions, attach them to the window object.

+ +

+ + Examples +

+ +

@@ -847,6 +883,10 @@ coffee --print app/scripts/*.coffee > concatenation.js IRC client of your choice, or on webchat.freenode.net. +
  • + satyr's Coco + — a CoffeeScript dialect that aims to be more radical and practical. +
  • yeungda's JCoffeeScript — A Java Library that uses Rhino to compile CoffeeScript, allowing @@ -858,7 +898,7 @@ coffee --print app/scripts/*.coffee > concatenation.js support, and some bonus commands.
  • - jashkenas's CoffeeScript TextMate Bundle + jashkenas' CoffeeScript TextMate Bundle — which provides syntax highlighting, snippet expansion, and the ability to run bits of CoffeeScript from within TextMate itself.
    • @@ -909,29 +949,27 @@ coffee --print app/scripts/*.coffee > concatenation.js — a CoffeeScript wrapper for CouchApps, web applications served directly from CouchDB. +
  • + sstephenson's Eco + — high-performance embedded CoffeeScript templates, after EJS and ERB. +
  • mauricemach's CoffeeKup — Markup as CoffeeScript. After _why's Markaby.
  • - jashkenas's Docco + jashkenas' Docco — a quick-and-dirty literate-programming-style documentation generator for CoffeeScript. Used to produce the annotated source.
    • -
  • - satyr's CUP - — The CoffeeScript Unofficial Playpen, where the changes to - the latest master can be experimented with. -
    • -
  • - satyr's xqjs - — A Firefox add-on that provides a simple JavaScript console - with the ability to execute CoffeeScripts within the current window. -
  • naturalethic's Congo - — An asynchronous MongoDB ORM, for use with Node.js and CoffeeScript. + — an asynchronous MongoDB ORM, for use with Node.js and CoffeeScript. +
    • +
  • + mauricemach's Zappa + — a DSL for building web apps, built on top of Express and Socket.IO.
    • diff --git a/documentation/js/array_comprehensions.js b/documentation/js/array_comprehensions.js index 766bafd9..bbbe4c90 100644 --- a/documentation/js/array_comprehensions.js +++ b/documentation/js/array_comprehensions.js @@ -1,15 +1,13 @@ -var food, lunch, pos, roid, roid2, _i, _j, _len, _len2, _len3, _ref, _ref2, _ref3; +var food, lunch, pos, roid, roid2, _i, _j, _len, _len2, _len3, _ref; _ref = ['toast', 'cheese', 'wine']; for (_i = 0, _len = _ref.length; _i < _len; _i++) { food = _ref[_i]; lunch = eat(food); } -_ref2 = asteroids; -for (pos = 0, _len2 = _ref2.length; pos < _len2; pos++) { - roid = _ref2[pos]; - _ref3 = asteroids; - for (_j = 0, _len3 = _ref3.length; _j < _len3; _j++) { - roid2 = _ref3[_j]; +for (pos = 0, _len2 = asteroids.length; pos < _len2; pos++) { + roid = asteroids[pos]; + for (_j = 0, _len3 = asteroids.length; _j < _len3; _j++) { + roid2 = asteroids[_j]; if (roid !== roid2) { if (roid.overlaps(roid2)) { roid.explode(); diff --git a/documentation/js/expressions_comprehension.js b/documentation/js/expressions_comprehension.js index 32f4baab..70b9f20c 100644 --- a/documentation/js/expressions_comprehension.js +++ b/documentation/js/expressions_comprehension.js @@ -1,10 +1,9 @@ -var globals, name, _ref, _results; +var globals, name, _results; var __hasProp = Object.prototype.hasOwnProperty; globals = ((function() { - _ref = window; _results = []; - for (name in _ref) { - if (!__hasProp.call(_ref, name)) continue; + for (name in window) { + if (!__hasProp.call(window, name)) continue; _results.push(name); } return _results; diff --git a/documentation/js/objects_reserved.js b/documentation/js/objects_reserved.js index 2e639c6b..b893fa42 100644 --- a/documentation/js/objects_reserved.js +++ b/documentation/js/objects_reserved.js @@ -1,3 +1,4 @@ $('.account').attr({ "class": 'active' -}); \ No newline at end of file +}); +log(object["class"]); \ No newline at end of file diff --git a/index.html b/index.html index 495bb532..ce4a5a9e 100644 --- a/index.html +++ b/index.html @@ -21,7 +21,7 @@ Table of Contents

    - Mini Overview + Overview Installation and Usage Language Reference Significant Whitespace @@ -46,6 +46,7 @@ Multiline Strings, Heredocs, and Block Comments Cake, and Cakefiles "text/coffeescript" Script Tags + Examples Resources Web Chat (IRC) Change Log @@ -215,63 +216,47 @@ cubes = ((function() { return _results; })());;alert(cubes);'>run: cubes
    -

    - For a longer CoffeeScript example, check out - Underscore.coffee, a port - of the Underscore.js - library of helper functions. Underscore.coffee can pass the entire Underscore.js - test suite. The CoffeeScript version is faster than the original for a number - of methods (in general, due to the speed of CoffeeScript's array comprehensions), and - after being minified and gzipped, is only 241 bytes larger than the original - JavaScript version. - Additional examples are included in the source repository, inside the - examples folder. -

    -

    Installation and Usage

    - The CoffeeScript compiler is written in pure CoffeeScript, using a - small DSL - on top of the Jison parser generator, and is available - as a Node.js utility. The core compiler however, - does not depend on Node, and can be run in other server-side-JavaScript environments, - or in the browser (see "Try CoffeeScript", above). + The CoffeeScript compiler + is itself written in CoffeeScript, + using the Jison parser generator. The command-line + version of coffee is available as a Node.js utility. + The core compiler however, does not depend on Node, and can be run in any + JavaScript environment, or in the browser (see "Try CoffeeScript", above).

    To install, first make sure you have a working copy of the latest tagged version of - Node.js, currently 0.1.102 or higher. - Then clone the CoffeeScript - source repository - from GitHub, or download the latest - release: 0.9.5. - To install the CoffeeScript compiler system-wide - under /usr/local, open the directory and run: -

    - - 
    -sudo bin/cake install
    - -

    - Alternatively, if you already have the - Node Package Manager installed, - you can use that to grab the latest CoffeeScript: + Node.js, and NPM + (the Node Package Manager). You can then install CoffeeScript with NPM: 

     npm install coffee-script
    +

    + If you'd prefer to install the latest master version of CoffeeScript, you + can clone the CoffeeScript + source repository + from GitHub, or download + the source directly. + To install the CoffeeScript compiler system-wide + under /usr/local, open the directory and run: +

    + + 
    +sudo bin/cake install
    +

    - Both of these provide the coffee command, which will execute CoffeeScripts - under Node.js by default, but is also used to compile CoffeeScript - .coffee files into JavaScript, or to run an an interactive REPL. - When compiling to JavaScript, coffee writes the output - as .js files in the same directory by default, but output - can be customized with the following options: + Both of these provide the coffee command, which can execute + coffee scripts, compile .coffee files into .js, and + provides an interactive REPL. The coffee command takes the + following options:

    @@ -379,10 +364,10 @@ Expressions 

    -coffee -c path/to/script.coffee
-coffee --interactive
+coffee -o lib/ -c src/
 coffee --watch --lint experimental.coffee
-coffee --print app/scripts/*.coffee > concatenation.js
    +coffee --print app/scripts/*.coffee > concatenation.js +coffee --bare --print --stdio

    @@ -420,20 +405,17 @@ coffee --print app/scripts/*.coffee > concatenation.js

    You don't need to use parentheses to invoke a function if you're passing - arguments:
    print "coffee". Implicit parentheses wrap forwards - to the end of the line, or block expression. + arguments:
    print "coffee". The implicit call wraps forward + to the end of the line or block expression.

    - +

    - You can use newlines to break up your expression into smaller pieces, - as long as CoffeeScript can determine that the line hasn't finished yet, - because it ends with an operator or a dot ... seen most commonly - in jQuery-chaining style JavaScript. + Within object literals, indentation can be used to create nested objects.

    - Functions and Invocation + Functions Functions are defined by a list of parameters, an arrow, and the function body. The empty function looks like this: ->

    @@ -458,9 +440,9 @@ cube = function(x) { Objects and Arrays Object and Array literals look very similar to their JavaScript cousins. - When you spread out each property on a separate line, the commas are - optional. Implicit objects may be created with indentation instead of - brackets, winding up looking quite similar to YAML. + When each property is listed on its own line, the commas are + optional. Objects may be created using indentation instead of + explicit braces, similar to YAML. 

    song = ["do", "re", "mi", "fa", "so"]
 
@@ -515,13 +497,17 @@ kids = {
 };;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 - them for you, so you don't have to worry about it (say, when using jQuery). + of an object, without quoting them as strings. CoffeeScript notices reserved words + used as keys in objects and quotes them for you, so you don't have to worry + about it (say, when using jQuery). 

    $('.account').attr class: 'active'
+
+log object.class
 
    $('.account').attr({
   "class": 'active'
 });
+log(object["class"]);

    @@ -579,7 +565,7 @@ inner = changeNumbers();;alert(inner);'>run: inner
    < attach them as properties on window, or on the exports object in CommonJS. The existential operator (covered below), gives you a reliable way to figure out where to add them, if you're targeting both - CommonJS and the browser: root = exports ? this + CommonJS and the browser: exports ? this

    @@ -594,7 +580,7 @@ inner = changeNumbers();;alert(inner);'>run: inner
    < CoffeeScript can compile if statements into JavaScript expressions, using the ternary operator when possible, and closure wrapping otherwise. There is no explicit ternary statement in CoffeeScript — you simply use - a regular if statement inline. + a regular if statement on a single line. 

    mood = greatlyImproved if singing
 
@@ -657,6 +643,25 @@ options || (options =
       You can use in to test for array presence, and of to
       test for JavaScript object-key presence.
     
    
+    
+    
    
+      All together now:
+    
    
+    
+

    + + + + + + + + + + + +
    CoffeeScriptJavaScript
    is===
    isnt!==
    not!
    and&&
    or||
    true, yes, ontrue
    false, no, offfalse
    @, thisthis
    ofin
    in(no JS equivalent)
    + 
    launch() if ignition is on
 
 volume = 10 if band isnt SpinalTap
@@ -829,18 +834,16 @@ lunch = eat food for f
 for roid, pos in asteroids
   for roid2 in asteroids when roid isnt roid2
     roid.explode() if roid.overlaps roid2
-
    var food, lunch, pos, roid, roid2, _i, _j, _len, _len2, _len3, _ref, _ref2, _ref3;
+
    var food, lunch, pos, roid, roid2, _i, _j, _len, _len2, _len3, _ref;
 _ref = ['toast', 'cheese', 'wine'];
 for (_i = 0, _len = _ref.length; _i < _len; _i++) {
   food = _ref[_i];
   lunch = eat(food);
 }
-_ref2 = asteroids;
-for (pos = 0, _len2 = _ref2.length; pos < _len2; pos++) {
-  roid = _ref2[pos];
-  _ref3 = asteroids;
-  for (_j = 0, _len3 = _ref3.length; _j < _len3; _j++) {
-    roid2 = _ref3[_j];
+for (pos = 0, _len2 = asteroids.length; pos < _len2; pos++) {
+  roid = asteroids[pos];
+  for (_j = 0, _len3 = asteroids.length; _j < _len3; _j++) {
+    roid2 = asteroids[_j];
     if (roid !== roid2) {
       if (roid.overlaps(roid2)) {
         roid.explode();
@@ -992,24 +995,22 @@ six = (one = 1) + (two = 2) + (three = 3);;alert(six);'>run: six
    # The first ten global properties.
 
 globals = (name for name of window)[0...10]
-
    var globals, name, _ref, _results;
+
    var globals, name, _results;
 var __hasProp = Object.prototype.hasOwnProperty;
 globals = ((function() {
-  _ref = window;
   _results = [];
-  for (name in _ref) {
-    if (!__hasProp.call(_ref, name)) continue;
+  for (name in window) {
+    if (!__hasProp.call(window, name)) continue;
     _results.push(name);
   }
   return _results;
 })()).slice(0, 10);
-