Crate rust_writer

Description

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;

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);
    });

Important Note

To simplify testing of this crate, a crate called test_builder is included as a dev dependency. This crate makes it easy to set up tests that load different files and ASTs seamlessly, allowing tests to focus on the specific functionality being verified.

This crate is widely used across the documentation, so it’s worthy to mention that the sample files used by TestBuilder are available in the repository and can be consulted as needed.

The syntax for TestBuilder is straightforward: methods like with_something_ast load an AST from a file named accordingly, while with_something_file load the entire file.

Modules

ast

This module leverages the syn crate and provides an easy mechanism to interact with a rust AST represented as a syn::File with just a few lines of code.

preserver

This module provides utilities to “preserve” portions of a Rust source file during parsing so that empty lines, comments, and certain attributes are not lost.

Enums

Error

Represents the various errors that can occur in the crate.