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

opal 0.3.19 → 0.3.20

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