= Java to Python (j2p)

This tool can translate java programs into python programs.
This is a complex mechanism and still experimental/in development. This documentation is very incomplete. This code is not yet published on the artifactory.

Some features:
* both single-file as multi-file projects
* translates calls to external libraries
* pluggable translators supporting calls to external liraries
* can generate pip-installable zip file
* Another tool [https://tracinsy.ewi.tudelft.nl/pubtrac/Utilities/wiki/pyrunner library] supports running these python zip files from java.

The repo contains the translator in the module named "core". The other modules, ending with "-t", are translator plug-ins described below.

== Internal mechanism
There are two main components in the core:
1. The translator that parses java code and creates equivalent python code
2. per-java-class translators that know how to translate a specific call to a java class function or field into equivalent python code. 

The first is generic and used for all java programs. It is currently pretty complete but details will be filled in over time as the need arises to support more java syntax.

The second is currently very partial. The reason is that there are a huge number of java classes, and every field and function in it will need a specialized translator. This will grow slowly over time as needed.


== Usage

== Overriding the translation
Comments can contain python code to override the automatic code, if the block starts with {{{#PY}}}. This code replaces the entire object (if/case/while block; statement) that follows the comment.

Python has strict requirements regarding indentation. To make this possible, we need to be strict about indentation as well. In a single line python comment, the code must look exactly like

{{{
 //#PY single_python_line 
}}}

  Note the single whitespace after the #PY. Your code starts after this single whitespace.

 In a multi line comment the code must look exactly like
{{{
/*#PY
 * codeline1
 * codeline2
 * ...
 */
}}}

Your code lines each start with "* ", note the whitespace after the star. You are free to indent before the "*".

Your code is automatically indented to the level needed at the insertion place in the code.

Code must be placed in either a standard block comment or a single line
comment. Starting a javadoc with {{{#PY}}} is not
allowed. This is to encourage proper use of javadoc.
 
  A comment block overrides also annotations.

 If the code block contains no code at all, it is translated as
 {{{pass}}}, to ensure that the code is a proper statement.


== Translation modules
J2P has a modular translation mechanism. A translation module can be created separately and plugged in as needed, to add support for translating libraries. Also this allows to change the translation process, for instance to use another python library for the translation.

A number of translation modules are already available

||=module=||=what it translates=||=details=||=limitations=||
||jackson-t||jackson serialization annotations||translates jackson to pyson annotations that look very similar to jackson||Covers what we need for translation of GeniusWeb||
||junit-t||junit calls assertTrue,assertEquals|| ||Very limited, no support yet for junit annotations||
||tudutils-t||translates calls to [https://tracinsy.ewi.tudelft.nl/pubtrac/Utilities/wiki/utilities utilities] package||limited, currently mainly to support parts of immutablelist||



== Resulting file


== FAQs
||=Question=||=Explanation=||
||I'm getting "No translator found for X". But X is a class that I'm trying to translate||The java files you are trying to translate are probably not compiled by the java compiler. When the translator finds a method call, it needs the compiled java to determine the proper signature (function name and arguments). ||