opal 0.3.20 → 0.3.21

data/.gitignore

@@ -1,16 +1,11 @@
 .DS_Store
-doc
-/tmp
 *.gem
 .yardoc
-/vendor
 .bundle
 Gemfile.lock
 pkg/*
-/runtime/*.js
-/*.js
-/docs/gh-pages
+/gh-pages
 /examples/**/*.js
 /build
 Gemfile.local
-Gemfile.local.lock
+Gemfile.local.lock

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format doc

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+
+rvm:
+  - 1.8.7
+  - 1.9.3
+
+before_script:
+  - "export DISPLAY=:99.0"
+  - "sh -e /etc/init.d/xvfb start"
+  - "bundle exec rake build dependencies spec"
+  

data/Gemfile

@@ -6,6 +6,12 @@ gem "rake"
 gem "racc"
 
 group :browser do
-  gem "opal-spec"
-  gem 'opal-dom'
+  gem 'opal-spec', :git => 'git://github.com/adambeynon/opal-spec.git'
+  gem 'opal-dom', :git => 'git://github.com/adambeynon/opal-dom.git'
+  gem 'capybara'
+end
+
+group :docs do
+  gem "redcarpet"
+  gem "albino"
 end

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2011 by Adam Beynon
+Copyright (C) 2012 by Adam Beynon
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -16,5 +16,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-
+THE SOFTWARE.

data/README.md

@@ -19,15 +19,11 @@ is a Freenode IRC channel at `#opal`.
 The Opal runtime and corelib are distributed here, and are required to
 run any code generated by opal.
 
-[Opal version 0.3.20](http://opalrb.org/opal.js) _(14.3kb Minified And Gzipped)_
+[Opal version 0.3.21](http://opalrb.org/opal.js) _(13.1kb Minified And Gzipped)_
 
 ## Installation
 
-Opal comes distributed as a gem, so either install with:
-
-    gem install opal
-
-Or add to your Gemfile:
+Opal should be added to your Gemfile:
 
 ```ruby
 gem "opal"
@@ -35,139 +31,150 @@ gem "opal"
 
 ## Usage
 
-To quickly compile ruby code into javascript, use the `Opal.parse()`
-method which returns a string of javascript code:
+The easiest way to use opal is to create a rake task using the
+`RakeTask` helper class. Assuming you have a single ruby file in
+your Opal app called `app.rb`:
 
 ```ruby
-require 'opal'
-
-Opal.parse("puts 'hello world'")
+# app.rb
+puts "Hello world"
 ```
 
-This will return a string of javascript:
+Then create a rake task similar to:
 
-```javascript
-(function() {
-  var self = Opal.top;
-  self.$puts('hello world');
-})();
+```ruby
+# Rakefile
+require 'opal/rake_task'
+
+Opal::RakeTask.new do |t|
+  t.files = ['app.rb']
+end
 ```
 
-This can then be written to a file and run in any browser. `Opal` is a
-global javascript variable that holds all the ruby classes and methods.
-`Opal.top` points to the top object in opal, so any file will have this
-object as its top level `self` variable.
+### Building the app
 
-### Creating a rake task
+Building the app is as simple as running:
 
-Using a Rakefile makes it simple to build your application code.
-Assuming your code is in a file `app.rb`, add a rake task:
+```
+rake opal:build
+```
+
+This will build all your listed files into `build/app_name.js`. The
+output name is based on the directory name. This can be overriden by
+setting the `.name` property in the task:
 
 ```ruby
-# Rakefile
+Opal::RakeTask.new do |t|
+  t.files = ['app.rb']
+  t.name  = 'my_awesome_app'
+end
+```
 
-require 'opal'
+### Building opal runtime
 
-desc "Build opal application"
-task :build do
-  src = File.read 'app.rb'
-  js  = Opal.parse src
+To run the app in the browser, the opal runtime is required. This can
+be built using:
 
-  File.open('app.js', 'w+') do |out|
-    out.write js
-  end
+```
+rake opal:dependencies
+```
+
+Which will build `opal.js` into `./build`.
+
+The output directory can also be overriden inside the rake task:
+
+```ruby
+Opal::RakeTask.new do |t|
+  t.files = ['app.rb']
+  t.build_dir = 'out_dir'
 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.
+The output directory will be created if it doesn't exist.
 
-### Setting up html file
+### Running the app
 
-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).
+The two compiled files need to be added to a html page so that they
+can run in the browser:
 
 ```html
 <!doctype html>
 <html>
 <head>
-  <title>Test Opal App</title>
+  <title>My awesome Opal app</title>
+
+  <script src="build/opal.js"></script>
+  <script src="build/my_awesome_app.js"></script>
+
+  <script>
+    // Run opal app
+    Opal.require('app')
+  </script>
 </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 message printed to the console.
+If you open the html file, observe the console and you should see
+`"Hello World"` printed to the console.
 
-## Builder and Dependency Builder
+It is necessary to run `Opal.require('app')` as all files built for
+opal are registered so that they can be required inside the ruby
+code.
 
-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:
+### Adding dependencies
 
-```ruby
-# Rakefile
+The `opal:dependencies` rake task above can be used to build gems which
+are designed to run in the browser. `opal-dom` is a gem that given opal
+access to the DOM in the browser.
 
-require 'opal'
+`opal-dom` first needs to be installed as a gem (currently it is only
+available from git):
 
-Opal::BuilderTask.new do |t|
-  t.name         = 'my-first-app'
-  t.dependencies = ['opal-spec']
-  t.files        = ['app.rb']
-end
+```ruby
+# Gemfile
+gem "opal"
+gem "opal-dom", :git => 'git://github.com/adambeynon/opal-dom.git'
 ```
 
-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-spec` into
-`build/`, run the simple rake task:
+Then add it to the dependencies to build:
 
 ```ruby
-rake dependencies
+Opal::RakeTask.new do |t|
+  t.files = ['app.rb']
+  t.dependencies = ['opal-dom']
+end
 ```
 
-This will try and find the `opal-spec` gem installed, so either
-install globally with `gem install opal-spec`, or add it to your
-Gemfile as `gem "opal-spec"` and run `bundle install`.
+Running `rake opal:dependencies` now will also build
+`build/opal-dom.js`.
 
-### Building app
-
-To build the listed files into your application, run:
+We can now update our application code:
 
 ```ruby
-rake build
+# app.rb
+require 'opal-dom'
+
+alert "Hello!"
 ```
 
-This will build to `/build/my-first-app.js`. To customize the output
-filename, change the `name` property in the raketask.
+And rebuild:
 
-### Running the app
+```
+rake opal:build
+```
 
-You should now be able to run the built app using a standard HTML page.
+And add `opal-dom` to the html page:
 
 ```html
-<!doctype html>
-<html>
-<head>
-  <title>Test Opal App</title>
-</head>
-<body>
-  <script src="build/opal.js"></script>
-  <script src="build/opal-spec.js"></script>
-  <script src="build/my-first-app.js"></script>
-</body>
-</html>
+<script src="build/opal.js"></script>
+<script src="build/opal-dom.js"></script>
+<script src="build/app.js"></script>
 ```
 
+Now running the app should cause an alert box to display.
+ 
 ## Features And Implementation
 
 Opal is a source-to-source compiler, so there is no VM as such and the
@@ -176,7 +183,7 @@ directly to underlying javascript features and objects where possible.
 
 ### Literals
 
-**self** is always compiled to `this`. Any context inside the generated
+**self** is always compiled to `self`. 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.
 
@@ -195,7 +202,7 @@ files points to a special object which is just an instance of the ruby
 nil         # => nil
 true        # => true
 false       # => false
-self        # => this
+self        # => self
 ```
 
 #### Strings
@@ -262,94 +269,6 @@ range instances.
 3...7       # => __range(3, 7, false)
 ```
 
-### Classes and Modules
-
-A compiled class or module body is simply just an anonymous javascript
-function that is used to keep any internal variables from escaping.
-
-Classes and modules themselves are created as named functions (which is
-used purely to aid debugging). Classes and modules may also be
-re-opended, so they are put through a runtime function `__klass` for
-classes, and `__module` for modules.
-
-For example, the `Kernel` module is generated as:
-
-```javascript
-(function(__base) {
-  function Kernel(){};
-  Kernel = __module(__base, "Kernel", Kernel);
-  var Kernel_prototype = Kernel.prototype;
-
-  Kernel_prototype.$class = function() {
-    return this._real;
-  };
-
-  Kernel._donate('$class', ...);
-})(__scope);
-```
-
-Firstly, the `__scope` is passed into the function which is used
-for defining constants, which means that if `Kernel` gets defined
-here then it can be set as a constant for the given scope. The
-named function (Kernel) follows, as well as the `__module()` call
-which simply sets the up the module if it doesn't already exist. If
-it does exist, then it overwrites the previous `Kernel` local variable.
-
-Next, `Kernel_prototype` is made a local variable to improve
-minimization of the code, then all the Kernel methods are set on the
-prototype. Modules cannot be instantiated in Opal (just like ruby), but
-the use of prototypes is to improve performance.
-
-Finally, the call to `Kernel._donate()` is to pass any defined methods
-into classes that have included `Kernel`, which is just `Object`. This
-method then adds all of Kernels methods into Objects prototype as this
-is the most efficient way to try and emulate rubys method chain.
-
-### 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
@@ -364,7 +283,7 @@ if so then to just carry out the math call.
 This ruby code will then be compiled into the following javascript:
 
 ```javascript
-(a = 3, b = 4, typeof(a) === "number" ? a + b : a.$plus(b))
+(a = 3, b = 4, typeof(a) === "number" ? a + b : /* method call */)
 ```
 
 This ternary statement falls back on sending a method to the receiver
@@ -372,68 +291,10 @@ 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
+### method_missing
 
-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. (`Array_prototype` is
-an example and would assume this method definition is inside the
-`Array` class body).
-
-```javascript
-Array_prototype.$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
-Array_prototype.$norm = function(a, b, c) {
-  return nil;
-};
-
-Array_prototype.$opt = function(a, b) {
-  if (b == null) b = 100;
-  return nil;
-};
-
-Array_prototype.$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.
+Method missing is fully supported in Opal. It is implemented as
+efficiently as possible.
 
 ### Logic and conditionals
 
@@ -696,6 +557,12 @@ Opal is released under the MIT license.
 
 ## Change Log
 
+**0.3.21** _(16 July 2012)_
+
+* Add `method_missing` support to all objects and classes
+* Add `Opal.build_gem()` method to quickly build installed gem
+* Add `Opal.build_files()` method to build directories of files
+
 **0.3.20** _(23 June 2012)_
 
 * Merge JSON into core. JSON module and various #to_json methods are