mirror of
https://github.com/cincheo/jsweet.git
synced 2025-12-15 07:19:22 +00:00
documentation
This commit is contained in:
Renaud Pawlak
parent
26ec65ecf9
commit
3aa4ce34cf
@ -1,7 +1,7 @@
|
||||
JSweet Language Specifications
|
||||
==============================
|
||||
|
||||
Version: 1.1.x
|
||||
Version: 1.2.x (snapshot)
|
||||
|
||||
Author: Renaud Pawlak
|
||||
|
||||
@ -898,11 +898,60 @@ By convention, putting the classes in a `def.libname` package defines a set of d
|
||||
|
||||
Candies (bridges to external JavaScript libraries) use definitions. For instance, the jQuery candy defines all the jQuery API in the `def.jquery` package.
|
||||
|
||||
Here is a list of rules and constraints that need to be followed when writing definitions.
|
||||
|
||||
- The `def.libname` package must be annotated with a `@jsweet.lang.Root` (to be placed in a `package-info.java` file).
|
||||
|
||||
- Within a `def.*` package, `@Ambient` annotations are not required. By conventions all declarations are ambient.
|
||||
|
||||
- Interfaces are preferred over classes, because interfaces can be merged and classes can be instantiated. Classes should be used only if the API defines an explicit constructor (objects can be created with `new`). To define an interface in JSweet, just annotate a class with `@jsweet.lang.Interface`.
|
||||
|
||||
- Top-level functions and variables must be defined as `public static` members in a `Globals` class.
|
||||
|
||||
- All classes, interfaces and packages, should be documented with comments following the Javadoc standard.
|
||||
|
||||
- When several types are possible for a function parameter, method overloading should be preferred over using union types. When method overloading is not possible, it can be more convenient to simply use the `Object` type. It is less strongly typed but it is easier to use.
|
||||
|
||||
- One can use string types to provide function overloading depending on a string parameter value.
|
||||
|
||||
- In a method signature, optional parameters can be defined with the `@jsweet.lang.Optional` annotation.
|
||||
|
||||
- In an interface, optional fields can be defined with the `@jsweet.lang.Optional` annotation.
|
||||
|
||||
Definitions can be embedded directly in a JSweet project to access an external library in a typed way, of they can be packaged in a candy (a Maven artifact), so that they can be shared by other projects. See the *Packaging* section for full details on how to create a candy. Note that you do not need to write definitions when a library is written with JSweet because the Java API is directly accessible and the TypeScript definitions can be automatically generated by JSweet using the `declaration` option.
|
||||
|
||||
### Untyped accesses
|
||||
|
||||
Sometimes, definitions are not available or are not correct, and just a small patch is required to access a functionality. Programmers have to keep in mind that JSweet is just a syntactic layer and that it is always possible to bypass typing in order to access a field or a function that is not explicitly specified in an API.
|
||||
|
||||
In that cases, the use of `$get` allows reflective access to methods and properties that can then be cast to the right type. For accessing functions in an untyped way, one can cast to `jsweet.lang.Function` and call the generic and untyped method `apply` on it. Note also the use of the `jsweet.util.Globals.any` helper method, which can be extremely useful to erase typing. Since the `any` method generates a cast to the `any` type in TypeScript, it is more radical than a cast to `Object` for instance. The following example shows how to use the `any` method to cast an `Int32Array` to a Java `int[]` (and then allow direct indexed accesses to it.
|
||||
Although, having a well-typed API is the preferred and advised way, when such an API is not available, the use of `jsweet.lang.Object.$get` allows reflective access to methods and properties that can then be cast to the right type. For accessing functions in an untyped way, one can cast to `jsweet.lang.Function` and call the generic and untyped method `apply` on it. For example, here is how to invoke the jQuery `$` method when the jQuery API is not available :
|
||||
|
||||
``` java
|
||||
import jsweet.dom.Globals.window;
|
||||
[...]
|
||||
Function $ = (Function)window.$get("$");
|
||||
$.apply("aCssSelector"):
|
||||
```
|
||||
|
||||
The `$get` function is available on instances of `jsweet.lang.Object` (or subclasses). For a `java.lang.Object`, you can cast it using the `jsweet.util.Globals.object` helper method. For example:
|
||||
|
||||
``` java
|
||||
import static jsweet.dom.Globals.object;
|
||||
[...]
|
||||
object(anyObject).$get("$");
|
||||
```
|
||||
|
||||
The other way it to use the `jsweet.util.Globals.$get` helper method. Using helper methods can be convenient to easily write typical (untyped JavaScript statement). For example:
|
||||
|
||||
``` java
|
||||
import static jsweet.dom.Globals.$get;
|
||||
import static jsweet.dom.Globals.$apply;
|
||||
[...]
|
||||
// generate anyObject["prop"]("param");
|
||||
$apply($get(anyObject, "prop"), "param");
|
||||
```
|
||||
|
||||
Finally, note also the use of the `jsweet.util.Globals.any` helper method, which can be extremely useful to erase typing. Since the `any` method generates a cast to the `any` type in TypeScript, it is more radical than a cast to `Object` for instance. The following example shows how to use the `any` method to cast an `Int32Array` to a Java `int[]` (and then allow direct indexed accesses to it.
|
||||
|
||||
``` java
|
||||
ArrayBuffer arb = new ArrayBuffer(2 * 2 * 4);
|
||||
@ -1462,7 +1511,7 @@ assert c instanceof MyClass;
|
||||
assert typeof(n3) == "number";
|
||||
```
|
||||
|
||||
From JSweet version 1.1.0, the `instanceof` operator is also allowed on interfaces, because JSweet keeps track of all the implemented interfaces for all objects. This interface tracking is ensure through an additional hidden property in the objects called `__interfaces` and containing the names of all the interfaces implemented by the objects (either directly or through its class inheritance tree determined at compile time). So, in case the type argument of the `instanceof` operator is an interface, JSweet simply checks out if the object’s `__interfaces` field exists and contains the given interface. For example, this code is fully valid in JSweet when `Point` is an interface:
|
||||
From JSweet version 1.1.0, the `instanceof` operator is also allowed on interfaces, because JSweet keeps track of all the implemented interfaces for all objects. This interface tracking is ensured through an additional hidden property in the objects called `__interfaces` and containing the names of all the interfaces implemented by the objects (either directly or through its class inheritance tree determined at compile time). So, in case the type argument of the `instanceof` operator is an interface, JSweet simply checks out if the object’s `__interfaces` field exists and contains the given interface. For example, this code is fully valid in JSweet when `Point` is an interface:
|
||||
|
||||
``` java
|
||||
Point p1 = new Point() {{ x=1; y=1; }};
|
||||
@ -1472,7 +1521,9 @@ assert p1 instanceof Point
|
||||
|
||||
#### Limitations and constraints
|
||||
|
||||
Since all numbers are mapped to JavaScript numbers, JSweet make no distinction between integers and floats for example. So, `n instanceof Integer` and `n instanceof Float` will always give the same result whatever the actual type of `n` is. The same limitation exists for strings and char, which are not distinguishable at runtime.
|
||||
Since all numbers are mapped to JavaScript numbers, JSweet make no distinction between integers and floats for example. So, `n instanceof Integer` and `n instanceof Float` will always give the same result whatever the actual type of `n` is. The same limitation exists for strings and chars, which are not distinguishable at runtime, but also for functions that have the same number of parameters. For example, an instance of `IntFunction<R>` will not be distinguishable at runtime from a `Function<String,R>`.
|
||||
|
||||
These limitations have a direct impact on function overloading, since overloading uses the `instanceof` operator to decide which overload to be called.
|
||||
|
||||
Like it is usually the case when working in JavaScript, serialized objects must be properly “revived” with their actual classes so that the `instanceof` operator can work again. For example a point object created through `Point p = (Point)JSON.parse({x:1,y:1})` will not work with regard to the `instanceof` operator. In case you meet such a use case, you can contact us to get some useful JSweet code to properly revive object types.
|
||||
|
||||
@ -1521,7 +1572,7 @@ It is important to stress that the `this` correct value is ensured thanks to a s
|
||||
Packaging
|
||||
---------
|
||||
|
||||
Packaging is one of the complex point of JavaScript, especially when coming from Java. Complexity with JavaScript packaging boils down to the fact that JavaScript did not define any packaging natively. As a consequence, many *de facto* solutions and quidelines came up along the years, making the understanding of packaging uneasy for regular Java programmers. JSweet provides useful options and generates code in order to simplify the life of Java programmers by making the packaging issues much more transparent and as “easy” as in Java for most cases. In this section, we will describe and explain typical packaging scenarios.
|
||||
Packaging is one of the complex point of JavaScript, especially when coming from Java. Complexity with JavaScript packaging boils down to the fact that JavaScript did not define any packaging natively. As a consequence, many *de facto* solutions and guidelines came up along the years, making the understanding of packaging uneasy for regular Java programmers. JSweet provides useful options and generates code in order to simplify the life of Java programmers by making the packaging issues much more transparent and as “easy” as in Java for most cases. In this section, we will describe and explain typical packaging scenarios.
|
||||
|
||||
### Use your files without any packaging
|
||||
|
||||
@ -1600,7 +1651,16 @@ The above code shows an excerpt of the JSweet jQuery API. As we can notice, the
|
||||
|
||||
Note: the notion of manual require of a module may be available in future releases. However, automatic require is sufficient for most programmers and hides the complexity of having to require modules explicitly. It also brings the advantage of having the same code whether modules are used or not.
|
||||
|
||||
Troubleshooting: when a candy does not define properly the `@Module` annotation, it is currently possible to overcome the problem with a “hack” and force the use of an external module. See: <https://github.com/cincheo/jsweet/issues/114>.
|
||||
Troubleshooting: when a candy does not define properly the `@Module` annotation, it is possible to force the declaration within the comment of a special file called `module_defs.java`. For example, to force the `BABYLON` namespace of the Babylonjs candy to be exported as a `babylonjs` module, you can write the following file:
|
||||
|
||||
``` java
|
||||
package myprogram;
|
||||
// declare module "babylonjs" {
|
||||
// export = BABYLON;
|
||||
// }
|
||||
```
|
||||
|
||||
Note that a JSweet project can only define one `module_defs.java` file, which shall contain all the module declarations in a comment.
|
||||
|
||||
### Root packages
|
||||
|
||||
@ -1627,13 +1687,19 @@ When using modules (see the *module* option), only one `@Root` package is allowe
|
||||
|
||||
### Packaging a JSweet jar (candy)
|
||||
|
||||
When creating a program (especially a library or a component) with JSweet, one may want to package it in a JSweet jar (a.k.a. a candy) and deploy it on a Maven repository, so that it can be used by other JSweet programs.
|
||||
A candy is a Maven artifact that contains everything required to easily access a JavaScript library from a JSweet client program. This library can be an external JavaScript library, a TypeScript program, or another JSweet program.
|
||||
|
||||
Candies are regular Jars that can be generated with the Maven `package` goal. To be a valid candy and recognized as such by the JSweet transpiler, your jar file must contain two additional resources (to be placed in the resources directory of your Maven project so that they end up being packaged in your jar by Maven).
|
||||
#### Anatomy of a candy
|
||||
|
||||
1. A `META-INF/candy-metadata.json` file that contains the expected target version of the transpiler (to be adapted to your target transpiler version).
|
||||
Like any Maven artifact, a candy has a group id, a artifact id (name), and a version. Besides, a typical candy should contain the following elements:
|
||||
|
||||
2. The program’s declarations in `d.ts` files, to be placed in the `src/typings` directory of the jar.
|
||||
1. The compiled Java files (\*.class), so that your client program that uses the candy can compile.
|
||||
|
||||
2. A `META-INF/candy-metadata.json` file that contains the expected target version of the transpiler (to be adapted to your target transpiler version).
|
||||
|
||||
3. The program’s declarations in `d.ts` files, to be placed in the `src/typings` directory of the jar. Note that these definitions are not mandatory if you intend to use JSweet for generating TypeScript source code (`tsOnly` option). In that case, you may delegate the JavaScript generation to an external `tsc` compiler and access the TypeScript definitions from another source.
|
||||
|
||||
4. Optionally, the JavaScript bundle of the library, which can in turn be automatically extracted and used by the JSweet client programs. JSweet expects the JavaScript to be packaged following the Webjars conventions: <http://www.webjars.org/>. When packaged this way, a JSweet transpiler using your candy will automatically extract the bundled JavaScript in a directory given by the `candiesJsOut` option (default: `js/candies`).
|
||||
|
||||
Here is an example of the `META-INF/candy-metadata.json` file:
|
||||
|
||||
@ -1643,13 +1709,17 @@ Here is an example of the `META-INF/candy-metadata.json` file:
|
||||
}
|
||||
```
|
||||
|
||||
Typically, `d.ts` files shall be generated by the JSweet transpiler using the following options:
|
||||
#### How to create a candy from a JSweet program
|
||||
|
||||
- `declaration`: turns on the generation of the `d.ts` files.
|
||||
A typical use case when building applications with JSweet, is to share a common library or module between several other JSweet modules/applications. Note that since a JSweet candy is a regular Maven artifact, it can also be used by a regular Java program as long as it does not use any JavaScript APIs.
|
||||
|
||||
- `dtsout`: tells where to put the generated `d.ts` files (for packaging, place them in `RESOURCES/src/typings`, where `RESOURCES` is your Maven project resources directory).
|
||||
So, a typical example in a project is to have a *commons* library containing DTOs and common utility functions, which can be shared between a Web client written in JSweet (for example using the angular or knockout libraries) and a mobile client written also in JSweet (for example using the ionic library). The great news is that this *commons* library can also be used by the Java server (JEE, Spring, ...) as is, because the DTOs do not use any JavaScript, and that the compiled Java code packaged in the candy can run on a Java VM. This this extremely helpful, because it means that when you develop this project in your favorite IDE, you will be able to refactor some DTOs and common APIs, and it will directly impact your Java server code, your Web client code, and your mobile client code!
|
||||
|
||||
Finally it is recommended (and good practice) to also package the generated JavaScript as a bundle. The adopted way by JSweet is to package the JavaScript following the WebJar conventions: <http://www.webjars.org/>. When packaged this way, a JSweet transpiler using your candy will automatically extract the bundled JavaScript and extract it in a directory given by the `candiesJsOut` option (default: `js/candies`).
|
||||
We provide a quick start project to help you starting with such a use case: <https://github.com/cincheo/jsweet-candy-quickstart>
|
||||
|
||||
#### How to create a candy for an existing JavaScript or TypeScript library
|
||||
|
||||
We provide a quick start project to help you starting with such a use case: <https://github.com/cincheo/jsweet-candy-js-quickstart>
|
||||
|
||||
Appendix 1: JSweet transpiler options
|
||||
-------------------------------------
|
||||
@ -1683,6 +1753,23 @@ Appendix 1: JSweet transpiler options
|
||||
Specify where to place generated JavaScript files (ignored if jsFile is
|
||||
specified). (default: js)
|
||||
|
||||
[--tsOnly]
|
||||
Tells the transpiler to not compile the TypeScript output (let an
|
||||
external TypeScript compiler do so).
|
||||
|
||||
[--disableJavaAddons]
|
||||
Tells the transpiler disable runtime addons (instanceof, overloading,
|
||||
class name access, static initialization [...] will not be fully
|
||||
supported).
|
||||
|
||||
[--definitions]
|
||||
Tells the transpiler to generate definitions from def.* packages in d.ts
|
||||
definition files. The output directory is given by the tsout
|
||||
option. This option can be used to create candies for existing
|
||||
JavaScript libraries and must not be confused with the 'declaration'
|
||||
option, that generates the definitions along with a program written in
|
||||
JSweet.
|
||||
|
||||
[--declaration]
|
||||
Tells the transpiler to generate the d.ts files along with the js files,
|
||||
so that other programs can use them to compile.
|
||||
|
||||
Binary file not shown.
@ -816,11 +816,54 @@ By convention, putting the classes in a \texttt{def.libname} package defines a s
|
||||
|
||||
Candies (bridges to external JavaScript libraries) use definitions. For instance, the jQuery candy defines all the jQuery API in the \texttt{def.jquery} package.
|
||||
|
||||
Here is a list of rules and constraints that need to be followed when writing definitions.
|
||||
|
||||
\begin{itemize}
|
||||
\item The \texttt{def.libname} package must be annotated with a \texttt{@jsweet.lang.Root} (to be placed in a \texttt{package-info.java} file).
|
||||
\item Within a \texttt{def.*} package, \texttt{@Ambient} annotations are not required. By conventions all declarations are ambient.
|
||||
\item Interfaces are preferred over classes, because interfaces can be merged and classes can be instantiated. Classes should be used only if the API defines an explicit constructor (objects can be created with \texttt{new}). To define an interface in JSweet, just annotate a class with \texttt{@jsweet.lang.Interface}.
|
||||
\item Top-level functions and variables must be defined as \texttt{public static} members in a \texttt{Globals} class.
|
||||
\item All classes, interfaces and packages, should be documented with comments following the Javadoc standard.
|
||||
\item When several types are possible for a function parameter, method overloading should be preferred over using union types. When method overloading is not possible, it can be more convenient to simply use the \texttt{Object} type. It is less strongly typed but it is easier to use.
|
||||
\item One can use string types to provide function overloading depending on a string parameter value.
|
||||
\item In a method signature, optional parameters can be defined with the \texttt{@jsweet.lang.Optional} annotation.
|
||||
\item In an interface, optional fields can be defined with the \texttt{@jsweet.lang.Optional} annotation.
|
||||
\end{itemize}
|
||||
|
||||
Definitions can be embedded directly in a JSweet project to access an external library in a typed way, of they can be packaged in a candy (a Maven artifact), so that they can be shared by other projects. See the \emph{Packaging} section for full details on how to create a candy. Note that you do not need to write definitions when a library is written with JSweet because the Java API is directly accessible and the TypeScript definitions can be automatically generated by JSweet using the \texttt{declaration} option.
|
||||
|
||||
\section{Untyped accesses}
|
||||
|
||||
Sometimes, definitions are not available or are not correct, and just a small patch is required to access a functionality. Programmers have to keep in mind that JSweet is just a syntactic layer and that it is always possible to bypass typing in order to access a field or a function that is not explicitly specified in an API.
|
||||
|
||||
In that cases, the use of \texttt{\$get} allows reflective access to methods and properties that can then be cast to the right type. For accessing functions in an untyped way, one can cast to \texttt{jsweet.lang.Function} and call the generic and untyped method \texttt{apply} on it. Note also the use of the \texttt{jsweet.util.Globals.any} helper method, which can be extremely useful to erase typing. Since the \texttt{any} method generates a cast to the \texttt{any} type in TypeScript, it is more radical than a cast to \texttt{Object} for instance. The following example shows how to use the \texttt{any} method to cast an \texttt{Int32Array} to a Java \texttt{int[]} (and then allow direct indexed accesses to it.
|
||||
Although, having a well-typed API is the preferred and advised way, when such an API is not available, the use of \texttt{jsweet.\-lang.\-Object.\$get} allows reflective access to methods and properties that can then be cast to the right type. For accessing functions in an untyped way, one can cast to \texttt{jsweet.\-lang.\-Function} and call the generic and untyped method \texttt{apply} on it. For example, here is how to invoke the jQuery \texttt{\$} method when the jQuery API is not available :
|
||||
|
||||
\begin{lstlisting}[language=Java]
|
||||
import jsweet.dom.Globals.window;
|
||||
[...]
|
||||
Function $ = (Function)window.$get("$");
|
||||
$.apply("aCssSelector"):
|
||||
\end{lstlisting}
|
||||
|
||||
The \texttt{\$get} function is available on instances of \texttt{jsweet.lang.Object} (or subclasses). For a \texttt{java.lang.Object}, you can cast it using the \texttt{jsweet.util.Globals.object} helper method. For example:
|
||||
|
||||
\begin{lstlisting}[language=Java]
|
||||
import static jsweet.dom.Globals.object;
|
||||
[...]
|
||||
object(anyObject).$get("$");
|
||||
\end{lstlisting}
|
||||
|
||||
The other way it to use the \texttt{jsweet.util.Globals.\$get} helper method. Using helper methods can be convenient to easily write typical (untyped JavaScript statement). For example:
|
||||
|
||||
\begin{lstlisting}[language=Java]
|
||||
import static jsweet.dom.Globals.$get;
|
||||
import static jsweet.dom.Globals.$apply;
|
||||
[...]
|
||||
// generate anyObject["prop"]("param");
|
||||
$apply($get(anyObject, "prop"), "param");
|
||||
\end{lstlisting}
|
||||
|
||||
Finally, note also the use of the \texttt{jsweet.util.Globals.any} helper method, which can be extremely useful to erase typing. Since the \texttt{any} method generates a cast to the \texttt{any} type in TypeScript, it is more radical than a cast to \texttt{Object} for instance. The following example shows how to use the \texttt{any} method to cast an \texttt{Int32Array} to a Java \texttt{int[]} (and then allow direct indexed accesses to it.
|
||||
|
||||
\begin{lstlisting}[language=Java]
|
||||
ArrayBuffer arb = new ArrayBuffer(2 * 2 * 4);
|
||||
@ -1445,7 +1488,7 @@ function references are wrapped in functions, which means that function pointers
|
||||
\chapter{Packaging}
|
||||
\label{packaging}
|
||||
|
||||
Packaging is one of the complex point of JavaScript, especially when coming from Java. Complexity with JavaScript packaging boils down to the fact that JavaScript did not define any packaging natively. As a consequence, many \emph{de facto} solutions and quidelines came up along the years, making the understanding of packaging uneasy for regular Java programmers. JSweet provides useful options and generates code in order to simplify the life of Java programmers by making the packaging issues much more transparent and as "easy" as in Java for most cases. In this section, we will describe and explain typical packaging scenarios.
|
||||
Packaging is one of the complex point of JavaScript, especially when coming from Java. Complexity with JavaScript packaging boils down to the fact that JavaScript did not define any packaging natively. As a consequence, many \emph{de facto} solutions and guidelines came up along the years, making the understanding of packaging uneasy for regular Java programmers. JSweet provides useful options and generates code in order to simplify the life of Java programmers by making the packaging issues much more transparent and as "easy" as in Java for most cases. In this section, we will describe and explain typical packaging scenarios.
|
||||
|
||||
\section{Use your files without any packaging}
|
||||
|
||||
@ -1524,7 +1567,16 @@ The above code shows an excerpt of the JSweet jQuery API. As we can notice, the
|
||||
|
||||
Note: the notion of manual require of a module may be available in future releases. However, automatic require is sufficient for most programmers and hides the complexity of having to require modules explicitly. It also brings the advantage of having the same code whether modules are used or not.
|
||||
|
||||
Troubleshooting: when a candy does not define properly the \texttt{@Module} annotation, it is currently possible to overcome the problem with a "hack" and force the use of an external module. See: \url{https://github.com/cincheo/jsweet/issues/114}.
|
||||
Troubleshooting: when a candy does not define properly the \texttt{@Module} annotation, it is possible to force the declaration within the comment of a special file called \texttt{module\_defs.java}. For example, to force the \texttt{BABYLON} namespace of the Babylonjs candy to be exported as a \texttt{babylonjs} module, you can write the following file:
|
||||
|
||||
\begin{lstlisting}[language=Java]
|
||||
package myprogram;
|
||||
// declare module "babylonjs" {
|
||||
// export = BABYLON;
|
||||
// }
|
||||
\end{lstlisting}
|
||||
|
||||
Note that a JSweet project can only define one \texttt{module\_defs.java} file, which shall contain all the module declarations in a comment.
|
||||
|
||||
\section{Root packages}
|
||||
|
||||
@ -1551,13 +1603,17 @@ When using modules (see the \emph{module} option), only one \texttt{@Root} packa
|
||||
|
||||
\section{Packaging a JSweet jar (candy)}
|
||||
|
||||
When creating a program (especially a library or a component) with JSweet, one may want to package it in a JSweet jar (a.k.a. a candy) and deploy it on a Maven repository, so that it can be used by other JSweet programs.
|
||||
A candy is a Maven artifact that contains everything required to easily access a JavaScript library from a JSweet client program. This library can be an external JavaScript library, a TypeScript program, or another JSweet program.
|
||||
|
||||
Candies are regular Jars that can be generated with the Maven \texttt{package} goal. To be a valid candy and recognized as such by the JSweet transpiler, your jar file must contain two additional resources (to be placed in the resources directory of your Maven project so that they end up being packaged in your jar by Maven).
|
||||
\subsection{Anatomy of a candy}
|
||||
|
||||
Like any Maven artifact, a candy has a group id, a artifact id (name), and a version. Besides, a typical candy should contain the following elements:
|
||||
|
||||
\begin{enumerate}
|
||||
\item The compiled Java files (*.class), so that your client program that uses the candy can compile.
|
||||
\item A \texttt{META-INF/candy-metadata.json} file that contains the expected target version of the transpiler (to be adapted to your target transpiler version).
|
||||
\item The program's declarations in \texttt{d.ts} files, to be placed in the \texttt{src/typings} directory of the jar.
|
||||
\item The program's declarations in \texttt{d.ts} files, to be placed in the \texttt{src/typings} directory of the jar. Note that these definitions are not mandatory if you intend to use JSweet for generating TypeScript source code (\texttt{tsOnly} option). In that case, you may delegate the JavaScript generation to an external \texttt{tsc} compiler and access the TypeScript definitions from another source.
|
||||
\item Optionally, the JavaScript bundle of the library, which can in turn be automatically extracted and used by the JSweet client programs. JSweet expects the JavaScript to be packaged following the Webjars conventions: \url{http://www.webjars.org/}. When packaged this way, a JSweet transpiler using your candy will automatically extract the bundled JavaScript in a directory given by the \texttt{candiesJsOut} option (default: \texttt{js/candies}).
|
||||
\end{enumerate}
|
||||
|
||||
Here is an example of the \texttt{META-INF/candy-metadata.json} file:
|
||||
@ -1568,19 +1624,21 @@ Here is an example of the \texttt{META-INF/candy-metadata.json} file:
|
||||
}
|
||||
\end{lstlisting}
|
||||
|
||||
Typically, \texttt{d.ts} files shall be generated by the JSweet transpiler using the following options:
|
||||
\subsection{How to create a candy from a JSweet program}
|
||||
|
||||
\begin{itemize}
|
||||
\item \texttt{declaration}: turns on the generation of the \texttt{d.ts} files.
|
||||
\item \texttt{dtsout}: tells where to put the generated \texttt{d.ts} files (for packaging, place them in \texttt{RESOURCES/src/typings}, where \texttt{RESOURCES} is your Maven project resources directory).
|
||||
\end{itemize}
|
||||
A typical use case when building applications with JSweet, is to share a common library or module between several other JSweet modules/applications. Note that since a JSweet candy is a regular Maven artifact, it can also be used by a regular Java program as long as it does not use any JavaScript APIs.
|
||||
|
||||
Finally it is recommended (and good practice) to also package the generated JavaScript as a bundle. The adopted way by JSweet is to package the JavaScript following the WebJar conventions: \url{http://www.webjars.org/}. When packaged this way, a JSweet transpiler using your candy will automatically extract the bundled JavaScript and extract it in a directory given by the \texttt{candiesJsOut} option (default: \texttt{js/candies}).
|
||||
So, a typical example in a project is to have a \emph{commons} library containing DTOs and common utility functions, which can be shared between a Web client written in JSweet (for example using the angular or knockout libraries) and a mobile client written also in JSweet (for example using the ionic library). The great news is that this \emph{commons} library can also be used by the Java server (JEE, Spring, ...) as is, because the DTOs do not use any JavaScript, and that the compiled Java code packaged in the candy can run on a Java VM. This this extremely helpful, because it means that when you develop this project in your favorite IDE, you will be able to refactor some DTOs and common APIs, and it will directly impact your Java server code, your Web client code, and your mobile client code!
|
||||
|
||||
A typical Maven \texttt{pom.xml} for building a candy can be found here: \url{https://gist.github.com/renaudpawlak/5d3f1fa092d718e12407ef1801fb5ddd}.
|
||||
We provide a quick start project to help you starting with such a use case: \url{https://github.com/cincheo/jsweet-candy-quickstart}
|
||||
|
||||
\subsection{How to create a candy for an existing JavaScript or TypeScript library}
|
||||
|
||||
We provide a quick start project to help you starting with such a use case: \url{https://github.com/cincheo/jsweet-candy-js-quickstart}
|
||||
|
||||
\chapter*{Appendix 1: JSweet transpiler options}
|
||||
|
||||
\begin{small}
|
||||
\begin{verbatim}
|
||||
[-h|--help]
|
||||
|
||||
@ -1611,6 +1669,23 @@ A typical Maven \texttt{pom.xml} for building a candy can be found here: \url{ht
|
||||
Specify where to place generated JavaScript files (ignored if jsFile is
|
||||
specified). (default: js)
|
||||
|
||||
[--tsOnly]
|
||||
Tells the transpiler to not compile the TypeScript output (let an
|
||||
external TypeScript compiler do so).
|
||||
|
||||
[--disableJavaAddons]
|
||||
Tells the transpiler disable runtime addons (instanceof, overloading,
|
||||
class name access, static initialization [...] will not be fully
|
||||
supported).
|
||||
|
||||
[--definitions]
|
||||
Tells the transpiler to generate definitions from def.* packages in d.ts
|
||||
definition files. The output directory is given by the tsout
|
||||
option. This option can be used to create candies for existing
|
||||
JavaScript libraries and must not be confused with the 'declaration'
|
||||
option, that generates the definitions along with a program written in
|
||||
JSweet.
|
||||
|
||||
[--declaration]
|
||||
Tells the transpiler to generate the d.ts files along with the js files,
|
||||
so that other programs can use them to compile.
|
||||
@ -1656,6 +1731,7 @@ A typical Maven \texttt{pom.xml} for building a candy can be found here: \url{ht
|
||||
Set the transpiler to ignore 'assert' statements, i.e. no code is
|
||||
generated for assertions.
|
||||
\end{verbatim}
|
||||
\end{small}
|
||||
|
||||
\chapter*{Appendix 2: packaging and static behavior}
|
||||
\label{static_behavior}
|
||||
|
||||
@ -245,7 +245,7 @@ public class JSweetCommandLineLauncher {
|
||||
switchArg = new Switch("definitions");
|
||||
switchArg.setLongFlag("definitions");
|
||||
switchArg.setHelp(
|
||||
"Tells the transpiler to generate definitions from def.* packages in d.ts definition files. Regular program elements will be ignored and no plain .ts files will be generated. The output directory is given by the tsout option. This option can be used to create candies for existing JavaScript libraries and must not be confused with the 'declaration' option, that generates the definitions along with a program written in JSweet.");
|
||||
"Tells the transpiler to generate definitions from def.* packages in d.ts definition files. The output directory is given by the tsout option. This option can be used to create candies for existing JavaScript libraries and must not be confused with the 'declaration' option, that generates the definitions along with a program written in JSweet.");
|
||||
jsap.registerParameter(switchArg);
|
||||
|
||||
// Generates declarations
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user