RubyGems - opal - Versions diffs - 0.3.18 → 0.3.19 - Mend

opal 0.3.18 → 0.3.19

Files changed (259) hide show

data/.gitignore +1 -1
data/Gemfile +1 -3
data/README.md +472 -10
data/Rakefile +10 -52
data/core/array.rb +9 -14
data/core/basic_object.rb +7 -10
data/core/boolean.rb +5 -1
data/core/class.rb +15 -38
data/core/dir.rb +89 -0
data/core/enumerable.rb +133 -57
data/core/error.rb +15 -1
data/core/file.rb +85 -0
data/core/hash.rb +186 -32
data/core/kernel.rb +30 -31
data/core/load_order +4 -2
data/core/module.rb +42 -62
data/core/numeric.rb +7 -1
data/core/object.rb +1 -1
data/core/proc.rb +6 -2
data/core/range.rb +16 -28
data/core/regexp.rb +3 -3
data/core/runtime.js +281 -350
data/core/string.rb +100 -110
data/docs/CNAME +1 -0
data/docs/Rakefile +55 -0
data/docs/css/styles.css +50 -0
data/docs/css/syntax.css +63 -0
data/docs/layout/post.html +3 -0
data/docs/layout/pre.html +11 -0
data/examples/dependencies/app.rb +3 -0
data/lib/opal.rb +2 -1
data/lib/opal/builder.rb +36 -10
data/lib/opal/builder_task.rb +51 -24
data/lib/opal/grammar.rb +2509 -2439
data/lib/opal/grammar.y +38 -5
data/lib/opal/lexer.rb +18 -2
data/lib/opal/parser.rb +375 -349
data/lib/opal/scope.rb +24 -2
data/lib/opal/version.rb +1 -1
data/spec/builder/build_order_spec.rb +20 -0
data/spec/builder/lib_name_for_spec.rb +24 -0
data/spec/grammar/call_spec.rb +9 -6
data/spec/grammar/lambda_spec.rb +64 -0
data/spec/grammar/sclass_spec.rb +5 -3
data/{core/spec → test}/core/array/allocate_spec.rb +0 -0
data/{core/spec → test}/core/array/append_spec.rb +0 -0
data/{core/spec → test}/core/array/assoc_spec.rb +0 -0
data/{core/spec → test}/core/array/at_spec.rb +0 -0
data/{core/spec → test}/core/array/clear_spec.rb +0 -0
data/{core/spec → test}/core/array/clone_spec.rb +0 -0
data/{core/spec → test}/core/array/collect_spec.rb +0 -0
data/{core/spec → test}/core/array/compact_spec.rb +0 -0
data/{core/spec → test}/core/array/concat_spec.rb +0 -0
data/{core/spec → test}/core/array/constructor_spec.rb +0 -0
data/{core/spec → test}/core/array/count_spec.rb +0 -0
data/{core/spec → test}/core/array/delete_at_spec.rb +0 -0
data/{core/spec → test}/core/array/delete_if_spec.rb +0 -0
data/{core/spec → test}/core/array/delete_spec.rb +0 -0
data/{core/spec → test}/core/array/each_index_spec.rb +0 -0
data/{core/spec → test}/core/array/each_spec.rb +0 -0
data/{core/spec → test}/core/array/element_reference_spec.rb +0 -0
data/{core/spec → test}/core/array/empty_spec.rb +0 -0
data/{core/spec → test}/core/array/eql_spec.rb +0 -0
data/{core/spec → test}/core/array/fetch_spec.rb +0 -0
data/{core/spec → test}/core/array/first_spec.rb +0 -0
data/{core/spec → test}/core/array/flatten_spec.rb +0 -0
data/{core/spec → test}/core/array/include_spec.rb +0 -0
data/{core/spec → test}/core/array/insert_spec.rb +0 -0
data/{core/spec → test}/core/array/last_spec.rb +0 -0
data/{core/spec → test}/core/array/length_spec.rb +0 -0
data/{core/spec → test}/core/array/map_spec.rb +0 -0
data/{core/spec → test}/core/array/plus_spec.rb +0 -0
data/{core/spec → test}/core/array/pop_spec.rb +0 -0
data/{core/spec → test}/core/array/push_spec.rb +0 -0
data/{core/spec → test}/core/array/rassoc_spec.rb +0 -0
data/{core/spec → test}/core/array/reject_spec.rb +0 -0
data/{core/spec → test}/core/array/replace_spec.rb +0 -0
data/{core/spec → test}/core/array/reverse_each_spec.rb +0 -0
data/{core/spec → test}/core/array/reverse_spec.rb +0 -0
data/{core/spec → test}/core/array/size_spec.rb +0 -0
data/{core/spec → test}/core/array/to_ary_spec.rb +0 -0
data/{core/spec → test}/core/array/uniq_spec.rb +0 -0
data/{core/spec → test}/core/array/zip_spec.rb +0 -0
data/test/core/class/fixtures/classes.rb +9 -0
data/test/core/class/new_spec.rb +108 -0
data/{core/spec → test}/core/enumerable/all_spec.rb +0 -0
data/{core/spec → test}/core/enumerable/any_spec.rb +0 -0
data/{core/spec → test}/core/enumerable/collect_spec.rb +0 -0
data/{core/spec → test}/core/enumerable/count_spec.rb +0 -0
data/test/core/enumerable/detect_spec.rb +48 -0
data/test/core/enumerable/drop_spec.rb +17 -0
data/test/core/enumerable/drop_while_spec.rb +24 -0
data/test/core/enumerable/each_with_index_spec.rb +11 -0
data/test/core/enumerable/each_with_object_spec.rb +17 -0
data/test/core/enumerable/entries_spec.rb +6 -0
data/test/core/enumerable/find_all_spec.rb +13 -0
data/test/core/enumerable/find_index_spec.rb +45 -0
data/test/core/enumerable/find_spec.rb +48 -0
data/test/core/enumerable/first_spec.rb +40 -0
data/{core/spec → test}/core/enumerable/fixtures/classes.rb +19 -0
data/test/core/enumerable/grep_spec.rb +21 -0
data/test/core/enumerable/take_spec.rb +40 -0
data/test/core/enumerable/to_a_spec.rb +6 -0
data/{core/spec → test}/core/false/and_spec.rb +0 -0
data/{core/spec → test}/core/false/inspect_spec.rb +0 -0
data/{core/spec → test}/core/false/or_spec.rb +0 -0
data/{core/spec → test}/core/false/to_s_spec.rb +0 -0
data/{core/spec → test}/core/false/xor_spec.rb +0 -0
data/test/core/file/expand_path_spec.rb +20 -0
data/{core/spec → test}/core/hash/allocate_spec.rb +0 -0
data/{core/spec → test}/core/hash/assoc_spec.rb +0 -0
data/{core/spec → test}/core/hash/clear_spec.rb +0 -0
data/{core/spec → test}/core/hash/clone_spec.rb +0 -0
data/test/core/hash/default_spec.rb +9 -0
data/{core/spec → test}/core/hash/delete_if_spec.rb +0 -0
data/test/core/hash/each_key_spec.rb +15 -0
data/test/core/hash/each_pair_spec.rb +30 -0
data/test/core/hash/each_spec.rb +30 -0
data/test/core/hash/each_value_spec.rb +15 -0
data/{core/spec → test}/core/hash/element_reference_spec.rb +14 -0
data/{core/spec → test}/core/hash/element_set_spec.rb +1 -0
data/test/core/hash/empty_spec.rb +10 -0
data/test/core/hash/fetch_spec.rb +24 -0
data/test/core/hash/flatten_spec.rb +46 -0
data/test/core/hash/has_key_spec.rb +24 -0
data/test/core/hash/has_value_spec.rb +12 -0
data/test/core/hash/include_spec.rb +24 -0
data/test/core/hash/index_spec.rb +13 -0
data/test/core/hash/indexes_spec.rb +9 -0
data/test/core/hash/indices_spec.rb +9 -0
data/test/core/hash/invert_spec.rb +12 -0
data/test/core/hash/keep_if_spec.rb +18 -0
data/test/core/hash/key_spec.rb +24 -0
data/test/core/hash/keys_spec.rb +10 -0
data/test/core/hash/length_spec.rb +10 -0
data/test/core/hash/member_spec.rb +24 -0
data/{core/spec → test}/core/hash/merge_spec.rb +0 -0
data/{core/spec → test}/core/hash/new_spec.rb +0 -0
data/test/core/hash/rassoc_spec.rb +34 -0
data/test/core/hash/replace_spec.rb +7 -0
data/test/core/hash/select_spec.rb +52 -0
data/test/core/hash/shift_spec.rb +19 -0
data/test/core/hash/size_spec.rb +10 -0
data/test/core/hash/update_spec.rb +17 -0
data/test/core/hash/value_spec.rb +12 -0
data/test/core/hash/values_at_spec.rb +9 -0
data/test/core/hash/values_spec.rb +7 -0
data/test/core/kernel/eql_spec.rb +15 -0
data/test/core/kernel/equal_value_spec.rb +12 -0
data/test/core/kernel/loop_spec.rb +23 -0
data/test/core/kernel/nil_spec.rb +7 -0
data/test/core/kernel/proc_spec.rb +9 -0
data/test/core/kernel/rand_spec.rb +14 -0
data/test/core/kernel/respond_to_spec.rb +24 -0
data/test/core/kernel/send_spec.rb +56 -0
data/test/core/kernel/tap_spec.rb +10 -0
data/test/core/kernel/to_s_spec.rb +5 -0
data/{core/spec → test}/core/matchdata/to_a_spec.rb +0 -0
data/{core/spec → test}/core/nil/and_spec.rb +0 -0
data/{core/spec → test}/core/nil/inspect_spec.rb +0 -0
data/{core/spec → test}/core/nil/nil_spec.rb +0 -0
data/{core/spec → test}/core/nil/or_spec.rb +0 -0
data/{core/spec → test}/core/nil/to_a_spec.rb +0 -0
data/{core/spec → test}/core/nil/to_f_spec.rb +0 -0
data/{core/spec → test}/core/nil/to_i_spec.rb +0 -0
data/{core/spec → test}/core/nil/to_s_spec.rb +0 -0
data/{core/spec → test}/core/nil/xor_spec.rb +0 -0
data/{core/spec → test}/core/numeric/equal_value_spec.rb +0 -0
data/test/core/range/begin_spec.rb +9 -0
data/test/core/range/case_compare_spec.rb +16 -0
data/test/core/range/end_spec.rb +9 -0
data/{core/spec → test}/core/regexp/match_spec.rb +0 -0
data/test/core/string/capitalize_spec.rb +10 -0
data/test/core/string/casecmp_spec.rb +16 -0
data/test/core/string/chomp_spec.rb +43 -0
data/test/core/string/chop_spec.rb +10 -0
data/test/core/string/chr_spec.rb +13 -0
data/test/core/string/comparison_spec.rb +13 -0
data/test/core/string/downcase_spec.rb +6 -0
data/test/core/string/element_reference_spec.rb +72 -0
data/test/core/string/empty_spec.rb +8 -0
data/test/core/string/end_with_spec.rb +12 -0
data/test/core/string/fixtures/classes.rb +3 -0
data/test/core/string/gsub_spec.rb +17 -0
data/test/core/string/include_spec.rb +12 -0
data/test/core/string/intern_spec.rb +9 -0
data/test/core/string/length_spec.rb +9 -0
data/test/core/string/lstrip_spec.rb +7 -0
data/test/core/string/match_spec.rb +27 -0
data/test/core/string/next_spec.rb +10 -0
data/test/core/string/ord_spec.rb +9 -0
data/test/core/string/partition_spec.rb +10 -0
data/test/core/string/reverse_spec.rb +7 -0
data/test/core/string/rstrip_spec.rb +7 -0
data/test/core/string/size_spec.rb +9 -0
data/test/core/string/slice_spec.rb +72 -0
data/test/core/string/split_spec.rb +5 -0
data/test/core/string/start_with_spec.rb +12 -0
data/test/core/string/strip_spec.rb +6 -0
data/test/core/string/sub_spec.rb +22 -0
data/test/core/string/succ_spec.rb +10 -0
data/test/core/string/sum_spec.rb +5 -0
data/test/core/string/swapcase_spec.rb +18 -0
data/test/core/string/to_a_spec.rb +9 -0
data/test/core/string/to_f_spec.rb +14 -0
data/test/core/string/to_i_spec.rb +25 -0
data/test/core/string/to_s_spec.rb +13 -0
data/test/core/string/to_str_spec.rb +13 -0
data/test/core/string/to_sym_spec.rb +9 -0
data/test/core/string/upcase_spec.rb +6 -0
data/test/core/symbol/to_proc_spec.rb +12 -0
data/{core/spec → test}/core/true/and_spec.rb +0 -0
data/{core/spec → test}/core/true/inspect_spec.rb +0 -0
data/{core/spec → test}/core/true/or_spec.rb +0 -0
data/{core/spec → test}/core/true/to_s_spec.rb +0 -0
data/{core/spec → test}/core/true/xor_spec.rb +0 -0
data/test/index.html +11 -0
data/{core/spec → test}/language/alias_spec.rb +4 -0
data/{core/spec → test}/language/and_spec.rb +0 -0
data/{core/spec → test}/language/array_spec.rb +0 -0
data/{core/spec → test}/language/block_spec.rb +0 -0
data/{core/spec → test}/language/break_spec.rb +0 -0
data/{core/spec → test}/language/case_spec.rb +0 -0
data/{core/spec → test}/language/defined_spec.rb +0 -0
data/{core/spec → test}/language/ensure_spec.rb +0 -0
data/test/language/fixtures/yield.rb +23 -0
data/{core/spec → test}/language/hash_spec.rb +0 -0
data/{core/spec → test}/language/if_spec.rb +0 -0
data/test/language/literal_lambda_spec.rb +47 -0
data/{core/spec → test}/language/loop_spec.rb +0 -0
data/{core/spec → test}/language/metaclass_spec.rb +0 -0
data/{core/spec → test}/language/next_spec.rb +0 -0
data/{core/spec → test}/language/or_spec.rb +0 -0
data/{core/spec → test}/language/predefined_spec.rb +0 -0
data/{core/spec → test}/language/regexp_spec.rb +0 -0
data/{core/spec → test}/language/send_spec.rb +0 -0
data/{core/spec → test}/language/singleton_class_spec.rb +0 -0
data/{core/spec → test}/language/super_spec.rb +0 -0
data/{core/spec → test}/language/symbol_spec.rb +0 -0
data/{core/spec → test}/language/undef_spec.rb +0 -0
data/{core/spec → test}/language/unless_spec.rb +0 -0
data/{core/spec → test}/language/until_spec.rb +0 -0
data/{core/spec → test}/language/variables_spec.rb +0 -0
data/{core/spec → test}/language/while_spec.rb +0 -0
data/test/language/yield_spec.rb +100 -0
data/test/opal/array/subclassing_spec.rb +32 -0
data/test/opal/class/bridge_class_spec.rb +37 -0
data/test/opal/exception/subclassing_spec.rb +17 -0
data/test/opal/runtime/_methods_spec.rb +48 -0
data/test/opal/runtime/class_hierarchy_spec.rb +22 -0
data/test/opal/runtime/def_spec.rb +23 -0
data/test/opal/string/subclassing_spec.rb +26 -0
data/test/spec_helper.rb +3 -0
metadata +437 -111
data/core/spec/core/class/new_spec.rb +0 -16
data/core/spec/core/hash/default_spec.rb +0 -4
data/core/spec/core/symbol/to_proc_spec.rb +0 -6
data/core/spec/index.html +0 -11
data/spec/builder/build_source_spec.rb +0 -52

data/.gitignore CHANGED

@@ -9,6 +9,6 @@ Gemfile.lock
 pkg/*
 /runtime/*.js
 /*.js
-/gh-pages
+/docs/gh-pages
 /examples/**/*.js
 /build

data/Gemfile CHANGED

@@ -6,7 +6,5 @@ gem "rake"
 # gem "racc"
 group :browser do
-  gem "opal-racc"
-  gem "opal-spec"
-  gem "opal-strscan"
+  gem "opal-spec", "0.1.6"
 end

data/README.md CHANGED

@@ -1,25 +1,487 @@
 # Opal
-Opal is a ruby to javascript compiler and runtime for the browser.
+**Opal is a ruby to javascript compiler.** Opal aims to take ruby files
+and generate efficient javascript that maintains rubys features. Opal
+will, by default, generate fast and efficient code in preference to
+keeping all ruby features.
-For docs, visit the website [http://opalrb.org](http://opalrb.org), or visit the [github wiki](http://github.com/adambeynon/opal/wiki).
+Opal comes with an implementation of the ruby corelib, written in ruby,
+that uses a bundled runtime (written in javascript) that tie all the
+features together. Whenever possible Opal bridges to native javascript
+features under the hood. The Opal gem includes the compiler used to
+convert ruby sources into javascript.
-There is also a [Google group for opal](https://groups.google.com/forum/#!forum/opalrb), or join the IRC channel on Freenode: `#opal`.
+Opal is [hosted on github](http://github.com/adambeynon/opal), and there
+is a Freenode IRC channel at `#opal`.
-## Installation And Usage
+## Downloads
-Install via rubygems:
+The Opal runtime and corelib are distributed here, and are required to
+run any code generated by opal.
+[Opal version 0.3.19](http://opalrb.org/opal.js) _(14.9kb Minified And Gzipped)_
+## Installation
+Opal comes distributed as a gem, so either install with:
     gem install opal
-Or using Bundler:
+Or add to your Gemfile:
+```ruby
+gem "opal"
+```
+## Usage
+To quickly compile ruby code into javascript, use the `Opal.parse()`
+method which returns a string of javascript code:
+```ruby
+require 'opal'
+Opal.parse("[1, 2, 3, 4].each { |a| puts a }")
+```
+This will return a string of javascript similar to the following:
+```javascript
+(function() {
+  // compiled ruby
+}).call(Opal.top);
+```
+This can then be written to a file and run in any browser.
+### Creating a rake task
+Using a Rakefile makes it simple to build your application code.
+Assuming your code is in a file `app.rb`, add a rake task:
+```ruby
+# Rakefile
+require 'opal'
+desc "Build opal application"
+task :build do
+  src = File.read 'app.rb'
+  js  = Opal.parse src
+  File.open('app.js', 'w+') do |out|
+    out.write js
+  end
+end
+```
+Running `rake build` will then read your app code, compile it and then
+write it out to a file ready to load in a web browser.
+### Setting up html file
+The generated `app.js` file can just be added into any HTML page. The
+opal runtime needs to be loaded first (you can download that above).
+```html
+<!doctype html>
+<html>
+<head>
+  <title>Test Opal App</title>
+</head>
+<body>
+  <script src="opal.js"></script>
+  <script src="app.js"></script>
+</body>
+</html>
+```
+When using `Opal.parse()` as above, the generated code will be run
+as soon as the page loads. Open the browsers console and you should
+see the 4 numbers printed to the console.
+## Builder and Dependency Builder
+The previous example was useful for building very simple apps using
+opal. For more complex apps with dependencies, Opal provides useful
+rake tasks to get started. Assuming opal is in your lib path, create
+a `Rakefile` similar to:
+```ruby
+# Rakefile
+require 'opal'
+Opal::BuilderTask.new do |t|
+  t.name         = 'my-first-app'
+  t.dependencies = ['opal-json']
+  t.files        = ['app.rb']
+end
+```
+This simple rake task is all you need to build an app with its
+dependencies.
+### Building dependencies
+To build the opal runtime `opal.js`, as well as `opal-json` into
+`build/`, run the simple rake task:
+```ruby
+rake dependencies
+```
+This will try and find the `opal-json` gem installed, so either
+install globally with `gem install opal-json`, or add it to your
+Gemfile as `gem "opal-json"` and run `bundle install`.
+### Building app
+To build the listed files into your application, run:
+```ruby
+rake build
+```
+This will build to `/build/my-first-app.js`. To customize the output
+filename, change the `name` property in the raketask.
+### Running the app
+You should now be able to run the built app using a standard HTML page.
+```html
+<!doctype html>
+<html>
+<head>
+  <title>Test Opal App</title>
+</head>
+<body>
+  <script src="build/opal.js"></script>
+  <script src="build/opal-json.js"></script>
+  <script src="build/my-first-app.js"></script>
+</body>
+</html>
+```
+### Main file
+When using the `BuilderTask`, the files generated will not be run
+automatically on page load. The files are registered so they can be
+loaded using `require()`. Builder is clever enough though that it will,
+by default, automatically require the first file in the app to be
+loaded. This will appear at the bottom of `my-first-app.js`:
+```javascript
+Opal.define('app', function() {
+  // app.rb code
+});
+Opal.require('app');
+```
+## Features And Implementation
+Opal is a source-to-source compiler, so there is no VM as such and the
+compiled code aims to be as fast and efficient as possible, mapping
+directly to underlying javascript features and objects where possible.
+### Literals
+**self** is always compiled to `this`. Any context inside the generated
+code is usually a function body; whether it be a method body, a block,
+a class/module body or the file itself.
+**true** and **false** are compiled directly into their native boolean
+equivalents. This makes interaction a lot easier as there is no need
+to convert values to opal specific values. It does mean that there is
+only a `Boolean` ruby class available, not seperate `TrueClass` and
+`FalseClass` classes.
+**nil** is compiled into a `nil` reference, which inside all generated
+files points to a special object which is just an instance of the ruby
+`NilClass` class. This object is available externally to javascript as
+`Opal.nil`.
+```ruby
+nil         # => nil
+true        # => true
+false       # => false
+self        # => this
+```
+#### Strings
+Ruby strings are compiled directly into javascript strings for
+performance as well as readability. This has the side effect that Opal
+does not support mutable strings - i.e. all strings are immutable.
+#### Symbols
+For performance reasons, symbols compile directly into strings. Opal
+supports all the symbol syntaxes, but does not have a real `Symbol`
+class. Symbols and Strings can therefore be used interchangeably.
+```ruby
+"hello world!"    # => "hello world!"
+:foo              # => "foo"
+<<-EOS            # => "\nHello there.\n"
+Hello there.
+EOS
+```
+#### Numbers
+In Opal there is a single class for numbers; `Numeric`. To keep opal
+as performant as possible, ruby numbers are mapped to native numbers.
+This has the side effect that all numbers must be of the same class.
+Most relevant methods from `Integer`, `Float` and `Numeric` are
+implemented on this class.
+```ruby
+42        # => 42
+3.142     # => 3.142
+```
+#### Arrays
+Ruby arrays are compiled directly into javascript arrays. Special
+ruby syntaxes for word arrays etc are also supported.
+```ruby
+[1, 2, 3, 4]        # => [1, 2, 3, 4]
+%w[foo bar baz]     # => ["foo", "bar", "baz"]
+```
-    gem "opal"
+#### Hash
-Ruby scripts can be compiled using:
+Inside a generated ruby script, a function `__hash` is available which
+creates a new hash. This is also available in javascript as `Opal.hash`
+and simply returns a new instance of the `Hash` class.
-    opal -c foo.rb -o foo.js
+```ruby
+{ :foo => 100, :baz => 700 }    # => __hash("foo", 100, "baz", 700)
+{ foo: 42, bar: [1, 2, 3] }     # => __hash("foo", 42, "bar", [1, 2, 3])
+```
+#### Range
+Similar to hash, there is a function `__range` available to create
+range instances.
+```ruby
+1..4        # => __range(1, 4, true)
+3...7       # => __range(3, 7, false)
+```
+### Methods
+A ruby method is just compiled directly into a function definition.
+These functions are added to the constructor's prototype so they can
+be called just like any javascript function. All ruby methods are
+defined with a `$` prefix to try and isolate them from javascript
+methods.
+#### Method Calls
+All method arguments are passed to the native function just like normal
+javascript function calls. Therefore, the given ruby code:
+```ruby
+do_something 1, 2, 3
+self.length
+[1, 2, 3].push 5
+```
+Will be compiled into the easy to read javascript:
+```javascript
+this.$do_something(1, 2, 3);
+this.$length();
+[1, 2, 3].$push(5);
+```
+There are some certain characters which are valid as ruby method names
+but not as javascript identifiers. These method calls are encoded to
+keep the generated method names sane.
+```ruby
+self.loaded?              # => this.$loaded$p()
+self.load!                # => this.$load$b()
+self.loaded = true        # => this.$loaded$e(true)
+self << :bar              # => this.$lshift$("bar")
+```
+Finally, method calls with splat arguments are also supported:
+```ruby
+self.push *[1, 2, 3]
+# => this.$push.apply(this, [1, 2, 3])
+```
+#### Optimized Math Operators
+In ruby, all math operators are method calls, but compiling this into
+javascript would end up being too slow. For this reason, math
+operators are optimized to test first if the receiver is a number, and
+if so then to just carry out the math call.
+```ruby
+3 + 4
+```
+This ruby code will then be compiled into the following javascript:
+```javascript
+(a = 3, b = 4, typeof(a) === "number" ? a + b : a.$plus(b))
+```
+This ternary statement falls back on sending a method to the receiver
+so all non-numeric receivers will still have the normal method call
+being sent. This optimization makes math operators a **lot faster**.
+Currently, the optimized method calls are `+`, `-`, `*` and `/`.
+#### Method Definitions
+Methods are implemented as regular javascript functions. Assuming the
+following method is defined inside a class body:
+```ruby
+def to_s
+  inspect
+end
+```
+This would generate the following javascript. (`def.` is a local
+variable set to be the class's instance prototype. It is used
+for minimization of code as well as trying to be readable).
+```javascript
+def.$to_s = function() {
+  return this.$inspect();
+};
+```
+The defined name retains the `$` prefix outlined above, and the `self`
+value for the method is `this`, which will be the receiver.
+Normal arguments, splat args and optional args are all supported:
+```ruby
+def norm(a, b, c)
+end
+def opt(a, b = 100)
+end
+def rest(a, *b)
+end
+```
+The generated code reads as expected:
+```javascript
+def.$norm = function(a, b, c) {
+  return nil;
+};
+def.$opt = function(a, b) {
+  if (b == null) b = 100;
+  return nil;
+};
+def.$rest = function(a, b) {
+  b = __slice.call(arguments, 1);
+  return nil;
+};
+```
+Currently, in opal there is no argument length checking to ensure that
+the correct number of arguments get passed to a function. This can be
+enabled in debug mode, but is not included in production builds as it
+adds a lot of overhead to **every** method call.
+### Compiled Files
+As described above, a compiled ruby source gets generated into a string
+of javascript code that is wrapped inside an anonymous function. This
+looks similar to the following:
+```javascript
+(function(undefined) {
+  var nil = Opal.nil, __slice = Opal.slice, __klass = Opal.klass;
+  // generated code
+}).call(Opal.top);
+```
+This function gets called with `Opal.top` as the context, which is the
+top level object available to ruby (`main`). Inside the function, `nil`
+is assigned to ensure a local copy is available, as well as all the
+helper methods used within the generated file. There is no return value
+from these functions as they are not used anywhere.
+As a complete example, assuming the following code:
+```ruby
+puts "foo"
+```
+This would compile directly into:
+```javascript
+(function(undefined) {
+  var nil = Opal.nil;
+  this.$puts("foo");
+}).call(Opal.top);
+```
+Most of the helpers are no longer present as they are not used in this
+example.
+### Using compiled sources
+If you write the generated code as above into a file `app.js` and add
+that to your HTML page, then it is obvious that `"foo"` would be
+written to the browser's console.
 ## License
-Opal is released under the MIT license.
+Opal is released under the MIT license.
+## Change Log
+**0.3.19** _(30 May 2012)_
+* Add BasicObject as the root class
+* Add `Opal.define` and `Opal.require` for requiring files
+* Builder uses a `main` option to dictate which file to require on load
+* Completely revamp runtime to reduce helper methods
+* Allow native bridges (Array, String, etc) to be subclassed
+* Make sure `.js` files can be built with `Opal::Builder`
+* Include the current file name when raising parse errors
+**0.3.18** _(20 May 2012)_
+* Fix various core lib bugs
+* Completely remove `require` from corelib
+* Improve Builder to detect dependencies in files
+**0.3.17** _(19 May 2012)_
+* Revamp of Builder and Parser tools
+* Remove opal-repl
+* Added a lot of specs for core lib
+**0.3.16** _(15 January 2012)_
+* Added HEREDOCS support in parser
+* Parser now handles masgn (mass/multi assignments)
+* More useful DependencyBuilder class to build gems dependencies
+* Blocks no longer passed as an argument in method calls
+**0.3.15**
+* Initial Release.