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

opal 0.3.18 → 0.3.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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.