former : experimenting

module/core/former/src/axiomatic.rs

@@ -1,14 +1,42 @@
 //! ....
 
+pub trait Storage : ::core::default::Default
+{
+  type Definition : FormerDefinition< Storage = Self >;
+}
+
+/// xxx
+pub trait StoragePerform : Storage
+{
+  fn preform( self ) -> < < Self as Storage >::Definition as FormerDefinition >::Formed;
+}
+
+/// xxx
+pub trait FormerDefinition
+{
+  // type Storage : StoragePerform< Definition = Self >;
+  type Storage : Storage< Definition = Self >;
+  type Formed;
+}
+
+// pub trait FormerDefinition
+// {
+//   type Storage : StoragePerform< Formed = Self::Formed >;
+//   type Formed;
+//   type Context;
+//   type FormerDefinition : FormerDefinition< Storage = Self::Storage, Formed = Self::Formed >;
+//   type End : FormingEnd< Self::FormerDefinition, Self::Context >;
+// }
+
 /// Defines a handler for the end of a subforming process, enabling the return of the original context.
 ///
 /// This trait is designed to be flexible, allowing for various end-of-forming behaviors in builder patterns.
 /// 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< Definition : FormerDefinition, Context >
 {
   /// Called at the end of the subforming process to return the modified or original context.
   ///
@@ -18,21 +46,41 @@ 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;
+  fn call( &self, storage : Definition::Storage, context : core::option::Option< Context > ) -> Definition::Formed;
 }
 
-impl< Storage, Context, F > FormingEnd< Storage, Context > for F
+impl< Definition : FormerDefinition, Context, F > FormingEnd< Definition, Context > for F
 where
-  F : Fn( Storage, core::option::Option< Context > ) -> Context,
+  F : Fn( Definition::Storage, core::option::Option< Context > ) -> Definition::Formed,
 {
   #[ inline( always ) ]
-  fn call( &self, storage : Storage, context : core::option::Option< Context > ) -> Context
+  fn call( &self, storage : Definition::Storage, context : core::option::Option< Context > ) -> Definition::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 ReturnFormed;
+
+impl< Definition : FormerDefinition > FormingEnd< Definition, () >
+for ReturnFormed
+where
+  Definition::Storage : StoragePerform< Definition = Definition >,
+  // xxx : rename Former -> Definition
+  // xxx : rename Definition -> Definition
+{
+  #[ inline( always ) ]
+  fn call( &self, storage : Definition::Storage, _context : core::option::Option< () > ) -> Definition::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 +95,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< Definition : FormerDefinition, Context >
 {
-  closure : Box< dyn Fn( Storage, Option< Context > ) -> Context >,
-  _marker : std::marker::PhantomData< Storage >,
+  closure : Box< dyn Fn( Definition::Storage, Option< Context > ) -> Definition::Formed >,
+  _marker : std::marker::PhantomData< Definition::Storage >,
 }
 
 #[ cfg( not( feature = "no_std" ) ) ]
-impl< Storage, Context > FormingEndWrapper< Storage, Context >
+impl< Definition : FormerDefinition, Context > FormingEndWrapper< Definition, Context >
 {
   /// Constructs a new `FormingEndWrapper` with the provided closure.
   ///
@@ -67,7 +115,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( Definition::Storage, Option< Context > ) -> Definition::Formed + 'static ) -> Self
   {
     Self
     {
@@ -80,7 +128,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< Definition : FormerDefinition, Context > fmt::Debug for FormingEndWrapper< Definition, Context >
 {
   fn fmt( &self, f : &mut fmt::Formatter< '_ > ) -> fmt::Result
   {
@@ -92,99 +140,70 @@ 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< Definition : FormerDefinition, Context > FormingEnd< Definition, Context >
+for FormingEndWrapper< Definition, Context >
 {
-  fn call( &self, storage : Storage, context : Option< Context > ) -> Context
+  fn call( &self, storage : Definition::Storage, context : Option< Context > ) -> Definition::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.
 
-pub trait FormerBegin< Storage, Formed, Context >
+pub trait FormerBegin< Definition : FormerDefinition, 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< Definition, Context >;
 
-  /// 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 >,
+    storage : core::option::Option< Definition::Storage >,
     context : core::option::Option< Context >,
     on_end : Self::End,
   ) -> Self;