therubyracer 0.11.0beta8 → 0.11.0

data/Changelog.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 0.11
+## 0.11.0 2012/12/04
 
 * upgrade V8 version to 3.11.8
 * remove dependency on libv8. enable compilation against system v8
@@ -91,7 +91,7 @@
 * upgrade to rspec 2
 * several bug fixes and stability fixes
 
-## 0.7.5 - 1010/08/03
+## 0.7.5 - 2010/08/03
 
 * upgrade to V8 2.3.3
 * property interceptors from ruby via [] and []=

data/README.md

@@ -7,13 +7,13 @@
 
 ## DESCRIPTION
 
-Embed the V8 Javascript interpreter into Ruby.
+Embed the V8 JavaScript interpreter into Ruby.
 
 
 ## FEATURES
 
-* Evaluate Javascript from with in Ruby
-* Embed your Ruby objects into the Javascript world
+* Evaluate JavaScript from within Ruby
+* Embed your Ruby objects into the JavaScript world
 * Manipulate JavaScript objects and call JavaScript functions from Ruby
 * API compatible with the The Ruby Rhino (for JRuby: http://github.com/cowboyd/therubyrhino)
 
@@ -21,13 +21,13 @@ Embed the V8 Javascript interpreter into Ruby.
 
     gem install therubyracer
 
-then in your ruby code
+then in your Ruby code
 
     require 'v8'
     # or if using bundler (as with Rails), add the following to your Gemfile
     gem "therubyracer", :require => 'v8'
 
-evaluate some simple javascript
+evaluate some simple JavaScript
 
     cxt = V8::Context.new
     cxt.eval('7 * 6') #=> 42
@@ -37,12 +37,12 @@ embed values into the scope of your context
     cxt['foo'] = "bar"
     cxt.eval('foo') # => "bar"
 
-embed ruby code into your scope and call it from javascript
+embed Ruby code into your scope and call it from JavaScript
 
     cxt["say"] = lambda {|this, word, times| word * times}
     cxt.eval("say('Hello', 3)") #=> HelloHelloHello
 
-embed a ruby object into your scope and access its properties/methods from javascript
+embed a Ruby object into your scope and access its properties/methods from JavaScript
 
     class MyMath
       def plus(lhs, rhs)
@@ -53,7 +53,7 @@ embed a ruby object into your scope and access its properties/methods from javas
     cxt['math'] = MyMath.new
     cxt.eval("math.plus(20,22)") #=> 42
 
-make a ruby object *be* your global javascript scope.
+make a Ruby object *be* your global JavaScript scope.
 
     math = MyMath.new
     V8::Context.new(:with => math) do |cxt|
@@ -64,9 +64,9 @@ you can do the same thing with Object#eval_js
 
     math.eval_js("plus(20,22)")
 
-## Different ways of loading javascript source
+## Different ways of loading JavaScript source
 
-In addition to just evaluating strings, you can also use streams such as files.
+In addition to just evaluating strings, you can also use streams, such as files.
 
 evaluate bytes read from any File/IO object:
 
@@ -81,11 +81,11 @@ or load it by filename
 
 ## Safe by default, dangerous by demand
 
-The Ruby Racer is designed to let you evaluate javascript as safely as possible unless you tell it to do something more
-dangerous. The default context is a hermetically sealed javascript environment with only the standard javascript objects
-and functions. Nothing from the ruby world is accessible at all.
+The Ruby Racer is designed to let you evaluate JavaScript as safely as possible unless you tell it to do something more
+dangerous. The default context is a hermetically sealed JavaScript environment with only the standard JavaScript objects
+and functions. Nothing from the Ruby world is accessible at all.
 
-For ruby objects that you explicitly embed into javascript, by default only the _public_ methods _below_ `Object` are
+For Ruby objects that you explicitly embed into JavaScript, by default only the _public_ methods _below_ `Object` are
 exposed by default. E.g.
 
     class A
@@ -118,19 +118,20 @@ exposed by default. E.g.
 If needed, you can override the [Ruby Access](https://github.com/cowboyd/therubyracer/blob/master/lib/v8/access.rb)
 to allow whatever behavior you'd like
 
-More documentation can be found on the [github wiki](https://github.com/cowboyd/therubyracer/wiki)
+More documentation can be found on the [GitHub wiki](https://github.com/cowboyd/therubyracer/wiki)
 
 ## PREREQUISITES
 
 For platforms for which there is a binary version of therubyracer gem available, there are no
-dependencies other than ruby and rubygems.
+
+dependencies other than Ruby and rubygems.
 
 If there is not a binary version for your system, then you will need to compile it from source.
 To do this, you must have v8 >= 3.11.8 installed somewhere on your system. There are several
-ways of doing this. For both you will need a C++ compiler.
+ways of doing this. For both, you will need a C++ compiler.
 
-The first method involves using a version of the v8 source which is maintained
-[as a rubygem called libv8][1]. To use it, all you have to do is
+The first method involves using a version of the v8 source, which is maintained
+[as a RubyGem called libv8][1]. To use it, all you have to do is
 add the following to your Gemfile:
 
     gem 'libv8', '~> 3.11.8'
@@ -139,9 +140,9 @@ This will download and build v8 from source for you as part of the gem installat
 process. When therubyracer is installed, it will find this gem if it is present and
 link against the v8 binaries contained therein.
 
-If you cannot, or do not wish to use the libv8 rubygem, then you can either install
-libv8 with you operating system's packaging system or you can [build it from source][2].
-If you build from source, be sure to set the library=shared option. Also, if you install
+If you cannot, or do not wish to use the libv8 RubyGem, you can either install libv8
+with you operating system's packaging system or you can [build it from source][2]. If
+you build from source, be sure to set the library=shared option. Also, if you install
 this shared library into a place that is not on your standard lib and include paths, then
 you can pass your non-standard locations to therubyracer using the
 `--with-v8-include` and `--with-v8-lib` configuration options.
@@ -182,4 +183,4 @@ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 [1]: https://github.com/cowboyd/libv8
-[2]: http://code.google.com/p/v8/wiki/BuildingWithGYP
+[2]: http://code.google.com/p/v8/wiki/BuildingWithGYP

data/ext/v8/backref.cc

@@ -14,32 +14,23 @@ namespace rr {
   }
 
   Backref::Backref(VALUE initial) {
-    allocate(initial);
+    set(initial);
+    rb_gc_register_address(&storage);
   }
 
   Backref::~Backref() {
-    deallocate();
+    rb_gc_unregister_address(&storage);
   }
 
-  void Backref::allocate(VALUE data) {
+  VALUE Backref::set(VALUE data) {
     this->storage = rb_funcall(Storage, _new, 1, data);
-    rb_gc_register_address(&storage);
-  }
-
-  void Backref::deallocate() {
-    rb_gc_unregister_address(&storage);
+    return data;
   }
 
   VALUE Backref::get() {
     return rb_funcall(storage, object, 0);
   }
 
-  VALUE Backref::set(VALUE data) {
-    deallocate();
-    allocate(data);
-    return data;
-  }
-
   v8::Handle<v8::Value> Backref::toExternal() {
     v8::Local<v8::Value> wrapper = v8::External::Wrap(this);
     v8::Persistent<v8::Value>::New(wrapper).MakeWeak(this, &release);

data/ext/v8/rr.h

@@ -96,6 +96,28 @@ private:
 
 /**
 * A pointer to V8 object managed by Ruby
+*
+* You deal with V8 objects as either pointers or handles.
+* While handles are managed by the V8 garbage collector, pointers
+* must be explicitly created and destroyed by your code.
+*
+* The pointer class provides a handly way to wrap V8 pointers
+* into Ruby objects so that they will be deleted when the
+* Ruby object is garbage collected. Automatic type coercion is
+* used to make wrapping and unwrapping painless.
+*
+* To create Ruby VALUE:
+*
+*  Pointer<v8::ScriptOrigin> ptr(new v8::ScriptOrigin());
+*  VALUE value = ptr; //automatically wraps in Data_Wrap_Struct
+*
+* Conversely, the pointer can be unwrapped from a struct
+* created in this way and the underlying methods can be
+* invoked:
+*
+*     VALUE value = ...;
+*     Pointer<v8::ScriptOrigin> ptr(value);
+*     ptr->CallMethod();
 */
 
 template <class T> class Pointer {
@@ -125,6 +147,29 @@ template <class T> VALUE Pointer<T>::Class;
 
 /**
 * A Reference to a V8 managed object
+*
+* Uses type coercion to quickly convert from a v8 handle
+* to a ruby object and back again. Suppose we have a v8 handle
+* that we want to return to Ruby. We can put it into a Ref:
+*
+*     v8::Handle<v8::Object> object = v8::Object::New();
+*     VALUE val = Ref<v8::Object>(object);
+*
+* this will create a `v8::Persistent` handle for the object
+* so that it will not be garbage collected by v8. It then
+* stuffs this new persistent handle into a Data_Wrap_Struct
+* which can then be passed to Ruby code. When this struct
+* is garbage collected by Ruby, it enqueues the corresponding
+* v8 handle to be released during v8 gc.
+*
+* By the same token, you can use Refs to unwrap a Data_Wrap_Struct
+* which has been generated in this fashion and call through to
+* the underlying v8 methods. Suppose we are passed a VALUE `val`
+* wrapping a v8::Object:
+*
+*     Ref<v8::Object> object(val);
+*     object->Get(v8::String::New("foo"));
+*
 */
 template <class T> class Ref {
 public:
@@ -135,9 +180,15 @@ public:
     this->handle = handle;
   }
   virtual ~Ref() {}
+  /*
+  *  Coerce a Ref into a Ruby VALUE
+  */
   virtual operator VALUE() const {
-    return handle.IsEmpty() ? Qnil : (new Holder(handle, Class))->value;
+    return handle.IsEmpty() ? Qnil : Data_Wrap_Struct(Class, 0, &Holder::enqueue, new Holder(handle));
   }
+  /*
+  * Coerce a Ref into a v8::Handle.
+  */
   virtual operator v8::Handle<T>() const {
     if (RTEST(this->value)) {
       Holder* holder = NULL;
@@ -153,6 +204,12 @@ public:
     holder->dispose();
   }
 
+  /*
+  * Pointer de-reference operators, this lets you use a ref to
+  * call through to underlying v8 methods. e.g
+  *
+  *     Ref<v8::Object>(value)->ToString();
+  */
   inline v8::Handle<T> operator->() const { return *this;}
   inline v8::Handle<T> operator*() const {return *this;}
 
@@ -173,10 +230,9 @@ public:
   class Holder {
     friend class Ref;
   public:
-    Holder(v8::Handle<T> handle, VALUE klass) {
+    Holder(v8::Handle<T> handle) {
       this->disposed_p = false;
       this->handle = v8::Persistent<T>::New(handle);
-      this->value = Data_Wrap_Struct(klass, 0, &enqueue, this);
     }
     virtual ~Holder() {
       this->dispose();
@@ -188,12 +244,10 @@ public:
       }
     }
   protected:
-    VALUE value;
     v8::Persistent<T> handle;
     bool disposed_p;
 
     static void enqueue(Holder* holder) {
-      holder->value = Qnil;
       GC::Finalize(holder);
     }
   };
@@ -214,8 +268,6 @@ public:
   v8::Handle<v8::Value> toExternal();
   static void release(v8::Persistent<v8::Value> handle, void* data);
 private:
-  void allocate(VALUE data);
-  void deallocate();
   VALUE storage;
   static VALUE Storage;
   static ID _new;
@@ -564,7 +616,6 @@ public:
   inline Object(VALUE value) : Ref<v8::Object>(value) {}
   inline Object(v8::Handle<v8::Object> object) : Ref<v8::Object>(object) {}
   virtual operator VALUE();
-  static VALUE toVALUE(VALUE yield, VALUE wrapper);
 
 protected:
   VALUE downcast();

data/lib/v8/context.rb

@@ -63,7 +63,9 @@ module V8
         end
         enter {link global, @native.Global()}
       else
-        @native = V8::C::Context::New()
+        V8::C::Locker() do
+          @native = V8::C::Context::New()
+        end
       end
       yield self if block_given?
     end

data/lib/v8/error.rb

@@ -13,8 +13,8 @@ module V8
     # @return [Exception] the underlying error (if any) that triggered this error to be raised
     attr_reader :cause
 
-    # @!attribute [V8::StackTrace] javascript_backtrace
-    # @return the complete JavaScript stack at the point this error was thrown
+    # @!attribute [r] javascript_backtrace
+    # @return [V8::StackTrace] the complete JavaScript stack at the point this error was thrown
     attr_reader :javascript_backtrace
 
     # keep an alias to the StandardError#backtrace method so that we can capture
@@ -103,6 +103,40 @@ module V8
 
   end
 
+  # Convert the result of a triggered JavaScript try/catch block into
+  # a V8::Error
+  #
+  # This is a bit of a yak-shave because JavaScript let's you throw all
+  # kinds of things. We do our best to make sure that the message property
+  # of the resulting V8::Error is as helpful as possible, and that it
+  # contains as much source location information as we can put onto it.
+  #
+  # For example:
+  #
+  #    throw 4
+  #    throw 'four'
+  #    throw {number: 4}
+  #
+  # are all valid cases, none of which actually reference an exception object
+  # with a stack trace and a message. only with something like:
+  #
+  #    throw new Error('fail!')
+  #
+  # do you get the a proper stacktrace and a message property. However a lot of
+  # times JavaScript library authors are lazy and do this:
+  #
+  #     throw {message: 'foo', otherMetadata: 'bar'}
+  #
+  # It's common enough so we do the courtesy of having the resulting V8::Error
+  # have as its message in ruby land the 'message' property of the value object
+  #
+  # To further complicate things, SyntaxErrors do not have a JavaScript stack
+  # (even if they occur during js execution). This can make debugging a nightmare
+  # so we copy in the source location of the syntax error into the message of
+  # the resulting V8::Error
+  #
+  # @param [V8::C::TryCatch] native trycatch object that has been triggered
+  # @return [V8::Error] the error generated by this try/catch
   def self.Error(trycatch)
     exception = trycatch.Exception()
     value = exception.to_ruby
@@ -114,8 +148,6 @@ module V8
       if cause = exception.GetHiddenValue("rr::Cause")
         cause = cause.Value()
       end
-      # SyntaxErrors do not have a JavaScript stack (even if they occur during js execution).
-      # To caputre where the error occured, we need to put it in the message
       if value['constructor'] == V8::Context.current['SyntaxError']
         info = trycatch.Message()
         resource_name = info.GetScriptResourceName().to_ruby

data/lib/v8/version.rb

@@ -1,3 +1,3 @@
 module V8
-  VERSION = "0.11.0beta8"
+  VERSION = "0.11.0"
 end

data/therubyracer.gemspec

@@ -4,8 +4,8 @@ require File.expand_path('../lib/v8/version', __FILE__)
 Gem::Specification.new do |gem|
   gem.authors       = ["Charles Lowell"]
   gem.email         = ["javascript-and-friends@googlegroups.com"]
-  gem.summary       = "Embed the V8 Javascript interpreter into Ruby"
-  gem.description   = "Call javascript code and manipulate javascript objects from ruby. Call ruby code and manipulate ruby objects from javascript."
+  gem.summary       = "Embed the V8 JavaScript interpreter into Ruby"
+  gem.description   = "Call JavaScript code and manipulate JavaScript objects from Ruby. Call Ruby code and manipulate Ruby objects from JavaScript."
   gem.homepage      = "http://github.com/cowboyd/therubyracer"
 
   gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: therubyracer
 version: !ruby/object:Gem::Version
-  version: 0.11.0beta8
-  prerelease: 6
+  version: 0.11.0
+  prerelease: 
 platform: ruby
 authors:
 - Charles Lowell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-13 00:00:00.000000000 Z
+date: 2012-12-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ref
@@ -27,8 +27,8 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Call javascript code and manipulate javascript objects from ruby. Call
-  ruby code and manipulate ruby objects from javascript.
+description: Call JavaScript code and manipulate JavaScript objects from Ruby. Call
+  Ruby code and manipulate Ruby objects from JavaScript.
 email:
 - javascript-and-friends@googlegroups.com
 executables: []
@@ -141,19 +141,22 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2118637317038769164
+      hash: -1132929021972714729
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
+      segments:
+      - 0
+      hash: -1132929021972714729
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: Embed the V8 Javascript interpreter into Ruby
+summary: Embed the V8 JavaScript interpreter into Ruby
 test_files:
 - spec/c/array_spec.rb
 - spec/c/constants_spec.rb