Github | Crates.io | Docs.rs

TLDR; - you can find a very simple example how to use this crate if you click the github link above

This crate is a Rust source code generator and it is useful for scenarios where you need to generate highly repetitive code that is slightly different per type (ie lots of traits on lots of types), esp. with doc comments and doctests that you wish to generate on a per type basis. All the code is generated from code fragment snippets using quote like you would if using procmacro (including the doc comment and doctests - NOT as code wedged in a comment like in macros by example). I had started with macros but hated trying to modify doc comments/tests as raw text - it made them impossible to read (there is no free lunch - heavy quote interpolation isn't terribly easy to read either)

My specific use case for building this is the next version of flexstr which has six different string types that call into a common inner type and will implement a large amount of traits, but with slight differences for each (due to limitations on the strings themselves if you are familiar with CStr vs. str. vs OsStr, etc.). Since all these are just wrappers to the inner type it makes sense to generate this code. My macros were starting to look like gibberish so I switched to code generation and I like the results of this better. Plus, since this is generated ahead of time the user has real Rust code to link to from the docs and there is no procmacro-like build time penalty in their compile.

Here are a few examples of code generated - these look exactly as if I had written them manually (including grouping the use into std, crate, and external sections automatically via my use-builder crate):

BStr Example CStr Example OsStr Example Path Example RawStr Example str Example

All generated from this file

While overall I think there will be "saved keystrokes" that really isn't the point. The goal is to generate this code in such a way as to have confidence it is correct, that I can read it, and that I can modify it and regenerate it and have confidence all six types are identical (where needed and different where needed). I'm fairly happy with the results, but there is still room for improvement.

This crate is built on top of my smaller crates (rust-format and quote-doctest) and those do much of the heavy lifting. The crate isn't quite where I want it, but I need to take a (hopefully) very brief break from open source to focus on some work projects so thought I would release it as is (it works just fine so far). It is a bit niche, but perhaps someone can find a use for it.