therubyrhino 1.72.5-jruby → 1.72.6-jruby

data/History.txt

@@ -1,3 +1,8 @@
+=== 1.72.6 2009-11-30
+* 2 major enhancements:
+  * evaluate an IO object such as a file or an socket input stream
+  * load javascript sources directly into the context with the file system
+
 === 1.72.5 2009-11-12
 * 2 major enhancements:
   * evaluate javascript with a ruby object as it's scope using Context#open(:with => object)

data/README.rdoc

@@ -21,7 +21,14 @@ Embed the Mozilla Rhino Javascript interpreter into Ruby
   
 # evaluate some simple javascript
   eval_js "7 * 6" #=> 42
-  
+
+# that's quick and dirty, but if you want more control over your
+# environment, use a Context:
+  Rhino::Context.open do |cxt|
+    cxt['foo'] = "bar"
+    cxt.eval('foo') # => "bar"
+  end
+
 # evaluate a ruby function from javascript
   
   Rhino::Context.open do |context|
@@ -63,6 +70,57 @@ Embed the Mozilla Rhino Javascript interpreter into Ruby
   Rhino::Context.open(:java => true) do |context|
     context.eval("java.lang.System.exit()") #it's dangerous!
   end
+
+  #limit the number of instructions that can be executed in order to prevent
+  #rogue scripts
+  Rhino::Context.open do |context|
+    context.instruction_limit = 100000
+    context.eval("while (true);") # => Error!
+  end
+
+==== Different ways of loading javascript source
+
+In addition to just evaluating strings, you can also use streams such as files.
+
+# evaluate bytes read from any File/IO object:
+  File.open("mysource.js") do |file|
+    eval_js file, "mysource.js"
+  end
+
+# or load it by filename
+  Rhino::Context.open do |context|
+    context.load("mysource.js")
+  end
+
+=== Safe by default
+
+The Ruby Rhino 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, only the +public+ methods *defined in their classes* are
+exposed by default. E.g.
+
+  class A
+    def a
+      "a"
+    end
+  end
+
+  class B < A
+    def b
+      "b"
+    end
+  end
+
+
+  Rhino::Context.open do |cxt|
+    cxt['a'] = A.new
+    cxt['b'] = B.new
+    cxt.eval("a.a()") # => 'a'
+    cxt.eval("b.b()") # => 'b'
+    cxt.eval("b.a()") # => 'TypeError: undefined property 'a' is not a function'
+  end
   
 == REQUIREMENTS:
 

data/lib/rhino/context.rb

@@ -1,12 +1,47 @@
 module Rhino
 
+# ==Overview
+#  All Javascript must be executed in a context which represents the execution environment in
+#  which scripts will run. The environment consists of the standard javascript objects
+#  and functions like Object, String, Array, etc... as well as any objects or functions which 
+#  have been defined in it. e.g.
+#  
+#   Context.open do |cxt|
+#     cxt['num'] = 5
+#     cxt.eval('num + 5') #=> 10
+#   end
+# 
+# == Multiple Contexts.
+# The same object may appear in any number of contexts, but only one context may be executing javascript code 
+# in any given thread. If a new context is opened in a thread in which a context is already opened, the second
+# context will "mask" the old context e.g.
+#
+#   six = 6
+#   Context.open do |cxt|
+#     cxt['num'] = 5
+#     cxt.eval('num') # => 5     
+#     Context.open do |cxt|
+#       cxt['num'] = 10
+#       cxt.eval('num') # => 10
+#       cxt.eval('++num') # => 11
+#     end
+#     cxt.eval('num') # => 5
+#   end
+#
+# == Notes
+# While there are many similarities between Rhino::Context and Java::OrgMozillaJavascript::Context, they are not
+# the same thing and should not be confused.
+
   class Context    
     attr_reader :scope
 
     class << self
-      def open(options = {})
+      
+      # initalize a new context with a fresh set of standard objects. All operations on the context
+      # should be performed in the block that is passed.
+      def open(options = {}, &block)
         ContextFactory.new.call do |native|
-          yield new(native, options)
+          block.call(new(native, options))
         end
       end
                       
@@ -29,33 +64,83 @@ module Rhino
       end      
     end
     
+    # Read a value from the global scope of this context
     def [](k)
       @scope[k]
     end
-    
+
+    # Set a value in the global scope of this context. This value will be visible to all the 
+    # javascript that is executed in this context.    
     def []=(k,v)
       @scope[k] = v
     end
-                            
-    def eval(str)
-      str = str.to_s
+
+    # Evaluate a string of javascript in this context:
+    # * <tt>source</tt> - the javascript source code to evaluate. This can be either a string or an IO object.
+    # * <tt>source_name</tt> - associated name for this source code. Mainly useful for backtraces.
+    # * <tt>line_number</tt> - associate this number with the first line of executing source. Mainly useful for backtraces
+    def eval(source, source_name = "<eval>", line_number = 1)
       begin
         scope = To.javascript(@scope)
-        result = @native.evaluateString(scope, str, "<eval>", 1, nil)
+        if IO === source || StringIO === source
+          result = @native.evaluateReader(scope, IOReader.new(source), source_name, line_number, nil)
+        else          
+          result = @native.evaluateString(scope, source.to_s, source_name, line_number, nil)
+        end
         To.ruby result
       rescue J::RhinoException => e
         raise Rhino::RhinoError, e
       end
     end
-    
+
+    # Read the contents of <tt>filename</tt> and evaluate it as javascript. Returns the result of evaluating the
+    # javascript. e.g.
+    #
+    # Context.open do |cxt|
+    #   cxt.load("path/to/some/lib.js")
+    # end
+    #
+    def load(filename)
+      File.open(filename) do |file|
+        eval file, filename, 1
+      end
+    end
+
+    # Set the maximum number of instructions that this context will execute.
+    # If this instruction limit is exceeded, then a Rhino::RunawayScriptError
+    # will be raised
     def instruction_limit=(limit)
       @native.setInstructionObserverThreshold(limit);
       @native.factory.instruction_limit = limit
     end
         
   end
+
+  class IOReader < Java::JavaIo::Reader #:nodoc:
+
+    def initialize(io)
+      @io = io
+    end
+
+    def read(charbuffer, offset, length)
+      begin
+        str = @io.read(length)
+        if str.nil?
+          return -1
+        else
+          jstring = Java::JavaLang::String.new(str)
+          for i in 0 .. jstring.length - 1          
+            charbuffer[i + offset] = jstring.charAt(i)
+          end
+          return jstring.length
+        end
+      rescue  StandardError => e        
+        raise Java::JavaIo::IOException.new, "Failed reading from ruby IO object"
+      end
+    end
+  end
       
-  class ContextFactory < J::ContextFactory
+  class ContextFactory < J::ContextFactory # :nodoc:
     
     def observeInstructionCount(cxt, count)
       raise RunawayScriptError, "script exceeded allowable instruction count" if count > @limit
@@ -67,7 +152,7 @@ module Rhino
   end
     
     
-  class RhinoError < StandardError
+  class RhinoError < StandardError # :nodoc:
     def initialize(native)
       @native = native
     end
@@ -81,5 +166,6 @@ module Rhino
     end        
   end
   
-  class RunawayScriptError < StandardError; end
+  class RunawayScriptError < StandardError # :nodoc:
+  end 
 end

data/lib/rhino/java.rb

@@ -2,13 +2,16 @@ require 'java'
 require 'rhino/rhino-1.7R2.jar'
 
 module Rhino
+  # This module contains all the native Rhino objects implemented in Java
+  # e.g. 
+  #   Rhino::J::NativeObject # => org.mozilla.javascript.NativeObject
   module J
     import "org.mozilla.javascript"
   end
 end
 
 unless Object.method_defined?(:tap)
-  class Object
+  class Object #:nodoc:
     def tap
       yield self
       self

data/lib/rhino/native_function.rb

@@ -1,5 +1,14 @@
 
 module Rhino
+  
+  # Wraps a function that has been defined in Javascript so that it can 
+  # be referenced and called from javascript. e.g.
+  #
+  #   plus = Rhino::Context.open do |cx|
+  #     cx.eval('function(lhs, rhs) {return lhs + rhs}')
+  #   end
+  #   plus.call(5,4) # => 9
+  #
   class NativeFunction < NativeObject    
     def call(*args)
       begin        

data/lib/rhino/native_object.rb

@@ -1,27 +1,60 @@
 
 module Rhino
+  # Wraps a javascript object and makes its properties available from ruby.
   class NativeObject
     include Enumerable
+    
+    # The native java object wrapped by this NativeObject. This will generally
+    # be an instance of org.mozilla.javascript.Scriptable
     attr_reader :j
     
-    def initialize(j)
+    def initialize(j) # :nodoc:
       @j = j
     end
     
+    # get a property from this javascript object, where +k+ is a string or symbol
+    # corresponding to the property name
+    # e.g.
+    #   jsobject = Context.open do |cxt|
+    #      cxt.eval('({foo: 'bar',  'Take me to': 'a funky town'})')
+    #   end
+    # 
+    #   jsobject[:foo] # => 'bar'
+    #   jsobject['foo'] # => 'bar'
+    #   jsobject['Take me to'] # => 'a funky town'
     def [](k)
-      To.ruby @j.get(k.to_s, @j)
+      To.ruby J::ScriptableObject.getProperty(@j,k.to_s)
     end
     
+    # set a property on the javascript object, where +k+ is a string or symbol corresponding
+    # to the property name, and +v+ is the value to set. e.g.
+    #
+    #   jsobject = eval_js "new Object()"
+    #   jsobject['foo'] = 'bar'
+    #   Context.open(:with => jsobject) do |cxt|
+    #     cxt.eval('foo') # => 'bar'
+    #   end
+
     def []=(k,v)
-      @j.put(k.to_s,@j,To.javascript(v))
+      #@j.put(k.to_s,@j,To.javascript(v))
+      J::ScriptableObject.putProperty(@j, k.to_s, To.javascript(v))
     end
     
+    # enumerate the key value pairs contained in this javascript object. e.g.
+    # 
+    #   eval_js("{foo: 'bar', baz: 'bang'}").each do |key,value|
+    #     puts "#{key} -> #{value} "
+    #   end
+    #
+    # outputs foo -> bar baz -> bang
     def each
       for id in @j.getAllIds() do
         yield id,@j.get(id,@j)
       end
     end
     
+    # Converts the native object to a hash. This isn't really a stretch since it's
+    # pretty much a hash in the first place.
     def to_h
       {}.tap do |h|
         each do |k,v|
@@ -30,6 +63,7 @@ module Rhino
       end
     end
     
+    # Convert this javascript object into a json string.
     def to_json(*args)
       to_h.to_json(*args)
     end

data/lib/rhino.rb

@@ -3,7 +3,7 @@ $:.unshift(File.dirname(__FILE__)) unless
 
 
 module Rhino
-  VERSION = '1.72.5'
+  VERSION = '1.72.6'
   require 'rhino/java'
   require 'rhino/object'
   require 'rhino/context'

data/spec/rhino/context_spec.rb

@@ -123,4 +123,40 @@ describe Rhino::Context do
       Context.new(nil)
     }.should raise_error
   end
+
+  describe "loading javascript source into the interpreter" do
+
+    it "can take an IO object in the eval method instead of a string" do
+      source = StringIO.new(<<-EOJS)
+/*
+* we want to have a fairly verbose function so that we can be assured tha
+* we overflow the buffer size so that we see that the reader is chunking
+* it's payload in at least several fragments.
+*
+* That's why we're wasting space here
+*/
+function five() {
+  return 5
+}
+foo = 'bar'
+five();
+      EOJS
+      Context.open do |cxt|
+        cxt.eval(source, "StringIO").should == 5
+        cxt['foo'].should == "bar"
+      end
+    end
+
+    it "can load a file into the runtime" do
+      mock(:JavascriptSourceFile).tap do |file|
+        File.should_receive(:open).with("path/to/mysource.js").and_yield(file)
+        Context.open do |cxt|
+          cxt.should_receive(:eval).with(file, "path/to/mysource.js", 1)
+          cxt.load("path/to/mysource.js")
+        end
+      end
+
+    end
+
+  end
 end

data/spec/rhino/native_object_spec.rb

@@ -27,6 +27,18 @@ describe Rhino::NativeObject do
   it "returns nil when the value is null, null, or not defined" do
     @o[:foo].should be_nil
   end
+
+
+  it "traverses the prototype chain when hash accessing properties from the ruby object" do
+    Rhino::Context.open do |cxt|
+      cxt.eval(<<EOJS)['bar'].should == "baz"
+function Foo() {}
+Foo.prototype.bar = 'baz'
+new Foo()
+EOJS
+    end
+  end
+
   
   describe Enumerable do
     it "enumerates according to native keys and values" do
@@ -35,6 +47,9 @@ describe Rhino::NativeObject do
       @j.put(5, @j, 'flip')
       @o.inject({}) {|i,p| k,v = p; i.tap {i[k] = v}}.should == {"foo" => 'bar', "bang" => 'baz', 5 => 'flip'}
     end
+
+    it "should traverse prototype chain when enumerating keys and values"
+
   end
   
 end

data/therubyrhino.gemspec

@@ -2,16 +2,16 @@
 
 Gem::Specification.new do |s|
   s.name = %q{therubyrhino}
-  s.version = "1.72.5"
+  s.version = "1.72.6"
   s.platform = %q{jruby}
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Charles Lowell"]
-  s.date = %q{2009-11-13}
+  s.date = %q{2009-11-30}
   s.description = %q{Embed the Mozilla Rhino Javascript interpreter into Ruby}
   s.email = ["cowboyd@thefrontside.net"]
   s.extra_rdoc_files = ["History.txt", "Manifest.txt"]
-  s.files = ["History.txt", "Manifest.txt", "README.rdoc", "Rakefile", "lib/rhino.rb", "lib/rhino/context.rb", "lib/rhino/java.rb", "lib/rhino/native_function.rb", "lib/rhino/native_object.rb", "lib/rhino/rhino-1.7R2.jar", "lib/rhino/ruby_function.rb", "lib/rhino/ruby_object.rb", "lib/rhino/wormhole.rb", "script/console", "script/destroy", "script/generate", "spec/rhino/context_spec.rb", "spec/rhino/native_object_spec.rb", "spec/rhino/ruby_object_spec.rb", "spec/rhino/wormhole_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "tasks/jruby.rake", "tasks/rspec.rake", "therubyrhino.gemspec"]
+  s.files = ["History.txt", "Manifest.txt", "README.rdoc", "Rakefile", "lib/rhino.rb", "lib/rhino/context.rb", "lib/rhino/java.rb", "lib/rhino/native_function.rb", "lib/rhino/native_object.rb", "lib/rhino/object.rb", "lib/rhino/rhino-1.7R2.jar", "lib/rhino/ruby_function.rb", "lib/rhino/ruby_object.rb", "lib/rhino/wormhole.rb", "script/console", "script/destroy", "script/generate", "spec/rhino/context_spec.rb", "spec/rhino/native_object_spec.rb", "spec/rhino/ruby_object_spec.rb", "spec/rhino/wormhole_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "tasks/jruby.rake", "tasks/rspec.rake", "therubyrhino.gemspec"]
   s.homepage = %q{http://github.com/cowboyd/therubyrhino}
   s.rdoc_options = ["--main", "README.rdoc"]
   s.require_paths = ["lib"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: therubyrhino
 version: !ruby/object:Gem::Version 
-  version: 1.72.5
+  version: 1.72.6
 platform: jruby
 authors: 
   - Charles Lowell
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-13 00:00:00 -05:00
+date: 2009-11-30 00:00:00 -06:00
 default_executable: 
 dependencies: 
   - !ruby/object:Gem::Dependency