opal 0.11.4 → 1.0.0.beta1

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "opal"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/opal

@@ -1,5 +1,4 @@
 #!/usr/bin/env ruby
 
 require 'bundler/setup'
-
 load "#{__dir__}/../exe/opal"

data/bin/opal-benchmark-ips

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+file = ARGV.shift
+if ARGV.any?
+  warn "usage example:\n\n  #{$0} benchmark-ips/bm_case.rb\n"
+  exit 1
+end
+exec 'bundle', 'exec', 'rake', 'bench:ips', "FILE=#{file}"

data/bin/opal-mspec

@@ -1,3 +1,11 @@
 #!/usr/bin/env ruby
 
-exec "#{__dir__}/../exe/#{File.basename($0)}", *ARGV
+specs = ARGV.map do |s|
+  s.end_with?('.rb') ? s : "#{s}/**/*_spec.rb"
+end
+
+env = {}
+env['MSPEC_PATTERN'] = "{#{specs.join(',')}}" if specs.any?
+exec env, 'rake', 'mspec'
+
+# RUBYOPT="-rbundler/setup -rmspec/opal/special_calls" bundle exec mspec run -t opal -pspec/ruby/spec_helper spec/ruby/core/true/*

data/bin/opal-repl

@@ -1,3 +1,4 @@
 #!/usr/bin/env ruby
 
-exec "#{__dir__}/../exe/#{File.basename($0)}", *ARGV
+require 'bundler/setup'
+load "#{__dir__}/../exe/opal-repl"

data/bin/rake

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle update
+
+git submodule update --init

data/docs/compiled_ruby.md

@@ -478,26 +478,107 @@ If you want to integrate a JavaScript library with Opal, so that you can make Ru
 ## Ruby from JavaScript
 
 Accessing classes and methods defined in Opal from the JavaScript runtime is
-possible via the `Opal` js object. The following class:
+possible via the `Opal` JS object. Consider following code:
 
 ```ruby
+module Bar
+  BAR = 123
+end
+
 class Foo
-  def bar
-    puts "called bar on class Foo defined in Ruby code"
+  include Bar
+  FOO = 456
+
+  def foo
+    puts "called #foo on class ::Foo defined in Ruby code"
   end
 end
+
+BAZ = 789
+```
+
+### Navigating constants
+
+Top level constants can be accessed as properties of `Opal`:
+
+
+```javascript
+Opal.Object;       // => Object
+Opal.Kernel;       // => Kernel
+Opal.Array;        // => Array
+Opal.RUBY_VERSION; // => "2.3"
+Opal.Foo;          // => Foo
+Opal.BAZ;          // => 789
+```
+
+To reach nested constants the safest way is to call `#const_get` on `Object`:
+
+```javascript
+Opal.Object.$$const_get('Bar::BAR'); // => 123
+Opal.Object.$$const_get('Foo::BAR'); // => 123
+Opal.Object.$$const_get('Foo::FOO'); // => 456
+Opal.Object.$$const_get('BAZ');      // => 789
+```
+
+Constants can also be navigated using the `$$` property, although this is limited to constants defined directly under the current object:
+
+```javascript
+Opal.Bar.$$.BAR // => 123
+Opal.Foo.$$.FOO // => 456
+Opal.Foo.$$.BAR // => undefined
 ```
 
-Can be accessed from JavaScript like this:
+
+### Calling methods
+
+**Methods** are always prefixed by a single `$`:
 
 ```javascript
-Opal.Foo.$new().$bar();
-// => "called bar on class Foo defined in Ruby code"
+// Equivalent to:
+//   Foo.new.foo
+Opal.Foo.$new().$foo(); // => "called #foo on class ::Foo defined in Ruby code"
+
+// Equivalent to:
+//   "hello there".sub('there', 'world')
+("hello there").$sub('there', 'world'); // => "hello world"
 ```
 
-Remember that all Ruby methods are prefixed with a `$`.
+**Methods names unsupported in JS** should be called using the JS bracket notation:
+
+```javascript
+// Equivalent to:
+//   hash = Hash.new["key"] = "value"
+//   hash["key"] = "value"
+var hash = Opal.Hash.$new();  // => {}
+hash["$[]="]("key", "value"); // => "value"
+
+// Equivalent to:
+//   [1,2,3].reverse!
+[1,2,3]['$reverse!'](); // => [3,2,1]
+
+// Equivalent to:
+//   1 == 2
+(1)['$=='](2); // => false
+```
+
+**Passing blocks** from JS is a bit more tricky, so the suggested solution is to use `Opal.send(…)`:
+
+```javascript
+// Equivalent to:
+//   [1,2,3].map {|n| n * 2}
+Opal.send([1,2,3], 'map', [], function(n) {return n * 2}); // => [2,4,6]
+```
+
+Alternatively blocks can also be called *the hard way* by assigning the block-function to the property `$$p` of the method:
+
+```javascript
+// Equivalent to:
+//   [1,2,3].map {|n| n * 2}
+array = [1,2,3]
+array.$map.$$p = function(n) {return n * 2}; // "$$p" stands for "proc"
+array.$map(); // => [2,4,6]
+```
 
-In the case that a method name can't be called directly due to a JavaScript syntax error, you will need to call the method using bracket notation. For example, you can call `foo.$merge(...)` but not `foo.$merge!(...)`, `bar.$fetch('somekey')` but not `bar.$[]('somekey')`. Instead you would write it like this: `foo['$merge!'](...)` or `bar['$[]']('somekey')`.
 
 
 ### Hash

data/docs/compiler.md

@@ -9,27 +9,12 @@ other runtime helpers.
 
 The compiler can be broken down into 3 separate stages:
 
-* lexing
-* parsing
+* lexing/parsing
 * code generation
 
-### Lexer
+### Lexer/Parser
 
-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`.
+The [opal parser][parser] relies on the `parser` gem, see debug/development documentation there to know more about its internals: https://whitequark.github.io/parser/.
 
 ### Code generation
 
@@ -42,8 +27,6 @@ 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

data/docs/jquery.md

@@ -30,27 +30,60 @@ gem 'opal-jquery'
 
 #### Usage
 
-`opal-jquery` can now be easily added to your opal application sources using a
-standard require:
+`opal-jquery` can now be easily added to your opal application sources:
 
 ```ruby
 # app/application.rb
-require 'opal'
-require 'jquery'
-require 'opal-jquery'
+
+# Remember to compile opal-jquery with your javascript application.
+# See "Compiling" below for an example on compiling dependencies.
+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.
 
+
+#### Compiling
+
+When compiling your application to javascript, you must be sure to include both
+Opal and Opal-JQuery so they'll be available to your application:
+
+```ruby
+require 'opal'
+require 'opal-jquery'
+
+builder = Opal::Builder.new
+builder.build('opal')
+builder.build('opal-jquery')
+builder.build('./app/application.rb')
+
+File.write('application.js', builder.to_s)
+```
+
+then simply load the compiled file in your html:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <script src='https://code.jquery.com/jquery-3.3.1.min.js' integrity='sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8=' crossorigin='anonymous'></script> 
+    <script type='text/javascript' src='./application.js'></script>
+  </head>
+  <body></body>
+</html>
+```
+
+NOTE: opal-jquery expects a jquery library to be loaded. This example loads it
+remotely from jquery.com, but a locally downloaded copy works just as well, or- 
+if you're using rails- jquery may be included automatically.
+
+This example builds opal, opal-jquery and the application into a single `.js` file, 
+but you may build them separately, if you so choose. Just remember to include 
+each respective script in your html!
+
 ### How does opal-jquery work
 
 `opal-jquery` provides an `Element` class, whose instances are toll-free

data/docs/promises.md

@@ -38,7 +38,7 @@ A promise can only be resolved or rejected once.
 
 ### Chaining Promises
 
-Promises become useful when chained together. The prevous example could be extended to get another object from the result of the first request.
+Promises become useful when chained together. The previous example could be extended to get another object from the result of the first request.
 
 ```ruby
 get_json('/users/1.json').then do |json|

data/docs/rails.md

@@ -1,26 +1,30 @@
 # Opal in a Rails application
 
-Add Opal to your Gemfile:
+Add Opal to your Rails app's Gemfile:
 
 ``` ruby
 gem 'opal-rails'
 ```
 
-Or to start off with Opal when you build your new Rails app:
+## Basic usage through the asset pipeline
 
-```bash
-rails new <app-name> --javascript=opal
-```
+To configure your asset pipeline to use opal-rails, make sure to `bundle install`, then rename 
+`app/assets/application.js` to `app/assets/application.js.rb` and set its contents to: 
 
-## Basic usage through the asset pipeline
+```ruby
+# app/assets/application.js.rb
+
+# Require the opal runtime and core library
+require 'opal'
+
+# For Rails 5.1 and above, otherwise use 'opal_ujs'
+require 'rails_ujs'
 
-```js
-// app/assets/application.js.rb
+# Require of JS libraries will be forwarded to sprockets as is
+require 'turbolinks'
 
-//= require opal
-//= require opal_ujs
-//= require turbolinks
-//= require_tree .
+# a Ruby equivalent of the require_tree Sprockets directive is available
+require_tree '.'
 ```
 
 Opal requires are forwarded to the Asset Pipeline at compile time (similarly to what happens for RubyMotion). You can use either the `.rb` or `.opal` extension:

data/docs/sinatra.md

@@ -1,14 +1,14 @@
 # Using Opal with Sinatra
 
-Add Opal to your Gemfile (or install using `gem`):
+Add Opal-Sprockets to your Gemfile (or install using `gem`):
 
 ```ruby
 # Gemfile
 gem 'sinatra'
-gem 'opal', '~> 0.6.2'
+gem 'opal-sprockets'
 ```
 
-Opal uses `sprockets` as its default build system, so the asset-pipeline
+Opal-Sprockets uses `sprockets` as its default build system, so the asset-pipeline
 from rails can be mimicked here to map all ruby assets in the `/assets`
 path to be compiled using opal.
 
@@ -16,16 +16,21 @@ path to be compiled using opal.
 
 ```ruby
 # config.ru
-require 'opal'
+require 'opal-sprockets'
 require 'sinatra'
 
-opal = Opal::Server.new {|s|
+opal = Opal::Sprockets::Server.new {|s|
   s.append_path 'app'
   s.main = 'application'
 }
 
-map opal.source_maps.prefix do
-  run opal.source_maps
+maps_prefix = Opal::Sprockets::Server::SOURCE_MAPS_PREFIX_PATH
+maps_app = Opal::SourceMapServer.new(opal.sprockets, maps_prefix)
+
+map maps_prefix do
+  use Rack::ConditionalGet
+  use Rack::ETag
+  run maps_app
 end
 
 map '/assets' do
@@ -37,7 +42,9 @@ get '/' do
     <!doctype html>
     <html>
       <head>
-        <script src="/assets/application.js"></script>
+        <script src="/assets/opal.js"></script>
+        <script src="/assets/application.self.js"></script>
+        <script type="text/javascript">Opal.load("application")</script>
       </head>
     </html>
   HTML

data/docs/using_sprockets.md

@@ -1,19 +1,20 @@
 # Opal & Sprockets
 
-Opal comes with built-in sprockets support, and provides a simple `Opal::Server`
-class to make it easy to get a rack server up and running for trying out opal.
-This server will automatically recompile ruby sources when they change, meaning
-you just need to refresh your page to autorun.
+The `opal-sprockets` gem adds sprockets support to Opal, providing a simple
+`Opal::Sprockets::server` class to make it easy to get a rack server up and 
+running for trying out opal. This server will automatically recompile ruby 
+sources when they change, meaning you just need to refresh your page to autorun.
 
 ## Getting setup
 
-Add `opal` to a `Gemfile`:
+Add `rack` & `opal-sprockets` to your `Gemfile`:
 
 ```ruby
 #Gemfile
 source 'https://rubygems.org'
 
-gem 'opal', '>= 0.6.0'
+gem 'rack'
+gem 'opal-sprockets'
 ```
 
 And install with `bundle install`.
@@ -28,17 +29,21 @@ require 'opal'
 puts "hello world"
 ```
 
-Finally, we need a html page to run, so create `index.html`:
+
+If we do not provide an HTML index, sprockets will generate one automatically; 
+however, it is often useful to override the default with a custom `erb` file: 
 
 ```html
+<%# index.erb %>
 <!DOCTYPE html>
 <html>
   <head>
     <meta charset="utf-8">
     <title>opal server example</title>
-    <script src="/assets/application.js"></script>
+    <%= javascript_include_tag @server.main %>
   </head>
   <body>
+    you've reached the custom index!
   </body>
 </html>
 ```
@@ -49,15 +54,15 @@ Finally, we need a html page to run, so create `index.html`:
 
 ```ruby
 # config.ru
-require 'bundler'
-Bundler.require
+require 'opal-sprockets'
 
 run Opal::Server.new { |s|
   s.append_path 'app'
 
   s.main = 'application'
 
-  s.index_path = 'index.html'
+  # override the default index with our custom index
+  s.index_path = 'index.erb'
 }
 ```