async-codegen 0.8.1

Minimalist async-IO code generation framework.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84


# Async Code Generator

[![crates.io version](https://img.shields.io/crates/v/async-codegen)](https://crates.io/crates/async-codegen)
[![apache2 license](https://img.shields.io/crates/l/async-codegen)](https://www.gnu.org/licenses/license-recommendations.html)
[![docs.rs docs](https://img.shields.io/docsrs/async-codegen)](https://docs.rs/async-codegen)

A library for async code generation that imposes no ownership choices (can use borrowed or owned data) and is fully composable using generics and general-purpose structs.

### Example

This may seem tedious, but the design allows for maximum re-usability and composability.

```rust
async fn write_function<O>(output: &mut O) -> Result<(), O::Error> where O: Output {
  // For more advanced usage, you can replace Str("") by other Writable implementations
  let function_def = FunctionDef {
    mods: SingularSeq(ModPub),
    name: Str("my_func"), 
    args: CombinedSeq(
      SingularSeq(FunctionParam(Str("var1"), Str("Type"))),
      SingularSeq(FunctionParam(Str("var2"), Parameterized(Str("Option"), SingularSeq(Str("bool")))))
    ),
    return_type: Parameterized(Str("Box"), SingularSeq(Str("str"))),
    where_conds: NoOpSeq,
    body: FunctionBodyImplement(Str("todo!()"))
  };
  function_def.write_to(output).await
}
```

Will render as:

```rust
pub fn my_func(var1: Type, var2: Option<bool>) -> Box<str> { 
  todo!()
}
```

## Design

The API is conceptually simple. Performing code generation is akin to writing a syntax tree.

### Model

Writable elements are composed from other writable elements. They are divided into two kinds:
1. `Writable` - the main trait used by the library
2. `WritableSeq` - for a sequence of writable values handled in the same way.

An example of a writable sequence would be function arguments, type variables, etc. An example of a standalone writable value would be a function body.

### Your Data

This library is made for industrial-strength, low-allocation code generation. As a result, it's intended that callers create their own writable types from their own data.

For example, let's say you want to generate a big enum. Well, you would implement your own `WritableSeq` to fill out the enum elements.

### Async and Errors

Every code generation-related function returns the library user's error type.

Also, the methods are `async` and must be awaited as such. This lets the library user plug in their favorite async runtime... because why not make code generation fast?

## Library

### Code Standards

Except for the `utils` module, the library is free of panics and unsafe code. That being said, we hold ourselves to high standards:

* Panics are clearly documented.
* Unsafe code is clearly explained through comments, and run through MIRI and testing.

### Dependency

Add this library to your Cargo.toml. Check crates.io for the latest version.

```toml
[dependencies]
async-codegen = "0.8.1"
```

### Licensing

Licensed under the Apache License v2.0. See the LICENSE.txt.