Documentation

[tomitrescak]

Hi, I am extremely interestedin using your project. Is there any documentation on how to use it? Mainly I miss the XML files that you use somehow to configure your compiler.

I even tried your visual tool, but I'm not sure what is the role of csproj files in there.

Thanks!

[EDIT]: Playing around with your code I managed to create tokens out of JAVA class, but am stuck with typescript transpilation because I do not have XML files needed. Following is the code I created to transpile a singe file which fails during transpilation as it is missing Java decription files:

            var tokens = GetParsedResultFromFile(args[0]);

            var sourceFiles = new Dictionary<string, IList<IAstNode>>();
            sourceFiles.Add("file", tokens);

            var compiled = TypeScriptCompiler.Compile(sourceFiles, "file");

[JonathanLydall]

Unfortunately there is no documentation, it is bare minimum implementation which only barely served my needs.

Be aware that it is known to fail on certain Java source files, it will quite possibly not work for all your needs. I am a large way through a re-write which is far more robust. But it's been on hold for a while and I don't know when I may be able to finish.

The transpiler only supports taking Java code and converting it to TypeScript code. Familiarity with C# is essential at this point if you want to try use it as there is no documentation. In theory you could emit your own language from the AST I extract, but I don't think the AST is necessarily detailed enough.

The transpiler uses a convention of one XML file per Java file you wish to transpile. The easiest way to create these XML files is using the "TranspilerUtils" solution. This provides a GUI with which to make new files.

Right now the file paths are hardcoded in TranspilerUtils in App.xaml.cs at the top of the file.

• DEFAULT_XML_FILE_PATH can point to any valid folder on your hard drive.
• DEFAULT_JAVA_FILE_PATH is the path containing the source .java files. I don't think it supports subfolders.
• DEFAULT_TRANSPILER_PATH is where the built Transpiler.exe can be found.

The PROJECT file paths are passed to the transpiler which it uses to conveniently add emitted typescript files to .csproj of the TypeScript project which uses the transpiled code.

Once the "TranspilerUtils" tool is working, it will list each Java file with a "New" button next to it. For each Java file, you can tell it how to handle different methods and fields for the class.

For my use case of the tool, I was taking a computer game's source code and only wanted to take certain bits, namely the logic of a simulation engine inside of it, this meant that on a class by class basis I wanted the transpiler to skip over certain methods/fields, and for others they may have needed to be overridden with a custom implementation in a derived class.

If you just click "New" for a Java file, it by default will try transpile everything. Once the new button is pushed, it changes to a combo box. This combo box gives the options to:

• "Compile"
• "Ignore" (equivalent to deleting the .XML file generated for that class, but has the benefit of keeping other settings in the XML file)
• "Parse Only", this is used to harvest "Types" from the file. I can't recall exactly how it works, but the transpiler uses "known types" to help it understand what are classes or methods, or something like that.

For each Java file, you can also customize what the transpiler does for each method by clicking the "Methods" tab in the right pane. In the name column, type the method name in the class (it is case sensitive) and choose an "Action" for the file:

• "Compile": The transpiler just transpiles the method as is.
• "Exclude": The transpiler won't include the method at all in the emitted TypeScript file.
• "Exclude (And in derived classes)": Much like exclude, but for other Java classes which derive from this file, the method is excluded as well.
• "Exclude (Body only)": Only a stub of the method is transpiled. This was useful for me for when other methods in the game would call a method like "draw", which was non-applicable to me.
• "Extend": If set for any of the methods in the file, the class name emitted changes to have a "_NeedsExtension" on the end, and it is up to you to make a typescript class which is derived from the transpiler generated class. This is useful if you need to change the body of that method, the base class is generated, but it does not interfere with your custom code. "Dependancies": (at the bottom of the tab), with this you can add dependant methods, I can't recall exactly how these work, but I think it would force those other methods to be compiled as well.

For each java file, you can also do something similar to methods on the field tab, the actions are self explanatory except for "Compile with delayed initialisation". This is made to solve a problem with the difference between TypeScript and Java and what they support in terms of initialisation of static variable values. Consider you have a scenario where a class has a static field which is an instance of itself, you can't instantiate it in JavaScript/TypeScript until the class is finished loading, but the class wants to instantiate it as it's still making the class. So my solution is to delay instantiation of the of the field until all classes are loaded.

That's about as much as I am willing to write tonight, I hope it helps you at least a little, and if nothing else allows you to assess it's usefulness in its current form.