JSweet candy generator
This tool is a helper to create candies (Java APIs) from TypeScript definition files.
Description
This tools consumes TypeScript definition files and produces the corresponding Java APIs, conforming to the JSweet core API (see the jsweet-core sub-project).
It comes with a command that generates a default JSweet candy Maven project, which you can publish and share with other projects.
Usage
All commands must be executed in the project's directory
Prerequisite: build the project (see the How to build section).
Initialize a candy project using the init-project command
The init-project command generates a default Maven project with all the appropriate configuration, so that you can place your candy Java API in this project later on. Optionally, you can ask the tool to create and publish the project on Github, assuming that you are part of the jsweet-candies organization (please contact us to become a member).
For example, the following command creates and publishes to Github a default (empty) candy project on Github for jquery-1.10.0-SNAPSHOT.
$ java -jar target/candy-tool.jar init-project --artifactId=jquery --version=1.10.0-SNAPSHOT -o ../candies --createGitHubRepository=true --gitHubUser=lgrignon
The created project's directory is candy-jquery and is placed in the ../candies directory, as specified with the -o option. If you specify the createGitHubRepository option, an empty Github repository with a default name and description will be created in the jsweet-candies organization. Please contact us to get authorized.
You can create a candy project with dependencies to other projects. For example, the following command creates a project for jqueryui-1.11.0-SNAPSHOT, which depends on the jquery-1.10.0-SNAPSHOT candy.
$ java -jar target/candy-tool.jar init-project --artifactId=jqueryui --version=1.11.0-SNAPSHOT --deps=jquery:1.10.0-SNAPSHOT -o ../candies
Generate the candy's Java sources from TypeScript using the generate-sources command
The generate-sources command parses the given TypeScript definition file and translates it to a Java API (*.java files). You don't need to have an initialized project to run this command. Note that TypeScript definitions can be easily fetched with external tools such as typings or npm.
$ java -jar target/candy-tool.jar generate-sources --name=jquery --tsFiles=typings/globals/jquery/index.d.ts -o ../candies/candy-jquery/src/main/java
When a TypeScript definition depends on another definition, should shall specify it as a dependency:
$ java -jar target/candy-tool.jar generate-sources --name=jqueryui --tsFiles=typings/jqueryui/index.d.ts --tsDeps=typings/jquery/index.d.ts -o ../candies/candy-jqueryui/src/main/java
Note that you can specify multiple definition files in the tsFiles and tsDeps options, as comma-separated lists.
Push your candy to a remote Github repository
Go to your candy's project directory (here candy-jquery).
$ git init
$ git add .
$ git commit -m "Initial commit"
$ git remote add origin https://github.com/jsweet-candies/candy-jquery.git
$ git push origin master
Compile/Package/Install/Deploy your candy
Go to your candy's project directory.
$ mvn install
Or, if you have the deployment authorization:
$ mvn deploy
By default, candies will be deployed to jsweet-candies, contact us if you want to share your candies with the community.
IMPORTANT: The candy generation tool is in "best effort" mode, which means that it will try to generate Java code out of the TypeScript definitions even when meeting unsupported cases. There are known limitations to the tool because TypeScript is a language that is evolving quite fast (especially, you should avoid complex module constructs in TypeScript definitions). If you hit errors while installing your candy, you must first open the project with your favorite IDE and fix the Java compilation errors manually. Please refer to the documentation and to existing candies to write valid definitions.
How to build
In the candy-generator's directory, generate TypeScript parser from syntax files (CUP/JFlex):
$ mvn generate-sources -P genparser
Then build the entire project:
$ mvn clean package
Optionally, if you need to re-package the Jar file used to run the tool.
$ mvn clean compile assembly:single
License
This tool's source code is licensed under GPL, which in short means that you can use is as is to generate any kinds of APIs (including closed-source commercial ones). You can also use/modify this tool's source code in any open source project (commercial or not), as long as you conform to the license terms (see the license file). On the other hand, your cannot embed this tool's source code in a closed-source commercial project. In case you would want to do so, you must contact Renaud Pawlak (renaud.pawlak@gmail.com), who can grant you a commercial license depending on your use case.