former : making subforming more friendly

module/core/former/Readme.md

@@ -86,9 +86,9 @@ pub struct UserProfile
 impl UserProfile
 {
   #[ inline( always ) ]
-  pub fn former() -> UserProfileFormer< UserProfile, former::ReturnFormed >
+  pub fn former() -> UserProfileFormer< UserProfile, former::ReturnStorage >
   {
-    UserProfileFormer::< UserProfile, former::ReturnFormed >::new()
+    UserProfileFormer::< UserProfile, former::ReturnStorage >::new()
   }
 }
 
@@ -103,7 +103,7 @@ pub struct UserProfileFormerStorage
 pub struct UserProfileFormer
 <
   Context = UserProfile,
-  End = former::ReturnFormed,
+  End = former::ReturnStorage,
 >
 where
   End : former::FormingEnd< UserProfile, Context >,
@@ -205,9 +205,9 @@ where
   }
 
   #[ inline( always ) ]
-  pub fn new() -> UserProfileFormer< UserProfile, former::ReturnFormed >
+  pub fn new() -> UserProfileFormer< UserProfile, former::ReturnStorage >
   {
-    UserProfileFormer::< UserProfile, former::ReturnFormed >::begin( None, former::ReturnFormed )
+    UserProfileFormer::< UserProfile, former::ReturnStorage >::begin( None, former::ReturnStorage )
   }
 
   #[ inline( always ) ]
@@ -226,7 +226,7 @@ where
   }
 
   #[ inline( always ) ]
-  pub fn end( mut self ) -> Context
+  pub fn end( mut self ) -> Formed
   {
     let on_end = self.on_end.take().unwrap();
     let context = self.context.take();

module/core/former/examples/former_trivial_expaned.rs

@@ -38,9 +38,9 @@ fn main()
   impl UserProfile
   {
     #[ inline( always ) ]
-    pub fn former() -> UserProfileFormer< UserProfile, former::ReturnFormed >
+    pub fn former() -> UserProfileFormer< UserProfile, former::ReturnStorage >
     {
-      UserProfileFormer::< UserProfile, former::ReturnFormed >::new()
+      UserProfileFormer::< UserProfile, former::ReturnStorage >::new()
     }
   }
 
@@ -55,7 +55,7 @@ fn main()
   pub struct UserProfileFormer
   <
     Context = UserProfile,
-    End = former::ReturnFormed,
+    End = former::ReturnStorage,
   >
   where
     End : former::FormingEnd< UserProfile, Context >,
@@ -157,9 +157,9 @@ fn main()
     }
 
     #[ inline( always ) ]
-    pub fn new() -> UserProfileFormer< UserProfile, former::ReturnFormed >
+    pub fn new() -> UserProfileFormer< UserProfile, former::ReturnStorage >
     {
-      UserProfileFormer::< UserProfile, former::ReturnFormed >::begin( None, former::ReturnFormed )
+      UserProfileFormer::< UserProfile, former::ReturnStorage >::begin( None, former::ReturnStorage )
     }
 
     #[ inline( always ) ]
@@ -178,7 +178,7 @@ fn main()
     }
 
     #[ inline( always ) ]
-    pub fn end( mut self ) -> Context
+    pub fn end( mut self ) -> Formed
     {
       let on_end = self.on_end.take().unwrap();
       let context = self.context.take();

module/core/former/src/axiomatic.rs

@@ -6,9 +6,9 @@
 /// Implementors can define how to transform or pass through the context during the forming process's completion.
 ///
 /// # Parameters
-/// - `Formed`: The type of the container being processed.
+/// - `Storage`: The type of the container being processed.
 /// - `Context`: The type of the context that might be altered or returned upon completion.
-pub trait FormingEnd< Formed, Context >
+pub trait FormingEnd< Storage, Context, Formed >
 {
   /// Called at the end of the subforming process to return the modified or original context.
   ///
@@ -18,21 +18,40 @@ pub trait FormingEnd< Formed, Context >
   ///
   /// # Returns
   /// Returns the transformed or original context based on the implementation.
-  #[ allow( dead_code ) ]
-  fn call( &self, storage : Formed, context : core::option::Option< Context > ) -> Context;
+  // #[ allow( dead_code ) ]
+  fn call( &self, storage : Storage, context : core::option::Option< Context > ) -> Formed;
 }
 
-impl< Storage, Context, F > FormingEnd< Storage, Context > for F
+impl< Storage, Context, Formed, F > FormingEnd< Storage, Context, Formed > for F
 where
-  F : Fn( Storage, core::option::Option< Context > ) -> Context,
+  F : Fn( Storage, core::option::Option< Context > ) -> Formed,
 {
   #[ inline( always ) ]
-  fn call( &self, storage : Storage, context : core::option::Option< Context > ) -> Context
+  fn call( &self, storage : Storage, context : core::option::Option< Context > ) -> Formed
   {
     self( storage, context )
   }
 }
 
+/// A `FormingEnd` implementation that returns the formed container itself instead of the context.
+///
+/// This struct is useful when the forming process should result in the formed container being returned directly,
+/// bypassing any additional context processing. It simplifies scenarios where the formed container is the final result.
+#[ derive( Debug, Default ) ]
+pub struct ReturnStorage;
+
+impl< Storage, Formed > FormingEnd< Storage, (), Formed >
+for ReturnStorage
+// where
+  // Storage : StoragePreform<>,
+{
+  #[ inline( always ) ]
+  fn call( &self, storage : Storage, _context : core::option::Option< () > ) -> Formed
+  {
+    storage.preform()
+  }
+}
+
 /// A wrapper around a closure to be used as a `FormingEnd`.
 ///
 /// This struct allows for dynamic dispatch of a closure that matches the
@@ -47,14 +66,14 @@ where
 /// * `Context` - The type of the context that may be altered or returned by the closure.
 ///               This allows for flexible manipulation of context based on the container.
 #[ cfg( not( feature = "no_std" ) ) ]
-pub struct FormingEndWrapper< Storage, Context >
+pub struct FormingEndWrapper< Storage, Context, Formed >
 {
-  closure : Box< dyn Fn( Storage, Option< Context > ) -> Context >,
+  closure : Box< dyn Fn( Storage, Option< Context > ) -> Formed >,
   _marker : std::marker::PhantomData< Storage >,
 }
 
 #[ cfg( not( feature = "no_std" ) ) ]
-impl< Storage, Context > FormingEndWrapper< Storage, Context >
+impl< Storage, Context, Formed > FormingEndWrapper< Storage, Context, Formed >
 {
   /// Constructs a new `FormingEndWrapper` with the provided closure.
   ///
@@ -67,7 +86,7 @@ impl< Storage, Context > FormingEndWrapper< Storage, Context >
   /// # Returns
   ///
   /// Returns an instance of `FormingEndWrapper` encapsulating the provided closure.
-  pub fn new( closure : impl Fn( Storage, Option< Context > ) -> Context + 'static ) -> Self
+  pub fn new( closure : impl Fn( Storage, Option< Context > ) -> Formed + 'static ) -> Self
   {
     Self
     {
@@ -80,7 +99,7 @@ impl< Storage, Context > FormingEndWrapper< Storage, Context >
 #[ cfg( not( feature = "no_std" ) ) ]
 use std::fmt;
 #[ cfg( not( feature = "no_std" ) ) ]
-impl< Storage, Context > fmt::Debug for FormingEndWrapper< Storage, Context >
+impl< Storage, Context, Formed > fmt::Debug for FormingEndWrapper< Storage, Context, Formed >
 {
   fn fmt( &self, f : &mut fmt::Formatter< '_ > ) -> fmt::Result
   {
@@ -92,96 +111,68 @@ impl< Storage, Context > fmt::Debug for FormingEndWrapper< Storage, Context >
 }
 
 #[ cfg( not( feature = "no_std" ) ) ]
-impl< Storage, Context > FormingEnd< Storage, Context >
-for FormingEndWrapper< Storage, Context >
+impl< Storage, Context, Formed > FormingEnd< Storage, Context, Formed >
+for FormingEndWrapper< Storage, Context, Formed >
 {
-  fn call( &self, storage : Storage, context : Option< Context > ) -> Context
+  fn call( &self, storage : Storage, context : Option< Context > ) -> Formed
   {
     ( self.closure )( storage, context )
   }
 }
 
-// /// A `FormingEnd` implementation that returns the original context without any modifications.
-// ///
-// /// This struct is used when no end-of-forming processing is needed, and the original context is to be returned as-is.
-// #[ derive( Debug, Default ) ]
-// pub struct NoEnd;
 //
-// impl< Formed, Context > FormingEnd< Formed, Context >
-// for NoEnd
-// {
-//   #[ inline( always ) ]
-//   fn call( &self, _formed : Formed, context : core::option::Option< Context > ) -> Context
-//   {
-//     context.unwrap()
-//   }
-// }
 
-/// A `FormingEnd` implementation that returns the formed container itself instead of the context.
+/// A trait for initiating a structured subforming process with contextual and intermediary storage linkage.
 ///
-/// This struct is useful when the forming process should result in the formed container being returned directly,
-/// bypassing any additional context processing. It simplifies scenarios where the formed container is the final result.
-#[ derive( Debug, Default ) ]
-pub struct ReturnFormed;
-
-impl< Storage > FormingEnd< Storage, Storage >
-for ReturnFormed
-{
-  #[ inline( always ) ]
-  fn call( &self, storage : Storage, _context : core::option::Option< Storage > ) -> Storage
-  {
-    storage
-  }
-}
-
-//
-
-/// A trait defining the initialization process for a subformer with contextual linkage.
-///
-/// This trait is designed for types that need to initiate a subforming process,
-/// passing themselves as the context and specifying a closure or handler (`on_end`) to be
-/// called upon completion. It facilitates the construction of builder pattern chains
-/// that maintain stateful context through each step of the process.
+/// This trait facilitates the creation of a subformer that carries through a builder pattern chain,
+/// utilizing intermediary storage for accumulating state or data before finally transforming it into
+/// a `Formed` structure. It is designed for scenarios where a multi-step construction or transformation
+/// process benefits from maintaining both transient state (`Storage`) and contextual information (`Context`),
+/// before concluding with the generation of a final product (`Formed`).
 ///
 /// # Type Parameters
 ///
-/// * `Formed` - Represents the type that is being constructed or transformed by the subformer.
-/// * `Context` - Denotes the contextual information or the environment in which `Formed` is being formed.
-///               This could be a reference to a parent builder, configuration settings, or any other
-///               relevant state.
+/// * `Storage` - Represents a mutable intermediary storage structure used throughout the subforming process
+///               to accumulate data, state, or partial computations. This storage is internal to the
+///               subformer and is eventually converted into the final `Formed` structure by the subformer,
+///               not directly by implementations of this trait.
+///
+/// * `Formed` - Denotes the final type that results from the subforming process. This is the intended outcome
+///              of the builder chain, constructed or transformed from the `Storage` with consideration of
+///              the provided `Context`.
+///
+/// * `Context` - Specifies the contextual backdrop against which the subforming process unfolds. This could
+///               encompass references to parent builders, configuration data, or any state influencing how
+///               `Storage` transitions into `Formed`.
 ///
-/// # Associated Types
+/// # Functions
 ///
-/// * `End` - Specifies the trait bound for the closure or handler that gets called at the completion
-///           of the subforming process. This type must implement the `FormingEnd<Formed, Context>`
-///           trait, which defines how the final transformation or construction of `Formed` is handled,
-///           potentially using the provided `Context`.
+/// * `_begin` - This function launches the subforming process, marking the start of a construction or transformation
+///              sequence defined by the implementing type. It establishes the foundational `Storage` and `Context`,
+///              alongside specifying an `on_end` completion handler that dictates the final conversion into `Formed`.
 ///
+/// The `FormerBegin` trait, by decoupling `Storage` from `Formed` and introducing a contextual layer, enables
+/// sophisticated and flexible construction patterns conducive to complex data transformations or object creation
+/// sequences within builder patterns.
 
+// xxx2 : change sequence
 pub trait FormerBegin< Storage, Formed, Context >
 {
 
-  /// * `End` - Specifies the trait bound for the closure or handler that gets called at the completion
-  ///           of the subforming process. This type must implement the `FormingEnd<Formed, Context>`
-  ///           trait, which defines how the final transformation or construction of `Formed` is handled,
-  ///           potentially using the provided `Context`.
-  type End : FormingEnd< Formed, Context >;
+  /// * `End` - A trait bound marking the closure or handler invoked upon completing the subforming process. Implementers
+  ///           of this trait (`End`) are tasked with applying the final transformations that transition `Storage`
+  ///           into `Formed`, optionally utilizing `Context` to guide this transformation. It is crucial that this
+  ///           associated type satisfies the `FormingEnd<Formed, Context>` trait, defining the precise mechanics of
+  ///           how the subformer concludes its operation.
+  type End : FormingEnd< Storage, Context, Formed >;
 
-  /// Initializes the subforming process by setting the context and specifying an `on_end` completion handler.
-  ///
-  /// This function is the entry point for initiating a subforming sequence, allowing the caller
-  /// to establish initial contextual information and define how the process concludes.
+  /// Launches the subforming process with an initial storage and context, setting up an `on_end` completion handler.
   ///
   /// # Parameters
   ///
-  /// * `context` - An optional parameter providing initial context for the subforming process. This
-  ///               might include configuration data, references to parent structures, or any state
-  ///               relevant to the formation of `Formed`.
-  ///
-  /// * `on_end` - A closure or handler of type `Self::End` that is invoked at the completion of
-  ///              the subforming process. This handler is responsible for applying any final transformations
-  ///              to `Formed` and potentially utilizing `Context` to influence the outcome.
-  ///
+  /// * `storage` - An optional initial state for the intermediary storage structure.
+  /// * `context` - An optional initial setting providing contextual information for the subforming process.
+  /// * `on_end` - A completion handler responsible for transforming the accumulated `Storage` into the final `Formed` structure.
   fn _begin
   (
     storage : core::option::Option< Storage >,