//! # Intro
//!
//! This document covers the usage of the crate's macros, it does 
//! not delve into the detailed logic of the generated code.
//! 
//! For a comprehensive understanding of the underlying
//! concepts and implementation details of the Actor Model,  
//! it's recommended to read the article  [Actors with Tokio](https://ryhl.io/blog/actors-with-tokio/)
//! by Alice Ryhl ( also known as _Darksonn_ ) also a great 
//! talk by the same author on the same subject if a more 
//! interactive explanation is prefered 
//! [Actors with Tokio – a lesson in ownership - Alice Ryhl](https://www.youtube.com/watch?v=fTXuGRP1ee4)
//! (video).
//! This article not only inspired the development of the 
//! `interthread` crate but serves as foundation 
//! for the Actor Model implementation logic in it. 


//! ## What is an Actor ?
//!
//! Despite being a fundamental concept in concurrent programming,
//! defining exactly what an actor is can be ambiguous.
//! 
//! - *Carl Hewitt*, often regarded as the father of the Actor Model,
//! [The Actor Model](https://www.youtube.com/watch?v=7erJ1DV_Tlo) (video).
//! 
//! - Wikipidia [Actor Model](https://en.wikipedia.org/wiki/Actor_model)
//!  
//!
//! a quote from [Actors with Tokio](https://ryhl.io/blog/actors-with-tokio/):
//! 
//! > "The basic idea behind an actor is to spawn a 
//! self-contained task that performs some job independently
//! of other parts of the program. Typically these actors
//! communicate with the rest of the program through 
//! the use of message passing channels. Since each actor 
//! runs independently, programs designed using them are 
//! naturally parallel."
//! > - Alice Ryhl 
//!
//! ## What is the problem ?
//! 
//! To achieve parallel execution of individual objects 
//! within the same program, it is challenging due 
//! to the need for various types that are capable of 
//! working across threads. The main difficulty 
//! lies in the fact that as you introduce thread-related types,
//! you can quickly lose sight of the main program 
//! idea as the focus shifts to managing thread-related 
//! concerns.
//!
//! It involves using constructs like threads, locks, channels,
//! and other synchronization primitives. These additional 
//! types and mechanisms introduce complexity and can obscure 
//! the core logic of the program.
//! 
//! 
//! Moreover, existing libraries like [`actix`](https://docs.rs/actix/latest/actix/), [`axiom`](https://docs.rs/axiom/latest/axiom/), 
//! designed to simplify working within the Actor Model,
//! often employ specific concepts, vocabulary, traits and types that may
//! be unfamiliar to users who are less experienced with 
//! asynchronous programming and futures. 
//! 
//! ## Solution 
//! 
//! The [`actor`](./attr.actor.html) macro -  when applied to the 
//! implementation block of a given "MyActor" object,
//! generates additional Struct types  
//! that enable communication between threads.
//! 
//! A notable outcome of applying this macro is the 
//! creation of the `MyActorLive` struct ("ActorName" + "Live"),
//! which acts as an interface/handle to the `MyActor` object.
//! `MyActorLive` retains the exact same public method signatures
//! as `MyActor`, allowing users to interact with the actor as if 
//! they were directly working with the original object.
//! 
//! ### Examples
//! 
//! 
//! Filename: Cargo.toml
//! 
//!```text
//![dependencies]
//!interthread = "2.0.0"
//!oneshot     = "0.1.6" 
//!```
//! 
//! Filename: main.rs
//!```rust no_run
//!pub struct MyActor {
//!    value: i8,
//!}
//!
//!#[interthread::actor] 
//!impl MyActor {
//!
//!    pub fn new( v: i8 ) -> Self {
//!       Self { value: v } 
//!    }
//!    pub fn increment(&mut self) {
//!        self.value += 1;
//!    }
//!    pub fn add_number(&mut self, num: i8) -> i8 {
//!        self.value += num;
//!        self.value
//!    }
//!    pub fn get_value(&self) -> i8 {
//!        self.value
//!    }
//!}
//!
//!fn main() {
//!
//!    let actor = MyActorLive::new(5);
//!
//!    let mut actor_a = actor.clone();
//!    let mut actor_b = actor.clone();
//!
//!    let handle_a = std::thread::spawn( move || { 
//!    actor_a.increment();
//!    });
//!
//!    let handle_b = std::thread::spawn( move || {
//!    actor_b.add_number(5);
//!    });
//!
//!    let _ = handle_a.join();
//!    let _ = handle_b.join();
//!
//!    assert_eq!(actor.get_value(), 11)
//!}
//!
//! ```
//! 
//! An essential point to highlight is that when invoking 
//! `MyActorLive::new`, not only does it return an instance 
//! of `MyActorLive`, but it also spawns a new thread that 
//! contains an instance of `MyActor` in it. 
//! This introduces parallelism to the program.
//! 
//! The code generated by the [`actor`](./attr.actor.html) takes 
//! care of the underlying message routing and synchronization, 
//! allowing developers to rapidly prototype their application's
//! core functionality. This fast sketching capability is
//! particularly useful when exploring different design options, 
//! experimenting with concurrency models, or implementing 
//! proof-of-concept systems. Not to mention, the cases where 
//! the importance of the program lies in the result of its work 
//! rather than its execution.
//!
//! 
//! # SDPL Framework
//! 
//! 
//!  The code generated by the [`actor`](./attr.actor.html) macro 
//! can be divided into four more or less important but distinct 
//! parts: [`script`](#script) ,[`direct`](#direct), 
//! [`play`](#play), [`live`](#live) .
//! 
//!  This categorization provides an intuitive 
//! and memorable way to understand the different aspects 
//! of the generated code.
//! 
//! Expanding the above example, uncomment the [`example`](./attr.example.html)
//! placed above the `main` function, go to `examples/inter/main.rs` in your 
//! root directory and find `MyActor` along with additional SDPL parts :
//! 
//! # `script`
//! 
//!  Think of script as a message type definition.
//! 
//!  The declaration of an `ActorName + Script` enum, which is 
//! serving as a collection of variants that represent 
//! different messages that may be sent across threads through a
//! channel. 
//! 
//!  Each variant corresponds to a struct with fields
//! that capture the input and/or output parameters of 
//! the respective public methods of the Actor.
//!  
//! 
//! ```rust no_run
//! 
//! pub enum MyActorScript {
//!     Increment {},
//!     AddNumber { num: i8, inter_send: oneshot::Sender<i8> },
//!     GetValue { inter_send: oneshot::Sender<i8> },
//! }
//! 
//! ```
//! 
//! > **Note**: Method `new` not included as a variant in the `script`. 
//! 
//! 
//! # direct
//! The implementation block of `script`struct, specifically 
//! the `direct` method which allows 
//! for direct invocation of the Actor's methods by mapping 
//! the enum variants to the corresponding function calls.
//! 
//! 
//!```rust no_run
//!impl MyActorScript {
//!    pub fn direct(self, actor: &mut MyActor) {
//!        match self {
//!            MyActorScript::Increment {} => {
//!                actor.increment();
//!            }
//!            MyActorScript::AddNumber { num, inter_send } => {
//!                inter_send
//!                    .send(actor.add_number(num))
//!                    .unwrap_or_else(|_error| {
//!                        core::panic!(
//!                            "'MyActorScript::AddNumber.direct'. Sending on a closed channel."
//!                        )
//!                    });
//!            }
//!            MyActorScript::GetValue { inter_send } => {
//!                inter_send
//!                    .send(actor.get_value())
//!                    .unwrap_or_else(|_error| {
//!                        core::panic!(
//!                            "'MyActorScript::GetValue.direct'. Sending on a closed channel."
//!                        )
//!                    });
//!            }
//!        }
//!    }
//!}
//!```
//! 
//! # play
//! The implementation block of `script`struct, specifically 
//! the `play` associated (static) method responsible for 
//! continuously receiving `script` variants from 
//! a dedicated channel and `direct`ing them.
//! 
//! Also this function serves as the home for the Actor itself.
//! 
//! 
//!```rust no_run
//!impl MyActorScript { 
//!    pub fn play(receiver: std::sync::mpsc::Receiver<MyActorScript>, 
//!               mut actor: MyActor) {
//!        while let std::result::Result::Ok(msg) = receiver.recv() {
//!            msg.direct(&mut actor);
//!        }
//!        eprintln!("MyActor the end ...");
//!    }
//!}
//!``` 
//! 
//! When using the [`edit`](./attr.actor.html#edit) argument in the [`actor`](./attr.actor.html) 
//! macro, such as 
//! 
//!```rust no_run
//!#[interthread::actor(edit(script(imp(play))))]
//!``` 
//! 
//! it allows for manual implementation of the `play` part, which 
//! gives the flexibility to customize and modify 
//! the behavior of the `play` to suit any requared logic.
//! 
//! In addition the Debug trait is implemented for the `script`struct.
//!  
//! ```rust no_run
//!impl std::fmt::Debug for MyActorScript {
//!    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
//!        match self {
//!            MyActorScript::Increment { .. } => write!(f, "MyActorScript::Increment"),
//!            MyActorScript::AddNumber { .. } => write!(f, "MyActorScript::AddNumber"),
//!            MyActorScript::GetValue { .. } => write!(f, "MyActorScript::GetValue"),
//!        }
//!    }
//!}
//! ```
//! 
//! 
//! # live
//! A struct `ActorName + Live`, which serves as an interface/handler 
//! replicating the public method signatures of the original Actor.
//! 
//! Invoking a method on a live instance, it's triggering the eventual 
//! invocation of the corresponding method within the Actor. 
//! 
//! The special method of `live` method `new`  
//! - declares a new channel
//! - initiates an instace of the Actor
//! - spawns the `play` component in a separate thread 
//! - returns an instance of `Self`
//! 
//! 
//! ```rust no_run 
//! 
//!#[derive(Clone)]
//!pub struct MyActorLive {
//!    sender: std::sync::mpsc::Sender<MyActorScript>,
//!}
//!impl MyActorLive {
//!    pub fn new(v: i8) -> Self {
//!        let actor = MyActor::new(v);
//!        let (sender, receiver) = std::sync::mpsc::channel();
//!        std::thread::spawn(move || { MyActorScript::play(receiver, actor) });
//!        Self { sender }
//!    }
//!    pub fn increment(&mut self) {
//!        let msg = MyActorScript::Increment {};
//!        let _ = self
//!            .sender
//!            .send(msg)
//!            .expect("'MyActorLive::method.send'. Channel is closed!");
//!    }
//!    pub fn add_number(&mut self, num: i8) -> i8 {
//!        let (inter_send, inter_recv) = oneshot::channel();
//!        let msg = MyActorScript::AddNumber {
//!            num,
//!            inter_send,
//!        };
//!        let _ = self
//!            .sender
//!            .send(msg)
//!            .expect("'MyActorLive::method.send'. Channel is closed!");
//!        inter_recv
//!            .recv()
//!            .unwrap_or_else(|_error| {
//!                core::panic!("'MyActor::add_number' from inter_recv. Channel is closed!")
//!            })
//!    }
//!    pub fn get_value(&self) -> i8 {
//!        let (inter_send, inter_recv) = oneshot::channel();
//!        let msg = MyActorScript::GetValue {
//!            inter_send,
//!        };
//!        let _ = self
//!            .sender
//!            .send(msg)
//!            .expect("'MyActorLive::method.send'. Channel is closed!");
//!        inter_recv
//!            .recv()
//!            .unwrap_or_else(|_error| {
//!                core::panic!("'MyActor::get_value' from inter_recv. Channel is closed!")
//!            })
//!    }
//!}
//! 
//! ```
//! The methods of `live` type have same method signature
//! as Actor's own methods 
//! - declare a `oneshot` channel
//! - declare a `msg` specific `script` variant
//! - send the `msg` via `live`'s channel 
//! - receive and return the output if any   
//! 
//! # Panics
//! 
//! The model will panic if an attempt is made to send or 
//! receive on the channel after it has been dropped. 
//! Generally, such issues are unlikely to occur, but 
//! if the `interact` option is used, it introduces a 
//! potential scenario for encountering this situation.
//!  
//! 
//! # Macro Implicit Dependencies
//!
//! The [`actor`](./attr.actor.html) macro generates code
//! that utilizes channels for communication. However, 
//! the macro itself does not provide any channel implementations.
//! Therefore, depending on the libraries used in your project, 
//! you may need to import additional crates.
//!
//!### Crate Compatibility
//!<table>
//!  <thead>
//!    <tr>
//!      <th>lib</th>
//!      <th><a href="https://docs.rs/oneshot">oneshot</a></th>
//!      <th><a href="https://docs.rs/async-channel">async_channel</a></th>
//!    </tr>
//!  </thead>
//!  <tbody>
//!    <tr>
//!      <td>std</td>
//!      <td style="text-align: center;">&#10003;</td>
//!      <td style="text-align: center;"><b>-</b></td>
//!    </tr>
//!    <tr>
//!      <td><a href="https://crates.io/crates/smol">smol</a></td>
//!      <td style="text-align: center;">&#10003;</td>
//!      <td style="text-align: center;">&#10003;</td>
//!    </tr>
//!    <tr>
//!      <td><a href="https://docs.rs/tokio">tokio</a></td>
//!      <td style="text-align: center;"><b>-</b></td>
//!      <td style="text-align: center;"><b>-</b></td>
//!    </tr>
//!    <tr>
//!      <td><a href="https://crates.io/crates/async-std">async-std</a></td>
//!      <td style="text-align: center;">&#10003;</td>
//!      <td style="text-align: center;"><b>-</b></td>
//!    </tr>
//!  </tbody>
//!</table>
//!
//! 
//!>**Note:** The table shows the compatibility of 
//!>the macro with different libraries, indicating whether 
//!>the dependencies are needed (✔) or not. 
//!>The macros will provide helpful messages indicating 
//!>the necessary crate imports based on your project's dependencies.
//!
//! 
//! Checkout `interthread` on [![GitHub](https://img.shields.io/badge/GitHub-%2312100E.svg?&style=plastic&logo=GitHub&logoColor=white)](https://github.com/NimonSour/interthread)
//! 

mod use_macro;
mod show;
mod file;
mod check;
mod error;
mod parse;
mod model;

static INTERTHREAD: &'static str            = "interthread";
static INTER_EXAMPLE_DIR_NAME: &'static str = "INTER_EXAMPLE_DIR_NAME";
static INTER: &'static str                  = "inter";
static GROUP: &'static str                  = "group";
static ACTOR: &'static str                  = "actor";
static EXAMPLE: &'static str                = "example";
static EXAMPLES: &'static str               = "examples";


// vars
static INTER_SEND: &'static str = "inter_send";
static INTER_RECV: &'static str = "inter_recv";

// Some of Attributes Arguments
static EDIT: &'static str               = "edit";
static FILE: &'static str               = "file";



#[cfg(windows)]
const LINE_ENDING: &'static str = "\r\n";
#[cfg(not(windows))]
const LINE_ENDING: &'static str = "\n";

/// # Code transparency and exploration
///  
/// The [`example`](./attr.example.html) 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`](./attr.example.html) 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`](./attr.actor.html)  inside the project 
/// in `src/my_file.rs`.
/// 
///Filename: my_file.rs 
///```rust no_run
///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 
///```rust no_run
///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`](./attr.actor.html) macro expanded.
/// 
/// 
///```text
///my_project/
///├── src/
///│  ├── my_file.rs      <---  macro "actor" 
///|  |
///│  └── main.rs         <---  macro "example" 
///|
///├── examples/          
///   ├── ...
///   └── inter/      
///      ├── my_file.rs   <--- expanded "src/my_file.rs"  
///```
///
/// [`example`](./attr.example.html) 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`](##mod)  (default)
///  - [`main`](##main) 
///
/// ## mod 
/// The macro generates an example code file within the 
/// `examples/inter` directory. For example:
///
///```rust no_run
///#[example(path="my_file.rs")]
///```
///
/// This is equivalent to:
///
///```rust no_run
///#[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. 
///
///```rust no_run
///#[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:
///
///```terminal
///$ 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  
///```text 
/// 
///#[interthread::example( 
///   
///    mod ✔
///    main 
///
///    (   
///        path = "path/to/file.rs" ❗️ 
///
///        expand(actor,group) ✔
///    )
/// )]
/// 
/// 
/// default:    ✔
/// required:   ❗️
/// 
/// 
///```
/// 
/// # Arguments
/// 
/// - [`path`](#path)
/// - [`expand`](#expand) (default)
/// 
/// # path
/// 
/// 
/// The `path` argument is a required parameter of the [`example`](./attr.example.html) 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`](./attr.example.html) 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`](./attr.actor.html) and 
/// [`group`](./attr.group.html) macros.
/// 
/// For example, if you want to expand only the
/// [`actor`](./attr.actor.html) macro in generated 
/// example code, you can use the following attribute:
/// 
/// ```rust no_run
/// #[example(path="my_file.rs",expand(actor))]
/// ```
/// This will generate an example code file that includes 
/// the expanded code of the [`actor`](./attr.actor.html) macro,
/// while excluding other macros like 
/// [`group`](./attr.group.html).
/// 
 

#[proc_macro_error::proc_macro_error]
#[proc_macro_attribute]
pub fn example( attr: proc_macro::TokenStream, _item: proc_macro::TokenStream ) -> proc_macro::TokenStream {

    let mut eaa   = model::attribute::ExampleAttributeArguments::default();

    let aaa_parser = 
    syn::meta::parser(|meta| eaa.parse(meta));
    syn::parse_macro_input!(attr with aaa_parser);


    let (file, lib)  = file::expand_macros(&eaa.get_path(),&eaa.expand);

    let some_lib = if eaa.main { Some(lib)} else { None };

    let path = show::example_show(file, &eaa.get_path(), some_lib );

    let msg = format!("The file has been SUCCESSFULLY created at {}",path.to_string_lossy());
    let note  = "To avoid potential issues and improve maintainability, it is recommended to comment out the macro after its successful execution. To proceed, please comment out the macro and re-run the compilation.";
    
    proc_macro_error::abort!( proc_macro2::Span::call_site(),msg; note = note);
    
}

 
/// ## Evolves a regular object into an actor
/// 
/// The macro is placed upon an implement block of an object
///  (`struct` or `enum`),
/// which has a public or restricted method named `new` returning  `Self`.
///
/// In case if the initialization could potentially fail, 
/// the method can be named `try_new` 
/// and return `Option<Self>` or `Result<Self>`.
/// 
/// The macro will copy method signatures from all 
/// public methods that do not consume the receiver, excluding 
/// methods like `pub fn foo(self, val: u8) -> ()` where `self` 
/// is consumed. Please ensure that the 
/// receiver is defined as `&mut self` or `&self`. 
/// 
/// If only a subset of methods is required to be 
/// accessible across threads, split the `impl` block 
/// into two parts. By applying the macro to a specific block, 
/// the macro will only consider the methods within that block, also see options
/// [`include-exclude`](#include-exclude).
/// 
/// ## Configuration Options
///```text 
/// 
///#[interthread::actor( 
///    
///    channel = 0 * 
///              n (usize)
///
///        lib = "std" *
///              "smol"
///              "tokio"
///              "async_std"
///
///        edit( 
///             script(..)
///             live(..)
///            ) 
///
///        file = "path/to/current/file.rs"
///        
///        name = "" 
///
///        show
///       
///       include | exclude  
///        
///       debut(
///             legend
///            ) 
///    interact
///)]
///
///*  -  default 
///
///
///```
///  
/// # Arguments
///  
///
/// - [`channel`](#channel)
/// - [`lib`](#lib) 
/// - [`edit`](#edit)
/// - [`file`](#file)
/// - [`name`](#name)
/// - [`show`](#show)
/// - [`include|exclude`](#include|exclude)
/// - [`debut`](#debut)
/// - [`interact`](#interact)
///
/// 
/// 
/// # channel
///
/// The `channel` argument specifies the type of channel. 
///   
/// - `0`  (default)
/// - [`usize`] ( buffer size)
/// 
/// The two macros
/// ```rust no_run
/// #[actor]
/// ```
/// and
/// ```rust no_run
/// #[actor(channel=0)]
/// ```
/// are in fact identical, both specifying same unbounded channel.
/// 
/// When specifying an [`usize`] value for the `channel` argument 
/// in the [`actor`](./attr.actor.html) macro, such as 
/// ```rust no_run
/// #[actor(channel=4)]
/// ```
/// the actor will use a bounded channel with a buffer size of 4.
/// This means that the channel can hold up to 4 messages in its 
/// buffer before blocking/suspending the sender.
///
/// Using a bounded channel with a specific buffer size allows 
/// for control over the memory usage and backpressure behavior 
/// of the model. When the buffer is full, any further attempts 
/// to send messages will block/suspend until there is available space. 
/// This provides a natural form of backpressure, allowing the 
/// sender to slow down or pause message production when the 
/// buffer is near capacity.
/// 
/// # lib
///
/// The `lib` argument specifies the 'async' library to use.
///
/// - `"std"` (default)
/// - `"smol"`
/// - `"tokio"`
/// - `"async_std"`
///
///## Examples
///```rust no_run
///use interthread::actor;
///
///struct MyActor;
///
///#[actor(channel=10, lib ="tokio")]
///impl MyActor{
///    pub fn new() -> Self{Self}
///}
///#[tokio::main]
///async fn main(){
///    let my_act = MyActorLive::new();
///}
///```
/// 
/// # edit
///
/// The `edit` argument specifies the available editing options.
/// When using this argument, the macro expansion will 
/// **exclude** the code related to `edit` options 
/// allowing the user to manually implement and 
/// customize those parts according to their specific needs.
/// 
/// 
/// The SDPL Model encompasses two main structs, namely `ActorScript` and `ActorLive`.
/// Within the `edit` statement, these are referenced as `script` 
/// and `live` respectively.
/// 
/// Each struct comprises three distinct sections: 
/// - `def` - definition
/// - `imp` - implementation block
/// - `trt` - implemented traits
///
/// ```rust no_run
/// edit(
///     script(
///         def,     // <- script definition
///         imp(..), // <- list of methods in impl block
///         trt(..)  // <- list of traits
///     ),
///     
///     live(
///         def,     // <- live definition
///         imp(..), // <- list of methods in impl block
///         trt(..)  // <- list of traits
///     )
/// )
/// ```
/// 
/// So this option instructs the macro to:
/// 
/// - Exclude specified sections of code from the generated model.
/// 
/// Examples:
/// - `edit(script)`: Excludes the entire Script enum.
/// - `edit(live(imp))`: Excludes the entire implementation block of the Live struct.
/// - `edit(live(def, imp(new)))`: Excludes both the definition of the Live struct and the method 'new.'
/// - `edit(script(imp(play)), live(imp(new)))`: Excludes the 'play' method from the Script enum and the 'new' method from the Live struct.
/// 
/// Exclusion of code becomes necessary when the user has already 
/// customized specific sections of the model. 
/// To facilitate the exclusion of parts from the generated 
/// model and enable printing them to the file for further 
/// user customization, consider the [`file`](#file) option,
/// which works in conjunction with the `edit` option.
/// 
/// # file
/// This argument is designed to address proc macro file blindness. It requires 
/// a string path to the current file as its value. Additionally, within the `edit` argument,
/// one can use the keyword `file` to specify which portion of the excluded code should be written
/// to the current module, providing the user with a starting point for customization.
///  
///  
/// ## Examples
/// 
/// Filename: main.rs
/// 
///```rust no_run
///pub struct MyActor(u8);
///
///#[interthread::actor(
///    file="src/main.rs",
///    edit(live(imp( file(increment) )))
///)]  
///
///impl MyActor {
///
///    pub fn new() -> Self {Self(0)}
///
///    pub fn increment(&mut self){
///        self.0 += 1;
///    }
///}
///```
/// This is the output after saving:
/// 
/// ```rust no_run
///
///pub struct MyActor(u8);
///
///#[interthread::actor(
///    file="src/main.rs",
///    edit(live(imp(increment)))
///)]  
///
///impl MyActor {
///
///    pub fn new() -> Self {Self(0)}
///
///    pub fn increment(&mut self){
///        self.0 += 1;
///    }
///}
///
/// //++++++++++++++++++[ Interthread  Write to File ]+++++++++++++++++//
/// // Object Name   : MyActor  
/// // Initiated By  : #[interthread::actor(file="src/main.rs",edit(live(imp(file(increment)))))]  
/// 
/// 
/// impl MyActorLive {
///     pub fn increment(&mut self) {
///         let msg = MyActorScript::Increment {};
///         let _ = self
///             .sender
///             .send(msg)
///             .expect("'MyActorLive::method.send'. Channel is closed!");
///     }
/// }
/// 
/// // *///.............[ Interthread  End of Write  ].................//
///
/// ```
/// 
/// To specify the part of your model that should be written to 
/// the file, simply enclose it within `file(..)` inside the `edit` 
/// argument. Once the desired model parts are written, 
/// the macro will automatically clean the `file` arguments, 
/// adjusting itself to the correct state.
/// 
/// 
/// Attempting to nest `file` arguments like: 
/// ```rust no_run
/// edit( file( script( file( def))))
/// ```
/// will result in an error.
/// 
/// 
/// A special case of the `edit` and `file` conjunction, 
/// using `edit(file)` results in the macro being replaced with 
/// the generated code on the file.
/// 
/// 
/// 
///  > **Note:** While it is possible to have multiple actor macros
/// within the same module, only one of the macro can have `file` 
/// active arguments (`file` within `edit`) at a time.
/// 
/// 
/// # name
/// 
/// The `name` attribute allows developers to provide a 
/// custom name for `actor`, overriding the default 
/// naming conventions of the crate. This can be useful 
/// when there are naming conflicts or when a specific 
/// naming scheme is desired.  
/// 
/// - "" (default): No name specified
///
/// ## Examples
///```rust no_run
///use interthread::actor;
/// 
///pub struct MyActor;
/// 
///#[actor(name="OtherActor")]
///impl MyActor {
///
///   pub fn new() -> Self {Self}
///}
///fn main () {
///   let other_act = OtherActorLive::new();
///}
///```
/// 
/// 
/// 
/// # show 
/// 
/// The `show` option is particularly useful for users who are just starting to 
/// work with this crate. When enabled, the model will generate doc comments 
/// for every block of code it produces, containing the code produce, with the 
/// exception of traits, which are simply listed.
/// 
/// Your text editor handles the rest.
/// 
/// By default, the model carries over the user's documentation comments from 
/// the actor object methods. 
/// Enabling `show` will add additional information, detailing the exact 
/// code generated by the model.
/// Try hovering over `AaLive` and its `new` method to see the generated code.
/// 
///  ## Examples
///```rust no_run
///use interthread::actor;
///pub struct Aa;
///  
///#[actor(show)]
///impl Aa {
///    /// This is my comment
///    /// Creates a new instance of AaLive.
///    pub fn new() -> Self { Self{} }
/// 
///}
///
///fn main() {    
///    let bb = AaLive::new(); 
///}
///
///```
/// Disable `show` to avoid performance overhead and excessive code generation, 
/// when the option is no longer needed.
/// 
///  
/// # include-exclude
/// The include and exclude options are mutually exclusive filters that control 
/// which methods are included in the generated model. Only one of these 
/// options can be used at a time.
/// 
/// Usage
/// 
/// - include: Specifies the methods to include in the generated model.
/// - exclude: Specifies the methods to exclude from the generated model.
/// 
/// For a given list of actor's methods `[a, b, c, d]`:
/// 
/// - Using `include(a)` will generate a model that only includes the method `a`.
/// - Using `exclude(a,b)` will generate a model that includes the methods `c`, and `d`.
/// 
/// ```rust no_run
/// #[interthread::actor( exclude(foo,bar))]
/// ```
/// 
/// # debut
/// 
/// The generated code is designed to 
/// compile successfully on Rust versions as early as 1.63.0.
/// 
/// When declared `debut`, the following additions and implementations 
/// are generated:
/// 
/// 
/// Within the [`live`](index.html#live) struct definition, the following
/// fields are generated:
/// 
/// - `pub debut: std::time::SystemTime`
/// - `pub name: String`
/// 
/// The following traits are implemented for the [`live`](index.html#live) struct:
/// 
/// - `PartialEq`
/// - `PartialOrd`
/// - `Eq`
/// - `Ord`
/// 
/// These traits allow for equality and ordering 
/// comparisons based on the `debut`value.
/// The `name` field is provided for user needs only and is not 
/// taken into account when performing comparisons. 
/// It serves as a descriptive attribute or label 
/// associated with each instance of the live struct.
/// 
/// In the [`script`](index.html#script) struct implementation block, which 
/// encapsulates the functionality of the model,
/// a static method named `debut` is generated. This 
/// method returns the current system time and is commonly 
/// used to set the `debut` field when initializing 
/// instances of the [`live`](index.html#live) struct.
/// 
/// 
/// Use macro [`example`](./attr.example.html) to see the generated code.
/// 
/// 
/// ## Examples
///  
///```rust no_run
///use std::thread::spawn;
///pub struct MyActor ;
///
///#[interthread::actor( debut )] 
///impl MyActor {
///    pub fn new() -> Self { Self{} } 
///}
///fn main() {
///
///    let actor_1 = MyActorLive::new();
///
///    let handle_2 = spawn( move || { 
///        MyActorLive::new()
///    });
///    let actor_2 = handle_2.join().unwrap();
///
///    let handle_3 = spawn( move || {
///        MyActorLive::new()
///    });
///    let actor_3 = handle_3.join().unwrap();
///    
///    // they are the same type objects
///    // but serving differrent threads
///    // different actors !   
///    assert!(actor_1 != actor_2);
///    assert!(actor_2 != actor_3);
///    assert!(actor_3 != actor_1);
///
///    // since we know the order of invocation
///    // we correctly presume
///    assert_eq!(actor_1 > actor_2, true );
///    assert_eq!(actor_2 > actor_3, true );
///    assert_eq!(actor_3 < actor_1, true );
///
///    // but if we check the order by `debute` value
///    assert_eq!(actor_1.debut < actor_2.debut, true );
///    assert_eq!(actor_2.debut < actor_3.debut, true );
///    assert_eq!(actor_3.debut > actor_1.debut, true );
///    
///    // This is because the 'debut' 
///    // is a time record of initiation
///    // Charles S Chaplin (1889)
///    // Keanu Reeves      (1964)
///
///
///    // we can count `live` instances for 
///    // every model
///    use std::sync::Arc;
///    let mut a11 = actor_1.clone();
///    let mut a12 = actor_1.clone();
///
///    let mut a31 = actor_3.clone();
///
///    assert_eq!(Arc::strong_count(&actor_1.debut), 3 );
///    assert_eq!(Arc::strong_count(&actor_2.debut), 1 );
///    assert_eq!(Arc::strong_count(&actor_3.debut), 2 );
///            
///
///    // or use getter `count`                 
///    assert_eq!(actor_1.inter_get_count(), 3 );
///    assert_eq!(actor_2.inter_get_count(), 1 );
///    assert_eq!(actor_3.inter_get_count(), 2 );
///    
///
///    use std::time::SystemTime;
///
///    // getter `debut` to get its timestamp   
///    let _debut1: SystemTime = actor_1.inter_get_debut();
///
///            
///    // the name field is not taken 
///    // into account when comparison is
///    // perfomed       
///    assert!( a11 == a12);
///    assert!( a11 != a31);
///
///    a11.name = String::from("Alice");
///    a12.name = String::from("Bob");
///
///    a31.name = String::from("Alice");
///
///    assert_eq!(a11 == a12, true );
///    assert_eq!(a11 != a31, true );
///
///    // setter `name` accepts any ToString  
///    a11.inter_set_name('t');
///    a12.inter_set_name(84u32);
///    a31.inter_set_name(3.14159);
///
///    // getter `name`                      
///    assert_eq!(a11.inter_get_name(), "t" );
///    assert_eq!(a12.inter_get_name(), "84" );
///    assert_eq!(a31.inter_get_name(), "3.14159" );
///
///}
///``` 
/// 
/// 
/// 
/// 
/// Using `debut` will generate fore additional
///methods in `live` implement block:
/// 
/// 1. `inter_set_name(s: ToString)`: Sets the value of the 
/// name field.
/// 2. `inter_get_name() -> &str`: Retrieves the value of the 
/// name field.
/// 3. `inter_get_debut() -> std::time::SystemTime`: Retrieves
/// the value of the debut field, which represents a timestamp.
/// 4. `inter_get_count() -> usize`: Provides the strong 
/// reference count for the debut field.
///  
/// > **Note:** Additional generated methods prefixed with `inter`
///  will have the same visibility as the initiating
///  method `new` or `try_new`. 
/// 
///This convention allows 
///- easy identification in text editor methods that 
///solely manipulate the internal state of the live struct and/or 
///methods that are added by the `interthread` macros
///- it mitigates the risk of potential naming conflicts in case if there
///is or will be a custom method `get_name`
///-  helps the macro  identify methods that are intended 
///to be used within its context (see [`interact`](#interact))
///
/// 
/// While `debut` can be declared as a standalone option, 
/// it can also be enhanced by adding the `legend` sub-option. 
/// This sub-option introduces extra `inter` methods, 
/// enabling the model to be saved on the heap upon the 
/// last instance being dropped.
///
/// > **Note:** Unfortunately, while we've established a 
/// consistent `inter` prefix method convention, the 
/// `legend` functionality introduces an exception. 
/// To maintain a coherent and orderly pattern `try_new` -> `try_old` 
/// 
/// 
///# Examples
///
///```rust no_run
/// pub struct MyActor(u8);
///
///
///#[interthread::actor( debut(legend) )] 
///impl MyActor {
///
///    pub fn new() -> Self { Self(0) }
///
///    pub fn set(&mut self, v: u8){
///        self.0 = v;
///    } 
///
///    pub fn get_value(&self) -> u8 {
///        self.0
///    }
///}
///
///
///fn main() {
///
///    let h = std::thread::spawn( || {
///        let mut act = MyActorLive::new();
///        act.inter_set_name("Zombie"); 
///        act.set(121);
///    });
///    
///    let _ = h.join();
///
///    let old_act = MyActorLive::try_old("Zombie").unwrap();
///
///    assert_eq!("Zombie".to_string(), old_act.inter_get_name());
///    assert_eq!(121u8, old_act.get_value());
///}
///
///```
/// When the thread scope ends, objects are dropped. Simply using 
/// `drop(..)` won't suffice. To conclude the thread scope correctly, 
/// use `join()`. Then, you can call `try_old` on the live struct 
/// to reinitialize the old model.
/// 
/// # interact
/// 
/// The `interact` option is designed to provide the model with 
/// comprehensive non-blocking functionality, along with convenient 
/// internal getter calls to access the state of the `live` instance via
/// so called `inter variables` in actor methods.
/// 
/// ### Rules and Definitions
/// 
/// 1. The interact variables should be prefixed with `inter_`.
/// 2. Special interact variables are `inter_send` and `inter_recv`.
/// 3. Declaring an `inter_variable_name : Type`, within actor method
/// arguments implies that the `live` instance has a method 
/// `fn inter_get_variable_name(&self) -> Type` which takes no arguments 
/// and returns the `Type`. Exceptions to this rule apply for special 
/// interact variables.
/// 4. If the actor method returns a type, accessing special interact variables
/// is not allowed. 
/// 5. Only one end of special interact variables can be accessed at a time.
///  
/// 
/// 
/// The primary purpose of `interact` is to leverage its oneshot `inter_send` 
/// and `inter_recv` ends. This allows for
/// a form of non-blocking behavior: one end of the channel will be directly 
/// sent into the respective method, while the other end will be returned 
/// from the live instance method. 
/// 
/// 
/// ## Examples
/// ```rust no_run
/// 
///pub struct MyActor;
///
///// opt `interact`
///#[interthread::actor( interact )] 
///impl MyActor {
///
///    pub fn new() -> Self { Self{} } 
///
///    // oneshot channel can be accessed 
///    // in methods that do not return 
///    pub fn heavy_work(&self, inter_send: oneshot::Sender<u8>){
///
///        std::thread::spawn(move||{
///            // do some havy computation
///            let _ = inter_send.send(5);
///        });
///    }
///}
///
///fn main () {
///
///    let actor = MyActorLive::new();
/// 
///    // the signature is different
///    let recv: oneshot::Receiver<u8> = actor.heavy_work(); 
///    let int = recv.recv().unwrap();
///
///    assert_eq!(5u8, int);
///}
/// 
/// ``` 
///  
/// While a method that does not return a type (see original `heavy_work`) 
/// typically does not require a oneshot channel, the 
/// model will accommodate the user's request by instantiating 
/// a channel pair. 
/// 
///```rust no_run
/// 
///pub fn heavy_work(&self) -> oneshot::Receiver<u8> {
///    let (inter_send, inter_recv) = oneshot::channel::<u8>();
///    let msg = MyActorScript::HeavyWork {
///        input: (inter_send),
///    };
///    let _ = self
///        .sender
///        .send(msg)
///        .expect("'MyActorLive::method.send'. Channel is closed!");
///    inter_recv
///}
///``` 
/// 
/// 
/// Also `interact` will detect interact variables in actor methods 
/// and subsequently call required getters within respective 
/// method of the `live` instance.
/// 
/// ## Examples
/// ```rust no_run
/// pub struct MyActor(String);
///
/// #[interthread::actor(debut, interact )] 
/// impl MyActor {
///
///     pub fn new() -> Self { Self("".to_string()) } 
///
///     // We know there is a getter `inter_get_name`
///     // Using argument `inter_name` we imply
///     // we want the return type of that getter
///     pub fn set_value(&mut self, inter_name: String){
///         self.0 = inter_name;
///     }
///     pub fn get_value(&self) -> String {
///         self.0.clone()
///     }
/// }
///
/// fn main () {
///
///     let mut actor = MyActorLive::new();
///
///     // Setting name for `live` instance
///     actor.inter_set_name("cloud");
///
///     // Setting actor's value now
///     // Note the signature, it's not the same  
///     actor.set_value();
///
///     assert_eq!("cloud".to_string(), actor.get_value());
/// }
/// ```
/// 
/// 
/// Here is how `live` instance method `set_value` will look like:
/// 
/// 
/// ```rust no_run
/// 
/// pub fn set_value(&mut self) {
///     let inter_name = self.inter_get_name();
///     let msg = MyActorScript::SetValue {
///         input: inter_name,
///     };
///     let _ = self
///         .sender
///         .send(msg)
///         .expect("'MyActorLive::method.send'. Channel is closed!");
/// }
/// 
/// ```
/// 
/// 
/// The signature has changed; it no longer takes arguments, as the 
/// getter call is happening inside providing the required type. 
/// It will work for any custom getter as long as it adheres to rule 3.
/// 
/// 
/// 
/// 
/// 


#[proc_macro_error::proc_macro_error]
#[proc_macro_attribute]
pub fn actor( attr: proc_macro::TokenStream, item: proc_macro::TokenStream ) -> proc_macro::TokenStream {
    
    let item_impl = syn::parse_macro_input!(item as syn::ItemImpl);

    let mut aaa = model::attribute::ActorAttributeArguments::default();
    let nested  = syn::parse_macro_input!(attr with syn::punctuated::Punctuated::<syn::Meta,syn::Token![,]>::parse_terminated); 
    aaa.parse_nested(nested);
    aaa.cross_check();

    check::channels_import( &aaa.lib );

    let edit_attr = aaa.edit.attr.clone();

    let aa = crate::model::AttributeArguments::Actor(aaa);

    let model_sdpl = crate::model::generate_model( aa,&item_impl,None);
    
    let (_,edit_sdpl) = model_sdpl.split();

    if let Some( edit_attr ) = edit_attr {

        parse::edit_write( &edit_attr, &item_impl, edit_sdpl);
    }

    let (code,_) = model_sdpl.get_code_edit();

    quote::quote!{
        #item_impl
        #code
    }.into()


}


/// ## A set of actors sharing  a single thread
///
/// In the realm of concurrent programming, creating a separate thread 
/// for each individual actor can sometimes incur a significant overhead. 
/// In such scenarios, developers may opt to populate an `actor`'s 
/// definition with complex encapsulations (potential actors), 
/// effectively creating a collection of objects running within 
/// a single thread. While this approach proves resource-efficient, 
/// it does come with a trade-off: accessing the methods of field 
/// types must be explicitly written within the main `actor` 
/// implementation block.
/// 
/// This is where the `group` macro comes into play. A `group` is a 
/// set of `actors` that share a single thread, consisting of 
/// a `main-actor` and `group-actors` contained within the 
/// `main-actor`'s fields. Developers can now bypass the need to rewrite 
/// method wrappers, gaining direct access to `group-actor` methods via 
/// dot notation, as seamlessly as if these `group-actors` were `actors` 
/// in their own right.
/// 
/// In this scenario, the methods of the `main-actor` take on the responsibility 
/// for interaction within and between `group-actors`, while the latter primarily 
/// serve to export their functionality. 
/// 
/// Before delving into further details, let's explore an example of a `group`. 
/// Assuming there is a good understanding of how an `actor` operates, once the 
/// `Live` instance is returned after invoking the `new` method, the `actor` is 
/// already running in a separate thread. Therefore, there’s no need to 
/// complicate the example with extra thread spawning just for visual clarity. 
/// 
/// 
/// ## Examples
///  
///```rust no_run
///
///// We have `Aa` and `Bb`
///pub struct Aa(u8);
///impl Aa {
///    pub fn add(&mut self, v: u8){
///        self.0 += v;
///    }
///}
///
///pub struct Bb(u8);
///impl Bb {
///    pub fn add(&mut self, v: u8){
///        self.0 += v;
///    }
///}
///
///// Definition of group
///pub struct AaBb {
///    pub a: Aa,
///    pub b: Bb,
///}
///
///#[interthread::group( file= "path/to/file.rs")]
///impl AaBb {
///
///    pub fn new( ) -> Self {
///        let a = Aa(0);
///        let b = Bb(0);
///        Self{ a,b}
///    }
///
///    pub fn add(&mut self, v:u8){
///        self.a.0 += v;
///        self.b.0 += v;
///    }
///
///    pub fn get_value(&mut self) -> (u8,u8) {
///        (self.a.0,self.b.0)
///    }
///}
///
///
///pub fn main(){
///
///    let mut group = AaBbGroupLive::new();
///    
///    // access to group method
///    group.add(1);
///    assert_eq!((1,1),group.get_value());
///
///    // access to field `a` method
///    group.a.add(10);
///    assert_eq!((11,1),group.get_value());
///
///    // access to field `b` method
///    group.b.add(100);
///    assert_eq!((11,101),group.get_value());
///}
///
///```
///
/// Behind the scenes, the macro will generate some additional types 
/// very similar to `actor`'s types, for `group-actor` 
/// `NameScriptGroup` and  `NameLiveGroup`:
///
///- `Aa` -       `AaScriptGroup`, `AaLiveGroup`
///- `Bb` -       `BbScriptGroup`, `BbLiveGroup`
///
/// For `main-actor` itself: `NameGroupScript` and  `NameGroupLive`:
///- `AaBb` -     `AaBbGroupScript`, `AaBbGroupLive` 
///
/// In the context of the `SDPL` framework, `group-actors` are designated as `SDL`
/// (Script, Direct, Live) and will share the `play` method with the `main-actor`,
/// which is full `SDPL`.
/// The following is a type schema of the `group` model in relation 
/// to the above example:
///  
/// ```rust no_run
/// 
/// struct Aa;
/// struct Bb;
/// 
/// enum AaScriptGroup;
/// struct AaLiveGroup;
/// 
/// enum BbScriptGroup;
/// struct BbLiveGroup;
/// 
/// struct AaBb {
///     pub a: Aa,
///     pub b: Bb,
/// }
/// 
/// enum AaBbGroupScript;
/// struct AaBbGroupLive {
///     pub a: AaLiveGroup,
///     pub b: BbLiveGroup,
/// }
/// 
/// ```
///
/// To view all the generated code by `group`, you can either utilize 
/// the [`example`](attr.example.html) macro or employ the 
/// [`edit`](attr.actor.html#edit) option within the `group` macro. 
/// For a convenient shortcut to see the full example using `edit`,
/// simply use `edit(file)`."
/// 
/// ```rust no_run
/// #[interthread::group( file="path/to/file.rs",edit(file))]
/// ```
/// To inspect the generated code for field `a` type from the 
/// above example, utilize the [`edit`](attr.actor.html#edit)
/// option as `edit(a::edit(file))`, for struct `AaBb` itself
/// use `edit(self::edit(file))`. 
/// 
/// ## Requirements for Using the `group` Macro
/// 
/// Much like individual actors, the `group` macro enables a 
/// set of actors to run collectively within a shared thread. 
/// While many requirements align with those of individual actors, 
/// there are some distinctions to be aware of. Below are the 
/// crucial conditions that need to be satisfied for the `group` 
/// macro to operate :
/// 
///- The object must be a struct with named fields.
///- As an `actor` impl block must contain a method named `new` 
///  returning a self-instance or `try_new` if it may fail to return.
///- The macro requires a `file` field with a file path to the 
///  current file at all times.
///- Fields in the definition block that are intended to act as 
///  `group-actor`s should have non-private visibility (public or restricted).
///  Private fields will not be considered as `group-actors` by the macro.
///
/// 
/// ## Configuration Options
/// The configuration options for a `group` are slightly different, 
/// but consist of the same arguments as those used for an `actor`
/// except couple of them.
/// In some cases (see notation `(AA)` in the table below), 
/// the argument is a list of the same arguments, specified as 
/// `argument(field_name::argument,..)`. 
/// In context of the example code from above, if we wanted to 
/// include any hypothetical static (associated) methods of struct `Aa`,
/// we would use the `show` argument, like so: 
/// ```rust 
/// show(a::show)
/// ```
/// To include the same argument for `main-actor` itself, we would write 
/// ```rust 
/// show(a::show, self::show)
/// ```
/// 
/// The following is the full table of configuration options:
/// 
/// ```text
///
/// #[interthread::group( 
///    
/// AA  channel = 0 * 
///              n (usize)
///
/// AA      lib = "std" *
///               "smol"
///               "tokio"
///               "async_std"
///
/// AA     file = "path/to/current/file.rs"
///
/// AA     debut(
///             legend
///             )
///    
/// AA      skip(
///             field_name
///             ..
///             )
///  
/// (AA)   show(
///             self::show,
///             ..
///             )
/// 
/// (AA) include(
///             self::include(
///                           method_name,
///                           ..
///                          ),
///             ..
///             )
/// 
/// (AA) exclude(
///             self::exclude(
///                           method_name,
///                           ..
///                          ),
///             ..
///             )
///
/// (AA)    edit( 
///             self::edit(
///                       script(..)
///                       live(..)
///                       ),
///             ..
///             ) 
///
/// (AA)    name(
///             self::name = "",
///             ..
///             )
///
/// (AA)    path(
///             a::path = "path/to/type.rs",
///             ..
///             )      
///    )
/// ]
///
///   *     -  default 
///   AA    -  similar to `actor` attribute argument.
///  (AA)   -  a list of similar to `actor` attribute arguments.
///
/// ```
/// All `group` configuration options (arguments) are the same as `actor`'s arguments, 
/// except for `path` and `skip`, which are unique to `group`.

/// # Arguments
///  
/// - [`channel`](attr.actor.html#channel)
/// - [`lib`](attr.actor.html#lib) 
/// - [`edit`](attr.actor.html#edit)
/// - [`file`](attr.actor.html#file)
/// - [`name`](attr.actor.html#name)
/// - [`show`](attr.actor.html#show)
/// - [`include|exclude`](attr.actor.html#include|exclude)
/// - [`debut`](attr.actor.html#debut)
/// - [`path`](#path)
/// - [`skip`](#skip)

/// # `path`
/// Argument `path` is used when a `group-actor` is defined in a file different from the `group` itself.

/// # `skip`
/// Argument `skip` is used when a non-private field of the `group` is necessary but should not be included 
/// as a `group-actor`.
///
/// 
/// 
/// # Handling Identical Types in the `group` Model
/// 
/// In certain situations, the `group` model may encounter a scenario where the `main-actor` 
/// possesses multiple fields of the same type. Let's consider an example:
/// 
/// ```rust
/// struct AaBb {
///     pub a:  Aa,
///     pub a1: Aa,
///     pub b:  Bb,
/// }
/// ```
/// 
/// Due to the model naming convention which is based on type names, both fields `a` and `a1` generate 
/// identical model names for both the `Script` and `Live` components. This leads to a 
/// compilation error:
/// 
/// ```text
/// the name `AaScriptGroup` is defined multiple times
/// `AaScriptGroup` must be defined only once in the type namespace of this module
/// ``` 
/// 
/// To resolve this scenario, adjust the names for identical types as follows:
/// 
///```rust no_run
/// struct AaBb {
///     pub a:  Aa,
///     pub a1: Aa,
///     pub b:  Bb,
/// }
/// 
/// // Usage of the macro may be as follows:
/// 
/// #[interthread::group(
///     file="path/to/file.rs",
///     name( a1::name="Aa1" )
/// )]
/// impl AaBb {
///     // ...
/// }
/// 
/// ```
/// 
/// 
/// 

#[proc_macro_error::proc_macro_error]
#[proc_macro_attribute]
pub fn group( attr: proc_macro::TokenStream, item: proc_macro::TokenStream ) -> proc_macro::TokenStream {

    let item_impl = syn::parse_macro_input!(item as syn::ItemImpl);

    let mut gaa = model::attribute::GroupAttributeArguments::default();
    let nested  = syn::parse_macro_input!(attr with syn::punctuated::Punctuated::<syn::Meta,syn::Token![,]>::parse_terminated); 
    gaa.parse_nested(nested);
    gaa.cross_check(&item_impl);
    
    
    check::channels_import( &gaa.lib );

     let edit_attr = gaa.edit.attr.clone();

    let aa = crate::model::AttributeArguments::Group(gaa);

    let model_sdpl = crate::model::generate_model( aa,&item_impl,None);

    let (_,edit_sdpl) = model_sdpl.split();

    if let Some( edit_attr ) = edit_attr {
        parse::edit_write( &edit_attr, &item_impl, edit_sdpl);
    }

    let (code,_) = model_sdpl.get_code_edit();

    quote::quote!{
        #item_impl
        #code
    }.into()

}