Description 📖📚

The crate docs should be considered the only source of truth for this crate usage.

rust_writer is a crate designed to simplify meta programming in Rust—but in a different way than the typical procedural macro crates (such as syn, quote, and proc_macro2).

While those crates excel at writing procedural macros, rust_writer leverages their capabilities to modify Rust source files. This makes it ideal for tasks that require in-place source code modifications rather than merely generating new code visible only to the compiler.

The crate is divided into two modules: the preserver module and the ast module. Although these modules can be used separately and even for purposes other than the crate's primary objective, using them together unlocks the full potential of the crate.

• The preserver module ensures that the original structure of the source code is maintained when it is parsed into an AST.
• The ast module provides various tools to simplify AST interactions, allowing precise modifications exactly where needed.

For further details, please refer to the individual module documentation. A complete example is often the best way to illustrate the functionality:

use quote::quote;
use rust_writer::{
    ast::{
        implementors::{ItemToFile, ItemToImpl, TokenStreamToMacro},
        mutator,
        mutator::{Mutator, ToMutate},
    },
    preserver::Preserver,
};
use syn::{parse_quote, ImplItem, Item, visit_mut::VisitMut};
use test_builder::TestBuilder;

// A mutator defined with the given implementors.
#[mutator(TokenStreamToMacro, ItemToFile, ItemToImpl<'a>)]
#[impl_from]
struct TestMutator;

// In this example, complete file can be found at https://github.com/tsenovilla/rust_writer/blob/main/test_builder/sample_files/complete_file.rs,
// while expanded_file can be found at https://github.com/tsenovilla/rust_writer/blob/main/test_builder/sample_files/expanded_file.rs
TestBuilder::default()
    .with_complete_file()
    .with_expanded_file()
    .execute(|builder| {
        let complete_file_path = builder.tempfile_path("complete_file.rs")
            .expect("This file exists");
        let expanded_file_path = builder.tempfile_path("expanded_file.rs")
            .expect("This file exists");
        let expected_code = std::fs::read_to_string(&expanded_file_path)
            .expect("File should be readable");

        // Preserve an impl block and the invocation of `my_macro` in the code.
        // The rest of the file remains unchanged, preserving its original AST structure.
        let preserver1 = Preserver::new("impl MyTrait for MyStruct");
        let mut preserver2 = Preserver::new("fn main");
        preserver2.add_inners(&["my_macro"]);

        let mut ast = rust_writer::preserver::preserve_and_parse(
            complete_file_path,
            &[&preserver1, &preserver2],
        )
        .expect("Preservation should be applied");

        // Add a function to the trait implementation.
        // Note the TEMP_DOC comment: it will become an empty line in the final code,
        // which is a neat trick to insert an empty line at the start of the function.
        let item_to_impl: ItemToImpl = (
            Some("MyTrait"),
            "MyStruct",
            ImplItem::Fn(parse_quote! {
                ///TEMP_DOC
                fn func(&self) -> bool {
                    false
                }
            }),
        )
        .into();

        // Add a TokenStream to the `my_macro` invocation.
        let token_stream_to_macro: TokenStreamToMacro = (
            parse_quote!(my_macro),
            None,
            quote! {
                struct SomeStruct {
                    field: u8,
                    string: String
                }
            },
        )
        .into();

        // Insert an item into the file so that `Path` is in scope.
        let item: Item = parse_quote!( use std::path::Path; );
        let item_to_file: ItemToFile = item.into();

        // Create a mutator for the given implementors.
        let test_mutator: TestMutator =
            (token_stream_to_macro, item_to_file, item_to_impl).into();
        let mut mutator: TestMutatorMutatorWrapper =
            Mutator::default().to_mutate(&test_mutator).into();

        // Mutate the AST.
        assert!(mutator.mutate(&mut ast, None).is_ok());

        // Unparse the AST and restore the preserved code.
        assert!(rust_writer::preserver::resolve_preserved(&ast, complete_file_path).is_ok());

        let actual_code = std::fs::read_to_string(complete_file_path)
            .expect("File should be readable");
        assert_eq!(actual_code, expected_code);
    });

Contributing 🤝🚀

Any contribution is more than welcome! 🤝🦾 Just open a PR with your changes and it'll be considered 😸