:mod:`jynx.lib.javaparser` -- Java parser for Jython
====================================================

.. module:: lib.javaparser
    :synopsis: Defines wrapper for Java parser package.

.. index:: pair: automatic; documentation
           single: docstring

A `java parser <http://code.google.com/p/javaparser/>`_ is used by Jynx. A Java parser was
necessary to acquire used type declarations in Java classes and those determined single-named
imports in generated Java code.

functions
---------

.. function:: parse(string) - > AST

    The parse function keeps a string argument and produces an AST which corresponds to the ``CompilationUnit``
    AST node.


Information extraction
----------------------

Information extraction from AST nodes is visitor based. A typical visitor looks like this ::

    @JavaClass
    class TypeVisitor(VoidVisitorAdapter):
        nodes = jproperty("Vector", initializer = "new Vector()")

        @signature("public Vector _()")
        def getNodes(self):
            return self.nodes

        @Override
        @signature("public void _(ReferenceType, Object)", overload = True)
        def visit(self, n, arg):
            self.nodes.add(n)

        @Override
        @signature("public void visit(TypeParameter, Object)", overload = True)
        def visit(self, n, arg):
            self.nodes.add(n)

        ....

Notice the user of method overloading.


Known issues
------------

I observed problems ( ``RuntimeError`` exceptions to be precise ) when calling ``super`` in a ``visit``
method ::

    @JavaClass
    class MyVisistor(VoidVisitorAdapter):

        def visit(self, n, arg):
            super(MyVisitor, self).visit(n, arg)
            ...

In some cases the problem can be removed by moving back to explicit super-class calls ::

    @JavaClass
    class MyVisistor(VoidVisitorAdapter):

        def visit(self, n, arg):
            VoidVisitorAdapter.visit(self, n, arg)
            ...

However, even this won't prevent all recursion errors.