Crate codebiber

Source
Expand description

§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 8fb912f5 >>
// << codegen bar >>
void autogen_line_bar1();
void autogen_line_bar2();
// << /codegen 88c5186d >>
// << codegen baz >>
void generated_line_by_some_other_function();
// << /codegen ded33021 >>

Note the hashsums. They protect against overwritting accidental modifications. They are simply a crc32 hahsum.

extern crate codebiber;

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

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

void handwritten_line3();

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

void handwritten_line4();

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

void handwritten_line5();
";
              
fn main() -> codebiber::Result
{
  let actual_output = codebiber::generate(INPUT, 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 8fb912f5 >>

void handwritten_line3();

  // << codegen bar >>
  void autogen_line_bar1();
  void autogen_line_bar2();
  // << /codegen 88c5186d >>

void handwritten_line4();

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

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 >> */
(* << /codegen >> *)

#if 0 // << codegen bar >>
#endif // << /codegen >>

  # << codegen bar >> For python like languages
  -- << /codegen >> Note how you can also write stuff after the marker

    esoteric langugage using keywords << codegen bar >> for comments
    << /codegen >>
";
              
fn main() -> codebiber::Result
{
  let actual_output = codebiber::generate(INPUT, 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"
/* << codegen foo >> */
void autogen_line_foo();
(* << /codegen 8fb912f5 >> *)

#if 0 // << codegen bar >>
void autogen_line_bar1();
void autogen_line_bar2();
#endif // << /codegen 88c5186d >>

  # << codegen bar >> For python like languages
  void autogen_line_bar1();
  void autogen_line_bar2();
  -- << /codegen 88c5186d >> Note how you can also write stuff after the marker

    esoteric langugage using keywords << codegen bar >> for comments
    void autogen_line_bar1();
    void autogen_line_bar2();
    << /codegen 88c5186d >>
";

Also note how every bar section shares the same hashsum. Thats because the hashsum is generated before indenting the code.

Re-exports§

pub use indentation::Indentation;
pub use gen::generate;
pub use gen::Fmt_Result;
pub use process::process_file;
pub use process::process_files;
pub use process::Process_Error as Error;
pub use process::Result;

Modules§

crc32
gen
indentation
parse_file
process