opal 0.8.1 → 0.9.0.beta1

data/docs/configuring_gems.md

@@ -2,8 +2,8 @@
 
 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.
+1. The opal gem running on a server (so the ruby code can get compiled to JavaScript).
+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:
 

data/docs/faq.md

@@ -6,7 +6,7 @@ To try and keep ruby relevant in a world where client-side apps are making javas
 
 ### 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.
+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?
 
@@ -14,4 +14,4 @@ We are running tests under ruby 2.0.0 conditions, but are mostly compatible with
 
 ### 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.
+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

@@ -25,6 +25,23 @@ 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.
+`opal` includes sprockets support 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.
+
+
+### Adding lookup paths
+
+Opal uses a load path which works with sprockets to create a set of locations which opal can require files
+from. If you want to add a directory to this load path, you can add it to the global environment.
+
+In the `Opal` module, a property `paths` is used to hold the load paths which
+`Opal` uses to require files from. You can add a directory to this:
+
+```ruby
+Opal.append_path '../my_lib'
+```
+
+Now, any ruby files in this directory can be discovered.
+
 
-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

@@ -42,11 +42,11 @@ 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.
+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.

data/docs/opal_parser.md

@@ -0,0 +1,53 @@
+# Parsing Ruby from JavaScript with `opal-parser`
+
+Generally is best to precompile Ruby source files to JavaScript server-side but sometimes may become useful to be able to compile Ruby to JavaScript directly from JS.
+
+Opal is able to compile its – pure Ruby – compiler to JavaScript (how cool is that!). The whole compiler chain is available in the `stdlib` as `opal-parser`.
+
+```ruby
+require 'opal-parser'
+```
+
+
+## Features
+
+### `Kernel#eval`
+
+`opal-parser` provides a partial implementation of `Kernel#eval` that only support the first parameter (String) and refuse any passed `binding`, `lineno` or `filename`.
+
+Example:
+
+```ruby
+require 'opal-parser'
+eval "puts 'hello world!'"
+```
+
+
+### `Kernel#require_remote`
+
+Will fetch a remote URL (by means of a sync `XMLHttpRequest`) and evaluate its contents as Ruby code.
+
+Example:
+
+```ruby
+require 'opal-parser'
+require_remote 'http://pastie.org/pastes/10444960/text'
+HelloWorld.new.say_hello!
+```
+
+
+### `Opal.compile()` and `Opal.eval()` (JavaScript)
+
+After requiring `opal-parser` both `Opal.compile()` and `Opal.eval()` functions are added to the JavaScript API.
+
+`Opal.compile(string, options)` (JavaScript) will forward the call to `Opal.compile` (Ruby) converting options from a plain JS object to a Ruby Hash.
+`Opal.eval(string)` will compile the given code to JavaScript and then pass it to the [native `eval()` function][eval].
+
+
+### Support for `<script type="text/ruby">`
+
+When `opal-parser` is required it will search the page for any `<script>` tag with type `text/ruby`.
+If an `src` attribute is present will fetch and eval the file with `Kernel#require_remote` otherwise it will get the script tags contents and eval them with `Kernel#eval`.
+
+
+[eval]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval

data/docs/unsupported_features.md

@@ -12,11 +12,11 @@ Encodings only have a very small implementation inside Opal.
 
 #### Threads ####
 
-Javascript does not have a native `Thread` implementation, so they are not present inside Opal. There is a placeholder `Thread` class just to provide some small level of compatibility with libraries that expect it. It does not have any function.
+JavaScript does not have a native `Thread` implementation, so they are not present inside Opal. There is a placeholder `Thread` class just to provide some small level of compatibility with libraries that expect it. It does not have any function.
 
 #### Frozen Objects ####
 
-Opal does not currently support frozen objects, but has placeholder methods to prevent other libraries breaking when expecting these methods. Opal could support frozen objects in the future once a similar implementation becomes available across Javascript runtimes.
+Opal does not currently support frozen objects, but has placeholder methods to prevent other libraries breaking when expecting these methods. Opal could support frozen objects in the future once a similar implementation becomes available across JavaScript runtimes.
 
 #### `method_added` and `method_removed` hooks ####
 

data/docs/upgrading.md

@@ -0,0 +1,22 @@
+# Upgrading from v0.8 to v0.9
+
+## `Opal::Processor.load_asset_code` deprecated
+
+`Opal::Processor.load_asset_code(sprockets, name)` has been deprecated in favor of `Opal::Sprockets.load_asset(name, sprockets)`.
+
+## `$console.log` instead of `pp`
+
+Previously `pp` would have forwarded the object to JS own `console.log` but now just prints calling `.inspect` on it similarly to what `p` does.
+
+```ruby
+require 'pp'
+pp a: 1, b: {c: 3}
+```
+
+Now:
+
+```ruby
+require 'console'
+$console.log a: 1, b: {c: 3}
+```
+

data/docs/using_sprockets.md

@@ -70,3 +70,18 @@ Run `bundle exec rackup` and visit the page `http://localhost:9292` in any
 browser. Observe the console to see the printed statement.
 
 You can just change `app/application.rb` and refresh the page to see any changes.
+
+
+## Using an existing `sprockets` instance
+
+We only need to append Opal paths to the existing sprockets instance.
+
+```ruby
+require 'sprockets'
+environment = Sprockets::Environment.new
+
+require 'opal'
+Opal.paths.each do |path|
+  environment.append_path path
+end
+```

data/examples/rack/config.ru

@@ -1,7 +1,20 @@
 require 'bundler'
 Bundler.require
 
+# Instructions: bundle in this directory
+# then run bundle exec rackup to start the server
+# and browse to localhost:9292
+
+# a very small application that just tries to authenticate a user and fails
+# it just writes to the console in the browser (no visible html)
+
+# with gems like opal-jquery or opal-browser you could manipulate the dom directly
+
 run Opal::Server.new { |s|
+  # the name of the ruby file to load. To use more files they must be required from here (see app)
   s.main = 'application'
+  # the directory where the code is (add to opal load path )
   s.append_path 'app'
+  # need to set the index explicitly for opal server to pick it up
+  s.index_path = 'index.html.erb'
 }

data/examples/sinatra/config.ru

@@ -7,6 +7,7 @@ opal = Opal::Server.new {|s|
 }
 
 sprockets   = opal.sprockets
+prefix      = '/assets'
 maps_prefix = '/__OPAL_SOURCE_MAPS__'
 maps_app    = Opal::SourceMapServer.new(sprockets, maps_prefix)
 
@@ -17,19 +18,17 @@ map maps_prefix do
   run maps_app
 end
 
-map '/assets' do
+map prefix do
   run sprockets
 end
 
 get '/' do
-  opal_boot_code = Opal::Processor.load_asset_code(sprockets, 'application')
-
   <<-HTML
     <!doctype html>
     <html>
       <head>
-        <script src="/assets/application.js"></script>
-        <script>#{opal_boot_code}</script>
+        <meta charset="utf-8">
+        #{::Opal::Sprockets.javascript_include_tag('application', sprockets: sprockets, prefix: prefix, debug: true)}
       </head>
     </html>
   HTML

data/lib/mspec/opal/runner.rb

@@ -5,6 +5,7 @@ class OSpecFilter
 
   def initialize
     @filters = Set.new
+    @seen = Set.new
   end
 
   def register
@@ -12,6 +13,7 @@ class OSpecFilter
   end
 
   def ===(description)
+    @seen << description
     @filters.include? description
   end
 
@@ -22,12 +24,58 @@ class OSpecFilter
   def fails(description)
     @filters << description
   end
+
+  def unused_filters_message(list: false)
+    unused = @filters - @seen
+    return if unused.size == 0
+
+    if list
+      puts
+      puts "Unused filters:"
+      unused.each {|u| puts "- #{u}"}
+      puts
+    else
+      warn "\nThere are #{unused.size} unused filters, re-run with ENV['LIST_UNUSED_FILTERS'] = true to list them\n\n"
+    end
+  end
 end
 
 class Object
   def opal_filter(description, &block)
     OSpecFilter.main.register_filters(description, block)
   end
+
+  # Copyed from MSpec, with changes.
+  def with_timezone(name, offset = nil, daylight_saving_zone = "")
+    zone = name.dup
+
+    if offset
+      # TZ convention is backwards
+      offset = -offset
+
+      zone += offset.to_s
+      zone += ":00:00"
+    end
+    zone += daylight_saving_zone
+
+    # WAS:
+    #
+    #   old = ENV["TZ"]
+    #   ENV["TZ"] = zone
+    #
+    #   begin
+    #     yield
+    #   ensure
+    #     ENV["TZ"] = old
+    #   end
+    #
+    if ENV["TZ"] == zone
+      yield
+    else
+      1.should == 1 # MSpec will get mad if the example has no expectations.
+      warn "Skipped spec for TZ=#{zone} as it's not supported"
+    end
+  end
 end
 
 class BrowserFormatter
@@ -171,10 +219,6 @@ class NodeJSFormatter < BrowserFormatter
     end
   end
 
-  def finish_with_code(code)
-    `global.OPAL_SPEC_CODE = code;`
-  end
-
   def finish_with_code(code)
     puts "\n\n"
     exit(code)
@@ -227,9 +271,10 @@ class OSpecRunner
     MSpec.actions :start
   end
 
-  def bm!(repeat)
+  def bm!(repeat, bm_filepath)
     `self.bm = {}`
-    MSpec.repeat = repeat;
+    `self.bm_filepath = bm_filepath`
+    MSpec.repeat = repeat
     MSpec.register :before, self
     MSpec.register :after,  self
   end
@@ -252,17 +297,15 @@ class OSpecRunner
 
   def did_finish
     %x{
-      var obj = self.bm, key, val, json, file;
+      var obj = self.bm, key, val, report = '';
       if (obj) {
         for (key in obj) {
           if (obj.hasOwnProperty(key)) {
             val = obj[key];
-            obj[key] = val.stopped - val.started;
+            report += key.replace(/\s/g, '_') + ' ' + ((val.stopped - val.started) / 1000) + '\n';
           }
         }
-        json = JSON.stringify(obj, null, '  ');
-        file = #{Time.now.strftime('tmp/bm_%Y-%m-%d_%H-%M-%S-%L.json')};
-        #{File.open(`file`, 'w') {|f| f.write(`json`)}}
+        require('fs').writeFileSync(self.bm_filepath, report);
       }
     }
     MSpec.actions :finish

data/lib/opal.rb

@@ -6,6 +6,6 @@ require 'opal/paths'
 require 'opal/version'
 
 # Opal is a ruby to javascript compiler, with a runtime for running
-# in any javascript environment.
+# in any JavaScript environment.
 module Opal
 end

data/lib/opal/builder.rb

@@ -143,7 +143,7 @@ module Opal
     def process_requires(filename, requires, options)
       requires.map { |r| process_require(r, options) }
     rescue MissingRequire => error
-      raise error, "A file required by #{filename.inspect} wasn't found.\n#{error.message}"
+      raise error, "A file required by #{filename.inspect} wasn't found.\n#{error.message}", error.backtrace
     end
 
     def already_processed

data/lib/opal/builder_processors.rb

@@ -62,7 +62,7 @@ module Opal
       end
 
       def mark_as_required(filename)
-        "Opal.mark_as_loaded(Opal.normalize_loadable_path(#{filename.to_s.inspect}));"
+        "Opal.loaded([#{filename.to_s.inspect}]);"
       end
     end
 

data/lib/opal/cli.rb

@@ -105,12 +105,8 @@ module Opal
         builder.build(local_require)
       end
 
-      if evals.any?
-        builder.build_str(evals.join("\n"), '-e')
-      else
-        if file and (filename != '-' or evals.empty?)
-          builder.build_str(file.read, filename)
-        end
+      evals_or_file do |contents, filename|
+        builder.build_str(contents, filename)
       end
 
       builder.build_str 'Kernel.exit', '(exit)' unless no_exit
@@ -127,14 +123,10 @@ module Opal
     end
 
     def show_sexp
-      if evals.any?
-        sexp = Opal::Parser.new.parse(evals.join("\n"), '-e')
-      else
-        if file and (file.path != '-' or evals.empty?)
-          sexp = Opal::Parser.new.parse(file.read, file.path)
-        end
+      evals_or_file do |contents, filename|
+        sexp = Opal::Parser.new.parse(contents, filename)
+        puts sexp.inspect
       end
-      puts sexp.inspect
     end
 
     def map
@@ -154,6 +146,18 @@ module Opal
       ]
     end
 
+    # Internal: Yelds a string of source code and the proper filename for either
+    #           evals, stdin or a filepath.
+    def evals_or_file
+      if evals.any?
+        yield evals.join("\n"), '-e'
+      else
+        if file and (filename != '-' or evals.empty?)
+          yield file.read, filename
+        end
+      end
+    end
+
     def puts(*args)
       output.puts(*args)
     end

data/lib/opal/cli_options.rb

@@ -119,7 +119,7 @@ module Opal
       dynamic_require_levels = %w[error warning ignore]
       on('-D', '--dynamic-require LEVEL', dynamic_require_levels,
                     'Set level of dynamic require severity.',
-                    "(deafult: error, values: #{dynamic_require_levels.join(', ')})") do |level|
+                    "(default: error, values: #{dynamic_require_levels.join(', ')})") do |level|
         options[:dynamic_require_severity] = level.to_sym
       end