Polyquine: Teach Rust types to codegen their own constructor!

crates.io: polyquine

cargo add polyquine

Purpose

This crate contains:

A Quine trait. Types that implement Quine have a method ctor_tokens(&self) -> TokenStream; The tokens returned by it are valid Rust expression that, when evaluated, produces the original value.
Implementations for:
- All primitives (i32, bool, etc.)
- String
- Fixed-size arrays [T; N]
- Some std::collections types (Vec, HashMap, HashSet, etc.)
- Tuples of up to 12 elements
- Box<T>, Option<T>
Declarative macros to implement Quine for:
- Iterables (derive_iterable). The given iterable must:
  - Have an .iter() method that returns an iterator over its elements.
  - Implement From<[T; N]>
A #[derive(Quine)] macro to derive the trait for enums and structs. All fields thereof must implement Quine.

For example:

#[derive(Quine)]
struct Node {
    value: i32,
    next: Option<Box<Node>>,
}

let node = Node {
    value: 1i32,
    next: Some(Box::new(Node {
        value: 2i32,
        next: None,
    })),
};
assert_ts_eq(
    &node.ctor_tokens(),
    // Evaluate this and you get the value of `node` back!
    &quote! {Node { value: 1i32, next: Some(Box::new(Node { value: 2i32, next: None })) }},
);

Attributes

You can supply a custom implementation for a specific variant only - handy when this variant contains a foreign type that does not implement Quine, or when you want some custom logic in its .ctor_tokens(). This is done using the attribute #[polyquine_with(arm = (val) => {...})].

#[derive(Quine)]
enum TestEnum {
    A,
    #[polyquine_with(arm = (val) => {
        let new_val = val + 1;
        quote! { TestEnum::B(#new_val) }
    })]
    B(i32),
}

let b = TestEnum::B(42i32);
assert_ts_eq(&b.ctor_tokens(), &quote! { TestEnum::B(43i32) }); // <- the value got incremented!

You can also skip variants using #[polyquine_skip]. By doing so, you pinky promise to never call .ctor_tokens() on an instance of that variant. If you do, it will panic!():

#[derive(Quine)]
enum TestEnum {
    A,
    #[polyquine_skip]
    B,
}

let a = TestEnum::A;
assert_ts_eq(
    &a.ctor_tokens(),
    &quote! {polyquine::quine::test::TestEnum::A},
); // All good for A

let b = TestEnum::B;
let _ = b.ctor_tokens(); // <- This should panic

Contributing

Contributions are always welcome!

If you need Quine to work with a specific type from std or a third-party crate, or have any other feature suggestions, open an issue tagged "feature request".
If you encounter any bugs / unexpected behaviour, open an issue. Please include the error message and relevant code snippets.
Pull requests are very much appreciated! I will do my best to review them ASAP. When submitting a patch, please:
- Make sure that the linter is happy and all tests pass:
```
cargo fmt
cargo clippy --workspace --fix
cargo test --workspace
```
- Include a short message explaining the changes and reasoning behind them

See the issues for planned feature tracking and known bugs

Notes

Version 0.0.2 is a complete rewrite. We now use our own trait instead of deriving quote::ToTokens. All field attributes from version 0.0.1 are no longer supported.
We ignore references, i.e. the implementation for &T is the same as for T. This may cause issues - please open an issue if you encounter any.
Please open an issue if any std type is not supported and you need it.
Rc, Arc and friends are unlikely to ever be supported. This is due to their shared ownership semantics: We can have multiple Rc's pointing to the same memory. When implementing Quine, the best we can do is re-construct their values separately. When evaluated, we will now have multiple independent copies of the original value - not a single value behind a shared reference.

Acknowledgements

Partially inspired by the parsel crate.

Why?

This is intended for cases where you need to construct a value and do some non-trivial logic on it at compile time (probably in a procedural macro), then take the result out of the macro as valid Rust code.

For example, when you are parsing a DSL at compile time and outputting the constructed (and possibly simplified / transformed) AST as the result of your macro call.

See this PR as proof that this use case is not completely made up.

Production readiness

still no.

Why the name?

A quine is a program that outputs its own source code. This crate teaches an arbitrary enum / struct to generate a Rust program that constructs it, thereby making it a quine. So, polyquine! This is only slightly pretentious.

also, trans rights! 🏳️‍⚧️

polyquine 0.0.8