opal 0.3.11 → 0.3.15

data/.gitignore

@@ -0,0 +1,13 @@
+.DS_Store
+doc
+/tmp
+*.gem
+.yardoc
+/vendor
+.bundle
+Gemfile.lock
+pkg/*
+/runtime/*.js
+/*.js
+/docs/_site
+/gh-pages

data/Gemfile

@@ -0,0 +1,10 @@
+source :rubygems
+
+# Specify your gem's dependencies in opal.gemspec
+gemspec
+
+gem "rake"
+
+group :test do
+  gem "opal-spec"
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (C) 2011 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.
+

data/README.md

@@ -1,122 +1,17 @@
 Opal
 ====
 
-Opal is a partial implementation of ruby designed to run in any
-javascript environment. The runtime is written in javascript, with all
-core libraries written directly in ruby with inline javascript to make
-them as fast as possible.
+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.
 
-Wherever possible ruby objects are mapped directly onto their native
-javascript counterparts to speed up the generated code and to improve
-interopability with existing javascript libraries.
+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.
 
-The opal compiler is a source-to-source compiler which outputs
-javascript which can then run on the core runtime.
-
-Opal does not aim to be 100% comaptible with other ruby implementations,
-but does so where the generated code can be efficient on all modern web
-browsers - including older versions of IE and mobile devices.
-
-Installing opal
-----------
-
-Install the gem:
-
-```
-$ gem install opal
-```
-
-The `opal` command should then be available. To run the simple repl use:
-
-```
-opal irb
-```
-
-Usage
------
-
-The quickest way to get opal running is to use the project generator.
-Simply run the command:
-
-```
-opal init my_project
-```
-
-replacing "my_project" with any name. This will make a "my_project"
-directory with a Rakefile, html document and libs needed for running
-opal in the browser.
-
-### Using opal in the browser
-
-Opal runs directly in the browser, and is distributed as two files,
-`opal.js` and `opal-parser.js`. To just run precompiled code, just the
-`opal.js` runtime is required which includes the runtime and opals
-implementation of the ruby core library (pre compiled).
-
-To evaluate ruby code directly in the browser, `opal-parser.js` is also
-required which will also load any ruby code found in script tags.
-
-### Bundle
-
-The Rakefile has a task to build your ruby project, so just run:
-
-```
-rake bundle
-```
-
-Open `index.html` in a browser, and now it should run. Edit, build and
-run to suit.
-
-Project structure
------------------
-
-This repo contains the code for the opal gem as well as the opal core
-library and runtime. Files inside `bin/` and `lib/` are the files that
-are used as part of the gem and run directly on your ruby environment.
-
-`corelib/` contains opal's core library implementation and is not used
-directly by the gem. These files are precompiled during development
-ready to be used in the gem or in a browser.
-
-`runtime/` contains opal's runtime written in javascript. It is not used
-directly by the gem, but is built ready to use in the js contexts that
-opal runs.
-
-`stdlib/` contains the stdlib files that opal comes packaged with. The
-gem does use these, but only as required. Opal does not include the full
-opal stdlib, and some parts are actually written in javascript for
-optimal performance. These can be `require()` at runtime.
-
-`opal.js` and `opal-parser.js` are included in the gem, but not the
-source repo. They are the latest built versions of opal and its parser
-which are built before the gem is published.
-
-Differences from ruby
----------------------
-
-### Optional method\_missing
-
-To optimize method dispatch, `method_missing` is, by default, turned off
-in opal. It can easily be enabled by passing `:method_missing => true`
-in the parser options.
-
-### Immutable strings and removed symbols
-
-All strings in opal are immutable to make them easier to map onto
-javascript strings. In opal a ruby string compiles directly into a js
-string without a wrapper so that they can be passed back between code
-bases easily. Also, symbol syntax is maintained, but all symbols just
-compile into javascript strings. The `Symbol` class is also therefore
-removed.
-
-### Unified Numeric class
-
-All numbers in opal are members of the `Numeric` class. The `Integer`
-and `Float` classes are removed.
-
-### Unified Boolean class
-
-Both `true` and `false` compile into their native javascript
-counterparts which means that they both become instances of the
-`Boolean` class and opal removes the `TrueClass` and `FalseClass`.
+For docs, visit the website:
+[http://adambeynon.github.com/opal](http://adambeynon.github.com/opal)
 
+Join the IRC channel on Freenode: `#opal`.

data/Rakefile

@@ -0,0 +1,126 @@
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'opal'
+require 'fileutils'
+require 'opal/version'
+
+namespace :browser do
+  desc "Build opal runtime to opal.js"
+  task :opal do
+    File.open("opal.js", 'w+') { |o| o.write build_runtime false }
+  end
+
+  desc "Build opal debug runtime to opal.debug.js"
+  task :debug do
+    File.open("opal.debug.js", 'w+') { |o| o.write build_runtime true }
+  end
+
+  desc "Tests for browser to opal.test.js"
+  task :test do
+    Opal::Builder.new('runtime/spec', :join => 'opal.test.js').build
+  end
+
+  desc "Build dependencies into runtime/"
+  task :dependencies do
+    Opal::DependencyBuilder.new(:out => 'runtime').build
+  end
+end
+
+desc "Build opal and debug opal into runtime/"
+task :browser => [:'browser:opal', :'browser:debug']
+
+desc "Run opal specs (from runtime/spec/*)"
+task :test => :browser do
+  Opal::Context.runner 'runtime/spec/**/*.rb'
+end
+
+desc "Check file sizes for core builds"
+task :sizes do
+  sizes 'runtime/opal.js'
+  sizes 'runtime/opal.debug.js'
+end
+
+desc "Rebuild grammar.rb for opal parser"
+task :parser do
+  %x(racc -l lib/opal/parser/grammar.y -o lib/opal/parser/grammar.rb)
+end
+
+namespace :docs do
+  task :clone do
+    if File.exists? 'gh-pages'
+     Dir.chdir('gh-pages') { sh 'git pull origin gh-pages' }
+    else
+      FileUtils.mkdir_p 'gh-pages'
+      Dir.chdir('gh-pages') do
+        sh 'git clone git@github.com:/adambeynon/opal.git .'
+        sh 'git checkout gh-pages'
+      end
+    end
+  end
+
+  desc "Copy required files into gh-pages dir"
+  task :copy => :browser do
+    %w[opal.js opal.debug.js index.html].each do |f|
+      FileUtils.cp f, "gh-pages/#{f}"
+    end
+  end
+end
+
+HEADER = <<-HEADER
+/*!
+ * opal v#{Opal::VERSION}
+ * http://adambeynon.github.com/opal
+ *
+ * Copyright 2012, Adam Beynon
+ * Released under the MIT license
+ */
+HEADER
+
+def build_runtime debug = false
+  rborder = File.read('runtime/corelib/load_order').strip.split
+  rbcore  = rborder.map { |c| File.read "runtime/corelib/#{c}.rb" }
+  jsorder = File.read('runtime/kernel/load_order').strip.split
+  jscore  = jsorder.map { |c| File.read "runtime/kernel/#{c}.js" }
+
+  parser  = Opal::Parser.new :debug => debug
+  parsed  = parser.parse rbcore.join("\n"), '(corelib)'
+  methods = Opal::Parser::METHOD_NAMES.map { |f, t| "'#{f}': 'm$#{t}$'" }
+  result  = []
+
+  result << '(function(undefined) {'
+  result << jscore.join
+  result << "var method_names = {#{methods.join ', '}};"
+  result << "var reverse_method_names = {}; for (var id in method_names) {"
+  result << "reverse_method_names[method_names[id]] = id;}"
+  result << parsed
+  result << '}).call(this);'
+
+  HEADER + result.join("\n")
+end
+
+def sizes file
+  o = File.read file
+  m = uglify o
+  g = gzip m
+
+  puts "#{file}:"
+  puts "development: #{o.size}, minified: #{m.size}, gzipped: #{g.size}"
+end
+
+# Used for uglifying source to minify
+def uglify(str)
+  IO.popen('uglifyjs -nc', 'r+') do |i|
+    i.puts str
+    i.close_write
+    return i.read
+  end
+end
+
+# Gzip code to check file size
+def gzip(str)
+  IO.popen('gzip -f', 'r+') do |i|
+    i.puts str
+    i.close_write
+    return i.read
+  end
+end

data/bin/opal

@@ -1,7 +1,6 @@
-#!/usr/bin/env ruby
+#! /usr/bin/env ruby
 
 require 'opal'
 require 'opal/command'
 
 Opal::Command.new ARGV
-

data/docs/spec_runner.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html; charset=utf-8">
+
+  <title>Opal Spec Runner</title>
+</head>
+<body>
+  <script src="../opal.debug.js"></script>
+  <script src="../opal-spec.js"></script>
+  <script src="../opal.test.js"></script>
+  <script>
+    opal.main('/runtime/spec/spec_helper.rb');
+  </script>
+</body>
+</html>

data/index.html

@@ -0,0 +1,434 @@
+<!DOCTYPE HTML>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html; charset=utf-8" />
+
+  <title>Opal</title>
+  <style>
+    body {
+      line-height: 22px;
+      font-size: 14px;
+      font-family: Helvetica Neue, Helvetica, Arial, sans-serif;
+    }
+
+    .content {
+      padding: 50px 50px 50px 50px;
+      width: 650px;
+    }
+
+    p {
+      width: 650px;
+    }
+
+    pre, code {
+      font-family: "Bitstream Vera Sans Mono", Monaco, "Lucida Console", monospace;
+      font-size: 12px;
+    }
+
+    pre {
+      line-height: 17px;
+      color: #444444;
+      white-space: pre;
+      padding: 3px 0px 3px 12px;
+      margin: 0px 0px 8px;
+
+      background: #FAFAFA;
+      -webkit-box-shadow: rgba(0,0,0,0.07) 0 1px 2px inset;
+      -webkit-border-radius: 3px;
+      -moz-border-radius: 3px;
+      border-radius: 3px;
+      border: 1px solid #DDDDDD;
+    }
+
+    code {
+      background-color: #FAFAFA;
+      padding: 1px;
+      color: #444444;
+      border: 1px solid #DEDEDE;
+    }
+
+    pre code {
+      border: none;
+      padding: 0px;
+    }
+
+    a {
+      color: #212121;
+    }
+  </style>
+</head>
+<body>
+  <div class="content">
+    <h1 id='opal'>Opal</h1>
+
+    <p>
+      <strong>Opal is a ruby to javascript compiler</strong>. 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.
+    </p>
+
+    <p>
+      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.
+    </p>
+
+    <p>
+      Opal is <a href='http://github.com/adambeynon/opal'>hosted on github</a>,
+      and there is a Freenode IRC channel at <code>#opal</code>.
+    </p>
+
+    <h2 id='downloads'>Downloads</h2>
+
+    <p>
+      The Opal runtime and corelib are distributed here, and are required to
+      run any code generated by opal.
+    </p>
+
+    <p>
+      <strong>Production</strong> version to be used in real apps/sites.
+    </p>
+
+    <p>
+      <a href='http://adambeynon.github.com/opal/opal.js'>
+        Production version 0.3.15
+      </a>
+      <em>(120kb Uncompressed, 13.7kb Minified And Gzipped)</em>
+    </p>
+
+    <p>
+      <strong>Debug</strong> version adds a lot of additional debug code.
+      See the debug section below.
+    </p>
+
+    <p>
+      <a href='http://adambeynon.github.com/opal/opal.debug.js'>
+        Debug version 0.3.15
+      </a>
+      <em>(183kb Uncompressed)</em>
+    </p>
+
+    <h2 id='installation'>Installation</h2>
+
+    <p>Opal comes distributed as a gem, so either install with:</p>
+
+    <pre><code>gem install opal</code></pre>
+
+    <p>Or add to your Gemfile:</p>
+
+    <pre><code>gem &quot;opal&quot;</code></pre>
+
+    <h2 id='usage'>Usage</h2>
+
+    <p>
+      Opal provides an <code>opal</code> command which can be used to
+      compile ruby sources into javascript. These can then be used in
+      any browser/javascript environment. Opal also comes with the
+      ability to run files direcly using
+      <a href='http://github.com/cowboyd/therubyracer'>therubyracer</a>,
+      which is a gem to embed v8 into ruby. This also allows Opal to provide
+      a REPL to run ruby code directly against the Opal runtime.
+    </p>
+
+    <h3 id='repl'>REPL</h3>
+
+    <p>To run the ruby repl, simply run:</p>
+
+    <pre><code>opal</code></pre>
+
+    <p>from the command line. To exit, type <code>exit</code>.</p>
+
+    <h3 id='running_a_ruby_file'>Running a ruby file</h3>
+
+    <p>
+      Opal can compile/eval any ruby file inside the v8 context by simply
+      passing a path to run:
+    </p>
+
+    <pre><code>opal path/to/file.rb</code></pre>
+
+    <p>Try running some code with <code>puts</code> statements.</p>
+
+    <h3 id='compiling_ruby_sources'>Compiling Ruby Sources</h3>
+
+    <p>If you have a ruby source <code>foo.rb</code>:</p>
+
+<pre>
+# foo.rb
+
+puts "Wow, running ruby"
+</pre>
+
+    <p>Compile it into <code>foo.js</code> using:</p>
+
+<pre>
+opal -c foo.rb
+</pre>
+
+    <p>
+      The generated code includes a wrapper which will register the
+      file with opal. Opal maintains an internal file system to make
+      <code>require()</code> work as expected. You will see this in
+      the output:
+    </p>
+
+<pre>
+// foo.js
+opal.file('foo.rb', function() {
+  // compiled ruby code
+});
+</pre>
+
+    <p>
+      This file is not enough to run by itself. It depends on
+      <code>opal.js</code> which can be downloaded above. Finally,
+      compiling a ruby source creates a wrapper around the code which
+      will register the file with the opal runtime. To actually load
+      this code, you can use the <code>main()</code> function:
+    </p>
+
+<pre>
+opal.main('foo');
+</pre>
+
+    <p>These files can be added to a HTML page:</p>
+
+<pre>
+&lt;!DOCTYPE html&gt;
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;script src="opal.js"&gt;&lt;/script&gt;
+    &lt;script src="foo.js"&gt;&lt;/script&gt;
+    &lt;script&gt;
+      opal.main('foo');
+    &lt;/script&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+
+  &lt;/body&gt;
+&lt;/html&gt;
+</pre>
+
+    <p>Open this file and check out the browsers' console.</p>
+
+    <h2 id='generated_code'>Generated Code</h2>
+
+    <p>
+      The Opal compiler is a source-to-source compiler; it reads in ruby
+      code and ouputs javascript code. The generated code makes use of native
+      javascript features when possible, and all code is output to the same
+      line number as the source. This, along with correctly indented output,
+      makes debugging very easy.
+    </p>
+
+    <h3 id='ruby_literals'>Ruby Literals</h3>
+
+    <h4 id='literals'>Literals</h4>
+
+    <p>
+      <strong>self</strong> is always compiled to <code>this</code> in
+      javascript which makes the generated code a lot cleaner to use. All
+      methods, blocks, classes, modules and top level code correctly have
+      their <code>this</code> value set.
+    </p>
+
+    <p>
+      <strong>true</strong> and <strong>false</strong> are also compiled into
+      their native javascript equivalents. This makes interacting with
+      external libraries a lot easier as there is no need to convert to
+      special ruby values.
+    </p>
+
+    <p>
+      <strong>nil</strong> is compiled into a special ruby object (an instance
+      of NilClass). A real object is used (instead of null and undefined) as
+      this allows nil to receive method calls which is a crucial ruby feature
+      which Opal maintains.
+    </p>
+
+    <h4 id='strings'>Strings</h4>
+
+    <p>
+      Ruby strings are compiled directly into javascript strings, for
+      performance as well as readability. This has the side affect that Opal
+      does not support mutable strings - all strings are immutable.
+    </p>
+
+    <h4 id='symbols'>Symbols</h4>
+
+    <p>
+      For performance reasons, Symbols compile into the string equivalents.
+      Opal supports the symbol syntax(es), but does not have a real Symbol
+      class. The Symbol constant is just an alias of String. Strings and
+      Symbols can be used in Opal interchangeably.
+    </p>
+
+    <h4 id='numbers'>Numbers</h4>
+
+    <p>
+      In Opal there is a single class for all numbers; <code>Numeric</code>.
+      To keep Opal as performant as possible, native javascript strings are
+      used. This has the side effect that all numbers must be an instance of
+      a single class. Most relevant methods from <code>Integer</code>,
+      <code>Float</code> and <code>Numeric</code> are implemented on this
+      class.
+    </p>
+
+    <h4 id='arrays'>Arrays</h4>
+
+    <p>Ruby arrays compile straight into javascript array literals.</p>
+
+    <h4 id='hash'>Hash</h4>
+
+    <p>
+      There is a special constructor available inside generated sources,
+      <code>$hash</code> which is used to create hash instances.
+    </p>
+
+    <h4 id='range'>Range</h4>
+
+    <p>
+      Similarly to hashes, the <code>$range</code> constructor can be used
+      to create new range instances.
+    </p>
+
+    <h3 id='ruby_methods'>Ruby Methods</h3>
+
+    <p>
+      A ruby method is just a function in the generated code. These functions
+      are added to the constructor&#8217;s prototypes so they are called just
+      like any other javascript function. All ruby methods are defined with
+      an <code>m$</code> prefix which isolates them from any javascript
+      function/property on the receiver.
+    </p>
+
+    <h4 id='method_calls'>Method Calls</h4>
+
+    <p>
+      All arguments are added to regular javascript function calls with the
+      addition of a block argument. If a block is given, then it will be the
+      first argument in the call. If no block is given then the first argument
+      will be null. This block argument is invisible to the ruby code.
+    </p>
+
+    <p>The following ruby code:</p>
+
+<pre>
+do_something 1, 2, 3
+self.length
+[1, 2, 3].push 5
+</pre>
+
+    <p>Will therefore compile into the following easy to read javascript:</p>
+
+<pre>
+this.m$do_something(null, 1, 2, 3);
+this.m$length();
+[1, 2, 3].m$push(null, 5);
+</pre>
+
+    <p>
+      There are of course some special characters valid as ruby names that are
+      not valid as javascript identifiers. These are specially encoded to keep
+      the generated javascript sane:
+    </p>
+
+<pre>
+this.loaded?        # =&gt; this.m$loaded$p()
+this.load!          # =&gt; this.m$load$b()
+this.loaded = true  # =&gt; this.m$loaded$e(null, true)
+</pre>
+
+    <p>Call arguments with splats are also supported.</p>
+
+<pre>
+this.push *[1, 2, 3]
+# =&gt; this.m$push.apply(this, [null].concat([1, 2, 3])
+</pre>
+
+    <p>When a block argument is given, it will be added as the first call arg.</p>
+
+<pre>
+describe &quot;some test&quot; do; ... end
+# =&gt; this.m$describe(function() { ... }, &quot;some test&quot;)
+</pre>
+
+    <h4 id='method_definitions'>Method Definitions</h4>
+
+    <p>
+      Methods are implemented as regular javascript functions. Assuming the
+      following method definition defined inside a class body:
+    </p>
+
+<pre>
+def to_s
+  inspect
+end
+</pre>
+
+    <p>
+      This would generate the following javascript (<code>$proto</code> will
+      be explained in the Class documentation):
+     </p>
+
+<pre>
+$proto.m$to_s = function() {
+  return this.m$inspect();
+};
+</pre>
+
+    <p>
+      The defined name retains the <code>m$</code> prefix outlined above,
+      and the <code>self</code> value for the method is <code>this</code>,
+      which will be the receiver.
+    </p>
+
+    <p>Normal arguments, splat args and optional args are all supported:</p>
+
+<pre>
+def norm(a, b, c)
+
+end
+
+def opt(a, b = 100)
+
+end
+
+def rest(a, *b)
+
+end
+</pre>
+
+    <p>
+      The generated code includes an empty block definition
+      <code>$block</code> which will not be used as this method does not
+      yield to a block:
+    </p>
+
+<pre>
+$proto.m$norm = function($block, a, b, c) {
+  return nil;
+};
+
+$proto.m$opt = function($block, a, b) {
+  if (b === undefined) b = 10;
+  return nil;
+};
+
+$proto.m$rest = function($block, a, b) {
+  b = Array.prototype.slice.call(arguments, 2);
+  return nil;
+};
+</pre>
+
+    <h2 id="change_log">Change Log</h2>
+
+    <h3>0.3.15</h3>
+
+    <p>Initial Release.</p>
+  </div>
+</body>
+</html>