opal 0.8.0 → 0.8.1.rc1

data/docs/compiler.md

@@ -0,0 +1,50 @@
+# 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][lexer] 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][parser] 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][sexps]. 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][compiler] takes these sexps from the parser
+and generates ruby code from them. Each type of sexp has [its own node type][base-node]
+used to generate javascript. Each node creates an array of one or more
+[fragments][fragments] 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.
+
+
+[lexer]: https://github.com/opal/opal/tree/master/lib/opal/parser/lexer.rb
+[parser]: https://github.com/opal/opal/tree/master/lib/opal/parser/grammar.y
+[sexps]: https://github.com/opal/opal/tree/master/lib/opal/parser/sexp.rb
+[compiler]: https://github.com/opal/opal/tree/master/lib/opal/compiler.rb
+[fragments]: https://github.com/opal/opal/tree/master/lib/opal/fragment.rb
+[base-node]: https://github.com/opal/opal/tree/master/lib/opal/nodes/base.rb

data/docs/compiler_directives.md

@@ -1,9 +1,7 @@
-# @title Compiler Directives
-
 # Compiler Directives
 
 The Opal compiler supports some special directives that can optimize or
-enhance the output of compiled ruby code to suit the ruby environment.
+enhance the output of compiled Ruby code to suit the Ruby environment.
 
 ## Require Directive
 
@@ -20,22 +18,22 @@ Assuming we have a file `foo.rb`:
     require 'baz'
 
 The compiler will collect these two dependencies, and then `Builder`
-will attempt to discover them within the opal load path to also compile
+will attempt to discover them within the Opal load path to also compile
 them into the target output. If these dependencies cannot be resolved,
 then a compile time error will be thrown.
 
 #### Dynamic Requires
 
 Opal only supports hard-coded requires. This means that any dynamically
-generated require statemnts cannot be discoeverd. Opal may raise an
+generated require statements cannot be discovered. Opal may raise an
 error or just produce a warning if a dynamic require is used. A dynamic
 require is any require that cannot be resolved using static analysis. A
-common use case of dynamic requires is to include a directory of ruby
+common use case of dynamic requires is to include a directory of Ruby
 files. In this case, see `require_tree` below.
 
 ### `require_relative`
 
-`require_relative` is also supported by opals compiler for ahead-of-time
+`require_relative` is also supported by Opal's compiler for ahead-of-time
 inclusion.
 
     # foo.rb
@@ -46,8 +44,8 @@ This example will try to resolve `bar.rb` in the same directory.
 ### `autoload`
 
 `autoload` is used to load a modules and classes within a modules
-namespace. Aslong as the string argument given to `autoload` can be
-resolved in Opals load paths, in the same way as `require`, then these
+namespace. As long as the string argument given to `autoload` can be
+resolved in Opal's load paths, in the same way as `require`, then these
 referenced dependencies will also be compiled.
 
     # foo.rb
@@ -59,7 +57,7 @@ In this example, `bar.rb` will also be required.
 
 ### `require_tree`
 
-`require_tree` can be used as an Opal friendly alternative to globbing
+`require_tree` can be used as an Opal-friendly alternative to globbing
 over a directory to require a list of dependencies.
 
     # foo.rb
@@ -70,58 +68,66 @@ directory and also compile them to the output. At runtime this method
 will then loop over all modules defined, and require them if they match
 that given module path.
 
-Note: The given directory **must** be inside Opals load path, otherwise
+Note: The given directory **must** be inside Opal's load path, otherwise
 no files will be compiled.
 
-### Handling non-ruby requirements
+### Handling non-Ruby requirements
 
-Opal's `require` method is also special as it allows non-ruby source
+Opal's `require` method is also special as it allows non-Ruby source
 files to be required and generated in the output. The obvious example of
-this is requiring javascript source files. Javascript sources are
-treated as first class citizens in Opal. The  Opal gem also supports
+this is requiring JavaScript source files. JavaScript sources are
+treated as first class citizens in Opal. The Opal gem also supports
 compiling `.erb` files using the same process.
 
 ## Opal Specific Code Compilation
 
 A special case `if` and `unless` statements can hide or show blocks of
 code from the Opal compiler. These check against `RUBY_ENGINE` or
-`RUBY_PLATFORM`. As these are valid ruby statements against constants
-that exist in all ruby runtimes, they will not affect any running code:
+`RUBY_PLATFORM`. As these are valid Ruby statements against constants
+that exist in all Ruby runtimes, they will not affect any running code:
 
-    if RUBY_ENGINE == 'opal'
-      # this code compiles
-    else
-      # this code never compiles
-    end
+```ruby
+if RUBY_ENGINE == 'opal'
+  # this code compiles
+else
+  # this code never compiles
+end
+```
 
 Unless statements are also supported:
 
-    unless RUBY_ENGINE == 'opal'
-      # this code will not run
-    end
+```ruby
+unless RUBY_ENGINE == 'opal'
+  # this code will not run
+end
+```
+
 
 Also `!=` statements work:
 
-    if RUBY_ENGINE != 'opal'
-      puts "do not run this code"
-    end
+```ruby
+if RUBY_ENGINE != 'opal'
+  puts 'do not run this code'
+end
+```
+
 
-These blocks of code dont run at all at runtime, but they also never
-compile so will never be in the output javascript code. This is
-particularly useful for using code in both mri and Opal.
+These blocks of code don't run at all at runtime, but they also never
+compile so will never be in the output JavaScript code. This is
+particularly useful for using code in both MRI and Opal.
 
 Some uses are:
 
   * Avoid `require` statements being picked up by Opal compile time
     require handling.
 
-  * To stop certain requires taking place for opal (and vice-versa for
+  * To stop certain requires taking place for Opal (and vice-versa for
     shared libraries).
 
-  * To wrap x-strings which might break in compiled javascript output.
+  * To wrap x-strings which might break in compiled JavaScript output.
 
   * To simply avoid compiling large blocks of code that are not needed
-    in the javascript/opal version of an app.
+    in the JavaScript/Opal version of an app.
 
 In all these examples `RUBY_PLATFORM` can be used instead of
 `RUBY_ENGINE`.

data/docs/configuring_gems.md

@@ -0,0 +1,148 @@
+# Configuring Gems For Opal
+
+To configure a gem to run in Opal the gem will need a couple of things:
+
+1. The opal gem running on a server (so the ruby code can get compiled to .js.)
+2. The opal search path has to know to look for your gem when it is required.
+
+This is done by having the following 2 lines in your outermost .rb file:
+
+```ruby
+require 'opal'
+Opal.append_path File.expand_path('..', __FILE__).untaint
+```
+
+However it only makes sense to execute these lines outside of Opal, since what they do is set things up for Opal to find and compile the files to .js. So how these lines get added to your gem depends on whether the gem can usefully run in the normal server environment as well as in Opal, or just strictly in Opal.
+
+For example, you have a gem that parses, validates, and gives details on email addresses.  This gem would be just as useful on the server, as running
+in the browser.
+
+On the other hand you have a gem that does something with the DOM.  There would be no point in making this gem available to the server.
+
+Each case is detailed below, assuming you have a Gem file structure like this:
+
+
+```
+/lib
+  /your_gem_directory
+    /your_gem_file1.rb
+    /your_gem_file2.rb
+    /...
+    /version.rb
+  /your_gem.rb
+```
+
+## Configuring Gems To Run Everywhere
+
+If your gem will work both in Opal and in a classic ruby environment
+your outer .rb file (`your_gem.rb`) needs to look like this
+
+```ruby
+# require all the files, regardless of whether this code is running
+# to run on the server, or inside of Opal.
+require_relative 'your_gem_directory/your_gem_file1.rb'
+require_relative 'your_gem_directory/your_gem_file2.rb'
+# etc
+require_relative 'your_gem_directory/version'
+unless RUBY_ENGINE == 'opal'
+  # Now if we are NOT running inside of opal, set things up so opal can find
+  # the files. The whole thing is rescued in case the opal gem is not available.
+  # This would happen if the gem is being used server side ONLY.
+  begin
+    require 'opal'
+    Opal.append_path File.expand_path('..', __FILE__).untaint
+  rescue LoadError
+  end
+end
+```
+
+So lets see what happens here.
+
+1. Somebody is going to require this file, perhaps implicitly (for example you are running in rails.)
+2. Standard ruby is going to execute the `require`s, which will load your gem sources, then
+3. because the `RUBY_ENGINE` is _not_ `opal`, Opal will be required, and your directory of sources added to Opal's search path.
+4. Someplace else in some Opal code, the gem will _again_ be required, and so opal searches and finds the gem,
+5. and runs this file again, _but now inside_ of the Opal environment.  This time the `RUBY_ENGINE` _is_ Opal so the `require 'opal'` etc will not be executed.
+
+The result is that you have two versions of the code, one in standard ruby, and a second compiled to .js and ready to be served.
+
+## Configuring Gems To Run In Opal Only
+
+If it makes no sense to run the code in standard Ruby (i.e. on the server) then the above code can look like this:
+
+```ruby
+# require all the files, only if Opal is executing
+if RUBY_ENGINE == 'opal'
+  require_relative 'your_gem_directory/your_gem_file1.rb'
+  require_relative 'your_gem_directory/your_gem_file2.rb'
+  # etc
+  require_relative 'your_gem_directory/version'
+else
+  # NOT running inside of opal, set things up
+  # so opal can find the files.
+  require 'opal'
+  Opal.append_path File.expand_path('..', __FILE__).untaint
+end
+```
+
+## Testing
+
+Regardless of which case your gem is designed for, you will want to make sure you test inside the Opal environment.  If nothing else you will want to make sure you have all the above configuration setup correctly.
+
+To do this add the following to your gemspec:
+
+```ruby
+spec.add_development_dependency "opal-rspec"
+spec.add_development_dependency "opal"
+```
+
+Then setup the following in config.ru (assuming your specs are in the /spec directory.)
+
+```ruby
+require 'bundler'
+Bundler.require
+
+require 'opal-rspec'
+Opal.append_path File.expand_path('../spec', __FILE__)
+
+run Opal::Server.new { |s|
+  s.main = 'opal/rspec/sprockets_runner'
+  s.append_path 'spec'
+  s.debug = false
+  s.index_path = 'spec/index.html.erb'
+}
+```
+
+Finally create a index.html.erb file in the spec directory with the following contents:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+</head>
+<body>
+  <%= javascript_include_tag @server.main %>
+</body>
+</html>
+```
+
+With all this setup, you can run specs normally to test standard ruby execution, and then do
+
+    bundle exec rackup
+
+and point your browser to localhost, and you will see your spec results running in the Opal environment.
+
+Don't forget to checkout the added features of the opal-rspec gem such as async specs.
+
+## Conditional Execution
+
+In some cases you might have to check whether you are in Opal or not, just wrap the code in:
+
+```ruby
+if RUBY_ENGINE == 'opal'
+  # …
+end
+```
+
+This might happen in your specs or in the actual gem code.
+

data/docs/encoding.md

@@ -0,0 +1,13 @@
+# Encoding
+
+Encoding support is partial and mostly given by the encoding set by the HTML page.
+We suggest to always set encoding to UTF-8 explicitly:
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <!-- ... -->
+```
+

data/docs/faq.md

@@ -0,0 +1,17 @@
+# FAQ
+
+### Why does Opal exist?
+
+To try and keep ruby relevant in a world where client-side apps are making javascript the primary development platform.
+
+### How compatible is Opal?
+
+We run opal against [rubyspec](https://github.com/rubyspec/rubyspec) as our primary testing setup. We try to make Opal as compatible as possible, whilst also taking into account restrictions of Javascript when applicable. Opal supports the majority of ruby syntax features, as well as a very large part of the corelib implementation. We support method\_missing, modules, classes, instance\_exec, blocks, procs and lots lots more. Opal can compile and run Rspec unmodified, as well as self hosting the compiler at runtime.
+
+### What version of ruby does Opal target?
+
+We are running tests under ruby 2.0.0 conditions, but are mostly compatible with 1.9 level features.
+
+### Why doesn't Opal support mutable strings?
+
+All strings in Opal are immutable because ruby strings just get compiled direclty into javascript strings, which are immutable. Wrapping ruby strings as a custom Javascript object would add a lot of overhead as well as making interaction between ruby and javascript libraries more difficult.

data/docs/getting_started.md

@@ -0,0 +1,30 @@
+# Getting Started
+
+Opal is a ruby to javascript compiler, an implementation of the ruby corelib and stdlib, and associated gems for building fast client side web applications in ruby.
+
+## Installation
+
+Opal is available as a gem, and can be installed via:
+
+```
+$ gem install opal
+```
+
+Or added to your Gemfile as:
+
+```ruby
+gem 'opal'
+```
+
+## Getting started with Opal
+
+At its very core, opal provides a simple method of compiling a string of ruby into javascript that can run on top of the opal runtime, provided by `opal.js`:
+
+```ruby
+Opal.compile("[1, 2, 3].each { |a| puts a }")
+# => "(function() { ... })()"
+```
+
+`opal` includes sprockets support to sprockets for compiling ruby (and erb) assets, and treating them as first class javascript citizens. It works in a similar way to coffeescript, where javascript files can simply require ruby sources, and ruby sources can require javascript and other ruby files.
+
+This relies on the opal load path. Any gem containing opal code registers that directory to the opal load path. opal will then use all opal load paths when running sprockets instances. For rails applications, opal-rails does this automatically. For building a simple application, we have to do this manually.

data/docs/jquery.md

@@ -0,0 +1,264 @@
+# JQuery
+
+`opal-jquery` offers a nicer ruby-like syntax for JQuery (and Zepto). It is
+useful for projects which cannot use `opal-browser` due to a reliance on jquery
+for plugins or other libraries.
+
+```ruby
+foos = Element.find('.foo')
+# => [<div class="foo">, ...]
+
+foos.class
+# => JQuery
+
+foos.on(:click) do
+  alert "element was clicked"
+end
+```
+
+### Getting Started
+
+#### Installation
+
+`opal-jquery` is distributed as a gem, and needs to be added to your `Gemfile`:
+
+```ruby
+# Gemfile
+gem 'opal'
+gem 'opal-jquery'
+```
+
+#### Usage
+
+`opal-jquery` can now be easily added to your opal application sources using a
+standard require:
+
+```ruby
+# app/application.rb
+require 'opal'
+require 'jquery'
+require 'opal-jquery'
+
+alert "Hello from jquery + opal"
+```
+
+> **Note**: this file requires two important dependencies, `jquery` and `opal-jquery`.
+> You need to bring your own `jquery.js` file as the gem does not include one. If
+> you are using the asset pipeline with rails, then this should be available
+> already, otherwise download a copy and place it into `app/` or whichever directory
+> you are compiling assets from. You can alternatively require a zepto instance.
+
+The `#alert` method is provided by `opal-jquery`. If the message displays, then
+`jquery` support should be working.
+
+### How does opal-jquery work
+
+`opal-jquery` provides an `Element` class, whose instances are toll-free
+bridged instances of jquery objects. Just like ruby arrays are just javascript
+arrays, `Element` instances are just jquery objects. This makes interaction
+with jquery plugins much easier.
+
+Also, `Element` will try to bridge with Zepto if it cannot find jQuery loaded,
+making it ideal for mobile applications as well.
+
+### Interacting with the DOM
+
+#### Finding Elements
+
+opal-jquery provides the `Element` class, which can be used to find elements in
+the current document:
+
+```ruby
+Element.find('#header')
+```
+
+`Element.find` is aliased to `Element[]`:
+
+```ruby
+Element['.my-class']
+```
+
+These methods acts just like `$('selector')`, and can use any jQuery
+compatible selector:
+
+```ruby
+Element.find('#navigation li:last')
+```
+
+The result is just a jQuery instance, which is toll-free bridged to
+instances of the `Element` class in ruby:
+
+```ruby
+Element.find('.foo').class
+# => Element
+```
+
+Instances of `Element` also have the `#find` method available for
+finding elements within the scope of each DOM node represented by
+the instance:
+
+```ruby
+el = Element.find('#header')
+el.find '.foo'
+# => #<Element .... >
+```
+
+#### Running code on document ready
+
+Just like jQuery, opal-jquery requires the document to be ready to
+be able to fully interact with the page. Any top level access should
+use the `ready?` method:
+
+```ruby
+Document.ready? do
+  alert "document is ready to go!"
+end
+```
+
+The `Kernel#alert` method is shown above too.
+
+#### Event handling
+
+The `Element#on` method is used to attach event handlers to elements:
+
+```ruby
+Element.find('#header').on :click do
+  puts "The header was clicked!"
+end
+```
+
+Selectors can also be passed as a second argument to handle events
+on certain children:
+
+```ruby
+Element.find('#header').on(:click, '.foo') do
+  puts "An element with a 'foo' class was clicked"
+end
+```
+
+An `Event` instance is optionally passed to block handlers as well,
+which is toll-free bridged to jquery events:
+
+```ruby
+Element.find('#my_link').on(:click) do |evt|
+  evt.stop_propagation
+  puts "stopped the event!"
+end
+```
+
+You can access the element which triggered the event by `#current_target`.
+
+```ruby
+Document.on :click do |evt|
+  puts "clicked on: #{evt.current_target}"
+end
+```
+
+#### CSS styles and classnames
+
+The various jQuery methods are available on `Element` instances:
+
+```ruby
+foo = Element.find('.foo')
+
+foo.add_class 'blue'
+foo.remove_class 'foo'
+foo.toggle_class 'selected'
+```
+
+There are also added convenience methods for opal-jquery:
+
+```ruby
+foo = Element.find('#header')
+
+foo.class_name
+# => 'red lorry'
+
+foo.class_name = 'yellow house'
+
+foo.class_name
+# => 'yellow house'
+```
+
+`Element#css` also exists for getting/setting css styles:
+
+```ruby
+el = Element.find('#container')
+el.css 'color', 'blue'
+el.css 'color'
+# => 'blue'
+```
+
+### HTTP/AJAX requests
+
+jQuery's Ajax implementation is also wrapped in the top level HTTP
+class.
+
+```ruby
+HTTP.get("/users/1.json") do |response|
+  puts response.body
+  # => "{\"name\": \"Adam Beynon\"}"
+end
+```
+
+The block passed to this method is used as the handler when the request
+succeeds, as well as when it fails. To determine whether the request
+was successful, use the `ok?` method:
+
+```ruby
+HTTP.get("/users/2.json") do |response|
+  if response.ok?
+    alert "successful!"
+  else
+    alert "request failed :("
+  end
+end
+```
+
+It is also possible to use a different handler for each case:
+
+```ruby
+request = HTTP.get("/users/3.json")
+
+request.callback {
+  puts "Request worked!"
+}
+
+request.errback {
+  puts "Request didn't work :("
+}
+```
+
+The request is actually triggered inside the `HTTP.get` method, but due
+to the async nature of the request, the callback and errback handlers can
+be added anytime before the request returns.
+
+#### Handling responses
+
+Web apps deal with JSON responses quite frequently, so there is a useful
+`#json` helper method to get the JSON content from a request:
+
+```ruby
+HTTP.get("/users.json") do |response|
+  puts response.body
+  puts response.json
+end
+
+# => "[{\"name\": \"Adam\"},{\"name\": \"Ben\"}]"
+# => [{"name" => "Adam"}, {"name" => "Ben"}]
+```
+
+The `#body` method will always return the raw response string.
+
+If an error is encountered, then the `#status_code` method will hold the
+specific error code from the underlying request:
+
+```ruby
+request = HTTP.get("/users/3.json")
+
+request.callback { puts "it worked!" }
+
+request.errback { |response|
+  puts "failed with status #{response.status_code}"
+}
+```