build-tar nps/nps.py nps/run_sums.sh nps/sum.js nps/sum.py nps/test_1.js nps/test_2.js nps/test_3.js @@ -1,3 +1,3 @@ #!/bin/sh - +cd `dirname $0` epydoc --config=epydoc.ini doc/build-doc @@ -46,14 +46,19 @@ pre, xmp { /*-----------------------------------------------------------------*/ h1,h2,h3 { - padding-left: 2em; - padding-right: 0.3em; - padding-top: 0.3em; - padding-bottom: 0.3em; - border-width: 0; - background: #227; - color: #FFF; - text-shadow: 2px 2px 2px #777; + padding-left: 2em; + padding-right: 0.3em; + padding-top: 0.3em; + padding-bottom: 0.3em; + border-style: solid; + border-width: 1; + border-color: #000; + background: #227; + color: #FFF; + text-shadow: 2px 2px 2px #777; + -moz-border-radius: 10px; + -webkit-border-radius: 10px; + } /*-----------------------------------------------------------------*/ @@ -196,7 +201,7 @@ function body_onload() { <h3>History</h3> <ul> -<li>2009-04-21 - Patrick Mueller - initial write-up</li> +<li>2009-04-22 - Patrick Mueller - version 0.5</li> </ul> <!-- ====================================================== --> @@ -219,7 +224,8 @@ You may want to get familiarity with this framework before using this package in anger. In lieu of that, examine the test cases. <p>Note that the <code>nitro_pie</code> module does not currently expose -all of the WebKit APIs. +all of the WebKit APIs. It does expose enough to do some interesting +things. <!-- ====================================================== --> <h2>Installation</h2> @@ -232,13 +238,79 @@ an appropriate directory to use with other Python code. <p>The module makes extensive use of the <code><a href="http://docs.python.org/library/ctypes.html#module-ctypes">ctypes</a></code> module, which is included in Python distributions starting with version 2.5. -This module has currently only be tested or used on Mac OS X, and will likely +The <code>nitro_pie</code> module has currently only be tested and used on Mac OS X, and will likely need some changes to run on other operating systems. Along with finding/building a copy of JavaScriptCore for those operating systems. <!-- ====================================================== --> <h2>Usage</h2> +<p>There are test cases available in the <code>test</code> subdirectory, +and a shell example available in the <code>nps</code> directory, to see +some real life usage. + +<p>All usages of <code>nitro_pie</code> start with obtaining a +<code>JSContext</code> object, via the following invocation: + +<pre> +context = JSContext() +</pre> + +<p>Once a context has been obtained, you can execute a script using +<code>JSContext</code>'s <code>eval()</code> method: + +<pre> +result = context.eval(script, None, script_file_name, 1) +</pre> + +<p>The <code>eval()</code> method will return the result of evaluating +JavaScript code, perhaps returning a <code>JSObject</code> instance +that you can further noodle on. + +<p>To add a new function to a context that a script executes in, +use the <code>JSContext</code> <code>makeFunctionWithCallback()</code> method, +and then add it to the 'global' object of the context: + +<pre> +function = context.makeFunctionWithCallback("print", callback_print) +globalObject = context.getGlobalObject() +globalObject.setProperty("print", function)</pre> +</pre> + +<p>The second argument to the <code>makeFunctionWithCallback()</code> method +is a Python callable, which should have the following signature: + +<pre> +def callback_print(context, function, thisObject, args) +</pre> + +<p>The <code>context</code> parameter is the context that the function +was invoked within. +The <code>function</code> parameter is the JavaScript function that is +currently executing. +The <code>thisObject</code> parameter is the <code>'this'</code> value +for the invocation. +The <code>args</code> parameter is the array of parameters passed +to the function. + +<p>The function should return whatever value it needs to return. Here's +an example of a function which prints it's arguments: + +<pre> +def callback_print(context, function, thisObject, args): + line = "" + + for arg in args: + if JSObject.isJSObject(arg): + printable = arg.toString() + else: + printable = str(arg) + + line = line + printable + + print line +</pre> + <!-- ====================================================== --> <h2>Data conversions</h2> @@ -316,6 +388,35 @@ such an object in Python. </table> +<h3>Notes</h3> + +<p>Because JavaScript values returned from the APIs may be either +natural Python types (given the mapping above), or instances of +<code>JSObject</code>, you will likely need to be able to sniff to see +if instances are <code>JSObject</code>'s at times. You can use the +function <code>JSObject.isJSObject()</code> to test for this, or just use +the more natural Python test of +<code>isInstance(object,JSObject)</code>. + +<p>There is currently no direct way of creating JavaScript objects or +arrays other than the 'primitive' values specified in the table above. +To do this indirectly, use <code>JSContext.eval()</code>. For instance, +to create a new empty object, use: + +<pre> +object = context.eval("({})") +</pre> + +<p>To create an array, use: + +<pre> +object = context.eval("[]") +</pre> + +<p>All JavaScript objects besides the primitives specified in the table +above can be accessed and manipulated as instances of +<code>JSObject</code>. + <!-- ====================================================== --> <h2>nitro_pie Module Reference</h2> @@ -325,8 +426,8 @@ at the <a href="http://developer.apple.com/documentation/Carbon/Reference/WebKit_JavaScriptCore_Ref/index.html#//apple_ref/doc/framework/javascriptcore_fw">JavaScriptCore Framework Reference</a> available at the ADC. -<p><a href="api/index.html">API doc</a> - +<p>Some <a href="api/index.html">Epydoc generated documentation</a> for the module +is also available. </body> doc/nitro_pie.html @@ -32,8 +32,8 @@ #-------------------------------------------------------------------- __author__ = "Patrick Mueller <pmuellr@yahoo.com>" -__date__ = "2009-03-25" -__version__ = "0.1" +__date__ = "2009-04-22" +__version__ = "0.5" import ctypes import ctypes.util @@ -63,19 +63,13 @@ JSUndefined = "{{undefined}}" #------------------------------------------------------------------- JSPropertyAttributeNone = 0 -"""Constant used when setting property values""" +"""Constant used when setting property values with JSObject::setProperty()""" JSPropertyAttributeReadOnly = 1 << 1 -"""Constant used when setting property values""" +"""Constant used when setting property values with JSObject::setProperty()""" JSPropertyAttributeDontEnum = 1 << 2 -"""Constant used when setting property values""" +"""Constant used when setting property values with JSObject::setProperty()""" JSPropertyAttributeDontDelete = 1 << 3 -"""Constant used when setting property values""" - -#------------------------------------------------------------------- -#_JSClassAttributeNone = 0 -#"""JSClassAttribute""" -#_JSClassAttributeNoAutomaticPrototype = 1 << 1 -#"""JSClassAttribute""" +"""Constant used when setting property values with JSObject::setProperty()""" #-------------------------------------------------------------------- def _string2jsString(string): @@ -118,23 +112,30 @@ def _jsString2string(jsString): #-------------------------------------------------------------------- class JSContext: - """Models a Context""" + """Models a Context + + A context maintains the variables and environment that a + script runs in.""" #---------------------------------------------------------------- @staticmethod def gc(): - """A veneer over JSGarbageCollect()""" + """Performs a garbage collection + + You do not need to call this to run + the garbage collector, but you can call if if you + explicitly want to run it. + """ _log() _JSGarbageCollect(None) #---------------------------------------------------------------- def __init__(self, ctx=None): - """A veneer over JSGlobalContextCreate(). - - Creates a new JSContext which does not need to be - retain()'d, but does need to be release()'d. + """Creates a new JSContext object + @type ctx: JSContext + @param ctx: an existing JSContext to base this on; for internal use only @rtype: JSContext @return: the new JSContext created """ @@ -150,14 +151,18 @@ class JSContext: #---------------------------------------------------------------- def __del__(self): - """Intended for internal use only.""" + """Intended for internal use only""" _log("JSContext() - ctx: %s" % (str(self.ctx))) while self.ctx: self.release() #---------------------------------------------------------------- def __str__(self): - """Intended for internal use only.""" + """Intended for internal use only + + @rtype: str + @return: a string representation of this object + """ return "JSContext{ctx=%s, ref=%d}" % (str(self.ctx), self.ref) @@ -171,15 +176,8 @@ class JSContext: raise Exception, "JSContext has been released" #---------------------------------------------------------------- - def retain(self): - """A veneer over JSGlobalContextRetain() - - Returns a new JSContext which should be release()'d - when you are finished with it. - - @rtype: JSContext - @return: the new retained JSContext - """ + def _retain(self): + """Intended for internal use only""" _log() self._checkAllocated() @@ -189,7 +187,10 @@ class JSContext: #---------------------------------------------------------------- def release(self): - """A veneer over JSGlobalContextRelease()""" + """Releases the context + + You should release the context when you are finished + with it.""" _log() if self.ref <= 0: @@ -208,15 +209,15 @@ class JSContext: sourceURL=None, startingLineNumber=1 ): - """A veneer over JSCheckScriptSyntax() - + """Checks a script for validity without running it + @rtype: boolean @return: whether the script is syntactically correct @type script: str | unicode @param script: the source code for the script to check @type sourceURL: str | unicode @param sourceURL: the URL of the source code - @type startingLineNumber: number + @type startingLineNumber: int @param startingLineNumber: the line number of the script """ _log() @@ -255,7 +256,12 @@ class JSContext: sourceURL=None, startingLineNumber=1 ): - """A veneer over JSEvaluateScript() + """Execute a script + + Executes a script, and returns the result. For scripts + which are expressions, this returns the expression value. + For scripts which contain statements, returns the value of + executing the final statement. @rtype: JSObject @return: result of evaluating the script @@ -265,7 +271,7 @@ class JSContext: @param thisObject: the global object when executing the script @type sourceURL: str | unicode @param sourceURL: the URL of the source code - @type startingLineNumber: number + @type startingLineNumber: int @param startingLineNumber: the line number of the script """ _log() @@ -300,7 +306,7 @@ class JSContext: #---------------------------------------------------------------- def getGlobalObject(self): - """A veneer over JSContextGetGlobalObject() + """Returns the 'global' object associated with a context @rtype: JSObject @return: the global object for this context @@ -313,7 +319,10 @@ class JSContext: #---------------------------------------------------------------- def makeConstructorWithCallback(self, callback): - """A veneer over JSObjectMakeConstructor() + """Create a new JavaScript constructor + + Create a JavaScript constructor implemented with a Python + function. @rtype: JSObject @return: the constructor created @@ -348,7 +357,10 @@ class JSContext: #---------------------------------------------------------------- def makeFunctionWithCallback(self, name, callback): - """A veneer over JSObjectMakeFunctionWithCallback() + """Create a new JavaScript function + + Create a JavaScript function implemented with a Python + function. @rtype: JSObject @return: the constructor created @@ -430,11 +442,32 @@ class JSContext: #-------------------------------------------------------------------- class JSObject: - """Models a JavaScript object """ + """Models a JavaScript object + + This class is used to represent non-primitive JavaScript + values such as objects, arrays, and functions. Primitive + values including strings, booleans, numbers, null and undefined + are represented as native Python values. + + Most methods of this class take an optional context value + parameter. If specified, the operation will occur against that + context, else it will occur against the context the object was + created in. + """ #-------------------------------------------------------------------- @staticmethod def isJSObject(o): + """Returns an indication of whether this is a JavaScript object. + + Typically used to test a result to see if it's a complex or + primitive JavaScript object. + + @rtype: boolean + @return: whether the specified object is a JSObject + @type o: any + @param o: the object to test to see if it's a JSObject + """ return isinstance(o,JSObject) #-------------------------------------------------------------------- @@ -458,7 +491,10 @@ class JSObject: #---------------------------------------------------------------- def __init__(self, jsRef, ctx): - """Intended for internal use only.""" + """Creates a new JSObject. + + Intended for internal use only. + """ _log("JSObject() - ctx: %s; jsRef: %s" % (str(ctx), str(jsRef))) self.ctx = ctx @@ -506,7 +542,13 @@ class JSObject: #---------------------------------------------------------------- def isEqual(self, jsObject, jsContext=None): - """A veneer over JSValueIsEqual()""" + """Returns whether the current JSObject is equal to the specified JSObject + + @rtype: boolean + @return: whether the specified object is equal to this JSObject + @type jsObject: JSObject + @param jsObject: the object to compare against + """ ctx = jsContext.ctx if jsContext else self.ctx self._checkAllocated(ctx) @@ -515,7 +557,13 @@ class JSObject: #---------------------------------------------------------------- def isStrictEqual(self, jsObject, jsContext=None): - """A veneer over JSValueisStrictEqual()""" + """Returns whether the current JSObject is strictly equal to the specified JSObject + + @rtype: boolean + @return: whether the specified object is strictly equal to this JSObject + @type jsObject: JSObject + @param jsObject: the object to compare against + """ ctx = jsContext.ctx if jsContext else self.ctx self._checkAllocated(ctx) @@ -524,7 +572,13 @@ class JSObject: #---------------------------------------------------------------- def isInstanceOf(self, jsConstructor, jsContext=None): - """A veneer over JSValueIsInstanceOfConstructor()""" + """Returns whether the current JSObject is an instance of the specified JSObject + + @rtype: boolean + @return: whether the current JSObject is an instance of the specified JSObject, which should be a constructor + @type jsConstructor: JSObject + @param jsConstructor: the constructor to test against + """ ctx = jsContext.ctx if jsContext else self.ctx self._checkAllocated(ctx) @@ -533,7 +587,11 @@ class JSObject: #---------------------------------------------------------------- def toBoolean(self, jsContext=None): - """A veneer over JSValueToBoolean()""" + """Returns the value of the current JSObject, converted to a boolean + + @rtype: boolean + @return: the object converted to a boolean value + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -543,7 +601,11 @@ class JSObject: #---------------------------------------------------------------- def toNumber(self, jsContext=None): - """A veneer over JSValueToBoolean()""" + """Returns the value of the current JSObject, converted to a number + + @rtype: float + @return: the object converted to a number + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -561,7 +623,11 @@ class JSObject: #---------------------------------------------------------------- def toString(self, jsContext=None): - """A veneer over JSValueToStringCopy()""" + """Returns the value of the current JSObject, converted to a string + + @rtype: str + @return: the object converted to a string + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -578,7 +644,11 @@ class JSObject: #---------------------------------------------------------------- def getPropertyNames(self, jsContext=None): - """A veneer over JSObjectCopyPropertyNames()""" + """Returns the names of the properties of this object + + @rtype: list of str + @return: the enumerable property names of this object + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -596,7 +666,13 @@ class JSObject: #---------------------------------------------------------------- def deleteProperty(self, propertyName, jsContext=None): - """A veneer over JSObjectDeleteProperty()""" + """Deletes the specified property + + @rtype: boolean + @return: whether the property could be deleted + @type propertyName: str|unicode + @param propertyName: the name of the property to delete + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -617,7 +693,13 @@ class JSObject: #---------------------------------------------------------------- def getProperty(self, propertyName, jsContext=None): - """A veneer over JSObjectGetProperty()""" + """Returns the specified property value + + @rtype: any + @return: the value of the specified property + @type propertyName: str|unicode + @param propertyName: the name of the property to retrieve + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -639,7 +721,13 @@ class JSObject: #---------------------------------------------------------------- def getPropertyAtIndex(self, propertyIndex, jsContext=None): - """A veneer over JSGetPropertyAtIndex()""" + """Returns the specified array element + + @rtype: any + @return: the value of the specified array index + @type propertyIndex: int + @param propertyIndex: the index of the array element to retrieve + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -657,7 +745,11 @@ class JSObject: #---------------------------------------------------------------- def getPrototype(self, jsContext=None): - """A veneer over JSObjectGetPrototype()""" + """Returns the prototype of this JSObject + + @rtype: any + @return: the prototype of this JSObject + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -669,7 +761,13 @@ class JSObject: #---------------------------------------------------------------- def hasProperty(self, propertyName, jsContext=None): - """A veneer over JSObjectHasProperty()""" + """Returns whether this JSObject contains the specified property + + @rtype: boolean + @return: whether this JSObject has this property + @type propertyName: str|unicode + @param propertyName: the name of the property to delete + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -684,7 +782,11 @@ class JSObject: #---------------------------------------------------------------- def isConstructor(self, jsContext=None): - """A veneer over JSObjectIsConstructor()""" + """Returns whether this JSObject is a constructor + + @rtype: boolean + @return: whether this JSObject is a constructor + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -694,7 +796,11 @@ class JSObject: #---------------------------------------------------------------- def isFunction(self, jsContext=None): - """A veneer over JSObjectIsFunction()""" + """Returns whether this JSObject is a function + + @rtype: boolean + @return: whether this JSObject is a function + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -704,7 +810,15 @@ class JSObject: #---------------------------------------------------------------- def setProperty(self, propertyName, value, attributes=JSPropertyAttributeNone, jsContext=None): - """A veneer over JSObjectSetProperty()""" + """Set the specified property to the specified value + + @type propertyName: str|unicode + @param propertyName: the name of the property to create/set + @type value: any + @param value: the value of the property + @type attributes: int + @param attributes: attribute values for the property. Values is a bit ORing of the JSPropertyAttribute* properties of this module. + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -725,7 +839,13 @@ class JSObject: #---------------------------------------------------------------- def setPropertyAtIndex(self, propertyIndex, value, jsContext=None): - """A veneer over JSObjectSetPropertyAtIndex()""" + """Set the specified element of this array to the specified value + + @type propertyIndex: int + @param propertyIndex: the array index of the element to set + @type value: any + @param value: the value of the array element + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -742,7 +862,11 @@ class JSObject: #---------------------------------------------------------------- def setPrototype(self, value, jsContext=None): - """A veneer over JSObjectSetPrototype()""" + """Set the prototype of this JSObjecto the specified value + + @type value: any + @param value: the new value of the prototype + """ _log() ctx = jsContext.ctx if jsContext else self.ctx @@ -964,14 +1088,22 @@ class JSLibrary: system defined method.""" libraryPath = None - """Holds the fully qualified name of the JavaScriptCore library""" + """Holds the fully qualified name of the JavaScriptCore library + + If this library is set, it overrides the libraryName variable + setting and is used as the complete name of the library. + """ _library = None #---------------------------------------------------------------- @staticmethod def getLibrary(): - """Return the JavaScriptCore library as a CDLL or equivalent""" + """Return the JavaScriptCore library as a CDLL or equivalent + + @rtype: ctypes.CDLL + @return: the JavaScriptCore library + """ if JSLibrary._library: return JSLibrary._library lib/nitro_pie.py test/test_iss.py test/test_properties.py test/test_prototype.py test/test_tos.py 38f25e2498a13f0495037413ffb33a9261f71e27 Patrick Mueller pmuellr@yahoo.com http://github.com/pmuellr/nitro_pie/commit/55efaee97fde3a93451d5cbce8c66b68bf2bb610 55efaee97fde3a93451d5cbce8c66b68bf2bb610 2009-04-22T08:58:11-07:00 2009-04-22T08:58:11-07:00 added nps (shell), fixed doc, labeled 0.5 71adc56b94e25baa9d1c51a70b6fb2432f35db1b Patrick Mueller pmuellr@yahoo.com