Skip to content
Browse files

Vague attempt to make the API look more documented.

Not really adding a lot of real information... and I think I've made a
mess of the call-seq presentation.
  • Loading branch information...
1 parent 1b5f0c6 commit afb6861a06029ae6d849ec4ef8f2f544d6a751e9 @matthewd matthewd committed
Showing with 119 additions and 49 deletions.
  1. +3 −2 ext/spidermonkey/context.c
  2. +37 −22 ext/spidermonkey/ruby_land_proxy.c
  3. +38 −13 ext/spidermonkey/runtime.c
  4. +8 −1 lib/johnson.rb
  5. +33 −11 lib/johnson/runtime.rb
View
5 ext/spidermonkey/context.c
@@ -35,9 +35,10 @@ static JSBool branch_callback(JSContext* js, JSScript* UNUSED(script))
/*
* call-seq:
- * native_initialize(options={})
+ * context.native_initialize(runtime, options) => context
*
- * Initializes the native spidermonkey values.
+ * Create the underlying SpiderMonkey context. This must be called
+ * first, and only once. Called by +initialize+ by default.
*/
static VALUE
initialize_native(VALUE self, VALUE rb_runtime, VALUE UNUSED(options))
View
59 ext/spidermonkey/ruby_land_proxy.c
@@ -52,9 +52,10 @@ static VALUE call_js_function_value(JohnsonRuntime* runtime, jsval target, jsval
/*
* call-seq:
- * [](name)
+ * proxy[name] => value
*
- * Returns the property with +name+.
+ * Retrieves the current value of the +name+ property of this JavaScript
+ * object.
*/
static VALUE
get(VALUE self, VALUE name)
@@ -90,9 +91,9 @@ get(VALUE self, VALUE name)
/*
* call-seq:
- * []=(name,value)
+ * proxy[name] = value => value
*
- * Sets the property with +name+ to +value+.
+ * Sets this JavaScript object's +name+ property to +value+.
*/
static VALUE
set(VALUE self, VALUE name, VALUE value)
@@ -131,9 +132,9 @@ set(VALUE self, VALUE name, VALUE value)
/*
* call-seq:
- * function?
+ * proxy.function? => true or false
*
- * Returns <code>true</code> if this is a function.
+ * Returns <code>true</code> if this JavaScript object is a function.
*/
static VALUE
function_p(VALUE self)
@@ -150,9 +151,10 @@ function_p(VALUE self)
/*
* call-seq:
- * respond_to?(symbol)
+ * proxy.respond_to?(symbol) => true or false
*
- * Returns <code>true</code> if _obj_ responds to given method.
+ * Returns <code>true</code> if this JavaScript object responds to the
+ * named method.
*/
static VALUE
respond_to_p(int argc, const VALUE* argv, VALUE self)
@@ -191,9 +193,10 @@ respond_to_p(int argc, const VALUE* argv, VALUE self)
/*
* call-seq:
- * native_call(global, *args)
+ * proxy.native_call(this, *args) => result
*
- * Call as a function with given +global+ using *args.
+ * Call this Ruby Object as a function, with the given +this+ object and
+ * arguments. Equivalent to the call method in JavaScript.
*/
static VALUE
native_call(int argc, VALUE* argv, VALUE self)
@@ -230,9 +233,12 @@ destroy_id_array(JSContext* context, void* data)
/*
* call-seq:
- * each { |obj| block }
+ * array_proxy.each {| element | block } => array_proxy
+ * object_proxy.each {| name, value | block } => object_proxy
*
- * Calls <em>block</em> with each item in the collection.
+ * Calls <em>block</em> with each item in this JavaScript array, or with
+ * each +name+/+value+ pair (like a Hash) for any other JavaScript
+ * object.
*/
static VALUE
each(VALUE self)
@@ -309,9 +315,11 @@ each(VALUE self)
/*
* call-seq:
- * length
+ * array_proxy.length => element_count
+ * object_proxy.length => property_count
*
- * Returns the length of the collection.
+ * Returns the number of entries in the JavaScript array, or the number
+ * of properties on the JavaScript object.
*/
static VALUE
length(VALUE self)
@@ -350,9 +358,10 @@ length(VALUE self)
/*
* call-seq:
- * runtime
+ * proxy.runtime => runtime
*
- * Returns runtime.
+ * Returns the Johnson::SpiderMonkey::Runtime against which this object
+ * is registered.
*/
static VALUE
runtime(VALUE self)
@@ -364,9 +373,10 @@ runtime(VALUE self)
/*
* call-seq:
- * function_property?(name)
+ * proxy.function_property?(name) => true or false
*
- * Returns <code>true</code> if +name+ is a function property.
+ * Returns <code>true</code> if this JavaScript object's +name+ property
+ * is a function.
*/
static VALUE
function_property_p(VALUE self, VALUE name)
@@ -400,9 +410,13 @@ function_property_p(VALUE self, VALUE name)
/*
* call-seq:
- * call_function_property(name, arguments)
+ * proxy.call_function_property(name, arguments) => result
*
- * Calls function +name+ with +arguments+.
+ * Calls this JavaScript object's +name+ method, passing the given
+ * arguments.
+ *
+ * Equivalent to:
+ * proxy[name].native_call(proxy, *arguments)
*/
static VALUE
call_function_property(int argc, VALUE* argv, VALUE self)
@@ -441,9 +455,10 @@ call_function_property(int argc, VALUE* argv, VALUE self)
/*
* call-seq:
- * to_s
+ * proxy.to_s => string
*
- * Converts object to a string.
+ * Converts the JavaScript object to a string, using its toString method
+ * if available.
*/
static VALUE to_s(VALUE self)
{
View
51 ext/spidermonkey/runtime.c
@@ -8,7 +8,7 @@
/*
* call-seq:
- * global
+ * runtime.global => proxy
*
* Returns the global object used for this context.
*/
@@ -33,9 +33,9 @@ static JSTrapStatus trap_handler( JSContext *context,
/*
* call-seq:
- * clear_trap(script, line_num)
+ * runtime.clear_trap(script, line_num) => runtime
*
- * Set the trap at +script+ and +line_num+ to +block+
+ * Clear the trap previously set at +line_num+ of +script+.
*/
static VALUE clear_trap(VALUE self, VALUE script, VALUE linenum)
{
@@ -57,9 +57,10 @@ static VALUE clear_trap(VALUE self, VALUE script, VALUE linenum)
/*
* call-seq:
- * set_trap(script, parsecode, block)
+ * runtime.set_trap(script, line_num, block) => true
*
- * Set the trap at +script+ and +parsecode+ to +block+
+ * Set a trap to invoke +block+ when execution of +script+ reaches
+ * +line_num+.
*/
static VALUE set_trap(VALUE self, VALUE script, VALUE linenum, VALUE block)
{
@@ -78,9 +79,10 @@ static VALUE set_trap(VALUE self, VALUE script, VALUE linenum, VALUE block)
/*
* call-seq:
- * native_compile(script, filename, linenum)
+ * runtime.native_compile(script_string, filename, linenum) => script_proxy
*
- * Compile +script+ with +filename+ using +linenum+
+ * Compile the JavaScript code in +script_string+, marked as originating
+ * from +filename+ starting at +linenum+.
*/
static VALUE native_compile(VALUE self, VALUE script, VALUE filename, VALUE linenum)
{
@@ -119,9 +121,10 @@ static VALUE native_compile(VALUE self, VALUE script, VALUE filename, VALUE line
/*
* call-seq:
- * evaluate_compiled_script(script)
+ * runtime.evaluate_compiled_script(script_proxy) => result
*
- * Evaluate +script+
+ * Evaluate previously compiled +script_proxy+, returning the final
+ * result from that script.
*/
static VALUE evaluate_compiled_script(VALUE self, VALUE compiled_script)
{
@@ -169,10 +172,13 @@ static VALUE evaluate_compiled_script(VALUE self, VALUE compiled_script)
#ifdef JS_GC_ZEAL
/*
* call-seq:
- * gc_zeal=(level)
+ * runtime.gc_zeal = level => level
*
* Sets the GC zeal.
- * 0 = normal, 1 = Very Frequent, 2 = Extremely Frequent
+ *
+ * 0:: Normal
+ * 1:: Very Frequent
+ * 2:: Extremely Frequent
*/
static VALUE
set_gc_zeal(VALUE self, VALUE zeal)
@@ -188,6 +194,12 @@ set_gc_zeal(VALUE self, VALUE zeal)
}
#endif
+/*
+ * call-seq:
+ * runtime.gc => nil
+ *
+ * Manually initiates a SpiderMonkey Garbage Collection run.
+ */
static VALUE
gc(VALUE self)
{
@@ -203,9 +215,10 @@ gc(VALUE self)
/*
* call-seq:
- * debugger=(debugger)
+ * runtime.debugger = debugger => debugger
*
- * Sets a debugger object
+ * Directs the runtime to install a full set of debug hooks, using the
+ * given +debugger+, which must be a Johnson::SpiderMonkey::Debugger.
*/
static VALUE
set_debugger(VALUE self, VALUE debugger)
@@ -268,6 +281,13 @@ JSBool gc_callback(JSContext *context, JSGCStatus status)
return JS_FALSE;
}
+/**
+ * call-seq:
+ * runtime.initialize_native(options) => runtime
+ *
+ * Create the underlying SpiderMonkey runtime. This must be called
+ * first, and only once. Called by +initialize+ by default.
+ */
static VALUE
initialize_native(VALUE self, VALUE UNUSED(options))
{
@@ -350,6 +370,11 @@ static VALUE allocate(VALUE klass)
void init_Johnson_SpiderMonkey_Runtime(VALUE spidermonkey)
{
+ /* HACK: These comments are *only* to make RDoc happy.
+ VALUE johnson = rb_define_module("Johnson");
+ VALUE spidermonkey = rb_define_module_under(johnson, "SpiderMonkey");
+ */
+
VALUE klass = rb_define_class_under(spidermonkey, "Runtime", rb_cObject);
rb_define_alloc_func(klass, allocate);
View
9 lib/johnson.rb
@@ -27,6 +27,11 @@
module Johnson
VERSION = "1.1.2"
+ ###
+ # Evaluate the given JavaScript +expression+ in a new runtime, after
+ # setting the given +vars+ into the global object.
+ #
+ # Returns the result of evaluating the given expression.
def self.evaluate(expression, vars={})
runtime = Johnson::Runtime.new
vars.each { |key, value| runtime[key] = value }
@@ -39,7 +44,9 @@ def self.parse(js, *args)
end
###
- # Create a new runtime and load all +files+. Returns a new Johnson::Runtime.
+ # Create a new runtime and load all +files+.
+ #
+ # Returns the new Johnson::Runtime.
def self.load(*files)
rt = Johnson::Runtime.new
rt.load(*files)
View
44 lib/johnson/runtime.rb
@@ -1,4 +1,6 @@
module Johnson
+ ###
+ # An interface to a JavaScript engine.
class Runtime
PRELUDE_PATH = File.expand_path File.dirname(__FILE__) +
@@ -6,31 +8,53 @@ class Runtime
PRELUDE = IO.read PRELUDE_PATH
+ ###
+ # The underlying JavaScript engine instance.
attr_reader :delegate
+ ###
+ # Create a new Runtime instance, using the given +delegate+ class,
+ # or a Johnson::SpiderMonkey::Runtime by default.
def initialize(delegate=Johnson::SpiderMonkey::Runtime)
@delegate = delegate.is_a?(Class) ? delegate.new : delegate
evaluate PRELUDE, PRELUDE_PATH, 1
global.Johnson.runtime = self
end
+ ###
+ # Access the +key+ property of the JavaScript +global+ object.
def [](key)
delegate[key]
end
+ ###
+ # Set the +key+ property of the JavaScript +global+ object to
+ # +value+.
def []=(key, value)
delegate[key] = value
end
- def evaluate(expression, filename=nil, linenum=nil)
- return nil if expression.nil?
- delegate.evaluate(expression, filename, linenum)
+ ###
+ # Execute the JavaScript source in +script+. If supplied, the script
+ # is marked as starting on line +linenum+ of +filename+.
+ #
+ # Equivalent to calling RubyLandScript#execute on the result of
+ # Runtime#compile.
+ def evaluate(script, filename=nil, linenum=nil)
+ return nil if script.nil?
+ delegate.evaluate(script, filename, linenum)
end
+ ###
+ # The JavaScript unique Global Object.
def global
delegate.global
end
+ ###
+ # Load and execute the named JavaScript +files+.
+ #
+ # Checks for (and skips) a shebang line at the top of any of them.
def load(*files)
files.map { |f|
delegate.evaluate(File.read(f).gsub(/\A#!.*$/, ''), f, 1)
@@ -38,7 +62,10 @@ def load(*files)
end
###
- # Johnson.require on each file in +files+
+ # Search the Ruby load path for each of the named +files+, and
+ # evaluate them *if they have not yet been loaded*.
+ #
+ # Calls Johnson.require() in JavaScript on each filename in turn.
def require(*files)
files.each do |file|
evaluate("Johnson.require('#{file}');")
@@ -46,17 +73,12 @@ def require(*files)
end
###
- # Compile +script+ with +filename+ and +linenum+
+ # Compile the JavaScript source in +script+. If supplied, the script
+ # is marked as starting on line +linenum+ of +filename+.
def compile(script, filename=nil, linenum=nil)
delegate.compile(script, filename, linenum)
end
- ###
- # Yield to +block+ in +filename+ at +linenum+
- def break(filename, linenum, &block)
- delegate.break(filename, linenum, &block)
- end
-
def evaluate_compiled_script(script)
delegate.evaluate_compiled(script)
end

0 comments on commit afb6861

Please sign in to comment.
Something went wrong with that request. Please try again.