From 5d893947eae8830d15d7ff8d7a393d5eef58a529 Mon Sep 17 00:00:00 2001 From: Jeremy Ashkenas Date: Sun, 21 Feb 2010 17:30:41 -0500 Subject: [PATCH] new version of the docs for 0.5.0 is done, or close to it. --- documentation/css/docs.css | 5 +- documentation/index.html.erb | 90 ++++++++++++++++++--------------- documentation/js/arguments.js | 2 +- index.html | 94 ++++++++++++++++++++--------------- lib/command_line.js | 2 +- lib/nodes.js | 1 + src/command_line.coffee | 2 +- src/nodes.coffee | 1 + 8 files changed, 112 insertions(+), 85 deletions(-) diff --git a/documentation/css/docs.css b/documentation/css/docs.css index 1953e350..e03bb5f9 100644 --- a/documentation/css/docs.css +++ b/documentation/css/docs.css @@ -63,7 +63,7 @@ code, pre, tt, textarea { div.code { position: relative; border: 1px solid #cacaca; - background: #fff; + background: #fafaff; padding: 7px 0 10px 0; -moz-border-radius: 5px; -webkit-border-radius: 5px; border-radius: 5px; -webkit-box-shadow: 0px 0px 7px #cacaca; @@ -75,6 +75,7 @@ div.code { div.code pre, div.code textarea { float: left; width: 450px; + background: #fafaff; border-left: 1px dotted #559; padding: 0 0 0 12px; margin: 0; @@ -98,7 +99,7 @@ div.code { height: 50px; left: 40px; right: 40px; top: 25px; background: #ddd; - padding-left: 250px; + padding-left: 235px; background: -webkit-gradient(linear, left top, left bottom, from(#f5f5f5), to(#d0d0d0)); background: -moz-linear-gradient(top, #f5f5f5, #d0d0d0); filter: progid:DXImageTransform.Microsoft.Gradient(GradientType=0, StartColorStr='#F5F5F5', EndColorStr='#D0D0D0'); diff --git a/documentation/index.html.erb b/documentation/index.html.erb index b5e2309d..0996aa87 100644 --- a/documentation/index.html.erb +++ b/documentation/index.html.erb @@ -137,18 +137,27 @@ alert reverse '!tpircseeffoC'

- The CoffeeScript compiler is written in pure Ruby, and is available - as a Ruby Gem. + The CoffeeScript compiler is written in pure CoffeeScript, 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). +

+ +

+ To install, either clone the + source repository, + or download the latest + release: 0.5.0. + Then, from within the coffee-script directory, run: 

-gem install coffee-script
+bin/cake install

Installing the gem provides the coffee command, which can be used to compile CoffeeScript .coffee files into JavaScript, as - well as debug them. In conjunction with - Node.js (or Narwhal), the coffee + well as debug them. The coffee command also provides direct evaluation and an interactive REPL. When compiling to JavaScript, coffee writes the output as .js files in the same directory by default, but output @@ -159,17 +168,14 @@ gem install coffee-script -i, --interactive - Launch an interactive CoffeeScript session. - Requires Node.js, - or Narwhal, with --narwhal. + Launch an interactive CoffeeScript session to try short snippets. -r, --run - Compile and execute scripts without saving the intermediate - JavaScript. Requires Node.js, - or Narwhal, with --narwhal. + Compile and execute a given CoffeeScript without saving the intermediate + JavaScript. @@ -195,7 +201,9 @@ gem install coffee-script -l, --lint - If the jsl (JavaScript Lint) command is installed, use it + If the jsl + (JavaScript Lint) + command is installed, use it to check the compilation of a CoffeeScript file. (Handy in conjunction with --watch) @@ -204,22 +212,7 @@ gem install coffee-script -e, --eval Compile and print a little snippet of CoffeeScript directly from the - command line (or from stdin). For example:
coffee -e "square: (x) -> x * x" - - - - -t, --tokens - - Instead of parsing the CoffeeScript, just lex it, and print out the - token stream: [:IDENTIFIER, "square"], [":", ":"], [:PARAM, "x"] ... - - - - -v, --verbose - - As the JavaScript is being generated, print out every step of code - generation, including lexical scope and the nodes in the - AST. + command line. For example:
coffee -e "square: (x) -> x * x" @@ -230,16 +223,25 @@ gem install coffee-script - -g, --globals + -t, --tokens - Suppress all variable declarations at the top-level, effectively adding - those variables to the global scope. (Used by the REPL.) + Instead of parsing the CoffeeScript, just lex it, and print out the + token stream: [IDENTIFIER square] [ASSIGN :] [PARAM_START (] ... - --install-bundle + -tr, --tree - Install the TextMate bundle for CoffeeScript syntax highlighting. + Instead of compiling the CoffeeScript, just lex and parse it, and print + out the parse tree: +

+  Expressions
+    Assign
+      Value "square"
+      Code "x"
+        Op *
+          Value "x"
+          Value "x"
@@ -268,7 +270,13 @@ coffee --print app/scripts/*.coffee > concatenation.js the left, and the direct compilation into JavaScript is on the right.

- + +

+ + Many of the examples can be run (where it makes sense) by pressing the "run" + button towards the bottom right. You can also paste examples into + "Try CoffeeScript" in the toolbar, and play with them from there. +

Significant Whitespace @@ -283,25 +291,27 @@ coffee --print app/scripts/*.coffee > concatenation.js

- You don't need to use parentheses to invoke a function, if you're passing + You don't need to use parentheses to invoke a function if you're passing arguments:
print "coffee"

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. + as long as CoffeeScript can determine that the line hasn't finished yet, + because it ends with an operator or a dot.

Functions and Invocation Functions are defined by a list of parameters, an arrow, and the - function body. The empty function looks like this: ->. All + function body. The empty function looks like this: -> All functions in CoffeeScript are named by default, for easier debugging.

<%= code_for('functions', 'cube(5)') %>

- If you'd like to create an anonymous function, just wrap it in parentheses: + If you'd like to assign a function literal to a variable, but not have + it be named, just wrap the function definition in parentheses: ((x) -> x * x)

@@ -315,7 +325,7 @@ coffee --print app/scripts/*.coffee > concatenation.js

<%= code_for('assignment', 'greeting') %>

- Declaration of new variables are pushed up to the top of the nearest + All declaration of new variables is pushed up to the top of the nearest lexical scope, so that assignment may always be performed within expressions.

@@ -702,6 +712,7 @@ coffee --print app/scripts/*.coffee > concatenation.js
  • If you'd like to chat, stop by #coffeescript on Freenode.
    • +

    diff --git a/documentation/js/arguments.js b/documentation/js/arguments.js index 2f31f65d..09aa0e35 100644 --- a/documentation/js/arguments.js +++ b/documentation/js/arguments.js @@ -1,7 +1,7 @@ (function(){ var backwards; backwards = function backwards() { - var arguments = Array.prototype.slice.call(arguments, 0); + arguments = Array.prototype.slice.call(arguments, 0); return alert(arguments.reverse()); }; backwards("stairway", "to", "heaven"); diff --git a/index.html b/index.html index 84c724ff..305451db 100644 --- a/index.html +++ b/index.html @@ -234,18 +234,27 @@ cubed_list = (function() {

    - The CoffeeScript compiler is written in pure Ruby, and is available - as a Ruby Gem. + The CoffeeScript compiler is written in pure CoffeeScript, 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). +

    + +

    + To install, either clone the + source repository, + or download the latest + release: 0.5.0. + Then, from within the coffee-script directory, run: 

    -gem install coffee-script
    +bin/cake install

    Installing the gem provides the coffee command, which can be used to compile CoffeeScript .coffee files into JavaScript, as - well as debug them. In conjunction with - Node.js (or Narwhal), the coffee + well as debug them. The coffee command also provides direct evaluation and an interactive REPL. When compiling to JavaScript, coffee writes the output as .js files in the same directory by default, but output @@ -256,17 +265,14 @@ gem install coffee-script -i, --interactive - Launch an interactive CoffeeScript session. - Requires Node.js, - or Narwhal, with --narwhal. + Launch an interactive CoffeeScript session to try short snippets. -r, --run - Compile and execute scripts without saving the intermediate - JavaScript. Requires Node.js, - or Narwhal, with --narwhal. + Compile and execute a given CoffeeScript without saving the intermediate + JavaScript. @@ -292,7 +298,9 @@ gem install coffee-script -l, --lint - If the jsl (JavaScript Lint) command is installed, use it + If the jsl + (JavaScript Lint) + command is installed, use it to check the compilation of a CoffeeScript file. (Handy in conjunction with --watch) @@ -301,22 +309,7 @@ gem install coffee-script -e, --eval Compile and print a little snippet of CoffeeScript directly from the - command line (or from stdin). For example:
    coffee -e "square: (x) -> x * x" - - - - -t, --tokens - - Instead of parsing the CoffeeScript, just lex it, and print out the - token stream: [:IDENTIFIER, "square"], [":", ":"], [:PARAM, "x"] ... - - - - -v, --verbose - - As the JavaScript is being generated, print out every step of code - generation, including lexical scope and the nodes in the - AST. + command line. For example:
    coffee -e "square: (x) -> x * x" @@ -327,16 +320,25 @@ gem install coffee-script - -g, --globals + -t, --tokens - Suppress all variable declarations at the top-level, effectively adding - those variables to the global scope. (Used by the REPL.) + Instead of parsing the CoffeeScript, just lex it, and print out the + token stream: [IDENTIFIER square] [ASSIGN :] [PARAM_START (] ... - --install-bundle + -tr, --tree - Install the TextMate bundle for CoffeeScript syntax highlighting. + Instead of compiling the CoffeeScript, just lex and parse it, and print + out the parse tree: +

    +  Expressions
+    Assign
+      Value "square"
+      Code "x"
+        Op *
+          Value "x"
+          Value "x"
    @@ -365,7 +367,13 @@ coffee --print app/scripts/*.coffee > concatenation.js the left, and the direct compilation into JavaScript is on the right.

    - + +

    + + Many of the examples can be run (where it makes sense) by pressing the "run" + button towards the bottom right. You can also paste examples into + "Try CoffeeScript" in the toolbar, and play with them from there. +

    Significant Whitespace @@ -380,20 +388,21 @@ coffee --print app/scripts/*.coffee > concatenation.js

    - You don't need to use parentheses to invoke a function, if you're passing + You don't need to use parentheses to invoke a function if you're passing arguments:
    print "coffee"

    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. + as long as CoffeeScript can determine that the line hasn't finished yet, + because it ends with an operator or a dot.

    Functions and Invocation Functions are defined by a list of parameters, an arrow, and the - function body. The empty function looks like this: ->. All + function body. The empty function looks like this: -> All functions in CoffeeScript are named by default, for easier debugging. 

    square: (x) -> x * x
@@ -414,7 +423,8 @@ cube = function cube(x) {
 };
 ;alert(cube(5));'>run: cube(5)

    - If you'd like to create an anonymous function, just wrap it in parentheses: + If you'd like to assign a function literal to a variable, but not have + it be named, just wrap the function definition in parentheses: ((x) -> x * x)

    @@ -436,7 +446,7 @@ greeting = "Hello CoffeeScript"; difficulty = 0.5; ;alert(greeting);'>run: greeting

    - Declaration of new variables are pushed up to the top of the nearest + All declaration of new variables is pushed up to the top of the nearest lexical scope, so that assignment may always be performed within expressions.

    @@ -703,13 +713,13 @@ alert("The Field: " + the_field); backwards "stairway", "to", "heaven" 
    var backwards;
 backwards = function backwards() {
-  var arguments = Array.prototype.slice.call(arguments, 0);
+  arguments = Array.prototype.slice.call(arguments, 0);
   return alert(arguments.reverse());
 };
 backwards("stairway", "to", "heaven");