opal 0.5.5 → 0.6.0

data/doc/compiler.md

@@ -1,42 +0,0 @@
-# Opal Compiler
-
-Opal is a source to source compiler. It accepts ruby code as a string and
-generates javascript code which can be run in any environment. Generated
-code relies on the opal runtime which provides the class system and some
-other runtime helpers.
-
-## Compiler stages
-
-The compiler can be broken down into 3 separate stages:
-
-* lexing
-* parsing
-* code generation
-
-### Lexer
-
-The [opal lexer](../lib/opal/parser/lexer.rb) is implemented in pure ruby using
-the `StringScanner` class from the opal stdlib. The source code is scanned
-and tokens are then provided to the parser. This process simply converts
-the ruby code given as a string, into a list of tokens representing the
-parts of the ruby code.
-
-### Parser
-
-The [opal parser](../lib/opal/parser/grammar.y) is implemented using a standard
-bison like syntax, but relies on `racc`, a ruby implementation of yacc/bison
-which is again available in the standard library. The parser takes these tokens
-generated by the lexer and builds a syntax tree representing the ruby code.
-This syntax tree is represented by [sexps](../lib/opal/parser/sexp.rb). As
-ruby is such a complex and dynamic language, there is a lot of interaction
-between the parser and the lexer, namely through a preserved `lex_state`.
-
-### Code generation
-
-The [opal compiler](../lib/opal/compiler.rb) takes these sexps from the parser
-and generates ruby code from them. Each type of sexp has [its own node type](../lib/opal/nodes/base.rb)
-used to generate javascript. Each node creates an array of one or more
-[fragments](../lib/opal/fragment.rb) which are the concatendated together to
-form the final javascript. Fragments are used as they contain the generated
-code as well as a reference back to the original sexp which is useful for
-generating source maps afterwards.

data/doc/compiler_options.md

@@ -1,5 +0,0 @@
-## General options to be used inside source files
-
-* method_missing
-* const_missing
-* optimized operators for Number

data/doc/examples/node_http_server.rb

@@ -1,49 +0,0 @@
-# run with:
-#
-#   bundle exec ./bin/opal ./doc/examples/node_http_server.rb
-#
-
-%x{
-  var http;
-  http = require('http');
-}
-
-
-module HTTP
-  class Server
-    %x{
-      var dom_class = http.Server;
-      #{self}['_proto'] = dom_class.prototype;
-      def = #{self}._proto;
-      dom_class.prototype._klass = #{self};
-    }
-
-    def self.__http__
-      Native(`http`)
-    end
-
-    alias_native :listen, :listen
-
-    def self.start options = {}, &block
-      host = options[:host] || '127.0.0.1'
-      port = options[:port] || 3000
-
-      server = __http__.createServer do |req, res|
-        req = Native(req)
-        res = Native(res)
-        status, headers, body = block.call(`req`)
-        res.writeHead(status, headers.to_n);
-        res.end(body.join(' '));
-      end
-
-      server.listen(port, host)
-      puts("Server running at http://#{host}:#{port}/");
-      server
-    end
-  end
-end
-
-util = Native(`require('util')`)
-HTTP::Server.start port: 3000 do |env|
-  [200, {'Content-Type' => 'text/plain'}, ["Hello World!\n", util.inspect(env)]]
-end

data/doc/external_libraries.md

@@ -1,9 +0,0 @@
-# Using external libraries in your opal app
-
-## with Opal::Builder
-
-_WIP_
-
-## With opal-sprockets
-
-_WIP_

data/doc/generated_javascript.md

@@ -1,272 +0,0 @@
-# Generated Javascript
-
-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.
-
-## Overview
-
-ruby                     | javascript
--------------------------|---------------------------
-`self`                   | `this`
-`true`                   | `true`
-`false`                  | `false`
-`nil`                    | `nil`
-`42`                     | `42`
-`3.142`                  | `3.142`
-`"hello"`                | `"hello"`
-`:world`                 | `"world"`
-`[1, 2, 3]`              | `[1, 2, 3]`
-`{ "a" => 2, "b" => 4 }` | `$opal.hash("a", 2, "b", 4)`
-`1..10`                  | `$opal.range(1, 10)`
-`recv.foo`               | `recv.$foo()`
-`recv.bar(1, 2, 3)`      | `recv.$bar(1, 2, 3)`
-`recv.baz = 10`          | `recv['$baz='](10)`
-`a + b`                  | `a['$+'](b)`
-
-## Literals
-
-**self** is mostly compiled to `this`. Methods and blocks are implemented
-as javascript functions, so their `this` value will be the right
-`self` value. Class bodies and the top level scope use a `self` variable
-to improve readability.
-
-**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 to a `nil` javascript variable. `nil` is a real object
-which allows methods to be called on it. Opal cannot send methods to `null`
-or `undefined`, and they are considered bad values to be inside ruby code.
-
-```ruby
-nil         # => nil
-true        # => true
-false       # => false
-self        # => self
-```
-
-##### 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"]
-```
-
-##### Hash
-
-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.
-
-```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)
-```
-
-## Logic and conditionals
-
-As per ruby, Opal treats only `false` and `nil` as falsy, everything
-else is a truthy value including `""`, `0` and `[]`. This differs from
-javascript as these values are also treated as false.
-
-For this reason, most truthy tests must check if values are `false` or
-`nil`.
-
-Taking the following test:
-
-```ruby
-val = 42
-
-if val
-  return 3.142;
-end
-```
-
-This would be compiled into:
-
-```javascript
-var val = 42;
-
-if (val !== false && val !== nil) {
-  return 3.142;
-}
-```
-
-This makes the generated truthy tests (`if` statements, `and` checks and
-`or` statements) a litle more verbose in the generated code.
-
-## Instance variables
-
-Instance variables in Opal work just as expected. When ivars are set or
-retrieved on an object, they are set natively without the `@` prefix.
-This allows real javascript identifiers to be used which is more
-efficient then accessing variables by string name.
-
-```ruby
-@foo = 200
-@foo  # => 200
-
-@bar  # => nil
-```
-
-This gets compiled into:
-
-```javascript
-this.foo = 200;
-this.foo;   // => 200
-
-this.bar;   // => nil
-```
-
-## Interacting with javascript
-
-Opal tries to interact as cleanly with javascript and its api as much
-as possible. Ruby arrays, strings, numbers, regexps, blocks and booleans
-are just javascript native equivalents. The only boxed core features are
-hashes.
-
-As most of the corelib deals with these low level details, opal provides
-a special syntax for inlining javascript code. This is done with
-x-strings or "backticks", as their ruby use has no useful translation
-in the browser.
-
-```ruby
-`window.title`
-# => "Opal: ruby to javascript compiler"
-
-%x{
-  console.log("ruby version is:");
-  console.log(#{ OPAL_VERSION });
-}
-
-# => ruby version is:
-# => 0.3.19
-```
-
-Even interpolations are supported, as seen here.
-
-This feature of inlining code is used extensively, for example in
-Array#length:
-
-```ruby
-class Array
-  def length
-    `this.length`
-  end
-end
-```
-
-X-Strings also have the ability to automatically return their value,
-as used by this example.
-
-## 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($opal) {
-  var $klass = $opal.klass, self = $opal.top;
-  // generated code
-})(Opal);
-```
-
-As a complete example, assuming the following code:
-
-```ruby
-puts "foo"
-```
-
-This would compile directly into:
-
-```javascript
-(function($opal) {
-  var $klass = $opal.klass, self = $opal.top;
-  self.$puts("foo");
-})(Opal);
-```
-
-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.
-
-## Debugging and finding errors
-
-Because Opal does not aim to be fully compatible with ruby, there are
-some instances where things can break and it may not be entirely
-obvious what went wrong.
-
-### Using javascript debuggers
-
-As opal just generates javascript, it is useful to use a native
-debugger to work through javascript code. To use a debugger, simply
-add an x-string similar to the following at the place you wish to
-debug:
-
-```ruby
-# .. code
-`debugger`
-# .. more code
-```
-The x-strings just pass the debugger statement straight through to the
-javascript output.
-
-All local variables and method/block arguments also keep their ruby
-names except in the rare cases when the name is reserved in javascript.
-In these cases, a `$` suffix is added to the name (e.g. `try` =>
-`try$`).

data/doc/home.md

@@ -1,17 +0,0 @@
-# Opal
-
-[Generated Javascript](generated_javascript.md) An overview of the compiler output
-
-[Method Missing](method_missing.md) How Opal implements method_missing
-
-[Using Ruby from Javascript](using_ruby_from_javascript.md) How to access ruby methods from JS
-
-## Usage
-
-[Static Application](static_applications.md) Just build your app and dependencies to a build.js file
-
-[Using Sprockets](using_sprockets.md) Use rack/sprockets to auto-recompile an opal application
-
-## Compiler
-
-[Opal Compiler](compiler.md) An overview of how the compiler works

data/doc/method_missing.md

@@ -1,58 +0,0 @@
-Opal supports `method_missing`! This is a key feature of ruby, and opal wouldn't be much use without it! This page details the implementation of `method_missing` for Opal.
-
-## Method dispatches
-
-Firstly, a ruby call `foo.bar 1, 2, 3` is compiled into the following javascript:
-
-```javascript
-foo.$bar(1, 2, 3)
-```
-
-This should be pretty easy to read. The `bar` method has a `$` prefix just to distinguish it from underlying javascript properties, as well as ruby ivars. Methods are compiled like this to make the generated code really readable.
-
-## Handling method_missing
-
-Javascript does not have an equivalent of `method_missing`, so how do we handle it? If a function is missing in javascript, then a language level exception will be raised.
-
-To get around this, we make use of our compiler. During parsing, we collect a list of all method calls made inside a ruby file, and this gives us a list of all possible method calls. We then add stub methods to the root object prototype (an opal object, not the global javascript Object) which will proxy our method missing calls for us.
-
-For example, assume the following ruby script:
-
-```ruby
-first 1, 2, 3
-second "wow".to_sym
-```
-
-After parsing, we know we only ever call 3 methods: `[:first, :second, :to_sym]`. So, imagine we could just add these 3 methods to `BasicObject` in ruby, we would get something like this:
-
-```ruby
-class BasicObject
-  def first(*args, &block)
-    method_missing(:first, *args, &block)
-  end
-
-  def second(*args, &block)
-    method_missing(:second, *args, &block)
-  end
-
-  def to_sym(*args, &block)
-    method_missing(:to_sym, *args, &block)
-  end
-end
-```
-
-It is obvious from here, that unless an object defines any given method, it will always resort in a dispatch to `method_missing` from one of our defined stub methods. This is how we get `method_missing` in opal.
-
-## Optimising generated code
-
-To optimise the generated code slightly, we reduce the code output from the compiler into the following javascript:
-
-```javascript
-Opal.add_stubs(["first", "second", "to_sym"]);
-```
-
-You will see this at the top of all your generated javascript files. This will add a stub method for all methods used in your file.
-
-## Alternative approaches
-
-The old approach was to inline `method_missing` calls by checking for a method on **every method dispatch**. This is still supported via a parser option, but not recommended.