
################################################################################
this is a pure python3.0 module.
pseudomethod is an extended language feature for python3.0.
it adds the ".." notation for calling regular functions as methods.
this allows u to extend any class or object on-the-fly w/o subclassing
& enhances python's functional programming ability.
pseudomethods r liberally used in the py3to2 application img2txt

a method is normally called by the "." notation:

  class Foo:
    def method(*args, **kwds):
      ...
  Foo().method(*args, **kwds)

pseudomethod allows u to call normal functions on-the-fly as methods
using the ".." notation:

  def function(self, *args, **kwds):
    ...
  class Foo: pass
  Foo()..function(*args, **kwds) # function temporarily bound to Foo

the only requirement for a function to b a pseudomethod is that it must accept
@ least one argument, which is the "self" object its passed to b a method of.

what actually happens is just simple rearrangement of symbols:

  a..b(*args, **kwds)  <==>  b(a, *args, **kwds)
  a..b()..c()..d()     <==>  d( c( b( a ) ) )

in this respect, the ".." notation could b thought of as a "flattener",
removing nesting of the 1st argument, & allowing an elegant style of
functional programming in python

for a real-world application using pseudomethod, check out the py3to2
application img2txt @:

  http://pypi.python.org/pypi/img2txt/

AUTHOR:
  kai zhu
  kaizhu@ugcs.caltech.edu

REQUIREMENTS:
- python3.0 or higher
- for python2.6, see py3to2 (which has pseudomethods enabled by default)

INSTALL:
  python3.0 setup.py install

API:
  type "help(pseudomethod)" for more details
  pseudomethod module:
  - parser - string & ast parser for pseudomethod syntax
  - importer - import hook for handling scripts containing pseudomethod
               syntax

MAGIC
  1 pseudomethod 1st initializes an import hook
  2 add the MAGIC LINE:

      from __future__ import pseudomethod

    to ur script & the import hook will take care of the rest

USAGE:
  start up the python3.0 interpreter & import pseudomethod:
    $ python3.0

    Python 3.0rc2 (r30rc2:67114, Nov  9 2008, 21:30:06)
    [GCC 3.4.6 20060404 (Red Hat 3.4.6-10)] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>>
    >>> import pseudomethod

  try out this simple pseudomethod script:
    ################################################################
    # copy this to file pseudomethod1.py
    from __future__ import pseudomethod

    def add_to_self(self, x): return self + x

    print(
      "ab"             ..add_to_self ( "c"  ),
      bytearray(b"ab") ..add_to_self ( b"c" ),
      1                ..add_to_self ( 2    ),
      [1, 2]           ..add_to_self ( [3]  ),
      )
    ################################################################
    >>>
    >>> import pseudomethod1
    abc bytearray(b'abc') 3 [1, 2, 3]

  for functional-style programming,
  pseudomethods are quite useful for cleaning up ugly nested arguments:
    ################################################################
    # copy this to file pseudomethod2.py
    from __future__ import pseudomethod

    print(
      list(zip(sorted([(2,3), (0,4), (1,5)], key = lambda x: x[0])\
               , range(2, 5))) # ugly, Ugly, UGLY !!!
      )

    print(
      [(2,3), (0,4), (1,5)] ..sorted(key = lambda x: x[0])\
                            ..zip(range(2, 5)) ..list() # elegant ^_^
    )
    ################################################################
    >>>
    >>> import pseudomethod2
    [((0, 4), 2), ((1, 5), 3), ((2, 3), 4)]
    [((0, 4), 2), ((1, 5), 3), ((2, 3), 4)]
    >>>

################################################################################
MECHANISM:
  1 this module installs an import hook to detect if a script contains the
    MAGIC LINE:
      from __future__ import pseudomethod
  2 the script is preparsed, replacing the ".." notation w/ ".__pseudomethod__."
    to keep the python parser happy
  3 the script is compiled into an ast object.  the ast is recursively searched
    for the attribute "__pseudomethod__" were some symbol rearrangement occurs.

RECENT CHANGELOG:
20081121 created pseudomethod package
