Codebiber

This crate is an rust library for metaprogramming. It allows mixing autogenerated code into handwritten code. It is heavily inspired by Ned Batchelder's cog application.

Disclaimer

This work is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.

It is an experimental library and has an experimental API, behavior and implementation and no longterm plans. Use at own risk.

Changelog

v0.0.1

• Minumum supported rust version is now 1.63 (for regular builds, not dev builds) 05ed194ddaa2127b671c0345cfdf8e4330419242
• Not using unstable features anymore 0341b2d033173a4f7d6e084ae14bd36f623db9d5

lib.rs:

Example

A silly example of using codebiber to mix autogenerated code with handwritten code.

Here, the original code contans handwritten lines

void handwritten_line1();
void handwritten_line2();

void handwritten_line3();

void handwritten_line4();

void handwritten_line5();

and some sections marked to be overwritten

// << codegen foo >>
// << /codegen >>

// << codegen bar >>
// << /codegen >>

and a section that was already generated by another function

// << codegen baz >>
void generated_line_by_some_other_function();
// << /codegen >>

The function generate accepts the input code, a configuration and most important the function which will generate the code.

In our example, the function will be called once for each section. Each time it accepts the section name (in our case foo, bar or baz) and returns the generated code for this section. If the section is not its responsibility, it can also return Ok(None) and the previous content will be used again.

In our example, the generator function gen_code_lines returns new code for the sections foo and bar while leaving baz untouched.

This results in the generated code section

// << codegen foo >>
void autogen_line_foo();
// << /codegen aaa272 >>

// << codegen bar >>
void autogen_line_bar1();
void autogen_line_bar2();
// << /codegen 00a214 >>

// << codegen baz >>
void generated_line_by_some_other_function();
// << /codegen 810c07 >>

Note the hashsums. They protect against overwritting accidental modifications. They are simply the first few bytes of a blake3 hahsum (how many can be configured).

extern crate codebiber;

const INPUT : &str = r"
void handwritten_line1();
void handwritten_line2();

// << codegen foo >>
// << /codegen >>

void handwritten_line3();

// << codegen bar >>
// << /codegen >>

void handwritten_line4();

// << codegen baz >>
void generated_line_by_some_other_function();
// << /codegen >>

void handwritten_line5();
";

fn main() -> codebiber::Result
{
let cfg = codebiber::Config{
// Anything checksum length other than 0 will catch unintended modifications
// since the last modification.
checksum_bytes_to_store: 3,
};

let actual_output = codebiber::generate(INPUT, cfg, gen_code_lines)?;

assert_eq!(actual_output, Some(EXPECTED_OUTPUT.to_owned()));

Ok(())
}

fn gen_code_lines(name: &str) -> codebiber::Fmt_Result
{
let generated = match name
{
"foo" => Some("void autogen_line_foo();".to_owned()),
"bar" => Some("void autogen_line_bar1();\nvoid autogen_line_bar2();".to_owned()),
_ => None,
};
Ok(generated)
}

const EXPECTED_OUTPUT : &str = r"
void handwritten_line1();
void handwritten_line2();

// << codegen foo >>
void autogen_line_foo();
// << /codegen aaa272 >>

void handwritten_line3();

// << codegen bar >>
void autogen_line_bar1();
void autogen_line_bar2();
// << /codegen 00a214 >>

void handwritten_line4();

// << codegen baz >>
void generated_line_by_some_other_function();
// << /codegen 810c07 >>

void handwritten_line5();
";

Please not how the generated code in the bar section is indented. That's because the generated code inherits the indentation of the marker line // << codegen bar >>

Example 2

While in this example all marker lines start with //, marker lines can start and with any characters as long as they don't end with < and don't contain <<.

extern crate codebiber;

const INPUT : &str = r"
/* << codegen foo >>