Attribute Macro example

#[example]

Code transparency and exploration

example simplifies exploring and interacting with expanded macro-generated code. It generates example files with expanded content of interthread macros, making it easy for developers to debug, test, and experiment.

Consider a macro actor inside the project in src/my_file.rs.

Filename: my_file.rs

 
pub struct MyActor;

 // you can have "example" macro in the same file
 // #[interthread::example(path="src/my_file.rs")]

#[interthread::actor]
impl MyActor {
    pub fn new(value: u32) -> Self {Self}
}

Filename: main.rs

#[interthread::example(path="src/my_file.rs")]
fn main(){
}

The macro will create and write to examples/inter/my_file.rs the content of src/my_file.rs with the actor macro expanded.

my_project/
├── src/
│  ├── my_file.rs      <---  macro "actor" 
|  |
│  └── main.rs         <---  macro "example" 
|
├── examples/          
   ├── ...
   └── inter/      
      ├── my_file.rs   <--- expanded "src/my_file.rs"  

When specifying the main argument in the example macro. It generates two files within the examples/inter directory: the expanded code file and an additional main.rs file.

#[example(main,path="my_file.rs")]

This option is particularly useful for debugging and experimentation. It allows developers to quickly run and interact with the generated code by executing:

$ cargo run --example inter

The expanded code file will be located at examples/inter/my_file.rs, while the main.rs file serves as an entry point for running the example.

Configuration Options

 
#[interthread::example( 

        main | mod *
 
        path = "path/to/file.rs"  

        expand(actor,family) *
 )]
 
 * - default   
 

Arguments

• path

• expand (default)

path

The path argument is a required parameter of the example macro. It expects the path to the file that needs to be expanded.

This argument is essential as it specifies the target file for code expansion.

example macro can be placed on any item in any file within your src directory.

expand

This argument allows the user to specify which interthread macros to expand.

By default, the value of expand includes the actor and family macros.

For example, if you want to expand only the actor macro in generated example code, you can use the following attribute:

#[example(path="my_file.rs",expand(actor))]

This will generate an example code file that includes the expanded code of the actor macro, while excluding other macros like family.