updating documentation for classes

zzen · Feb 28, 2010 · a356935 · a356935
1 parent f742725
commit a356935
Show file tree

Hide file tree

Showing 7 changed files with 88 additions and 76 deletions.
diff --git a/documentation/coffee/super.coffee → documentation/coffee/classes.coffee b/documentation/coffee/super.coffee → documentation/coffee/classes.coffee
diff --git a/documentation/coffee/prototypes.coffee b/documentation/coffee/prototypes.coffee
@@ -0,0 +1,2 @@
+String::dasherize: ->
+  this.replace(/_/g, "-")
diff --git a/documentation/css/idle.css b/documentation/css/idle.css
@@ -57,6 +57,7 @@ pre.idle .FunctionName {
    color: #21439C;
 }
 pre.idle .Variable {
+  color: #A535AE;
 }
 pre.idle .Comment {
    color: #919191;

diff --git a/documentation/index.html.erb b/documentation/index.html.erb
@@ -52,7 +52,7 @@
         <a href="#slice_splice">Array Slicing and Splicing with Ranges</a>
         <a href="#expressions">Everything is an Expression</a>
         <a href="#existence">The Existential Operator</a>
-        <a href="#inheritance">Inheritance, and Calling Super from a Subclass</a>
+        <a href="#classes">Classes, Inheritance, and Super</a>
         <a href="#pattern_matching">Pattern Matching</a>
         <a href="#fat_arrow">Function Binding</a>
         <a href="#embedded">Embedded JavaScript</a>
@@ -592,8 +592,8 @@ coffee --print app/scripts/*.coffee > concatenation.js</pre>
     </p>
 
     <p>
-      <span id="inheritance" class="bookmark"></span>
-      <b class="header">Inheritance, and Calling Super from a Subclass</b>
+      <span id="classes" class="bookmark"></span>
+      <b class="header">Classes, Inheritance, and Super</b>
       JavaScript's prototypal inheritance has always been a bit of a
       brain-bender, with a whole family tree of libraries that provide a cleaner
       syntax for classical inheritance on top of JavaScript's prototypes:
@@ -607,18 +607,20 @@ coffee --print app/scripts/*.coffee > concatenation.js</pre>
       set the prototype chain.
     </p>
     <p>
-      CoffeeScript provides <tt>extends</tt>
-      to help with prototype setup, <tt>::</tt> for quick access to an
-      object's prototype, and converts <tt>super()</tt> into a call against
-      the immediate ancestor's method of the same name.
+      Instead of repetitively attaching functions to a prototype, CoffeeScript
+      provides a basic <tt>class</tt> structure that allows you to name your class,
+      set the superclass, assign prototypal properties, and define the constructor,
+      in a single assignable expression.
     </p>
-    <%= code_for('super', true) %>
+    <%= code_for('classes', true) %>
     <p>
-      <b>A cautionary note:</b> JavaScript allows you to return a different value from
-      a constructor function, ignoring the newly-created object. In CoffeeScript,
-      it's best practice to always return <tt>this</tt> as the last line of a
-      constructor, as seen above.
+      If structuring your prototypes classically isn't your cup of tea, CoffeeScript
+      provides a couple of lower-level conveniences. The <tt>extends</tt> operator
+      helps with proper prototype setup, as seen above, <tt>::</tt> gives you
+      quick access to an object's prototype, and <tt>super()</tt>
+      is converted into a call against the immediate ancestor's method of the same name.
     </p>
+    <%= code_for('prototypes', '"one_two".dasherize()') %>
 
     <p>
       <span id="pattern_matching" class="bookmark"></span>

diff --git a/documentation/js/super.js → documentation/js/classes.js b/documentation/js/super.js → documentation/js/classes.js
@@ -1,5 +1,12 @@
 (function(){
-  var Animal, Horse, Snake, _a, _b, sam, tom;
+  var Animal, Horse, Snake, sam, tom;
+  var __extends = function(child, parent) {
+    var ctor = function(){ };
+    ctor.prototype = parent.prototype;
+    child.__superClass__ = parent.prototype;
+    child.prototype = new ctor();
+    child.prototype.constructor = child;
+  };
   Animal = function Animal() {  };
   Animal.prototype.move = function move(meters) {
     return alert(this.name + " moved " + meters + "m.");
@@ -8,11 +15,7 @@
     this.name = name;
     return this;
   };
-  _a = function(){};
-  _a.prototype = Animal.prototype;
-  Snake.__superClass__ = Animal.prototype;
-  Snake.prototype = new _a();
-  Snake.prototype.constructor = Snake;
+  __extends(Snake, Animal);
   Snake.prototype.move = function move() {
     alert("Slithering...");
     return Snake.__superClass__.move.call(this, 5);
@@ -21,11 +24,7 @@
     this.name = name;
     return this;
   };
-  _b = function(){};
-  _b.prototype = Animal.prototype;
-  Horse.__superClass__ = Animal.prototype;
-  Horse.prototype = new _b();
-  Horse.prototype.constructor = Horse;
+  __extends(Horse, Animal);
   Horse.prototype.move = function move() {
     alert("Galloping...");
     return Horse.__superClass__.move.call(this, 45);

diff --git a/documentation/js/prototypes.js b/documentation/js/prototypes.js
@@ -0,0 +1,5 @@
+(function(){
+  String.prototype.dasherize = function dasherize() {
+    return this.replace(/_/g, "-");
+  };
+})();
diff --git a/index.html b/index.html
@@ -38,7 +38,7 @@
         <a href="#slice_splice">Array Slicing and Splicing with Ranges</a>
         <a href="#expressions">Everything is an Expression</a>
         <a href="#existence">The Existential Operator</a>
-        <a href="#inheritance">Inheritance, and Calling Super from a Subclass</a>
+        <a href="#classes">Classes, Inheritance, and Super</a>
         <a href="#pattern_matching">Pattern Matching</a>
         <a href="#fat_arrow">Function Binding</a>
         <a href="#embedded">Embedded JavaScript</a>
@@ -1156,8 +1156,8 @@ <h2>
     </p>
 
     <p>
-      <span id="inheritance" class="bookmark"></span>
-      <b class="header">Inheritance, and Calling Super from a Subclass</b>
+      <span id="classes" class="bookmark"></span>
+      <b class="header">Classes, Inheritance, and Super</b>
       JavaScript's prototypal inheritance has always been a bit of a
       brain-bender, with a whole family tree of libraries that provide a cleaner
       syntax for classical inheritance on top of JavaScript's prototypes:
@@ -1171,35 +1171,30 @@ <h2>
       set the prototype chain.
     </p>
     <p>
-      CoffeeScript provides <tt>extends</tt>
-      to help with prototype setup, <tt>::</tt> for quick access to an
-      object's prototype, and converts <tt>super()</tt> into a call against
-      the immediate ancestor's method of the same name.
+      Instead of repetitively attaching functions to a prototype, CoffeeScript
+      provides a basic <tt>class</tt> structure that allows you to name your class,
+      set the superclass, assign prototypal properties, and define the constructor,
+      in a single assignable expression.
     </p>
-    <div class='code'><pre class="idle"><span class="FunctionName">Animal</span><span class="Keyword">:</span> <span class="Storage">-&gt;</span>
+    <div class='code'><pre class="idle"><span class="Variable">class</span> Animal
+  <span class="FunctionName">move</span><span class="Keyword">:</span> <span class="FunctionArgument">(</span><span class="FunctionArgument">meters</span><span class="FunctionArgument">)</span> <span class="Storage">-&gt;</span>
+    alert <span class="Variable">@name</span> <span class="Keyword">+</span> <span class="String"><span class="String">&quot;</span> moved <span class="String">&quot;</span></span> <span class="Keyword">+</span> meters <span class="Keyword">+</span> <span class="String"><span class="String">&quot;</span>m.<span class="String">&quot;</span></span>
 
-<span class="FunctionName">Animal::move</span><span class="Keyword">:</span> <span class="FunctionArgument">(</span><span class="FunctionArgument">meters</span><span class="FunctionArgument">)</span> <span class="Storage">-&gt;</span>
-  alert <span class="Variable">@name</span> <span class="Keyword">+</span> <span class="String"><span class="String">&quot;</span> moved <span class="String">&quot;</span></span> <span class="Keyword">+</span> meters <span class="Keyword">+</span> <span class="String"><span class="String">&quot;</span>m.<span class="String">&quot;</span></span>
+<span class="Variable">class</span> Snake <span class="Variable">extends</span> Animal
+  <span class="FunctionName">constructor</span><span class="Keyword">:</span> <span class="FunctionArgument">(</span><span class="FunctionArgument">name</span><span class="FunctionArgument">)</span> <span class="Storage">-&gt;</span>
+    <span class="Variable">@name</span><span class="Keyword">:</span> name
 
-<span class="FunctionName">Snake</span><span class="Keyword">:</span> <span class="FunctionArgument">(</span><span class="FunctionArgument">name</span><span class="FunctionArgument">)</span> <span class="Storage">-&gt;</span>
-  <span class="Variable">@name</span><span class="Keyword">:</span> name
-  <span class="Variable">this</span>
+  <span class="FunctionName">move</span><span class="Keyword">:</span> <span class="Storage">-&gt;</span>
+    alert <span class="String"><span class="String">&quot;</span>Slithering...<span class="String">&quot;</span></span>
+    <span class="Variable">super</span> <span class="Number">5</span>
 
-Snake <span class="Variable">extends</span> Animal
+<span class="Variable">class</span> Horse <span class="Variable">extends</span> Animal
+  <span class="FunctionName">constructor</span><span class="Keyword">:</span> <span class="FunctionArgument">(</span><span class="FunctionArgument">name</span><span class="FunctionArgument">)</span> <span class="Storage">-&gt;</span>
+    <span class="Variable">@name</span><span class="Keyword">:</span> name
 
-<span class="FunctionName">Snake::move</span><span class="Keyword">:</span> <span class="Storage">-&gt;</span>
-  alert <span class="String"><span class="String">&quot;</span>Slithering...<span class="String">&quot;</span></span>
-  <span class="Variable">super</span> <span class="Number">5</span>
-
-<span class="FunctionName">Horse</span><span class="Keyword">:</span> <span class="FunctionArgument">(</span><span class="FunctionArgument">name</span><span class="FunctionArgument">)</span> <span class="Storage">-&gt;</span>
-  <span class="Variable">@name</span><span class="Keyword">:</span> name
-  <span class="Variable">this</span>
-
-Horse <span class="Variable">extends</span> Animal
-
-<span class="FunctionName">Horse::move</span><span class="Keyword">:</span> <span class="Storage">-&gt;</span>
-  alert <span class="String"><span class="String">&quot;</span>Galloping...<span class="String">&quot;</span></span>
-  <span class="Variable">super</span> <span class="Number">45</span>
+  <span class="FunctionName">move</span><span class="Keyword">:</span> <span class="Storage">-&gt;</span>
+    alert <span class="String"><span class="String">&quot;</span>Galloping...<span class="String">&quot;</span></span>
+    <span class="Variable">super</span> <span class="Number">45</span>
 
 <span class="FunctionName">sam</span><span class="Keyword">:</span> <span class="Keyword">new</span> <span class="TypeName">Snake</span> <span class="String"><span class="String">&quot;</span>Sammy the Python<span class="String">&quot;</span></span>
 <span class="FunctionName">tom</span><span class="Keyword">:</span> <span class="Keyword">new</span> <span class="TypeName">Horse</span> <span class="String"><span class="String">&quot;</span>Tommy the Palomino<span class="String">&quot;</span></span>
@@ -1210,7 +1205,14 @@ <h2>
 
 
 
-</pre><pre class="idle"><span class="Storage">var</span> Animal, Horse, Snake, _a, _b, sam, tom;
+</pre><pre class="idle"><span class="Storage">var</span> Animal, Horse, Snake, sam, tom;
+<span class="Storage">var</span> <span class="FunctionName">__extends</span> = <span class="Storage">function</span>(<span class="FunctionArgument">child, parent</span>) {
+  <span class="Storage">var</span> <span class="FunctionName">ctor</span> = <span class="Storage">function</span>(){ };
+  <span class="LibraryClassType">ctor</span>.<span class="LibraryConstant">prototype</span> = parent.<span class="LibraryConstant">prototype</span>;
+  child.__superClass__ <span class="Keyword">=</span> parent.<span class="LibraryConstant">prototype</span>;
+  <span class="LibraryClassType">child</span>.<span class="LibraryConstant">prototype</span> = <span class="Keyword">new</span> <span class="TypeName">ctor</span>();
+  <span class="LibraryClassType">child</span>.<span class="LibraryConstant">prototype</span>.<span class="FunctionName">constructor</span> = child;
+};
 Animal <span class="Keyword">=</span> <span class="Storage">function</span> <span class="FunctionName">Animal</span>() {  };
 <span class="LibraryClassType">Animal</span>.<span class="LibraryConstant">prototype</span>.<span class="FunctionName">move</span> = <span class="Storage">function</span> <span class="FunctionName">move</span>(<span class="FunctionArgument">meters</span>) {
   <span class="Keyword">return</span> <span class="LibraryFunction">alert</span>(<span class="Variable">this</span>.<span class="LibraryConstant">name</span> <span class="Keyword">+</span> <span class="String"><span class="String">&quot;</span> moved <span class="String">&quot;</span></span> <span class="Keyword">+</span> meters <span class="Keyword">+</span> <span class="String"><span class="String">&quot;</span>m.<span class="String">&quot;</span></span>);
@@ -1219,11 +1221,7 @@ <h2>
   <span class="Variable">this</span>.<span class="LibraryConstant">name</span> <span class="Keyword">=</span> name;
   <span class="Keyword">return</span> <span class="Variable">this</span>;
 };
-<span class="FunctionName">_a</span> = <span class="Storage">function</span>(){};
-<span class="LibraryClassType">_a</span>.<span class="LibraryConstant">prototype</span> = Animal.<span class="LibraryConstant">prototype</span>;
-Snake.__superClass__ <span class="Keyword">=</span> Animal.<span class="LibraryConstant">prototype</span>;
-<span class="LibraryClassType">Snake</span>.<span class="LibraryConstant">prototype</span> = <span class="Keyword">new</span> <span class="TypeName">_a</span>();
-<span class="LibraryClassType">Snake</span>.<span class="LibraryConstant">prototype</span>.<span class="FunctionName">constructor</span> = Snake;
+__extends(Snake, Animal);
 <span class="LibraryClassType">Snake</span>.<span class="LibraryConstant">prototype</span>.<span class="FunctionName">move</span> = <span class="Storage">function</span> <span class="FunctionName">move</span>() {
   <span class="LibraryFunction">alert</span>(<span class="String"><span class="String">&quot;</span>Slithering...<span class="String">&quot;</span></span>);
   <span class="Keyword">return</span> Snake.__superClass__.move.<span class="LibraryFunction">call</span>(<span class="Variable">this</span>, <span class="Number">5</span>);
@@ -1232,11 +1230,7 @@ <h2>
   <span class="Variable">this</span>.<span class="LibraryConstant">name</span> <span class="Keyword">=</span> name;
   <span class="Keyword">return</span> <span class="Variable">this</span>;
 };
-<span class="FunctionName">_b</span> = <span class="Storage">function</span>(){};
-<span class="LibraryClassType">_b</span>.<span class="LibraryConstant">prototype</span> = Animal.<span class="LibraryConstant">prototype</span>;
-Horse.__superClass__ <span class="Keyword">=</span> Animal.<span class="LibraryConstant">prototype</span>;
-<span class="LibraryClassType">Horse</span>.<span class="LibraryConstant">prototype</span> = <span class="Keyword">new</span> <span class="TypeName">_b</span>();
-<span class="LibraryClassType">Horse</span>.<span class="LibraryConstant">prototype</span>.<span class="FunctionName">constructor</span> = Horse;
+__extends(Horse, Animal);
 <span class="LibraryClassType">Horse</span>.<span class="LibraryConstant">prototype</span>.<span class="FunctionName">move</span> = <span class="Storage">function</span> <span class="FunctionName">move</span>() {
   <span class="LibraryFunction">alert</span>(<span class="String"><span class="String">&quot;</span>Galloping...<span class="String">&quot;</span></span>);
   <span class="Keyword">return</span> Horse.__superClass__.move.<span class="LibraryFunction">call</span>(<span class="Variable">this</span>, <span class="Number">45</span>);
@@ -1245,7 +1239,14 @@ <h2>
 tom <span class="Keyword">=</span> <span class="Keyword">new</span> <span class="TypeName">Horse</span>(<span class="String"><span class="String">&quot;</span>Tommy the Palomino<span class="String">&quot;</span></span>);
 sam.move();
 tom.move();
-</pre><button onclick='javascript: var Animal, Horse, Snake, _a, _b, sam, tom;
+</pre><button onclick='javascript: var Animal, Horse, Snake, sam, tom;
+var __extends = function(child, parent) {
+  var ctor = function(){ };
+  ctor.prototype = parent.prototype;
+  child.__superClass__ = parent.prototype;
+  child.prototype = new ctor();
+  child.prototype.constructor = child;
+};
 Animal = function Animal() {  };
 Animal.prototype.move = function move(meters) {
   return alert(this.name + " moved " + meters + "m.");
@@ -1254,11 +1255,7 @@ <h2>
   this.name = name;
   return this;
 };
-_a = function(){};
-_a.prototype = Animal.prototype;
-Snake.__superClass__ = Animal.prototype;
-Snake.prototype = new _a();
-Snake.prototype.constructor = Snake;
+__extends(Snake, Animal);
 Snake.prototype.move = function move() {
   alert("Slithering...");
   return Snake.__superClass__.move.call(this, 5);
@@ -1267,11 +1264,7 @@ <h2>
   this.name = name;
   return this;
 };
-_b = function(){};
-_b.prototype = Animal.prototype;
-Horse.__superClass__ = Animal.prototype;
-Horse.prototype = new _b();
-Horse.prototype.constructor = Horse;
+__extends(Horse, Animal);
 Horse.prototype.move = function move() {
   alert("Galloping...");
   return Horse.__superClass__.move.call(this, 45);
@@ -1282,11 +1275,21 @@ <h2>
 tom.move();
 ;'>run</button><br class='clear' /></div>
     <p>
-      <b>A cautionary note:</b> JavaScript allows you to return a different value from
-      a constructor function, ignoring the newly-created object. In CoffeeScript,
-      it's best practice to always return <tt>this</tt> as the last line of a
-      constructor, as seen above.
+      If structuring your prototypes classically isn't your cup of tea, CoffeeScript
+      provides a couple of lower-level conveniences. The <tt>extends</tt> operator
+      helps with proper prototype setup, as seen above, <tt>::</tt> gives you
+      quick access to an object's prototype, and <tt>super()</tt>
+      is converted into a call against the immediate ancestor's method of the same name.
     </p>
+    <div class='code'><pre class="idle"><span class="FunctionName">String::dasherize</span><span class="Keyword">:</span> <span class="Storage">-&gt;</span>
+  <span class="Variable">this</span>.replace(<span class="String"><span class="String">/</span>_<span class="String">/</span>g</span>, <span class="String"><span class="String">&quot;</span>-<span class="String">&quot;</span></span>)
+</pre><pre class="idle"><span class="LibraryClassType">String</span>.<span class="LibraryConstant">prototype</span>.<span class="FunctionName">dasherize</span> = <span class="Storage">function</span> <span class="FunctionName">dasherize</span>() {
+  <span class="Keyword">return</span> <span class="Variable">this</span>.<span class="LibraryFunction">replace</span>(<span class="String"><span class="String">/</span>_<span class="String">/</span>g</span>, <span class="String"><span class="String">&quot;</span>-<span class="String">&quot;</span></span>);
+};
+</pre><button onclick='javascript: String.prototype.dasherize = function dasherize() {
+  return this.replace(/_/g, "-");
+};
+;alert("one_two".dasherize());'>run: "one_two".dasherize()</button><br class='clear' /></div>
 
     <p>
       <span id="pattern_matching" class="bookmark"></span>