Attribute Macro interthread::example

#[example]

Code transparency and exploration

The example macro serves as a convenient tool for code transparency and exploration. Automatically generating an expanded code file, it provides developers with a tangible representation of the code produced by the interthread macros.

Having the expanded code readily available in the examples/inter directory offers a few key advantages:

• It provides a clear reference point for developers to inspect and understand the underlying code structure.

• The generated code file serves as a starting point for customization. Developers can copy and paste the generated code into their own project files and make custom changes as needed. This allows for easy customization of the generated actor implementation to fit specific requirements or to add additional functionality.

• Helps maintain a clean and focused project structure, with the examples directory serving as a dedicated location for exploring and experimenting with the generated code.

example macro helps developers to actively engage with the generated code and facilitates a smooth transition from the generated code to a customized implementation. This approach promotes code transparency, customization, and a better understanding of the generated code’s inner workings, ultimately enhancing the development experience when working with the interthread macros.

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

Filename: my_file.rs

use interthread::{actor,example};

pub struct Number;

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

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

Filename: main.rs

use interthread::example;
#[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"  

example macro can be placed on any item in any file within your src directory, providing flexibility in generating example code for/from different parts of your project.

It provides two options for generating example code files:

• mod (default)
• main

mod

The macro generates an example code file within the examples/inter directory. For example:

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

This is equivalent to:

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

The generated example code file will be located at examples/inter/my_file.rs.

This option provides developers with an easy way to view and analyze the generated code, facilitating code inspection and potential code reuse.

main

This option is used 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 testing 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( 
   
    mod ✔
    main 

    (   
        path = "path/to/file.rs" ❗️ 

        expand(actor,group) ✔
    )
 )]
 
 
 default:    ✔
 required:   ❗️
 
 

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.

! One more time 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 group 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 group.