pymonkey: docs/src/pymonkey.txt annotate

annotate docs/src/pymonkey.txt @ 85:e9f450d30c0e

Added more documentation.

author	Atul Varma <varmaa@toolness.com>
date	Sun, 09 Aug 2009 15:37:29 -0700
parents	4945e4073110
children	c41f1d2e8f9d

rev	line source
51 fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	1 :mod:`pymonkey` --- Access SpiderMonkey from Python
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	2 ===================================================
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	3
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	4 .. module:: pymonkey
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	5 :synopsis: Access SpiderMonkey from Python
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	6
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	7 .. testsetup:: *
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	8
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	9 import pymonkey
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	10
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	11 This module offers a low-level interface to the `Mozilla SpiderMonkey
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	12 <https://developer.mozilla.org/en/SpiderMonkey>`_ JavaScript engine.
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	13
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	14 .. exception:: error
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	15
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	16 This is the type of any SpiderMonkey-related errors thrown by this
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	17 module.
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	18
54 234fca1c4b86 Added docs for pymonkey.undefined. Atul Varma <varmaa@toolness.com> parents: 53 diff changeset	19 .. data:: undefined
234fca1c4b86 Added docs for pymonkey.undefined. Atul Varma <varmaa@toolness.com> parents: 53 diff changeset	20
234fca1c4b86 Added docs for pymonkey.undefined. Atul Varma <varmaa@toolness.com> parents: 53 diff changeset	21 This is the singleton that represents the JavaScript value
234fca1c4b86 Added docs for pymonkey.undefined. Atul Varma <varmaa@toolness.com> parents: 53 diff changeset	22 ``undefined``, as Python has no equivalent representation
234fca1c4b86 Added docs for pymonkey.undefined. Atul Varma <varmaa@toolness.com> parents: 53 diff changeset	23 (JavaScript's ``null`` is mapped to Python's ``None`` object).
234fca1c4b86 Added docs for pymonkey.undefined. Atul Varma <varmaa@toolness.com> parents: 53 diff changeset	24 For instance:
234fca1c4b86 Added docs for pymonkey.undefined. Atul Varma <varmaa@toolness.com> parents: 53 diff changeset	25
234fca1c4b86 Added docs for pymonkey.undefined. Atul Varma <varmaa@toolness.com> parents: 53 diff changeset	26 >>> cx = pymonkey.Runtime().new_context()
56 72e84bd75905 Made another doctest easier to read. Atul Varma <varmaa@toolness.com> parents: 55 diff changeset	27 >>> cx.evaluate_script(cx.new_object(), '', '<string>', 1)
57 a2b617731398 pymonkey.undefined now has a 'falsy' value. Atul Varma <varmaa@toolness.com> parents: 56 diff changeset	28 pymonkey.undefined
54 234fca1c4b86 Added docs for pymonkey.undefined. Atul Varma <varmaa@toolness.com> parents: 53 diff changeset	29
57 a2b617731398 pymonkey.undefined now has a 'falsy' value. Atul Varma <varmaa@toolness.com> parents: 56 diff changeset	30 This object also has a "falsy" value:
54 234fca1c4b86 Added docs for pymonkey.undefined. Atul Varma <varmaa@toolness.com> parents: 53 diff changeset	31
57 a2b617731398 pymonkey.undefined now has a 'falsy' value. Atul Varma <varmaa@toolness.com> parents: 56 diff changeset	32 >>> if not pymonkey.undefined:
a2b617731398 pymonkey.undefined now has a 'falsy' value. Atul Varma <varmaa@toolness.com> parents: 56 diff changeset	33 ... print "See, it's falsy!"
a2b617731398 pymonkey.undefined now has a 'falsy' value. Atul Varma <varmaa@toolness.com> parents: 56 diff changeset	34 See, it's falsy!
54 234fca1c4b86 Added docs for pymonkey.undefined. Atul Varma <varmaa@toolness.com> parents: 53 diff changeset	35
53 2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	36 .. class:: Object
2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	37
2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	38 This is the type of JavaScript objects. Such objects can only be
2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	39 created via Pymonkey calls like :meth:`Context.new_object()` or
2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	40 through the execution of JS code, but this type object can be used
2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	41 with Python's built-in :func:`isinstance()` to verify that an
2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	42 object is a JS object, like so:
2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	43
2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	44 >>> obj = pymonkey.Runtime().new_context().new_object()
2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	45 >>> isinstance(obj, pymonkey.Object)
2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	46 True
2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	47
78 c48b393f6461 Added docs for Object.get_runtime(). Atul Varma <varmaa@toolness.com> parents: 58 diff changeset	48 .. method:: get_runtime()
c48b393f6461 Added docs for Object.get_runtime(). Atul Varma <varmaa@toolness.com> parents: 58 diff changeset	49
c48b393f6461 Added docs for Object.get_runtime(). Atul Varma <varmaa@toolness.com> parents: 58 diff changeset	50 Returns the :class:`Runtime` that the object belongs to.
c48b393f6461 Added docs for Object.get_runtime(). Atul Varma <varmaa@toolness.com> parents: 58 diff changeset	51
85 e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	52 .. class:: Function
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	53
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	54 This is the type of JavaScript functions, which is a subtype of
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	55 :class:`Object`.
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	56
51 fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	57 .. class:: Context
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	58
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	59 This is the type of JavaScript context objects. Contexts can only
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	60 be created via a call to :meth:`Runtime.new_context()`, but this
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	61 type object can be used with Python's built-in :func:`isinstance()`
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	62 to verify that an object is a context, like so:
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	63
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	64 >>> cx = pymonkey.Runtime().new_context()
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	65 >>> isinstance(cx, pymonkey.Context)
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	66 True
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	67
58 7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	68 .. method:: get_runtime()
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	69
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	70 Returns the :class:`Runtime` that the context belongs to.
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	71
79 228a56e7e793 Added docs for context.get_object_private(). Atul Varma <varmaa@toolness.com> parents: 78 diff changeset	72 .. method:: new_object([private_obj])
228a56e7e793 Added docs for context.get_object_private(). Atul Varma <varmaa@toolness.com> parents: 78 diff changeset	73
228a56e7e793 Added docs for context.get_object_private(). Atul Varma <varmaa@toolness.com> parents: 78 diff changeset	74 Creates a new :class:`Object` instance and returns
228a56e7e793 Added docs for context.get_object_private(). Atul Varma <varmaa@toolness.com> parents: 78 diff changeset	75 it. ``private_obj`` is any Python object that is privately
228a56e7e793 Added docs for context.get_object_private(). Atul Varma <varmaa@toolness.com> parents: 78 diff changeset	76 stored within the new JS object; it can be retrieved using
80 4945e4073110 Fixed typos in docs. Atul Varma <varmaa@toolness.com> parents: 79 diff changeset	77 :meth:`get_object_private()`.
58 7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	78
85 e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	79 .. method:: new_function(callable, name)
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	80
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	81 Creates a new :class:`Function` instance that wraps the
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	82 given Python callable. In JS-land, the callable will
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	83 have the given name.
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	84
79 228a56e7e793 Added docs for context.get_object_private(). Atul Varma <varmaa@toolness.com> parents: 78 diff changeset	85 .. method:: get_object_private(object)
228a56e7e793 Added docs for context.get_object_private(). Atul Varma <varmaa@toolness.com> parents: 78 diff changeset	86
80 4945e4073110 Fixed typos in docs. Atul Varma <varmaa@toolness.com> parents: 79 diff changeset	87 Returns the ``private_obj`` passed to :meth:`new_object()`
79 228a56e7e793 Added docs for context.get_object_private(). Atul Varma <varmaa@toolness.com> parents: 78 diff changeset	88 when `object` was first created. If it doesn't exist, ``None``
228a56e7e793 Added docs for context.get_object_private(). Atul Varma <varmaa@toolness.com> parents: 78 diff changeset	89 is returned.
228a56e7e793 Added docs for context.get_object_private(). Atul Varma <varmaa@toolness.com> parents: 78 diff changeset	90
85 e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	91 If `object` was created with :meth:`new_function()`, then this
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	92 method returns the Python callable wrapped by `object`.
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	93
79 228a56e7e793 Added docs for context.get_object_private(). Atul Varma <varmaa@toolness.com> parents: 78 diff changeset	94 This functionality is useful if you want to represent Python
228a56e7e793 Added docs for context.get_object_private(). Atul Varma <varmaa@toolness.com> parents: 78 diff changeset	95 objects in JS-land.
58 7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	96
85 e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	97 .. method:: clear_object_private(object)
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	98
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	99 Clears the ``private_obj`` passed to :meth:`new_object()`
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	100 when `object` was first created. If it doesn't exist, this
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	101 function returns nothing.
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	102
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	103 If `object` was created with :meth:`new_function()`, then this
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	104 method effectively "unbinds" the Python callable wrapped by
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	105 `object`. If `object` is later called, an exception will be
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	106 raised.
e9f450d30c0e Added more documentation. Atul Varma <varmaa@toolness.com> parents: 80 diff changeset	107
58 7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	108 .. method:: init_standard_classes(object)
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	109
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	110 Defines the standard JavaScript classes on the given
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	111 :class:`Object`, such as ``Array``, ``eval``, ``undefined``, and
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	112 so forth. For more information, see the documentation to
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	113 `JS_InitStandardClasses()
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	114 <https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JS_InitStandardClasses>`_,
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	115 which this method wraps.
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes(). Atul Varma <varmaa@toolness.com> parents: 57 diff changeset	116
51 fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	117 .. class:: Runtime()
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	118
53 2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	119 Creates a new JavaScript runtime. JS objects created by the runtime
2055d853b995 Added docs for pymonkey.Object. Atul Varma <varmaa@toolness.com> parents: 51 diff changeset	120 may only interact with other JS objects of the same runtime.
51 fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	121
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	122 .. method:: new_context()
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	123
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	124 Creates a new Context object and returns it. Contexts are best
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	125 conceptualized as threads of execution in a JS runtme; each one
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	126 has a program counter, a current exception state, and so
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	127 forth. JS objects may be freely accessed and changed by contexts
fabd3f2271fa Added some basic, incomplete docs on the pymonkey module, which include a doctest that's run when pymonkey is built. Atul Varma <varmaa@toolness.com> parents: diff changeset	128 that are associated with the same JS runtime as the objects.

Mercurial > pymonkey

annotate docs/src/pymonkey.txt @ 85:e9f450d30c0e