:mod:`pymonkey` --- Access SpiderMonkey from Python
===================================================

.. module:: pymonkey
   :synopsis: Access SpiderMonkey from Python

.. testsetup:: *

   import pymonkey

This module offers a low-level interface to the `Mozilla SpiderMonkey
<https://developer.mozilla.org/en/SpiderMonkey>`_ JavaScript engine.

.. exception:: error

   This is the type of any SpiderMonkey-related errors thrown by this
   module.

.. data:: undefined

   This is the singleton that represents the JavaScript value
   ``undefined``, as Python has no equivalent representation
   (JavaScript's ``null`` is mapped to Python's ``None`` object).
   For instance:

     >>> cx = pymonkey.Runtime().new_context()
     >>> cx.evaluate_script(cx.new_object(), '', '<string>', 1)
     pymonkey.undefined

   This object also has a "falsy" value:

     >>> if not pymonkey.undefined:
     ...   print "See, it's falsy!"
     See, it's falsy!

.. class:: Object

   This is the type of JavaScript objects. Such objects can only be
   created via Pymonkey calls like :meth:`Context.new_object()` or
   through the execution of JS code, but this type object can be used
   with Python's built-in :func:`isinstance()` to verify that an
   object is a JS object, like so:

     >>> obj = pymonkey.Runtime().new_context().new_object()
     >>> isinstance(obj, pymonkey.Object)
     True

   .. method:: get_runtime()

      Returns the :class:`Runtime` that the object belongs to.

.. class:: Context

   This is the type of JavaScript context objects. Contexts can only
   be created via a call to :meth:`Runtime.new_context()`, but this
   type object can be used with Python's built-in :func:`isinstance()`
   to verify that an object is a context, like so:

     >>> cx = pymonkey.Runtime().new_context()
     >>> isinstance(cx, pymonkey.Context)
     True

   .. method:: get_runtime()

      Returns the :class:`Runtime` that the context belongs to.

   .. method:: new_object()

      Creates a new :class:`Object` instance and returns it.

   .. method:: init_standard_classes(object)

      Defines the standard JavaScript classes on the given
      :class:`Object`, such as ``Array``, ``eval``, ``undefined``, and
      so forth. For more information, see the documentation to
      `JS_InitStandardClasses()
      <https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JS_InitStandardClasses>`_,
      which this method wraps.

.. class:: Runtime()

   Creates a new JavaScript runtime. JS objects created by the runtime
   may only interact with other JS objects of the same runtime.

   .. method:: new_context()

      Creates a new Context object and returns it. Contexts are best
      conceptualized as threads of execution in a JS runtme; each one
      has a program counter, a current exception state, and so
      forth. JS objects may be freely accessed and changed by contexts
      that are associated with the same JS runtime as the objects.