1
0
Fork 0
mirror of https://github.com/rubyjs/therubyrhino synced 2023-03-27 23:21:34 -04:00

add documentation for Context and NativeFunction

This commit is contained in:
Charles Lowell 2009-11-15 21:56:31 -05:00
parent 7caeebff1f
commit b5fb736cfd
3 changed files with 69 additions and 12 deletions

View file

@ -1,12 +1,47 @@
module Rhino 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 class Context
attr_reader :scope attr_reader :scope
class << self 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| ContextFactory.new.call do |native|
yield new(native, options) block.call(new(native, options))
end end
end end
@ -29,25 +64,35 @@ module Rhino
end end
end end
# Read a value from the global scope of this context
def [](k) def [](k)
@scope[k] @scope[k]
end 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) def []=(k,v)
@scope[k] = v @scope[k] = v
end end
def eval(str) # Evaluate a string of javascript in this context:
str = str.to_s # * <tt>source</tt> - the javascript source code to evaluate
# * <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)
source = source.to_s
begin begin
scope = To.javascript(@scope) scope = To.javascript(@scope)
result = @native.evaluateString(scope, str, "<eval>", 1, nil) result = @native.evaluateString(scope, source, source_name, line_number, nil)
To.ruby result To.ruby result
rescue J::RhinoException => e rescue J::RhinoException => e
raise Rhino::RhinoError, e raise Rhino::RhinoError, e
end end
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) def instruction_limit=(limit)
@native.setInstructionObserverThreshold(limit); @native.setInstructionObserverThreshold(limit);
@native.factory.instruction_limit = limit @native.factory.instruction_limit = limit
@ -55,7 +100,7 @@ module Rhino
end end
class ContextFactory < J::ContextFactory class ContextFactory < J::ContextFactory #:nodoc:
def observeInstructionCount(cxt, count) def observeInstructionCount(cxt, count)
raise RunawayScriptError, "script exceeded allowable instruction count" if count > @limit raise RunawayScriptError, "script exceeded allowable instruction count" if count > @limit
@ -67,7 +112,7 @@ module Rhino
end end
class RhinoError < StandardError class RhinoError < StandardError #:nodoc:
def initialize(native) def initialize(native)
@native = native @native = native
end end
@ -81,5 +126,5 @@ module Rhino
end end
end end
class RunawayScriptError < StandardError; end class RunawayScriptError < StandardError; end #:nodoc:
end end

View file

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

View file

@ -1,5 +1,14 @@
module Rhino 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 class NativeFunction < NativeObject
def call(*args) def call(*args)
begin begin