# HG changeset patch
# User Atul Varma <varmaa@toolness.com>
# Date 1250306800 25200
# Node ID c41f1d2e8f9dbef29ee1a04eb5e6111246398914
# Parent  e77bc7c799e833b1b89c754fe9d9379d3c06d192
Added more docs.

diff -r e77bc7c799e8 -r c41f1d2e8f9d docs/rendered/_sources/pymonkey.txt
--- a/docs/rendered/_sources/pymonkey.txt	Sun Aug 09 22:54:15 2009 -0700
+++ b/docs/rendered/_sources/pymonkey.txt	Fri Aug 14 20:26:40 2009 -0700
@@ -79,9 +79,21 @@
    .. method:: new_function(callable, name)
 
       Creates a new :class:`Function` instance that wraps the
-      given Python callable.  In JS-land, the callable will
+      given Python callable.  In JS-land, the function will
       have the given name.
 
+      When the function is executed from JavaScript, `callable`
+      will be passed three positional arguments.
+
+      The first argument is a :class:`Context` that represents the
+      JS context which is calling the function.
+
+      The second argument is an :class:`Object` that represents the
+      value of ``this`` for the duration of the call.
+
+      The third argument is a tuple containing the arguments
+      passed to the function.
+
    .. method:: get_object_private(object)
 
       Returns the ``private_obj`` passed to :meth:`new_object()`
@@ -91,8 +103,8 @@
       If `object` was created with :meth:`new_function()`, then this
       method returns the Python callable wrapped by `object`.
 
-      This functionality is useful if you want to represent Python
-      objects in JS-land.
+      This functionality is useful if you want to securely represent
+      Python objects in JS-land.
 
    .. method:: clear_object_private(object)
 
@@ -105,6 +117,25 @@
       `object`. If `object` is later called, an exception will be
       raised.
 
+   .. method:: evaluate_script(globalobj, code, filename, lineno)
+
+      Evaluates the text `code` using `globalobj` as the global
+      object/scope.
+
+      It's assumed that `code` is coming from the file named by `filename`;
+      the first line of `code` is assumed to be line number `lineno` of
+      `filename`. This metadata is very useful for debugging stack traces,
+      exceptions, and so forth.
+
+   .. method:: call_function(thisobj, func, args)
+
+      Calls a JavaScript function.
+
+      `thisobj` is an :class:`Object` that will be used as the value
+      of ``this`` when the function executes, `func` is the
+      :class:`Function` to execute, and `args` is a tuple of arguments
+      to pass to the function.
+
    .. method:: init_standard_classes(object)
 
       Defines the standard JavaScript classes on the given
diff -r e77bc7c799e8 -r c41f1d2e8f9d docs/rendered/genindex.html
--- a/docs/rendered/genindex.html	Sun Aug 09 22:54:15 2009 -0700
+++ b/docs/rendered/genindex.html	Fri Aug 14 20:26:40 2009 -0700
@@ -52,15 +52,17 @@
 <table width="100%" class="indextable"><tr><td width="33%" valign="top">
 <dl>
 
-<dt><a href="pymonkey.html#pymonkey.Context.clear_object_private">clear_object_private() (pymonkey.Context method)</a></dt>
-<dt><a href="pymonkey.html#pymonkey.Context">Context (class in pymonkey)</a></dt></dl></td><td width="33%" valign="top"><dl>
+<dt><a href="pymonkey.html#pymonkey.Context.call_function">call_function() (pymonkey.Context method)</a></dt>
+<dt><a href="pymonkey.html#pymonkey.Context.clear_object_private">clear_object_private() (pymonkey.Context method)</a></dt></dl></td><td width="33%" valign="top"><dl>
+<dt><a href="pymonkey.html#pymonkey.Context">Context (class in pymonkey)</a></dt>
 </dl></td></tr></table>
 
 <h2 id="E">E</h2>
 <table width="100%" class="indextable"><tr><td width="33%" valign="top">
 <dl>
 
-<dt><a href="pymonkey.html#pymonkey.error">error</a></dt></dl></td><td width="33%" valign="top"><dl>
+<dt><a href="pymonkey.html#pymonkey.error">error</a></dt>
+<dt><a href="pymonkey.html#pymonkey.Context.evaluate_script">evaluate_script() (pymonkey.Context method)</a></dt></dl></td><td width="33%" valign="top"><dl>
 </dl></td></tr></table>
 
 <h2 id="F">F</h2>
diff -r e77bc7c799e8 -r c41f1d2e8f9d docs/rendered/pymonkey.html
--- a/docs/rendered/pymonkey.html	Sun Aug 09 22:54:15 2009 -0700
+++ b/docs/rendered/pymonkey.html	Fri Aug 14 20:26:40 2009 -0700
@@ -131,9 +131,18 @@
 <dl class="method">
 <dt id="pymonkey.Context.new_function">
 <tt class="descname">new_function</tt><big>(</big><em>callable</em>, <em>name</em><big>)</big><a class="headerlink" href="#pymonkey.Context.new_function" title="Permalink to this definition">¶</a></dt>
-<dd>Creates a new <a title="pymonkey.Function" class="reference" href="#pymonkey.Function"><tt class="xref docutils literal"><span class="pre">Function</span></tt></a> instance that wraps the
-given Python callable.  In JS-land, the callable will
-have the given name.</dd></dl>
+<dd><p>Creates a new <a title="pymonkey.Function" class="reference" href="#pymonkey.Function"><tt class="xref docutils literal"><span class="pre">Function</span></tt></a> instance that wraps the
+given Python callable.  In JS-land, the function will
+have the given name.</p>
+<p>When the function is executed from JavaScript, <cite>callable</cite>
+will be passed three positional arguments.</p>
+<p>The first argument is a <a title="pymonkey.Context" class="reference" href="#pymonkey.Context"><tt class="xref docutils literal"><span class="pre">Context</span></tt></a> that represents the
+JS context which is calling the function.</p>
+<p>The second argument is an <a title="pymonkey.Object" class="reference" href="#pymonkey.Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a> that represents the
+value of <tt class="docutils literal"><span class="pre">this</span></tt> for the duration of the call.</p>
+<p>The third argument is a tuple containing the arguments
+passed to the function.</p>
+</dd></dl>
 
 <dl class="method">
 <dt id="pymonkey.Context.get_object_private">
@@ -143,8 +152,8 @@
 is returned.</p>
 <p>If <cite>object</cite> was created with <a title="pymonkey.Context.new_function" class="reference" href="#pymonkey.Context.new_function"><tt class="xref docutils literal"><span class="pre">new_function()</span></tt></a>, then this
 method returns the Python callable wrapped by <cite>object</cite>.</p>
-<p>This functionality is useful if you want to represent Python
-objects in JS-land.</p>
+<p>This functionality is useful if you want to securely represent
+Python objects in JS-land.</p>
 </dd></dl>
 
 <dl class="method">
@@ -160,6 +169,27 @@
 </dd></dl>
 
 <dl class="method">
+<dt id="pymonkey.Context.evaluate_script">
+<tt class="descname">evaluate_script</tt><big>(</big><em>globalobj</em>, <em>code</em>, <em>filename</em>, <em>lineno</em><big>)</big><a class="headerlink" href="#pymonkey.Context.evaluate_script" title="Permalink to this definition">¶</a></dt>
+<dd><p>Evaluates the text <cite>code</cite> using <cite>globalobj</cite> as the global
+object/scope.</p>
+<p>It&#8217;s assumed that <cite>code</cite> is coming from the file named by <cite>filename</cite>;
+the first line of <cite>code</cite> is assumed to be line number <cite>lineno</cite> of
+<cite>filename</cite>. This metadata is very useful for debugging stack traces,
+exceptions, and so forth.</p>
+</dd></dl>
+
+<dl class="method">
+<dt id="pymonkey.Context.call_function">
+<tt class="descname">call_function</tt><big>(</big><em>thisobj</em>, <em>func</em>, <em>args</em><big>)</big><a class="headerlink" href="#pymonkey.Context.call_function" title="Permalink to this definition">¶</a></dt>
+<dd><p>Calls a JavaScript function.</p>
+<p><cite>thisobj</cite> is an <a title="pymonkey.Object" class="reference" href="#pymonkey.Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a> that will be used as the value
+of <tt class="docutils literal"><span class="pre">this</span></tt> when the function executes, <cite>func</cite> is the
+<a title="pymonkey.Function" class="reference" href="#pymonkey.Function"><tt class="xref docutils literal"><span class="pre">Function</span></tt></a> to execute, and <cite>args</cite> is a tuple of arguments
+to pass to the function.</p>
+</dd></dl>
+
+<dl class="method">
 <dt id="pymonkey.Context.init_standard_classes">
 <tt class="descname">init_standard_classes</tt><big>(</big><em>object</em><big>)</big><a class="headerlink" href="#pymonkey.Context.init_standard_classes" title="Permalink to this definition">¶</a></dt>
 <dd>Defines the standard JavaScript classes on the given
diff -r e77bc7c799e8 -r c41f1d2e8f9d docs/rendered/searchindex.js
--- a/docs/rendered/searchindex.js	Sun Aug 09 22:54:15 2009 -0700
+++ b/docs/rendered/searchindex.js	Fri Aug 14 20:26:40 2009 -0700
@@ -1,1 +1,1 @@
-Search.setIndex({desctypes:{"0":"method","1":"exception","2":"class","3":"data"},terms:{spidermonkei:[0,1],represent:1,all:0,code:[0,1],untrust:0,lack:0,concept:0,get_object_priv:1,privat:1,depend:0,readabl:0,program:1,isinst:1,liter:1,string:1,veri:0,vast:0,level:1,"try":0,pass:1,casual:0,even:[],index:0,evaluate_script:1,abl:0,access:[0,1],"new":1,objdir:0,method:1,full:0,never:0,onli:[0,1],here:0,objcec:[],path:0,valu:1,search:0,doctest:0,chang:1,tremend:0,via:[0,1],modul:[0,1],api:0,test_pymonkei:[],from:[0,1],would:0,memori:0,init_standard_class:1,call:1,type:1,more:[0,1],mozilla:[0,1],ctype:0,known:0,central:0,must:0,none:1,retriev:1,work:0,conceptu:1,can:[0,1],learn:0,akin:0,root:0,give:0,process:0,challeng:0,indic:0,want:[0,1],unfortun:[],alwai:0,goal:0,secur:0,write:0,how:0,verifi:1,map:1,product:0,clone:0,usabl:0,befor:0,mai:1,associ:1,third:0,counter:1,inform:1,sandbox:0,environ:0,subtyp:1,callabl:1,becaus:0,intermediari:0,through:1,dynam:0,platform:0,easier:0,them:0,js_initstandardclass:1,"return":1,thei:[],python:[0,1],now:[],xpcom:0,name:1,anyth:0,get_runtim:1,easili:0,trap:0,each:1,debug:0,side:0,mean:0,realli:0,wrap:1,"static":0,collector:0,out:0,path_to_objdir:0,profil:0,rational:0,print:1,forth:1,situat:0,free:[],standard:[0,1],reason:[],base:0,thrown:1,thread:1,traceback:0,first:1,singleton:1,obviou:0,pyrex:0,feel:[],arrai:1,number:0,instruct:0,facil:0,given:1,script:0,interact:1,too:0,"final":0,store:1,relationship:0,tool:0,huh:[],than:0,wide:0,kind:[],provid:0,browser:0,pre:1,falsi:1,ani:[0,1],packag:0,have:[0,1],tabl:0,need:0,"null":1,engin:[0,1],built:1,equival:1,latter:0,client:0,note:0,also:[0,1],ideal:0,exampl:[],build:0,which:[0,1],noth:[0,1],object:[0,1],plai:0,"class":1,don:0,clear:1,later:1,doe:[],runtim:1,awesom:0,particularli:0,involv:0,current:[0,1],new_object:1,execut:[0,1],solut:0,should:0,busi:0,contribut:0,pave:0,increas:0,requir:0,enabl:0,where:0,new_context:1,see:1,disadvantag:0,best:1,detect:0,someth:0,state:1,outstand:0,between:0,atul:0,javascript:[0,1],extens:0,preprocessor:0,complementari:0,come:0,expos:0,cycl:0,howev:0,blargh:[],instanc:[0,1],context:[0,1],logic:0,freeli:1,com:0,private_obj:1,simpli:[],within:1,sweep:0,header:0,duplic:0,quit:0,java:0,due:0,mark:0,clear_object_priv:[0,1],straight:0,defin:[0,1],error:1,advantag:0,unintuit:[],readm:0,blah:[],develop:0,parti:0,make:0,belong:1,cross:0,same:1,complex:0,document:[0,1],http:0,wherea:0,effect:1,hand:0,fairli:0,moment:0,rais:1,stack:0,pymonkei:[0,1],off:0,macro:0,without:0,thi:[0,1],undefin:1,programm:0,model:0,capi:0,new_funct:1,just:0,less:0,obtain:0,languag:0,web:0,easi:0,except:1,add:[],other:[0,1],around:0,read:0,swig:0,envis:0,know:[],world:0,like:[0,1],vibrant:0,manual:0,resolv:0,server:0,collect:0,either:0,docutil:1,page:0,right:[],some:0,back:0,mirror:0,librari:0,rhino:0,refer:0,run:0,garbag:0,broken:0,repositori:0,about:0,actual:0,manag:0,runtm:1,serverj:0,contributor:0,your:0,span:1,wai:0,ergonom:0,custom:0,avail:0,interfac:1,low:1,lot:0,suit:[],"function":[0,1],offer:1,eas:0,"true":1,count:0,made:0,possibl:0,similar:0,featur:0,creat:[0,1],doesn:[0,1],repres:1,exist:[0,1],file:0,check:[],probabl:0,boop:[],todo:[],when:1,field:0,valid:0,test:0,you:[0,1],boof:[],matur:0,relat:1,eval:1,unbind:1,land:[0,1],sphinx:0,directori:0,obj:1,time:0},titles:["Pymonkey Documentation","<tt class=\"docutils literal docutils literal\"><span class=\"pre\">pymonkey</span></tt> &#8212; Access SpiderMonkey from Python"],modules:{pymonkey:1},descrefs:{"pymonkey.Runtime":{new_context:[1,0]},"pymonkey.Object":{get_runtime:[1,0]},"pymonkey.Context":{get_object_private:[1,0],new_object:[1,0],clear_object_private:[1,0],new_function:[1,0],init_standard_classes:[1,0],get_runtime:[1,0]},pymonkey:{Function:[1,2],undefined:[1,3],Object:[1,2],Context:[1,2],error:[1,1],Runtime:[1,2]}},filenames:["index","pymonkey"]})
\ No newline at end of file
+Search.setIndex({desctypes:{"0":"method","1":"exception","2":"class","3":"data"},terms:{spidermonkei:[0,1],represent:1,all:0,code:[0,1],untrust:0,lack:0,concept:0,get_object_priv:1,privat:1,depend:0,readabl:0,program:1,isinst:1,liter:1,string:1,veri:[0,1],vast:0,level:1,"try":0,second:1,pass:1,casual:0,even:[],index:0,evaluate_script:1,abl:0,access:[0,1],"new":1,objdir:0,method:1,metadata:1,full:0,never:0,onli:[0,1],here:0,objcec:[],path:0,valu:1,search:0,doctest:0,chang:1,tremend:0,via:[0,1],modul:[0,1],filenam:1,api:0,test_pymonkei:[],from:[0,1],would:0,memori:0,init_standard_class:1,call:1,scope:1,type:1,more:[0,1],thisobj:1,mozilla:[0,1],ctype:0,known:0,central:0,must:0,none:1,retriev:1,work:0,conceptu:1,can:[0,1],learn:0,akin:0,root:0,give:0,process:0,challeng:0,indic:0,want:[0,1],unfortun:[],alwai:0,goal:0,secur:[0,1],write:0,how:0,verifi:1,map:1,product:0,clone:0,usabl:0,befor:0,mai:1,associ:1,third:[0,1],counter:1,inform:1,sandbox:0,environ:0,subtyp:1,callabl:1,becaus:0,intermediari:0,through:1,dynam:0,platform:0,easier:0,them:0,js_initstandardclass:1,"return":1,thei:[],python:[0,1],now:[],xpcom:0,name:1,anyth:0,get_runtim:1,easili:0,trap:0,each:1,debug:[0,1],side:0,mean:0,realli:0,wrap:1,"static":0,collector:0,out:0,path_to_objdir:0,profil:0,lineno:1,rational:0,print:1,forth:1,situat:0,free:[],standard:[0,1],reason:[],base:0,thrown:1,thread:1,traceback:0,first:1,singleton:1,obviou:0,pyrex:0,feel:[],arrai:1,number:[0,1],instruct:0,facil:0,given:1,script:0,interact:1,too:0,"final":0,store:1,relationship:0,tool:0,huh:[],than:0,wide:0,kind:[],provid:0,posit:1,browser:0,pre:1,falsi:1,ani:[0,1],packag:0,have:[0,1],tabl:0,need:0,"null":1,engin:[0,1],built:1,equival:1,latter:0,client:0,note:0,also:[0,1],ideal:0,exampl:[],build:0,which:[0,1],noth:[0,1],trace:1,object:[0,1],plai:0,"class":1,don:0,clear:1,later:1,doe:[],runtim:1,awesom:0,text:1,particularli:0,line:1,involv:0,current:[0,1],new_object:1,execut:[0,1],solut:0,should:0,busi:0,contribut:0,pave:0,increas:0,requir:0,enabl:0,contain:1,where:0,new_context:1,see:1,arg:1,disadvantag:0,best:1,detect:0,someth:0,state:1,outstand:0,between:0,atul:0,call_funct:1,javascript:[0,1],extens:0,preprocessor:0,complementari:0,come:[0,1],expos:0,cycl:0,howev:0,blargh:[],instanc:[0,1],context:[0,1],logic:0,freeli:1,com:0,private_obj:1,simpli:[],within:1,sweep:0,header:0,assum:1,duplic:0,quit:0,java:0,evalu:1,due:0,mark:0,clear_object_priv:[0,1],argument:1,func:1,straight:0,durat:1,defin:[0,1],error:1,advantag:0,unintuit:[],readm:0,blah:[],develop:0,parti:0,make:0,belong:1,cross:0,same:1,complex:0,document:[0,1],http:0,wherea:0,effect:1,hand:0,fairli:0,moment:0,rais:1,stack:[0,1],pymonkei:[0,1],off:0,macro:0,without:0,thi:[0,1],undefin:1,programm:0,model:0,capi:0,new_funct:1,just:0,less:0,obtain:0,languag:0,web:0,easi:0,except:1,add:[],other:[0,1],around:0,read:0,swig:0,envis:0,know:[],world:0,like:[0,1],vibrant:0,manual:0,resolv:0,server:0,collect:0,either:0,docutil:1,page:0,right:[],some:0,back:0,global:1,mirror:0,librari:0,rhino:0,refer:0,run:0,garbag:0,broken:0,repositori:0,about:0,actual:0,manag:0,runtm:1,three:1,serverj:0,contributor:0,your:0,span:1,wai:0,ergonom:0,custom:0,avail:0,interfac:1,low:1,lot:0,suit:[],"function":[0,1],offer:1,tupl:1,globalobj:1,eas:0,"true":1,count:0,made:0,possibl:0,similar:0,featur:0,creat:[0,1],doesn:[0,1],repres:1,exist:[0,1],file:[0,1],check:[],probabl:0,boop:[],todo:[],when:1,field:0,valid:0,test:0,you:[0,1],boof:[],matur:0,relat:1,eval:1,unbind:1,land:[0,1],sphinx:0,directori:0,obj:1,time:0},titles:["Pymonkey Documentation","<tt class=\"docutils literal docutils literal\"><span class=\"pre\">pymonkey</span></tt> &#8212; Access SpiderMonkey from Python"],modules:{pymonkey:1},descrefs:{"pymonkey.Runtime":{new_context:[1,0]},"pymonkey.Object":{get_runtime:[1,0]},"pymonkey.Context":{get_object_private:[1,0],new_object:[1,0],call_function:[1,0],evaluate_script:[1,0],clear_object_private:[1,0],new_function:[1,0],init_standard_classes:[1,0],get_runtime:[1,0]},pymonkey:{Function:[1,2],undefined:[1,3],Object:[1,2],Context:[1,2],error:[1,1],Runtime:[1,2]}},filenames:["index","pymonkey"]})
\ No newline at end of file
diff -r e77bc7c799e8 -r c41f1d2e8f9d docs/src/pymonkey.txt
--- a/docs/src/pymonkey.txt	Sun Aug 09 22:54:15 2009 -0700
+++ b/docs/src/pymonkey.txt	Fri Aug 14 20:26:40 2009 -0700
@@ -79,9 +79,21 @@
    .. method:: new_function(callable, name)
 
       Creates a new :class:`Function` instance that wraps the
-      given Python callable.  In JS-land, the callable will
+      given Python callable.  In JS-land, the function will
       have the given name.
 
+      When the function is executed from JavaScript, `callable`
+      will be passed three positional arguments.
+
+      The first argument is a :class:`Context` that represents the
+      JS context which is calling the function.
+
+      The second argument is an :class:`Object` that represents the
+      value of ``this`` for the duration of the call.
+
+      The third argument is a tuple containing the arguments
+      passed to the function.
+
    .. method:: get_object_private(object)
 
       Returns the ``private_obj`` passed to :meth:`new_object()`
@@ -91,8 +103,8 @@
       If `object` was created with :meth:`new_function()`, then this
       method returns the Python callable wrapped by `object`.
 
-      This functionality is useful if you want to represent Python
-      objects in JS-land.
+      This functionality is useful if you want to securely represent
+      Python objects in JS-land.
 
    .. method:: clear_object_private(object)
 
@@ -105,6 +117,25 @@
       `object`. If `object` is later called, an exception will be
       raised.
 
+   .. method:: evaluate_script(globalobj, code, filename, lineno)
+
+      Evaluates the text `code` using `globalobj` as the global
+      object/scope.
+
+      It's assumed that `code` is coming from the file named by `filename`;
+      the first line of `code` is assumed to be line number `lineno` of
+      `filename`. This metadata is very useful for debugging stack traces,
+      exceptions, and so forth.
+
+   .. method:: call_function(thisobj, func, args)
+
+      Calls a JavaScript function.
+
+      `thisobj` is an :class:`Object` that will be used as the value
+      of ``this`` when the function executes, `func` is the
+      :class:`Function` to execute, and `args` is a tuple of arguments
+      to pass to the function.
+
    .. method:: init_standard_classes(object)
 
       Defines the standard JavaScript classes on the given