Python Bytecode Assembler
=========================

This is a simple assembler that handles most low-level bytecode details like
jump offsets, stack size tracking, line number table generation, constant and
variable name index tracking, etc.  That way, you can focus your attention on
on the desired semantics of your bytecode instead of on these mechanical
issues.

Simple usage::

    >>> from peak.util.assembler import Code
    >>> c = Code()
    >>> c.LOAD_CONST(42)
    >>> c.RETURN_VALUE()

    >>> eval(c.code())
    42

    >>> from dis import dis
    >>> dis(c.code())
      0           0 LOAD_CONST               0 (42)
                  3 RETURN_VALUE

Labels and backpatching forward references::

    >>> c = Code()
    >>> ref = c.JUMP_ABSOLUTE()     # jump w/unspecified target
    >>> c.LOAD_CONST(1)
    >>> ref()                       # resolve the forward reference
    >>> c.RETURN_VALUE()
    >>> dis(c.code())
      0           0 JUMP_ABSOLUTE            6
                  3 LOAD_CONST               0 (1)
            >>    6 RETURN_VALUE


    >>> c = Code()
    >>> lbl = c.label()     # create a label at this point in the code
    >>> c.LOAD_CONST(1)
    >>> ref = c.JUMP_ABSOLUTE(lbl)  # and jump to it
    >>> dis(c.code())
      0     >>    0 LOAD_CONST               0 (1)
                  3 JUMP_ABSOLUTE            0


For more examples, see ``assembler.txt`` in the ``peak.util`` package
directory.  You can also use ``codeobject.set_lineno(number)`` to set the
current line number.

There are a few features that aren't tested yet, and not all opcodes may be
fully supported.  Notably, the following features are NOT reliably supported
yet:

* Closures and cell variables

* Wide jump addressing (for generated bytecode>64K in size)

* The computed stack effects of the ``MAKE_CLOSURE``, ``MAKE_FUNCTION``,
  ``END_FINALLY``, and ``POP_BLOCK`` opcodes may not be correct.

* Line number tables seem to have some problems under Python 2.3, although they
  work find in Python 2.4.  I don't yet know whether this is a problem with my
  code or with the ``dis`` module.

If you find any other issues, please let me know.

