Mercurial > pymonkey

annotate docs/src/pymonkey.txt @ 80:4945e4073110

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fixed typos in docs.
author Atul Varma <varmaa@toolness.com>
date Fri, 07 Aug 2009 18:59:10 -0700
parents 228a56e7e793
children e9f450d30c0e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
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
52 .. 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
53
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
54 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
55 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
56 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
57 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
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 >>> 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
60 >>> 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
61 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
62
58
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes().
Atul Varma <varmaa@toolness.com>
parents: 57
diff changeset
63 .. 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
64
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes().
Atul Varma <varmaa@toolness.com>
parents: 57
diff changeset
65 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
66
79
228a56e7e793 Added docs for context.get_object_private().
Atul Varma <varmaa@toolness.com>
parents: 78
diff changeset
67 .. method:: new_object([private_obj])
228a56e7e793 Added docs for context.get_object_private().
Atul Varma <varmaa@toolness.com>
parents: 78
diff changeset
68
228a56e7e793 Added docs for context.get_object_private().
Atul Varma <varmaa@toolness.com>
parents: 78
diff changeset
69 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
70 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
71 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
72 :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
73
79
228a56e7e793 Added docs for context.get_object_private().
Atul Varma <varmaa@toolness.com>
parents: 78
diff changeset
74 .. method:: get_object_private(object)
228a56e7e793 Added docs for context.get_object_private().
Atul Varma <varmaa@toolness.com>
parents: 78
diff changeset
75
80
4945e4073110 Fixed typos in docs.
Atul Varma <varmaa@toolness.com>
parents: 79
diff changeset
76 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
77 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
78 is returned.
228a56e7e793 Added docs for context.get_object_private().
Atul Varma <varmaa@toolness.com>
parents: 78
diff changeset
79
228a56e7e793 Added docs for context.get_object_private().
Atul Varma <varmaa@toolness.com>
parents: 78
diff changeset
80 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
81 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
82
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes().
Atul Varma <varmaa@toolness.com>
parents: 57
diff changeset
83 .. 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
84
7a3461ccaf1d Added documentation for Context methods get_runtime(), new_object(), and init_standard_classes().
Atul Varma <varmaa@toolness.com>
parents: 57
diff changeset
85 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
86 :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
87 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
88 `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
89 <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
90 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
91
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
92 .. 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
93
53
2055d853b995 Added docs for pymonkey.Object.
Atul Varma <varmaa@toolness.com>
parents: 51
diff changeset
94 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
95 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
96
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
97 .. 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
98
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
99 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
100 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
101 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
102 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
103 that are associated with the same JS runtime as the objects.