opal 0.3.2 → 0.3.6

data/README.md

@@ -3,166 +3,124 @@ Opal: Ruby runtime for javascript
 
 **Homepage**:      [http://opalscript.org](http://opalscript.org)  
 **Github**:        [http://github.com/adambeynon/opal](http://github.com/adambeynon/opal)  
-**Documentation**: [http://adambeynon.github.com/opal/index.html](http://adambeynon.github.com/opal/index.html)  
 
 Description
 -----------
 
-Opal is a ruby runtime and set of core libraries designed to run
-directly on top of javascript. It supports the gem packaging system for
-building ruby ready for the browser. It also uses therubyracer to
-provide a command line REPL and environment for running ruby server-side
-inside a javascript context.
+Opal is a Ruby runtime and standard library designed to run directly on
+top of javascript. It can be run within the browser or on the command
+line through the bundled build tools. Opal includes a parser/compiler
+that builds ruby ahead of time directly into javascript that runs with
+the bundled runtime.
+
+Features
+--------
+
+* Full method\_missing support for all objects and classes
+* Debug mode to provide stack traces and arg checking
+* Private and public method support
+* Full operator overloading (`[]`, `[]=`, `+`, `-`, `==`, etc)
+* Toll free bridges to javascript objects (`String`, `Number`, `Array`
+  etc)
+* Inline javascript within ruby code using backticks
+* In browser loading of `<script type="text/ruby></script>` tags
+* Generated code is clean and maintains line numbers to ease debugging
+* super(), metaclasses, eigenclasses, blocks, yield, block\_given?,
+  ranges, arg count errors, lambda, singletons, etc....
 
 Installation
 ------------
 
-Opal is distributed as a gem, so install with:
+The best way to get started with opal is to clone this repo and use the
+`opal` bin file directly:
 
-    $ gem install opal
+    $ git clone git://github.com/adambeynon/opal.git
 
-Alternativley, you may just clone this git repo. No building is
-neccessary.
+Although opal is distributed as a gem, the latest gem release is mostly
+incompatible with the loading and runtime system for opal, so until a
+newer gem is released (0.3.5), it is best to stick with the repo.
+
+### Try without installing
+
+Browser can be used inside a repl on the
+[http://opalscript.org](http://opalscript.org) homepage which gives an
+IRB style interface for running ruby code which is compiled and
+evaluated within the browser (no plugins!).
+
+Alternatively the opal runtime and opal parser can be downloaded
+directly from the `extras` directory in this repository.
 
 Usage
 -----
 
-The opal build tools can be used in three ways. As a simple repl, the
-bundler tasks and the simple build tasks.
+Opal can be used within in the browser, or on the command line using the
+build tools. A Nodejs environment is also partially implemented.
 
-**1. opal Command-line tool**
+### Browser
 
-In its current form, the `opal` executable is very simple - it provides
-a simple ruby repl that uses therubyracer to provide an embedable
-javascript context. If you have installed the gem, to run the REPL,
-simply type:
+To run within the browser, you can either use the latest build version
+on the opal website, or clone the build tools as above, and then run the
+following task in this directory:
 
-    $ opal
+    $ rake opal
 
-or if you have cloned this repository, type:
+This will place a non minified version ready to run within the browser
+into `extras/opal.js`
 
-    $ bin/opal
+#### Compiling ruby sources
 
-The REPL can be used like any other repl, and internally each command is
-being compiled into javascript, and run in the context which opal is
-already loaded into.
+To run ruby code in the browser, ruby must either be precompiled to
+javascript using these build tools, or the `opal_dev.js` file can parse
+and compile ruby code referenced in html `script` tags that use the
+`text/ruby` type.
 
-**2. Builder Rake Task**
+### Command line
 
-To build simple ruby files (without a .gemspec) is to use the
-BuilderTask class in a rake file. This can be done by adding the
-following to a `Rakefile`:
+Opal is bundled with a set of build tools available in the `opalite/`
+directory. These are available when running opal from the command line
+or including it from ruby sources.
 
-    require 'opal'
+#### Ruby repl
 
-    Opal::Rake::BuilderTask.new do |t|
-      t.files   = 'ruby/**/*.rb'
-      t.out     = 'js/ruby_code.js'
-    end
+To run the repl, clone this repo as directed above and run:
 
-When using the rake task, the `files` and `out` optional are usually
-best required. The `files` will take an array, or a single string, and
-can be globs. It is important to use relative paths here not absolute
-paths. This will be default create a rake task called `opal` in your
-rakefile, but you can rename it by passing another name into `new`. To
-compile the javascript run:
+    $ bin/opal irb
 
-    $ rake opal
+This will act like any other repl to try out commands. The repl relies
+on `therubyracer` as its javascript engine.
 
-The out file will now contain the compiled ruby code. Run this in a
-browser by including it into a html document, but make sure to include
-the latest `opal.js` file first.
+Running tests
+-------------
 
-**Main file**
+Opal uses a subset of the `rubyspec` specs for ruby until it reaches a
+mature enough state to just use rubyspec directly. These tests are found
+in the `spec/` folder. They can be run either through the command line,
+or built ready to open in the browser.
 
-By default the builder task will automatically load the first listed
-file in the `files` array when the file is loaded in the browser. The
-`main` option allows you to specify another file:
+### Running in the browser
 
-    Opal::Rake::BuilderTask.new do |t|
-      t.files = ['ruby/file_1.rb', 'ruby/file_2.rb', 'ruby/file_3.rb']
-      t.out   = 'out.js'
-      t.main  = 'ruby/file_2.rb'
-    end
+To run in the browser, first build the specs (compile into js ready):
 
-**File watching**
+    $ rake opal_spec
 
-To save manually compiling each time you change a file, the `watch`
-option can be set to automatically recompile everytime a listed file is
-modified. Observe the command line after using this task:
+This will build the specs into `extras/` so open `extras/opal.spec.html`
+in any browser to see how the specs run.
 
-    Opal::Rake::BuilderTask.new do |t|
-      t.files  = 'ruby/*.rb'
-      t.out    = 'my_code.js'
-      t.watch  = true
-    end
+### Running on command line
 
-Built-in gems
-------------
+The opal binary has a `spec` flag which can be passed one or any number
+of specs. For example, to run the `and` and `&&` specs from this repo,
+run:
+
+    $ bin/opal spec spec/language/and_spec.rb
+
+Between gem releases every spec will pass. The master branch in this
+repo may contain broken specs, but these will be fixed before the next
+gem release and version bump.
+
+Examples
+--------
 
-Opal uses gems as the main means of distributing and building code ready
-for the browser. Opal uses its own gem system, and cannot access gems
-included in the standard ruby installation. To aid this, the actual opal
-gem includes several gems that offer the basic features. These gems are:
-
-**core**
-
-The core gem offers the ruby core library. It is mostly written in ruby,
-but has a large proportion of inline javascript to make it as performant
-as possible. Many of the classes are toll-free bridged to native
-javascript objects, including Array, String, Numeric and Proc. Read the
-[core library documentation](http://adambeynon.github.com/opal/gems/core/index.html)
-for more information.
-
-**dev**
-
-The dev gem contains a ruby parser and compiler written in javascript.
-It is a clone of the default opal parser written in ruby. This gem is in
-the process of being replaced with the pure ruby version, which will be
-compiled into javascript for this gem. This gem can be loaded into
-javascript to allow in browser compilation of ruby sources from external
-files or through html `script` tags.
-
-**json**
-
-The json gem included methods for parsing json strings and then
-generating json objects from a string of json code. This gem aims to be
-API compatible with the standard json library. Similarly to that
-library, json objects are mapped to Hash, Array, true, false, nil,
-String and Numeric as appropriate. See the
-[JSON documentation](http://adambeynon.github.com/opal/gems/json/index.html)
-for the full api.
-
-**rquery**
-
-RQuery is a port/abstraction of the jQuery javascript library for DOM
-manipulation. jQuery is actually included as part of the gem, and top
-level classes like Element, Document and Request are used to interact
-with the document and elements. The api tries to stay as close to the
-jquery interface as possible, but adds appropriate ruby syntax features
-on top. See the [rquery documentation](http://adambeynon.github.com/opal/gems/rquery/index.html)
-for the full api.
-
-**ospec**
-
-OSpec is a minimal clone of the ruby rspec library. It implements the
-core features available in rspec, and works both from the command line
-and in browser. The core, json and rquery gems all have tests/specs
-written ready for ospec. See the [ospec guide](http://adambeynon.github.com/opal/gems/ospec/index.html)
-to get started.
-
-Changelog
----------
-
-- **31 March 2011**: 0.3.2 Release
-    - Added BuilderTask for easy building for simple projects.
-    - Amended build options in Builder to support new rake task.
-
-- **30 March 2011**: 0.3.1 Release
-    - Fix to make `opal` an executable
-
-- **30 March 2011**: 0.3.0 Release
-    - Major redesign of build tools to use v8 for server side opal
-    - Split all opal packages into actual gems
-    - File and Dir classes for both browser and v8 gem runtimes
+Examples can be found in the `examples/` directory in this repo, and
+rely on `extras/opal.js` being created using the above commands.
 

data/bin/opal

@@ -1,10 +1,10 @@
 #!/usr/bin/env ruby
 
-lib = File.expand_path(File.dirname(__FILE__) + '/../lib')
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+opal_lib = File.expand_path('../../opal_lib', __FILE__)
+$:.unshift opal_lib unless $:.include? opal_lib
 
 require 'opal'
 require 'opal/command'
 
-Opal::Command.ruby_repl
+Opal::Command.start
 

data/lib/core.rb

@@ -0,0 +1,114 @@
+class Module
+
+  def private(*args)
+    `$rb.private_methods(self, args);`
+    self
+  end
+
+  def public(*args)
+    `$rb.public_methods(self, args);`
+    self
+  end
+
+  def include(*mods)
+    `var i = mods.length - 1, mod;
+    while (i >= 0) {
+      mod = mods[i];
+      #{`mod`.append_features self};
+      #{`mod`.included self};
+      i--;
+    }
+    return self;`
+  end
+
+  def append_features(mod)
+    `$rb.include_module(mod, self);`
+    self
+  end
+
+  def included(mod)
+    nil
+  end
+end
+
+module Kernel
+  private
+
+  # Try to load the library or file named `path`. An error is thrown if the
+  # path cannot be resolved.
+  #
+  # @param [String] path The path to load
+  # @return [true, false]
+  def require(path)
+    `$rb.require(path) ? Qtrue : Qfalse;`
+    true
+  end
+
+  # Prints the message to `STDOUT`.
+  #
+  # @param [Array<Object>] args Objects to print using `to_s`
+  # @return [nil]
+  def puts(*a)
+    $stdout.puts *a
+    nil
+  end
+end
+
+class << $stdout
+  # FIXME: Should this really be here? We only need to override this when we
+  # are in the browser context as we don't have native access to file
+  # descriptors etc
+  def puts(*a)
+    `for (var i = 0, ii = a.length; i < ii; i++) {
+      console.log(#{`a[i]`.to_s}.toString());
+    }`
+    nil
+  end
+end
+
+class Object
+  include Kernel
+end
+
+class Symbol
+  def to_s
+    `return self.toString();`
+  end
+end
+
+class String
+  def to_s
+    `return self.toString();`
+  end
+end
+
+require 'core/basic_object'
+require 'core/object'
+require 'core/module'
+require 'core/class'
+require 'core/kernel'
+require 'core/top_self'
+require 'core/nil_class'
+require 'core/true_class'
+require 'core/false_class'
+require 'core/enumerable'
+require 'core/array'
+require 'core/numeric'
+require 'core/hash'
+require 'core/error'
+require 'core/string'
+require 'core/symbol'
+require 'core/proc'
+require 'core/range'
+require 'core/regexp'
+require 'core/match_data'
+require 'core/file'
+require 'core/dir'
+
+`var platform = opal.platform;`
+RUBY_PLATFORM = `platform.platform`
+RUBY_ENGINE = `platform.engine`
+RUBY_VERSION = `platform.version`
+
+ARGV = `platform.argv`
+

data/{gems/core/lib → lib}/core/array.rb

@@ -1,55 +1,5 @@
-# Arrays are ordered collections, indexed by integers starting at `0`.
-# Indexes may be negative, where `-1` represents the last item in the
-# array, `-2` the last but one, etc. Arrays may be constructed by using a
-# method like {Array.[]}, or by using an array literal:
-#
-#     Array[1, 2, 3, 4, 5]   # => [1, 2, 3, 4, 5]
-#     ['a', 'b', 'c', 'd']   # => ["a", "b", "c", "d"]
-#
-# Implementation details
-# ----------------------
-#
-# Ruby arrays are toll-free bridged to native javascript arrays, meaning
-# that anywhere that a ruby array is required, a normal javascript array
-# may be passed instead. The {Array} class infact makes use of a lot of
-# the standard javascript functions on array prototypes to make its
-# functionality as fast as possible.
-#
-# Due to the fact that arrays may be constructed in a javascript
-# environment, and then passed through to a ruby method, Opal cannot
-# guarantee that an array will not have a bad value. Bad values are
-# those which ruby cannot send messages to, and therefore is an object
-# that will raise an error when it is accessed by methods in {Array}, or
-# any other object accessing an arrays elements. Bad values from
-# javascript include the native `true`, `false`, `null` and `undefined`
-# values from javascript, as well as any object literal.
-#
-# Ruby compatibility
-# ------------------
-#
-# As instances of {Array} are actually javascript arrays, they can
-# perform all the same functionality as Rubyspec defines arrays should.
-# While not 100% of methods are currently implemented, the missing
-# methods are being added quickly. All implemented methods are listed in
-# this file. Any method that is only partially implemented also contains
-# a list of restrictions in its description.
-#
-# The main area of partialy implemented methods are the enumerating
-# methods like {#each}, {#each\_index} and {#reverse\_each}. Rubyspec
-# defines that they should return an Enumerator if no block is passed to
-# that method. Currently this does not happen, and `self` is returned
-# with no side effects.
-#
-# Custom subclasses of {Array} may also be defined, and this is
-# implemented in {.allocate}, when the array is created using {.new}.
-# Internally a native javascript array is still used, but its class and
-# method table are swizzled.
-#
-# Finally the {Array} class does not include the Enumerable module. Its
-# methods are mostly implemented directly on the Array class. The
-# Enumerable module will be added shortly, and the relevant methods
-# moved back into that module.
 class Array
+  # include Enumerable
 
   # Returns a new array populated with the given objects.
   #
@@ -57,24 +7,30 @@ class Array
   #
   #     Array['a', 'b', 'c']    # => ['a', 'b', 'c']
   #
-  # **FIXME** should support custom subclasses
-  #
   # @param [Object] objs
   # @return [Array]
   def self.[](*objs)
-    objs
+    `var ary = #{allocate};
+    ary.splice.apply(ary, [0, 0].concat(objs));
+    return ary;`
   end
 
-  # **FIXME** should support custom subclasses
   def self.allocate
-    []
+    `var arr = [];
+    arr.$klass = self;
+    arr.$m = self.$m_tbl;
+    return arr;`
   end
 
-  def initialize(*objs)
-    `for (var i = 0, length = objs.length; i < length; i++) {
-      self.push(objs[i]);
+  def initialize(len, fill = nil)
+    `var ary = self;
+
+    for (var i = 0; i < len; i++) {
+      ary[i] = fill;
     }
 
+    ary.length = len;
+
     return self;`
   end
 
@@ -132,9 +88,7 @@ class Array
     `return self.length;`
   end
 
-  def size
-    `return self.length;`
-  end
+  alias_method :size, :length
 
   # Yields the block once for each element in `self`, passing that element as
   # a parameter.
@@ -153,39 +107,23 @@ class Array
   #
   # @return [Array] returns the receiver
   def each
-    `for (var i = 0, length = self.length; i < length; i++) {
-      try {
-        #{yield `self[i]`};
-      } catch (e) {
-        switch (e.$keyword) {
-          case 2:
-            return e.$value;
-          default:
-            throw e;
-        }
-      }
-    }
+    raise "Array#each no block given" unless block_given?
 
-    return self;`
+    `for (var i = 0, len = self.length; i < len; i++) {`
+      yield `self[i]`
+    `}`
+    self
   end
 
   # Similar to {#each}, but also passes in the current element index to the
   # block.
   def each_with_index
-    `for (var i = 0, length = self.length; i < length; i++) {
-      try {
-        #{yield `self[i]`, `i`};
-      } catch (e) {
-        switch (e.$keyword) {
-          case 2:
-            return e.$value;
-          default:
-            throw e;
-        }
-      }
-    }
+    raise "Array#each_with_index no block given" unless block_given?
 
-    return self;`
+    `for (var i = 0, len = self.length; i < len; i++) {
+      #{ yield `self[i]`, `i` };
+    }`
+    self
   end
 
   # Same as {#each}, but passes the index of the element instead of the 
@@ -205,20 +143,12 @@ class Array
   #
   # @return [Array] returns receiver
   def each_index
-    `for (var i = 0, length = self.length; i < length; i++) {
-      try {
-        #{yield `i`};
-      } catch (e) {
-        switch (e.$keyword) {
-          case 2:
-            return e.$value;
-          default:
-            throw e;
-        }
-      }
-    }
+    raise "Array#each_index no block given" unless block_given?
 
-    return self;`
+    `for (var i = 0, len = self.length; i < len; i++) {`
+      yield `i`
+    `}`
+    self
   end
 
   # Append - pushes the given object(s) onto the end of this array. This
@@ -234,10 +164,9 @@ class Array
   # @param [Object] obj the object(s) to push onto the array
   # @return [Array] returns the receiver
   def push(*objs)
-    `for (var i = 0, length = objs.length; i < length; i++) {
+    `for (var i = 0, ii = objs.length; i < ii; i++) {
       self.push(objs[i]);
     }
-
     return self;`
   end
 
@@ -256,7 +185,7 @@ class Array
   # @param [Object] obj the object to look for
   # @return [Numeric, nil] result
   def index(obj)
-    `for (var i = 0, length = self.length; i < length; i++) {
+    `for (var i = 0, len = self.length; i < len; i++) {
       if (#{`self[i]` == obj}.$r) {
         return i;
       }
@@ -276,7 +205,7 @@ class Array
   # @param [Array] other the array to concat with
   # @return [Array] returns new concatenated array
   def +(other)
-    `return self.concat(other);`
+    `return self.slice(0).concat(other.slice());`
   end
 
   # Difference. Creates a new array that is a copy of the original array,
@@ -392,19 +321,11 @@ class Array
   def select
     `var result = [], arg;
 
-    for (var i = 0; i < self.length; i++) {
-      try {
-        arg = self[i];
-        if (#{yield `arg`}.$r) {
-          result.push(arg);
-        }
-      } catch (e) {
-        switch (e.$keyword) {
-          case 2:
-            return e.$value;
-          default:
-            throw e;
-        }
+    for (var i = 0, ii = self.length; i < ii; i++) {
+      arg = self[i];
+
+      if (#{yield `arg`}.$r) {
+        result.push(arg);
       }
     }
 
@@ -422,25 +343,18 @@ class Array
   #
   # @return [Array] new array
   def collect
+    raise "Array#collect no block given" unless block_given?
+
     `var result = [];
 
-    for (var i = 0; i < self.length; i++) {
-      try {
-        result.push(#{yield `self[i]`});
-      } catch (e) {
-        switch (e.$keyword) {
-          case 2:
-            return e.$value;
-          default:
-            throw e;
-        }
-      }
+    for (var i = 0, ii = self.length; i < ii; i++) {
+      result.push(#{ yield `self[i]` });
     }
 
     return result;`
   end
 
-  # alias_method 'map', 'collect'
+  alias_method :map, :collect
 
   # Yields the block once for each element of `self`, replacing the element with
   # the value returned by the block. See also `Enumerable#collect`.
@@ -455,17 +369,8 @@ class Array
   #
   # @return [Array] returns the receiver
   def collect!
-    `for (var i = 0; i < self.length; i++) {
-      try {
-        self[i] = #{yield `self[i]`};
-      } catch (e) {
-        switch (e.$keyword) {
-          case 2:
-            return e.$value;
-          default:
-            throw e;
-        }
-      }
+    `for (var i = 0, ii = self.length; i < ii; i++) {
+      self[i] = #{yield `self[i]`};
     }
 
     return self;`
@@ -632,25 +537,17 @@ class Array
   #
   # @return [Array] returns amended receiver
   def delete_if
-    `for (var i = 0; i < self.length; i++) {
-      try {
-        if (#{yield `self[i]`}.$r) {
-          self.splice(i, 1);
-          i--;
-        }
-      } catch (e) {
-        switch(e.$keyword) {
-          case 2:
-            return e.$value;
-          default:
-            throw e;
-        }
+    `for (var i = 0, ii = self.length; i < ii; i++) {
+      if (#{yield `self[i]`}.$r) {
+        self.splice(i, 1);
+        i--;
+        ii = self.length;
       }
     }
-
     return self;`
   end
 
+
   # Drop first `n` elements from receiver, and returns remaining elements in
   # array.
   #
@@ -1013,7 +910,6 @@ class Array
     for (var i = 0; i < self.length; i++) {
       test = self[i];
       if (test.hasOwnProperty('length') && test[1] != undefined) {
-        console.log("trying " + i);
         if (#{`test[1]` == obj}.$r) return test;
       }
     }
@@ -1127,17 +1023,10 @@ class Array
   #
   # @return [Array] returns the receiver
   def reverse_each
-    `for (var i = self.length - 1; i >= 0; i--) {
-      try {
-        #{yield `self[i]`};
-      } catch (e) {
-        switch (e.$keyword) {
-          case 2:
-            return e['@exit_value'];
-          default:
-            throw e;
-        }
-      }
+    `var ary = self, len = ary.length;
+
+    for (var i = len - 1; i >= 0; i--) {
+      #{yield `ary[i]`};
     }
 
     return self;`
@@ -1295,23 +1184,14 @@ class Array
   #
   # @return [Array] new array with elements
   def take_while
-    `var result = [];
-
-    for (var i = 0; i < self.length; i++) {
-      try {
-        if (#{yield `self[i]`}.$r) {
-          result.push(self[i]);
-        } else {
-          break;
-        }
-      } catch (e) {
-        switch (e.$keyword) {
-          case 2:
-            return e['@exit_value'];
+    `var result = [], arg;
 
-          default:
-            throw e;
-        }
+    for (var i = 0, ii = self.length; i < ii; i++) {
+      arg = self[i];
+      if (#{yield `arg`}.$r) {
+        result.push(self[i]);
+      } else {
+        break;
       }
     }
 
@@ -1490,7 +1370,7 @@ class Array
   # @param [Numeric] length last index
   # @return [Array, Object, nil] result
   def [](index, length = `undefined`)
-    `var size = self.length;
+    `var ary = self, size = ary.length;
 
     if (index < 0) index += size;
 
@@ -1498,9 +1378,9 @@ class Array
 
     if (length != undefined) {
       if (length <= 0) return [];
-      return self.slice(index, index + length);
+      return ary.slice(index, index + length);
     } else {
-      return self[index];
+      return ary[index];
     }`
   end
 
@@ -1508,7 +1388,8 @@ class Array
   #
   # **TODO** need to expand functionlaity.
   def []=(index, value)
-    `return self[index] = value;`
+    `if (index < 0) index += self.length;
+    return self[index] = value;`
   end
 end