Adding `async_codegen` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add async-codegen

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

async-codegen = "0.12.1"

The async_codegen library will be automatically available globally. Read the async_codegen library documentation.

Back to the crate overview.

Readme

Async Code Generator

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.

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:

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:

Writable - the main trait used by the library
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.

[dependencies]
async-codegen = "0.12.0"

The repository can also be built with Buck2, if you use it.

Licensing

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

Adding async_codegen library as a dependency

Adding `async_codegen` library as a dependency