opal 0.3.1 → 0.3.2

data/Changelog

@@ -0,0 +1,31 @@
+2011-03-31  Adam Beynon <adam@adambeynon.com>
+
+  * Changelog, README.md, opal.gemspec: Update to 0.3.2
+
+  * lib/opal/rake/builder_task.rb: Added task used in Rakefiles for
+  building simple opal projects.
+
+  * lib/opal/builder.rb: Update builder options to correctly glob files
+  passed as strings or arrays.
+
+  * lib/opal.rb: Load builder tasks for rakefiles.
+
+  * README.md: Update to list packaged gems and links to relevant docs.
+  Also added docs on using BuilderTask.
+
+  * gems/core/Rakefile: Use markdown for markup in documentation.
+
+  * gems/core/lib/core/object.rb: Add core Object class to aid
+  documentation.
+
+  * gems/core/lib/core.rb, gems/core/lib/core/array.rb,
+  gems/core/lib/core/basic_object.rb, gems/core/lib/core/class.rb,
+  gems/core/lib/core/error.rb, gems/core/lib/core/false_class.rb,
+  gems/core/lib/core/hash.rb, gems/core/lib/core/kernel.rb,
+  gems/core/lib/core/module.rb, gems/core/lib/core/nil_class.rb,
+  gems/core/lib/core/numeric.rb, gems/core/lib/core/proc.rb,
+  gems/core/lib/core/regexp.rb, gems/core/lib/core/string.rb,
+  gems/core/lib/core/symbol.rb, gems/core/lib/core/true_class.rb: Update
+  core documentation with implementation details for toll free classes
+  and special use information.
+

data/README.md

@@ -3,6 +3,7 @@ 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
 -----------
@@ -46,9 +47,117 @@ 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.
 
+**2. Builder Rake Task**
+
+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`:
+
+    require 'opal'
+
+    Opal::Rake::BuilderTask.new do |t|
+      t.files   = 'ruby/**/*.rb'
+      t.out     = 'js/ruby_code.js'
+    end
+
+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:
+
+    $ rake opal
+
+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.
+
+**Main file**
+
+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:
+
+    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
+
+**File watching**
+
+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:
+
+    Opal::Rake::BuilderTask.new do |t|
+      t.files  = 'ruby/*.rb'
+      t.out    = 'my_code.js'
+      t.watch  = true
+    end
+
+Built-in gems
+------------
+
+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
 

data/gems/core/README.md

@@ -1,5 +1,14 @@
 Core Library
 ============
 
-Core ruby libraries for opal.
+**Homepage**:      [http://opalscript.org](http://opalscript.org)  
+**GitHub**:        [http://github.com/adambeynon/opal](http://github.com/adambeynon/opal)  
+
+Synopsis
+--------
+
+This gem contains the core library implementation for opal. It is kept
+as a seperate gem so that the base opal.js loader simply contains the
+core runtime and object hierarchy setup, and then this gem simply
+implements the methods for the standard library.
 

data/gems/core/Rakefile

@@ -2,6 +2,7 @@ require 'yard'
 
 YARD::Rake::YardocTask.new do |t|
   t.files   = ['lib/**/*.rb']
-  t.options = ['--title', 'Opal Core Library']
+  t.options = ['--title', 'Documentation for Opal Core Library',
+              '--markup', 'markdown']
 end
 

data/gems/core/lib/core.rb

@@ -12,6 +12,7 @@ module Kernel
 end
 
 require 'core/basic_object'
+require 'core/object'
 require 'core/module'
 require 'core/class'
 require 'core/kernel'

data/gems/core/lib/core/array.rb

@@ -1,19 +1,63 @@
-# Arrays are ordered, indexed by integers starting at 0
+# 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.
 #
-# For efficiency, an array instance is simply a native javascript array. There
-# is no wrapping, it is simply a toll-free class
+# 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
+
   # Returns a new array populated with the given objects.
   #
   # @example
   #
-  #     Array['a', 'b', 'c']
-  #     # => ['a', 'b', 'c']
+  #     Array['a', 'b', 'c']    # => ['a', 'b', 'c']
   #
-  # FIXME should support custom subclasses
+  # **FIXME** should support custom subclasses
   #
   # @param [Object] objs
   # @return [Array]
@@ -21,7 +65,7 @@ class Array
     objs
   end
 
-  # FIXME should support custom subclasses
+  # **FIXME** should support custom subclasses
   def self.allocate
     []
   end
@@ -105,7 +149,7 @@ class Array
   #     # => 'b'
   #     # => 'c'
   #
-  # TODO: needs to return enumerator for no block.
+  # **TODO** needs to return enumerator for no block.
   #
   # @return [Array] returns the receiver
   def each
@@ -149,7 +193,7 @@ class Array
   #
   # If no block given, an enumerator is returned instead.
   #
-  # TODO: enumerator functionality not yet implemented.
+  # **TODO** enumerator functionality not yet implemented.
   #
   # @example
   #
@@ -250,8 +294,8 @@ class Array
   end
 
   # Equality. Two arrays are equal if they contain the same number of elements
-  # and if each element is equal to (according to {Object#==} the corresponding
-  # element in the second array.
+  # and if each element is equal to (according to {BasicObject#==} the
+  # corresponding element in the second array.
   #
   # @example
   #
@@ -275,9 +319,9 @@ class Array
   end
 
   # Searches through an array whose elements are also arrays, comparing `obj`
-  # with their first element of each contained array using {Object#==}. Returns
-  # the first contained array that matches (that is, the first associated array)
-  # or `nil` if no match is found. See also {#rassoc}.
+  # with their first element of each contained array using {BasicObject#==}.
+  # Returns the first contained array that matches (that is, the first
+  # associated array) or `nil` if no match is found. See also {#rassoc}.
   #
   # @example
   #
@@ -368,7 +412,7 @@ class Array
   end
 
   # Yields the block once for each element of the receiver. Creates a new array
-  # containing the values returned by the block. See also {Enumerable#collect}.
+  # containing the values returned by the block. See also `Enumerable#collect`.
   #
   # @example
   #
@@ -399,7 +443,7 @@ class Array
   # 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}.
+  # the value returned by the block. See also `Enumerable#collect`.
   #
   # @example
   #
@@ -978,7 +1022,7 @@ class Array
   end
 
   # Returns a new array containing the items in `self` for which the block is
-  # not true. See also {#delete_if}.
+  # not true. See also `#delete_if`.
   #
   # @example
   #
@@ -1001,7 +1045,7 @@ class Array
     return result;`
   end
 
-  # Equivalent to {#delete_if!}, deleting elements from self for which the block
+  # Equivalent to `#delete_if!`, deleting elements from self for which the block
   # evaluates to true, but returns nil if no changes were made.
   #
   # @example
@@ -1161,7 +1205,7 @@ class Array
   # elements down by one). Returns `nil` if the array is empty.
   #
   # If a number `n` is given, returns an array of the first n elements (or 
-  # less), just like {#slice} does.
+  # less), just like `#slice` does.
   #
   # @example
   #
@@ -1206,7 +1250,7 @@ class Array
   #     a.slice! 100
   #     # => nil
   #
-  # TODO does not yet work with ranges
+  # **TODO** does not yet work with ranges
   #
   # @param [Range, Number] index to begin with
   # @param [Number] length last index
@@ -1440,7 +1484,7 @@ class Array
   #     a[5, 1]                         # => []
   #     a[5..10]                        # => []
   #
-  # @TODO: does not yet work with ranges
+  # **TODO** does not yet work with ranges
   #
   # @param [Range, Numeric] index to begin
   # @param [Numeric] length last index
@@ -1462,7 +1506,7 @@ class Array
 
   # Element reference setting.
   #
-  # @TODO: need to expand functionlaity.
+  # **TODO** need to expand functionlaity.
   def []=(index, value)
     `return self[index] = value;`
   end

data/gems/core/lib/core/basic_object.rb

@@ -1,3 +1,8 @@
+# BasicObject is the root object in opal. Even {Object} inherits from
+# {BasicObject}. Instances of BasicObject (or subclasses of) are useful
+# as they give almost a clean interface in which the absolute minimum of
+# methods are defined on it. It therefore becomes useful for such
+# applications as HashStructs.
 class BasicObject
   def initialize
     # ...
@@ -11,5 +16,19 @@ class BasicObject
   def equal?(other)
     self == other
   end
+
+  def __send__(method_id, *args)
+    `args.unshift(self);
+    return self.$m[#{method_id.to_s}].apply(self, args);`
+  end
+
+  def instance_eval(&block)
+    `block(self)` if block_given?
+    self
+  end
+
+  def method_missing(sym, *args)
+    raise NoMethodError, "undefined method `#{sym}` for #{self.inspect}"
+  end
 end
 

data/gems/core/lib/core/class.rb

@@ -1,4 +1,4 @@
-class Class
+class Class < Module
 
   # def new(*args)
   #   `var obj = self.$m.allocate(self);

data/gems/core/lib/core/error.rb

@@ -1,9 +1,44 @@
+# Instances of {Exception} and its subclasses are used to hold error
+# information between `raise` calls, `begin` blocks and `rescue` statements.
+# `Exceptions` will hold an optional `message`, which is a description
+# of the error that occured. The exception `type` is also useful, and is
+# just the name of the class that is a decendant of `Exception`.
+# Subclasses are generally made of `StandardError`, but a subclass of
+# any core `Exception` class is valid.
+#
+# Implementation details
+# ----------------------
+#
+# Inside opal, exceptions are instances of the native javascript `Error`
+# objects. This allows an efficient means to "piggy-back" the javascript
+# try/catch/finally statements, as well as the `throw` statement for
+# actually raising exceptions.
+#
+# Subclasses of `Exception` can also be used on top of `Error`, and the
+# correct class and method tables for these subclasses are set in
+# {.allocate}.
+#
+# Exceptions cannot be altered once created, so their message is
+# permanently fixed. To improve debugging opal, once an exception it
+# {#initialize}, the native error has its `.message` property set to a
+# descriptive name with the format `ErrorClassName: error_message`. This
+# helps to observe top level error statements appearing in debug tools.
+# The original error message may be received using the standard
+# {#message} or {#to_s} methods.
+#
+# Accessing the `backtrace` of an exception is platform dependant. It is
+# fully supported on the server side v8 context, but differs in the
+# browser context as some browsers have better support than others. The
+# backtrace should not be relied on, and is supported purely on a
+# platform to platform basis.
 class Exception
-  # we also need to set err.$m to the right method table incase a subclass adds
+
+  # We also need to set err.$m to the right method table incase a subclass adds
   # custom methods.. just get this from the klass: self.
   def self.allocate
     `var err = new Error();
     err.$klass = self;
+    err.$m = self.$m_tbl;
     return err;`
   end
 

data/gems/core/lib/core/false_class.rb

@@ -1,17 +1,77 @@
+# Instances of `FalseClass` represent logically false values. There may
+# only be one instance of `FalseClass`, which is the global value
+# `false`. Attempts to create a new instance will yield an error.
+# `FalseClass` provides methods to perform logical operations with other
+# ruby objects.
+#
+# Implementation details
+# ----------------------
+#
+# Due to the way messages are passed inside opal, `false` is not
+# actually toll-free bridged onto the native javascript `false` value.
+# In javascript, `false` and `true` are both instances of the Boolean
+# type, which means they would need to share the same method_table in
+# opal, which would remove their ability to be true instances of Rubys'
+# `TrueClass` or `FalseClass`.
+#
+# As javascripts `false` is not actually the value used in opal, passing
+# the native `false` value will cause errors when messages are sent to
+# it. Within a file directly loaded by opal, `Qfalse` is a free variable
+# that points to the actualy ruby instance of this class. This variable
+# may be passed around freely.
 class FalseClass
 
+  # Returns a string representation of `false`, which is simply
+  # `"false"`.
+  #
+  # @example
+  #
+  #     false.to_s    # => "false"
+  #
+  # @return [String]
   def to_s
     "false"
   end
 
+  # And; This always returns `false`.
+  #
+  # @example
+  #
+  #     false & true    # => false
+  #     false & nil     # => false
+  #     false & false   # => false
+  #
+  # @return [false]
   def &(other)
     false
   end
 
+  # Or; If `other` is `false` or `nil`, returns `false`, otherwise
+  # returns `true`.
+  #
+  # @example
+  #
+  #     false & false     # => false
+  #     false & nil       # => false
+  #     false & true      # => true
+  #     false & [1, 2, 3] # => true
+  #
+  # @return [true, false]
   def |(other)
     `return other.$r ? Qtrue : Qfalse;`
   end
 
+  # Exclusive Or; If `other` is `false` or `nil`, then it returns
+  # `false`, otherwise returns `true`.
+  #
+  # @example
+  #
+  #     false & false     # => false
+  #     false & nil       # => false
+  #     false & true      # => true
+  #     false & [1, 2, 3] # => true
+  #
+  # @return [true, false]
   def ^(other)
     `return other.$r ? Qtrue : Qfalse;`
   end

data/gems/core/lib/core/hash.rb

@@ -1,10 +1,42 @@
-# A Hash is a collection of key-value pairs. It is similar to an array except
+# A `Hash` is a collection of key-value pairs. It is similar to an array except
 # that indexing is done via arbitrary keys of any object type, not an integer
 # index. Hahses enumerate their values in the order that the corresponding keys
 # were inserted.
 #
 # Hashes have a default value that is returned when accessing keys that do not
 # exist in the hash. By default, that valus is `nil`.
+#
+# Implementation details
+# ----------------------
+#
+# An Opal hash is actually toll-free bridged to a custom javascript
+# prototype called RHash. This is all handled internally and is actually
+# just an implementation detail, and is only done for the convenience of
+# construction through literals and methods such as {Hash.new}.
+#
+# Although its syntax is similar to that of an object literal in
+# javascript, it is very important to know that they are completely
+# different, and a javascript/json object cannot be used in place of a
+# ruby hash. All ruby objects require, at minimum, a `.$m` property
+# which is their method table. When trying to send a message to a non
+# ruby object, like a javascript object, errors will start occuring when
+# this method table is not found.
+#
+# Hash and the JSON gem contain methods for converting native objects into
+# `Hash` instances, so those should be used if you need to use objects from
+# an external javascript library.
+#
+# Ruby compatibility
+# ------------------
+#
+# `Hash` implements the majority of methods from the ruby standard
+# library, and those that are not implemented are being added
+# constantly.
+#
+# The `Enumerable` module is not yet implemented in opal, so most of the
+# relevant methods used by `Hash` are implemented directly into this class.
+# When `Enumerable` gets implemented, the relevant methods will be moved
+# back into that module.
 class Hash
   # Returns a new array populated with the values from `self`.
   #
@@ -116,7 +148,7 @@ class Hash
   end
 
   # Equality - Two hashes are equal if they each contain the same number of keys
-  # and if each key-value paid is equal, accordind to {Object#==}, to the
+  # and if each key-value paid is equal, accordind to {BasicObject#==}, to the
   # corresponding elements in the other hash.
   #
   # @example

data/gems/core/lib/core/kernel.rb

@@ -1,3 +1,6 @@
+# The {Kernel} module is directly included into {Object} and provides a
+# lot of the core object functionality. It is not, however, included in
+# {BasicObject}.
 module Kernel
   # Repeatedly executes the given block.
   #
@@ -107,10 +110,6 @@ module Kernel
     false
   end
 
-  def method_missing(sym, *args)
-    raise NoMethodError, "undefined method `#{sym}` for #{self.inspect}"
-  end
-
   def to_a
     [self]
   end
@@ -171,11 +170,6 @@ module Kernel
     self == other
   end
 
-  def __send__(method_id, *args)
-    `args.unshift(self);
-    return self.$m[#{method_id.to_s}].apply(self, args);`
-  end
-
   def send(method_id, *args)
     __send__ method_id, *args
   end
@@ -224,11 +218,6 @@ module Kernel
     to_s
   end
 
-  def instance_eval(&block)
-    `block(self)` if block_given?
-    self
-  end
-
   def const_set(name, value)
     `return rb_const_set(VM.class_real(self.$klass), name, value);`
   end

data/gems/core/lib/core/module.rb

@@ -1,4 +1,6 @@
-
+# Implements the core functionality of modules. This is inherited from
+# by instances of {Class}, so these methods are also available to
+# classes.
 class Module
 
   def name

data/gems/core/lib/core/nil_class.rb

@@ -1,3 +1,16 @@
+# `NilClass` has a single instance `nil`. No more instances of this
+# class can be created, and attempts to do so will yield an error.
+#
+# Implementation details
+# ----------------------
+#
+# `nil` is an actual ruby object, and is not just a reference to the
+# native `null` or `undefined` values in javascript. Sending messages to
+# `nil` in ruby is a very useful feature of ruby, and this would not be
+# possible in opal if `nil` was just the `null` or `undefined` value.
+#
+# To access `nil` from javascript, `Qnil` points to this instance and is
+# available in both ruby and javascript sources loaded by opal.
 class NilClass
 
   def to_i

data/gems/core/lib/core/numeric.rb

@@ -1,3 +1,43 @@
+# Numeric objects represent numbers in opal. Unlike ruby, this class is
+# used to represent both floats and integers, and there is currently no
+# class representing bignums. Numeric values may only be made using
+# their literal representations:
+#
+#     1       # => 1
+#     2.0     # => 2
+#     0.05    # => 0.05
+#
+# Implementation details
+# ----------------------
+#
+# Opal numbers are toll-free bridged to native javascript numbers so
+# that anywhere a ruby number is expected, a native javascript number
+# may be used in its place. Javascript only has a single class/prototype
+# to represent numbers, meaning that all integers and floats contain the
+# same prototype. For this reason, Opal follows suit and implements all
+# numbers as a direct instance of {Numeric}.
+#
+# Floats and Integers could be truley represented using wrappers, but
+# this would **dramatically** increase performance overhead at the very
+# core parts of the opal runtime. This overhead is too great, and the
+# benefits would be too few.
+#
+# Ruby compatibility
+# ------------------
+#
+# As discussed, {Numeric} is the only class used to represent numbers in
+# opal. Most of the useful methods from `Fixnum`, `Integer` and `Float`
+# are implemented on this class.
+#
+# It is also important to note that there is no distinguishment between
+# floats and integers, so that, `1` and `1.0` are exactly equal.
+#
+# Custom subclasses of Numeric may be used so that a numeric literal is
+# passed in. This differs from the ruby approach of number inheritance,
+# but does allow for certain circumstances where a subclass of number
+# might be useful. Opal does not try to implement `Integer` or `Float`
+# for these purposes, but it is easily done. This approach will still
+# not allow for literals to be used to make these subclass instances.
 class Numeric
   # Unary Plus - Returns the receivers value
   #
@@ -23,7 +63,7 @@ class Numeric
     `return -self;`
   end
 
-  # Returns `self` modulo `other`. See {#divmod} for more information.
+  # Returns `self` modulo `other`. See `divmod` for more information.
   #
   # @param [Numeric] other number to use for module
   # @return [Numeric] result

data/gems/core/lib/core/object.rb

@@ -0,0 +1,6 @@
+# Core object in hierarchy. Most of the implementation of this core
+# object are implemented in {Kernel}.
+class Object < BasicObject
+
+end
+

data/gems/core/lib/core/proc.rb

@@ -1,5 +1,39 @@
+# `Proc` objects are blocks of code that can also be bound to local
+# variables in their defined scope. When called, a proc will maintain
+# its `self` value, and still have the ability to access variables
+# defined within the same scope. A proc may also be called in another
+# context and have its `self` value tempararily adjusted.
+#
+# Creation of procs may be done by passing a block into the {Proc.new}
+# constructor, or the {Kernel} method {Kernel#proc}:
+#
+#     a = Proc.new { 14 }       # => #<Proc:0x98aef>
+#     b = proc { 42 + a.call }  # => #<Proc:0x98ef3>
+#
+#     a.call       # => 14
+#     b.call       # => 56
+#
+# Implementation details
+# ----------------------
+#
+# Due to their obvious similarities in functionality, a proc instance is
+# simply a native javascript function allowing it to maintain access to
+# variables in its outer scope, and to have its `self` value changed on
+# demand.
+#
+# When a proc is defined, its `self` value is stored on the function
+# instance itself as a `.$self` property, so when the proc is called in
+# future, this is the default value passed as the self property. This
+# also means that every function used in the same context as opal may be
+# used as a `Proc` meaning the transition back and forth between ruby
+# and javascript contexts is easy.
 class Proc
 
+  def self.new(&block)
+    raise "No block given" unless block_given?
+    block
+  end
+
   def to_proc
     self
   end

data/gems/core/lib/core/regexp.rb

@@ -1,3 +1,22 @@
+# A `Regexp` holds a regular expression, that can be used to match
+# against strings. Regexps may be created as literals, or using the
+# {Regexp.new} method:
+#
+#     /abc/                 # => /abc/
+#     Regexp.new '[a-z]'    # => /[a-z]/
+#
+# Implementation details
+# ----------------------
+#
+# Instances of {Regexp} are toll-free bridged to native javascript
+# regular expressions. This means that javascript regexp instances may
+# be passed directly into ruby methods that expect a regexp instance.
+#
+# Due to the limitations of some browser engines, regexps from ruby are
+# not always compatible with the target browser javascript engine.
+# Compatibility differences change between engines, so reading up on a
+# particular browsers documentation might point to differences
+# discovered. The majority of regexp syntax is typically the same.
 class Regexp
   def inspect
     `return self.toString();`

data/gems/core/lib/core/string.rb

@@ -1,18 +1,66 @@
-# A {String} object holds a sequence of bytes, typically representing
-# characters.
+# -*- encoding: utf-8 -*-
+
+# String objects holds a sequence of bytes, typically representing
+# characters. Strings may be constructed by using methods like
+# {String.new} or literals, like the following:
+#
+#     String.new("foo")     # => "foo"
+#     "bar"                 # => "bar"
+#
+# Strings in Opal are immutable; which means that their contents cannot
+# be changed. This means that a lot of methods like `strip!` are not
+# present, and will yield a `NoMethodError`. Thier immutable
+# counterparts are still available, which typically just return a new
+# string.
+#
+# Implementation details
+# ----------------------
+#
+# Ruby strings are toll-free bridged to native javascript strings,
+# meaning that anywhere that a ruby string is required, a normal
+# javascript string may be passed. This dramatically improves the
+# performance of Opal due to a lower overhead in allocating strings as
+# well as the ability to used functions of the String prototype to
+# perform many of the core ruby methods.
+#
+# It is due to this limitation that strings are immutable. Javascript
+# strings are immutable too, which limits what can be done with them in
+# regards to Ruby methods.
+#
+# Ruby compatibility
+# ------------------
+#
+# As discussed, {String} instances are immutable so they do not
+# implement any of the self mutable methods found in the ruby core
+# library. Most of these methods have their relative immutable
+# implementations, or alternative methods to take their place.
+#
+# Custom subclasses of {String} can be used, and are constructed in the
+# {.new} method. To due opals internals, a regular string is constructed
+# using `new String(string_content)`, and its class and method table
+# simply pointed at the custom subclass. As these custom subclasses are
+# simply javascript strings as well, they are also limited to being
+# immutable. This is because they share the same internal structre as
+# regular {String} instances.
 #
-# Implementation Details
-# ======================
+# String instances will never actually have their {.allocate} methods
+# called. Due to the way opal bridges strings to javascript, when a new
+# string is constructed, its value must be know. This is not possible in
+# `allocate` as the value is not passed. Therefore the creation of
+# strings (including subclasses) is done in {.new} where the string
+# value is passed as an argument.
 #
-# For performance, strings in Opal are build directly on top of native
-# javascript strings, so that they are infact the same object. This has the side
-# effect that all strings are immutable, that is, they cannot be changed. Most
-# of the string methods that end in '!' are therefore not implemented, but their
-# counterparts are: 'upase' exists, but 'upcase!' does not, for example.
+# Finally, strings do not currently include the `Comparable` module, as
+# it is not yet implemented. The main methods used by {String} from this
+# module are implemented directly as String methods. When `Comparable`
+# is implemented, these methods will be moved back to the module.
 class String
 
   def self.new(str = "")
-    `return new String(str);`
+    `var result = new String(str);
+    result.$klass = self;
+    result.$m = self.$m_tbl;
+    return result;`
   end
 
   # Copy - returns a new string containing `count` copies of the receiver.
@@ -137,11 +185,11 @@ class String
   #
   # @return [Symbol]
   def to_sym
-    `return $opal.Y(self);`
+    `return VM.Y(self);`
   end
 
   def intern
-    `return $opal.Y(self);`
+    `return VM.Y(self);`
   end
 
   # Returns a new string with the characters from `self` in reverse order.
@@ -212,7 +260,7 @@ class String
   # obj is not a regexp, then it calls =~ on it, using the receiver as an
   # argument
   #
-  # @TODO passing a non regexp is not currently supported
+  # **TODO** passing a non regexp is not currently supported
   #
   # @param [Regexp, Objec] obj
   # @return [Numeric, nil]
@@ -295,7 +343,7 @@ class String
   # self. Returns `nil` if not found. If the second param is present then it
   # specifies the index of self to begin searching.
   #
-  # @TODO: regexp and offsets not yet implemented.
+  # **TODO** regexp and offsets not yet implemented.
   #
   # @example
   #

data/gems/core/lib/core/symbol.rb

@@ -1,3 +1,30 @@
+# `Symbols` are used to represent names and can often be used in place
+# of enum variables used in other languages. Symbols can be constructed
+# using their literal syntax or one of the various `to_sym` methods
+# found in the standard library:
+#
+#     :some_symbol        # => :some_symbol
+#     "a_string".to_sym   # => :a_string
+#
+# It is important to note that regardless of the context that created
+# them, two symbols with the same name will always be the exact same
+# object. The opal runtime guarantees this as it creates them. If one
+# exists already with the required name, it will be returned instead of
+# creating a new one.
+#
+# Implementation details
+# ----------------------
+#
+# Internally, symbols are just javascript strings. They are constructed
+# with the javascript `new String(symbol_name)` syntax. Once created,
+# they have their class and method tables altered to point towards the
+# {Symbol} class. This avoids them conflicting with regular strings.
+#
+# Symbols are implemented as strings for performance. They are only
+# created once per name, so past the initial creation phase, which
+# happends just the once, they perform as quickly as just passig them
+# between method calls, and as strings their native prototype offers all
+# the required functionality needed by the class.
 class Symbol
 
   def inspect

data/gems/core/lib/core/true_class.rb

@@ -1,3 +1,24 @@
+# Instances of `TrueClass` represent logically true values. There may
+# only be one instance of `TrueClass`, which is the global value
+# `true`. Attempts to create a new instance will yield an error.
+# `TrueClass` provides methods to perform logical operations with other
+# ruby objects.
+#
+# Implementation details
+# ----------------------
+#
+# Due to the way messages are passed inside opal, `true` is not
+# actually toll-free bridged onto the native javascript `true` value.
+# In javascript, `true` and `true` are both instances of the Boolean
+# type, which means they would need to share the same method_table in
+# opal, which would remove their ability to be true instances of Rubys'
+# `TrueClass` or `FalseClass`.
+#
+# As javascripts `true` is not actually the value used in opal, passing
+# the native `true` value will cause errors when messages are sent to
+# it. Within a file directly loaded by opal, `Qtrue` is a free variable
+# that points to the actualy ruby instance of this class. This variable
+# may be passed around freely.
 class TrueClass
   def to_s
     "true"

data/lib/opal.rb

@@ -10,3 +10,5 @@ require 'opal/gem'
 require 'opal/bundle'
 require 'opal/builder'
 
+require 'opal/rake/builder_task'
+

data/lib/opal/builder.rb

@@ -29,26 +29,26 @@ module Opal
       @project_dir = options[:project_dir] || Dir.getwd
       @project_name = File.basename @project_dir
 
-      out = options[:out] || File.join('javascripts', "#@project_name.js")
-      @out = File.join @project_dir, out
-      FileUtils.mkdir_p File.dirname(@out)
-
       files = options[:files] || []
-      @files = []
+      files = [files] unless files.is_a? Array
+      @files = Dir.[](*files)
 
-      if Array === files
-        files.each do |file|
-          @files << file
-        end
+      @watch = options[:watch]
+
+      raise "Opal::Builder - No input files could be found!" if @files.empty?
+
+      @main = options[:main]
+
+      if @main
+        raise "Opal::Builder - Main file does not exist!" unless File.exists? @main
+        @files << @main unless @files.include? @main
       else
-        Dir.glob(File.join(@project_dir, files)) do |file|
-          @files << file
-        end
+        @main = @files.first
       end
 
-      @watch = options[:watch]
-
-      raise "Opal::Builder - No input files!" if @files.empty?
+      out = options[:out] || File.basename(@main, '.rb') + '.js'
+      @out = File.join @project_dir, out
+      FileUtils.mkdir_p File.dirname(@out)
     end
 
     # Actually build the simple builder. This is simply used as a looper to
@@ -79,11 +79,13 @@ module Opal
 
     # Does the actual rebuild of a project
     def rebuild
+      puts "rebuilding to #@out"
+      puts @files.inspect
       File.open(@out, 'w') do |out|
         @files.each do |file|
           out.write wrap_source file
         end
-        main = File.basename(@files.first).sub(/\.rb/, '')
+        main = File.basename(@main).sub(/\.rb/, '')
         out.write "opal.require('#{main}');\n"
       end
     end

data/lib/opal/rake/builder_task.rb

@@ -0,0 +1,44 @@
+require 'rake'
+require 'rake/tasklib'
+
+module Opal
+  module Rake
+
+    class BuilderTask < ::Rake::TaskLib
+
+      attr_accessor :files
+
+      attr_accessor :out
+
+      attr_accessor :main
+
+      attr_accessor :watch
+
+      def initialize(name = :opal)
+        @name    = name
+        @files   = []
+        @out     = nil
+        @main    = nil
+        @watch   = false
+
+        yield self if block_given?
+        define_rake_task
+      end
+
+      def define_rake_task
+        desc "Build opal files"
+        task(@name) do
+          options = {}
+          options[:files] = @files
+          options[:out]   = @out if @out
+          options[:main]  = @main if @main
+          options[:watch] = @watch
+
+          builder = Opal::Builder.new options
+          builder.build
+        end
+      end
+    end
+  end
+end
+

data/opal.gemspec

@@ -1,7 +1,7 @@
 
 Gem::Specification.new do |gem|
   gem.name          = "opal"
-  gem.version       = "0.3.1"
+  gem.version       = "0.3.2"
   gem.authors       = ["Adam Beynon"]
   gem.email         = ["adam@adambeynon.com"]
   gem.homepage      = "http://github.com/adambeynon/opal"

metadata

@@ -2,7 +2,7 @@
 name: opal
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors: 
 - Adam Beynon
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-30 00:00:00 +01:00
+date: 2011-03-31 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -25,6 +25,7 @@ extra_rdoc_files: []
 
 files: 
 - .gitignore
+- Changelog
 - LICENSE
 - README.md
 - Rakefile
@@ -45,6 +46,7 @@ files:
 - gems/core/lib/core/module.rb
 - gems/core/lib/core/nil_class.rb
 - gems/core/lib/core/numeric.rb
+- gems/core/lib/core/object.rb
 - gems/core/lib/core/proc.rb
 - gems/core/lib/core/range.rb
 - gems/core/lib/core/regexp.rb
@@ -186,6 +188,7 @@ files:
 - lib/opal/context/file_system.rb
 - lib/opal/context/loader.rb
 - lib/opal/gem.rb
+- lib/opal/rake/builder_task.rb
 - lib/opal/ruby/nodes.rb
 - lib/opal/ruby/parser.rb
 - lib/opal/ruby/ruby_parser.rb