RubyGems - opal - Versions diffs - 0.3.19 → 0.3.20 - Mend

opal 0.3.19 → 0.3.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (66) hide show

data/.gitignore +3 -1
data/Gemfile +3 -2
data/README.md +304 -48
data/Rakefile +1 -2
data/core/alpha.rb +2 -1
data/core/array.rb +92 -96
data/core/basic_object.rb +1 -10
data/core/boolean.rb +6 -18
data/core/class.rb +9 -10
data/core/comparable.rb +1 -1
data/core/enumerable.rb +11 -11
data/core/enumerator.rb +2 -10
data/core/error.rb +16 -31
data/core/hash.rb +32 -36
data/core/json.rb +50 -0
data/core/kernel.rb +48 -57
data/core/load_order +3 -5
data/core/module.rb +37 -35
data/core/nil_class.rb +4 -0
data/core/numeric.rb +10 -30
data/core/proc.rb +1 -1
data/core/range.rb +3 -4
data/core/regexp.rb +21 -6
data/core/runtime.js +278 -370
data/core/string.rb +21 -37
data/core/struct.rb +11 -3
data/core/time.rb +44 -37
data/lib/opal.rb +3 -3
data/lib/opal/builder.rb +48 -27
data/lib/opal/builder_task.rb +3 -20
data/lib/opal/grammar.rb +18 -13
data/lib/opal/grammar.y +7 -4
data/lib/opal/parser.rb +290 -199
data/lib/opal/scope.rb +187 -176
data/lib/opal/version.rb +1 -1
data/test/core/kernel/define_singleton_method_spec.rb +21 -0
data/test/core/time/at_spec.rb +7 -0
data/test/core/time/day_spec.rb +5 -0
data/test/core/time/friday_spec.rb +9 -0
data/test/core/time/hour_spec.rb +5 -0
data/test/core/time/min_spec.rb +5 -0
data/test/core/time/monday_spec.rb +9 -0
data/test/core/time/month_spec.rb +5 -0
data/test/core/time/now_spec.rb +5 -0
data/test/core/time/saturday_spec.rb +9 -0
data/test/index.html +2 -1
data/test/language/singleton_class_spec.rb +0 -16
data/test/opal/array/to_json_spec.rb +7 -0
data/test/opal/boolean/singleton_class_spec.rb +9 -0
data/test/opal/boolean/to_json_spec.rb +9 -0
data/test/opal/hash/to_json_spec.rb +9 -0
data/test/opal/json/parse_spec.rb +31 -0
data/test/opal/kernel/to_json_spec.rb +5 -0
data/test/opal/nil/to_json_spec.rb +5 -0
data/test/opal/numeric/to_json_spec.rb +6 -0
data/test/opal/runtime/call_spec.rb +16 -0
data/test/opal/runtime/defined_spec.rb +11 -0
data/test/opal/runtime/super_spec.rb +16 -0
data/test/opal/string/to_json_spec.rb +6 -0
data/test/spec_helper.rb +1 -3
metadata +48 -15
data/core/dir.rb +0 -89
data/core/file.rb +0 -85
data/core/match_data.rb +0 -35
data/core/rational.rb +0 -16
data/test/core/file/expand_path_spec.rb +0 -20

data/.gitignore CHANGED

@@ -11,4 +11,6 @@ pkg/*
 /*.js
 /docs/gh-pages
 /examples/**/*.js
-/build
+/build
+Gemfile.local
+Gemfile.local.lock

data/Gemfile CHANGED

@@ -3,8 +3,9 @@ source :rubygems
 gemspec
 gem "rake"
-# gem "racc"
+gem "racc"
 group :browser do
-  gem "opal-spec", "0.1.6"
+  gem "opal-spec"
+  gem 'opal-dom'
 end

data/README.md CHANGED

@@ -19,7 +19,7 @@ is a Freenode IRC channel at `#opal`.
 The Opal runtime and corelib are distributed here, and are required to
 run any code generated by opal.
-[Opal version 0.3.19](http://opalrb.org/opal.js) _(14.9kb Minified And Gzipped)_
+[Opal version 0.3.20](http://opalrb.org/opal.js) _(14.3kb Minified And Gzipped)_
 ## Installation
@@ -41,18 +41,22 @@ method which returns a string of javascript code:
 ```ruby
 require 'opal'
-Opal.parse("[1, 2, 3, 4].each { |a| puts a }")
+Opal.parse("puts 'hello world'")
 ```
-This will return a string of javascript similar to the following:
+This will return a string of javascript:
 ```javascript
 (function() {
-  // compiled ruby
-}).call(Opal.top);
+  var self = Opal.top;
+  self.$puts('hello world');
+})();
 ```
-This can then be written to a file and run in any browser.
+This can then be written to a file and run in any browser. `Opal` is a
+global javascript variable that holds all the ruby classes and methods.
+`Opal.top` points to the top object in opal, so any file will have this
+object as its top level `self` variable.
 ### Creating a rake task
@@ -98,7 +102,7 @@ opal runtime needs to be loaded first (you can download that above).
 When using `Opal.parse()` as above, the generated code will be run
 as soon as the page loads. Open the browsers console and you should
-see the 4 numbers printed to the console.
+see the message printed to the console.
 ## Builder and Dependency Builder
@@ -114,7 +118,7 @@ require 'opal'
 Opal::BuilderTask.new do |t|
   t.name         = 'my-first-app'
-  t.dependencies = ['opal-json']
+  t.dependencies = ['opal-spec']
   t.files        = ['app.rb']
 end
 ```
@@ -124,16 +128,16 @@ dependencies.
 ### Building dependencies
-To build the opal runtime `opal.js`, as well as `opal-json` into
+To build the opal runtime `opal.js`, as well as `opal-spec` into
 `build/`, run the simple rake task:
 ```ruby
 rake dependencies
 ```
-This will try and find the `opal-json` gem installed, so either
-install globally with `gem install opal-json`, or add it to your
-Gemfile as `gem "opal-json"` and run `bundle install`.
+This will try and find the `opal-spec` gem installed, so either
+install globally with `gem install opal-spec`, or add it to your
+Gemfile as `gem "opal-spec"` and run `bundle install`.
 ### Building app
@@ -158,28 +162,12 @@ You should now be able to run the built app using a standard HTML page.
 </head>
 <body>
   <script src="build/opal.js"></script>
-  <script src="build/opal-json.js"></script>
+  <script src="build/opal-spec.js"></script>
   <script src="build/my-first-app.js"></script>
 </body>
 </html>
 ```
-### Main file
-When using the `BuilderTask`, the files generated will not be run
-automatically on page load. The files are registered so they can be
-loaded using `require()`. Builder is clever enough though that it will,
-by default, automatically require the first file in the app to be
-loaded. This will appear at the bottom of `my-first-app.js`:
-```javascript
-Opal.define('app', function() {
-  // app.rb code
-});
-Opal.require('app');
-```
 ## Features And Implementation
 Opal is a source-to-source compiler, so there is no VM as such and the
@@ -274,6 +262,49 @@ range instances.
 3...7       # => __range(3, 7, false)
 ```
+### Classes and Modules
+A compiled class or module body is simply just an anonymous javascript
+function that is used to keep any internal variables from escaping.
+Classes and modules themselves are created as named functions (which is
+used purely to aid debugging). Classes and modules may also be
+re-opended, so they are put through a runtime function `__klass` for
+classes, and `__module` for modules.
+For example, the `Kernel` module is generated as:
+```javascript
+(function(__base) {
+  function Kernel(){};
+  Kernel = __module(__base, "Kernel", Kernel);
+  var Kernel_prototype = Kernel.prototype;
+  Kernel_prototype.$class = function() {
+    return this._real;
+  };
+  Kernel._donate('$class', ...);
+})(__scope);
+```
+Firstly, the `__scope` is passed into the function which is used
+for defining constants, which means that if `Kernel` gets defined
+here then it can be set as a constant for the given scope. The
+named function (Kernel) follows, as well as the `__module()` call
+which simply sets the up the module if it doesn't already exist. If
+it does exist, then it overwrites the previous `Kernel` local variable.
+Next, `Kernel_prototype` is made a local variable to improve
+minimization of the code, then all the Kernel methods are set on the
+prototype. Modules cannot be instantiated in Opal (just like ruby), but
+the use of prototypes is to improve performance.
+Finally, the call to `Kernel._donate()` is to pass any defined methods
+into classes that have included `Kernel`, which is just `Object`. This
+method then adds all of Kernels methods into Objects prototype as this
+is the most efficient way to try and emulate rubys method chain.
 ### Methods
 A ruby method is just compiled directly into a function definition.
@@ -352,12 +383,12 @@ def to_s
 end
 ```
-This would generate the following javascript. (`def.` is a local
-variable set to be the class's instance prototype. It is used
-for minimization of code as well as trying to be readable).
+This would generate the following javascript. (`Array_prototype` is
+an example and would assume this method definition is inside the
+`Array` class body).
 ```javascript
-def.$to_s = function() {
+Array_prototype.$to_s = function() {
   return this.$inspect();
 };
 ```
@@ -384,16 +415,16 @@ end
 The generated code reads as expected:
 ```javascript
-def.$norm = function(a, b, c) {
+Array_prototype.$norm = function(a, b, c) {
   return nil;
 };
-def.$opt = function(a, b) {
+Array_prototype.$opt = function(a, b) {
   if (b == null) b = 100;
   return nil;
 };
-def.$rest = function(a, b) {
+Array_prototype.$rest = function(a, b) {
   b = __slice.call(arguments, 1);
   return nil;
 };
@@ -404,6 +435,144 @@ the correct number of arguments get passed to a function. This can be
 enabled in debug mode, but is not included in production builds as it
 adds a lot of overhead to **every** method call.
+### 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:
+```javascript
+val = 42
+if val
+  return 3.142;
+end
+```
+This would be compiled into:
+```ruby
+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
+```
+The only point of warning is that when variables are used for the
+first time in ruby, they default to `nil`. In javascript, they default
+to `undefined`/`null`.
+To keep things working in opal, ivars must be preset to `nil` before
+they can be used. In the top scope and other corner cases, this needs
+to be done on a per scope basis, which can add overhead.
+To improve performance, once a class body is compiled, all ivars used
+within methods in that class are preset on the prototype of the class
+to be `nil`. This means that all known ivars are already set to nil,
+and this is done just once during the lifespan of the app.
+```ruby
+class Foo
+  def bar
+    @lol
+  end
+  def woosh
+    @kapow
+  end
+end
+```
+This example gets compiled into something similar to:
+```javascript
+(function() {
+  function Foo(){}
+  // ...
+  Foo.prototype.lol = Foo.prototype.woosh = nil;
+  Foo.prototype.$bar = function() {
+    return this.lol;
+  };
+  // etc ...
+})()
+```
+### 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 and nil.
+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
@@ -411,17 +580,16 @@ of javascript code that is wrapped inside an anonymous function. This
 looks similar to the following:
 ```javascript
-(function(undefined) {
-  var nil = Opal.nil, __slice = Opal.slice, __klass = Opal.klass;
+(function() {
+  var nil = Opal.nil, self = Opal.top;
   // generated code
-}).call(Opal.top);
+})();
 ```
-This function gets called with `Opal.top` as the context, which is the
-top level object available to ruby (`main`). Inside the function, `nil`
-is assigned to ensure a local copy is available, as well as all the
-helper methods used within the generated file. There is no return value
-from these functions as they are not used anywhere.
+Inside the function, `nil` is assigned to ensure a local copy is
+available, as well as all the helper methods used within the
+generated file. There is no return value from these functions as they
+are not used anywhere.
 As a complete example, assuming the following code:
@@ -432,10 +600,10 @@ puts "foo"
 This would compile directly into:
 ```javascript
-(function(undefined) {
-  var nil = Opal.nil;
-  this.$puts("foo");
-}).call(Opal.top);
+(function() {
+  var nil = Opal.nil, self = Opal.top;
+  self.$puts("foo");
+})();
 ```
 Most of the helpers are no longer present as they are not used in this
@@ -447,12 +615,100 @@ 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.
+### JSON
+The opal corelib includes JSON support instead of treating it as an
+external lib. The `JSON` module provides the usual parsing methods.
+```ruby
+JSON.parse '{"a": 10, "b": [1, 2, 3], "c": null}'
+# => { "a" => 10, "b" => [1, 2, 3], "c" => nil }
+```
+Opal expects `JSON` to be present in the browser, so older browsers
+may require a shim (json2.js) to work with opal. Most mobile browsers
+and modern desktop browsers include json support natively.
+## 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.
+### Undefined methods
+By default, opal aims to be as fast as possible, so `method_missing` is
+not turned on by default. Instead, when calling a method that doesn't
+exist, a native error will be raised.
+```ruby
+self.do_something()
+```
+Might raise an error similar to:
+```
+Error: 'undefined' is not a function (evaluating 'this.$do_something()')
+```
+As described above, all ruby methods will have a `$` prefix which gives
+a good indication that it is a opal method that doesnt exist, and most
+js engines output the missing function name.
+### Undefined constants
+If trying to access a constant that doesn't exist, there is no runtime
+error. Instead, the value of that expression is just `undefined` as
+constants are retrieved from objects that hold all constants in the
+scope. Trying to send a method to an undefined constant will therefore
+just raise an ugly javascript `TypeError`.
+If you are using the constant as a reference, it may not be until much
+later that the error occurs.
+### 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.
+Inside methods and blocks, the current `self` value is always the
+native `this` value. You will not see `self` inside debuggers as it is
+never used to refer to the actual ruby self value.
+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$`).
 ## License
 Opal is released under the MIT license.
 ## Change Log
+**0.3.20** _(23 June 2012)_
+* Merge JSON into core. JSON module and various #to_json methods are
+  now included as part of corelib
+* Make `Time` class bridge to native `Date` constructor
+* Use named functions as class constuctors to make debugging easier
+* Classes are now real functions with prototypes. Bridged classes are
+  now directly corresponding to the ruby class (e.g. Array === Opal.Array)
+* Set ivars used inside methods in class to `nil` inside class definition
+  to avoid doing it everytime method is called
+* Add debug comments to output for def, class and module stating the file
+  and line number the given code was generated from
 **0.3.19** _(30 May 2012)_
 * Add BasicObject as the root class