Inching towards release.

Troy Melhase · Troy Melhase · commit 2853dfb47275 · 2011-10-24T18:13:39.000Z
diff --git a/bin/j2py b/bin/j2py
@@ -1,6 +1,11 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+""" j2py -> Java to Python compiler script.
 
+This is all very ordinary.  We import the package bits, open and read
+a file, translate it, and write it out.
+
+"""
 import sys
 from collections import defaultdict
 from logging import _levelNames as logLevels, exception, warning, info, basicConfig
@@ -17,15 +22,18 @@ version = '0.5'
 
 
 def isWindows():
+    """ True if running on Windows. """
     return sys.platform.startswith('win')
 
 
 def badLogLevel(name, value):
+    """ Raise an error indicating a bad log level. """
     msg = 'option %s: invalid loglevel: %r'
     raise OptionValueError(msg % (name, value))
 
 
 def checkLogLevel(option, opt, value):
+    """ Option type checker (see LocalOption class) to verify a log level. """
     try:
         lvl = int(value)
     except (ValueError, ):
@@ -40,12 +48,14 @@ def checkLogLevel(option, opt, value):
 
 
 class LocalOption(Option):
+    """ Supplements the Option class with our log level checker. """
     TYPES = Option.TYPES + ('loglevel', )
     TYPE_CHECKER = Option.TYPE_CHECKER.copy()
     TYPE_CHECKER['loglevel'] = checkLogLevel
 
 
-def mainProfile(options):
+def profileMain(options):
+    """ Runs our main function with profiling if indicated by options. """
     if options.profile:
 	import cProfile, pstats
 	prof = cProfile.Profile()
@@ -59,11 +69,13 @@ def mainProfile(options):
 
 
 def configFromDir(inname, dirname):
+    """ Returns a file name from the given config directory. """
     name = path.join(dirname, path.basename(path.splitext(inname)[0]))
     return '%s.py' % path.abspath(name)
 
 
 def main(options):
+    """ Compile the indicated java source with the given options. """
     timed = defaultdict(time)
     timed['overall']
 
@@ -155,6 +167,7 @@ def main(options):
 
 
 def config(argv):
+    """ Return an options object from the given argument sequence. """
     parser = OptionParser(option_class=LocalOption, version='%prog '+version)
     addopt = parser.add_option
     addopt('-i', '--input', dest='inputfile',
@@ -215,4 +228,4 @@ def config(argv):
 
 
 if __name__ == '__main__':
-    sys.exit(mainProfile(config(sys.argv)))
+    sys.exit(profileMain(config(sys.argv)))
diff --git a/doc/conf.py b/doc/conf.py
@@ -16,7 +16,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -25,7 +25,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.todo', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc', ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -41,7 +41,7 @@
 
 # General information about the project.
 project = u'java2python'
-copyright = u'2010, Troy Melhase'
+copyright = u'2011, Troy Melhase'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
diff --git a/doc/glossary.rst b/doc/glossary.rst
@@ -0,0 +1,26 @@
+.. _glossary:
+
+********
+Glossary
+********
+
+
+.. glossary::
+
+  ANTLR
+    `ANother Tool for Language Recognition`_, the language tool used by
+    this package to parse Java source code.
+
+  AST
+    Abstract Syntax Tree
+
+  Block
+    A class that combines an AST visitor and template generator.
+
+  Template
+    A class that can serialize a block to Python source.
+
+  Visitor
+    A class that accepts AST nodes and generates code via templating.
+
+.. _ANother Tool for Language Recognition: http://www.antlr.org/
diff --git a/doc/index.rst b/doc/index.rst
@@ -25,6 +25,7 @@ Contents:
    usage.rst
    features.rst
    customization.rst
+   glossary.rst
 
 
 Indices and tables
@@ -33,4 +34,5 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+* :ref:`glossary`
 
diff --git a/doc/intro.rst b/doc/intro.rst
@@ -10,7 +10,7 @@ What it Does
 |j2py| reads the Java source files you give it and produces
 somewhat-roughly-equivalent Python source code.  It tries to make the
 same decisions you would if you were porting the code manually.  It
-can perform the translation faster and more accuratly than you could,
+can perform the translation faster and more accurately than you could,
 because it's a dumb machine that does what its told and you're a smart
 person with lots of books you haven't read and a love of chocolate so
 sometimes you're easily distracted and make mistakes.  Like me and
@@ -41,8 +41,8 @@ How it Works
 
 |j2py| first converts the source code you give it into an abstract
 syntax tree.  (That's a lie, really.  |j2py| doesn't do this step,
-Antlr does this step, and Antlr is a whole lot bigger and cooler than
-|j2py| could ever be.  Obviously, really smart people worked on Antlr
+ANTLR does this step, and ANTLR is a whole lot bigger and cooler than
+|j2py| could ever be.  Obviously, really smart people worked on ANTLR
 and only one fairly dim one worked on |j2py|).
 
 After the syntax tree is constructed, it's walked and its nodes are
@@ -63,16 +63,16 @@ of Java source code that you can't make into nice and neat and obvious
 Python equivalents.
 
 To get around these trouble spots, |j2py| takes one of two approaches
-(and sometimes both if she's feeling especially fiesty or if you
+(and sometimes both if she's feeling especially feisty or if you
 haven't paid her much attention lately).  The first approach is to try
 and make the problem go away.  For example, in Java the `if` statement
-can contain an assigment expression::
+can contain an assignment expression::
 
     if (++x == 0) { ... }
 
-There isn't a single statement equivalent in Python because assigments
+There isn't a single statement equivalent in Python because assignments
 are statements there, not expressions.  So |j2py| does what it can,
-presuably what you would do::
+presumably what you would do::
 
     x += 1
     if x == 0:
@@ -82,7 +82,7 @@ Careful readers will have spotted just how close we came to driving
 over a cliff with that `++x` expression.  If the increment had been
 done on the other side of the variable, the meaning of the statement
 would have changed and the Python code would have been wrong.
-Fortuatly, I've driven by lots of cliffs and have been scared by all
+Fortunately, I've driven by lots of cliffs and have been scared by all
 of them so I thought of this ahead of time and decided to do something
 about it::
 
@@ -96,7 +96,7 @@ will get translated to::
         ...
 
 See what |j2py| did there?  It tried to do what you would do.  For
-further explaination and enumeration see the :ref:`features` chapter.
+further explanation and enumeration see the :ref:`features` chapter.
 
 
 Why Bother?
diff --git a/java2python/compiler/template.py b/java2python/compiler/template.py
@@ -426,6 +426,8 @@ def sprinkleBlanks(body):
 			yield blank
 		yield item
 		prev = item
+        for handler in self.configHandlers('PostWalk'):
+            handler(self)
 	head = any(self.iterHead())
 	body = list(super(Class, self).iterBody())
 	tail = () if (body or head) else [self.factory.expr(left='pass')]
diff --git a/java2python/config/__init__.py b/java2python/config/__init__.py
@@ -1,29 +1,32 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+""" java2python.config -> subpackage for run-time configuration. """
+
 from functools import reduce
 from imp import load_source
 from os import path
 
 
 class Config(object):
-    """ Config -> wraps multiple configuration modules
+    """ Config -> wraps multiple configuration modules """
 
-    """
     def __init__(self, names):
 	self.configs = [self.load(name) for name in names]
 
     def every(self, key, default=None):
+        """ Returns the value at the given key from each config module. """
 	return [getattr(config, key, default) for config in self.configs]
 
     def last(self, key, default=None):
+        """ Returns the value at the given key from the last config module to define it. """
 	for config in reversed(self.configs):
 	    if hasattr(config, key):
 		return getattr(config, key)
 	return default
 
     @staticmethod
     def load(name):
-	""" import and return a module from dotted form or filename. """
+	""" Imports and returns a module from dotted form or filename. """
 	if path.exists(name):
 	    mod = load_source(str(hash(name)), name)
 	else:
diff --git a/java2python/config/default.py b/java2python/config/default.py
@@ -52,7 +52,7 @@
 # These generators are called after a class has been completely
 # generated; this specific one sorts method bodies by name.
 # NB:  the code generator doesn't actually use this.
-classPostWalkMutators = [
+classPostWalkHandlers = [
     basic.classContentSort,
 ]
 
diff --git a/java2python/lang/selector.py b/java2python/lang/selector.py
diff --git a/java2python/mod/basic.py b/java2python/mod/basic.py
diff --git a/java2python/mod/transform.py b/java2python/mod/transform.py
diff --git a/test/selector/test_all.py b/test/selector/test_all.py

Original file line number	Diff line number	Diff line change
`@@ -52,7 +52,7 @@`
`52`	`52`	`# These generators are called after a class has been completely`
`53`	`53`	`# generated; this specific one sorts method bodies by name.`
`54`	`54`	`# NB: the code generator doesn't actually use this.`
`55`		`-classPostWalkMutators = [`
	`55`	`+classPostWalkHandlers = [`
`56`	`56`	`basic.classContentSort,`
`57`	`57`	`]`
`58`	`58`