typeshare-java 0.5.0

# typeshare-java

`typeshare-java` is a CLI tool for converting Rust types into Java types. It is
part of the wider [typeshare](https://crates.io/crates/typeshare) ecosystem.

## Installation

First, install the CLI:

```sh
cargo install typeshare-java
```

Then, install the annotations:

```sh
cargo add typeshare
```

## Feature Support

| Feature         | Status | Comment                                         |
|-----------------|--------|-------------------------------------------------|
| Structs         | ✅     | -                                               |
| Struct Generics | ✅     | -                                               |
| Unit Enums      | ✅     | -                                               |
| Algebraic Enums | 🚧     | Gson only. Anonymous structs not supported yet. |
| Enum Generics   | ❌     | -                                               |
| Type Aliases    | ❌     | -                                               |
| Constants       | ❌     | -                                               |

## Usage

### CLI

To get started, run:

```sh
cd <your-rust-project>
typeshare-java --output-file output.java ./
```

### Annotations

#### Getting Started

For `typeshare-java` to generate types from your Rust code, it requires you to
add a special annotation:

```rs
#[typeshare]
struct Color {
    r: u8,
    g: u8,
    b: u8,
}
```

In some cases, you may also need to add serde annotations:

```rs
#[typeshare]
#[serde(tag = "type", content = "content")]
pub enum BestNflTeam {
    KansasCity,
    Lies(String),
}
```

#### Adding Java Annotations

Java annotations can be added as follows:

```rs
#[typeshare(java(annotations = "@Getter"))]
pub enum Color {
    Red,
    Blue,
    Green,
}
```

Multiple annotations can be added like this:

```rs
#[typeshare(java(annotations = "
    @Getter
    @JsonAdapter(MyCustomAdapter.class)
"))]
pub enum Color {
    Red,
    Blue,
    Green,
}
```

### Config

In most cases, config options can be passed via the command line. However, some
options can only be added in a `typeshare.toml` file. Here is an example config
file:

```toml
[java]
package = "com.typeshare.java"
namespace_class = true

[java.header_comment]
type = "None"

[java.serializer]
type = "Gson"
```

#### Options

##### `header-comment`

A header comment can be added to each generated file.

```toml
[java.header_comment]
type = "Default" // Generated by typeshare-java <version>
// Or...
type = "None"
// Or...
type = "Custom"
comment = "This comment will be included at the top of each generated file"
```

##### `package`

The package name of the output.

```java
package <package>; // Added to the top of output files
```

##### `prefix`

An optional prefix for type names.

```rs
#[typeshare]
struct Example {}
```

With prefix set to "Tada":

```java
public record TadaExample() {}
```

##### `namespace_class`

Java only supports one top level file per class. We can get around this by
wrapping classes in a namespace class. This will have the same name as the
crate, converted to pascal case.

```rs
#[typeshare]
struct Inner {}

#[typeshare]
struct Outer {
    pub inner: Inner,
}
```

If the crate is named `my_crate` and namespace classes are enabled, the
following Java code will be generated:

```java
public class MyCrate {

    public record Inner() {}

    public record Outer(Inner inner) {}

}
```

##### `serializer`

Java has several serialization/deserialization packages. Depending on the Rust
code you're working with, serializer specific code may need to be emitted.
Currently, only `None` and `Gson` are supported. If `None` (default), then
some data structures, such as algebraic enums, cannot be converted to Java code.

```toml
[java.serializer]
type = "None"
// Or...
type = "Gson"
```

#### `indent`

The indent type and size can be configured as follows:

```toml
[java.indent]
type = "Spaces"
size = 4
```