# Technical Specification: The `former` Derive Macro
### 1. Introduction & Core Concepts
* **1.1. Problem Solved:** The `former` derive macro simplifies the implementation of the Builder pattern in Rust. It automates the generation of fluent, readable, and maintainable APIs for object initialization, reducing boilerplate code for complex `struct` and `enum` types.
* **1.2. Guiding Principles:**
* **Clarity over Brevity:** The generated code and public APIs should be easy to understand and predictable.
* **Composition over Configuration:** Favor nested builders (subformers) for complex data structures to maintain a clear, hierarchical construction flow.
* **Convention over Configuration:** Provide sensible defaults for common patterns (e.g., handling of `Option<T>`, default collection formers) while allowing explicit overrides for customization.
* **Dependencies: Prefer `macro_tools`:** The macro's internal implementation **must** prefer the abstractions provided by the `macro_tools` crate over direct usage of `syn`, `quote`, and `proc-macro2`.
* **1.3. Key Terminology (Ubiquitous Language):**
* **Former:** The builder struct generated by the `#[derive(Former)]` macro (e.g., `MyStructFormer`).
* **Storage:** An internal, temporary struct (`...FormerStorage`) that holds the intermediate state of the object being built.
* **Definition:** A configuration struct (`...FormerDefinition`) that defines the types and `End` condition for a forming process.
* **Subformer:** A `Former` instance used to build a part of a larger object.
### 2. Core Behavioral Specification
This section defines the core user-facing contract of the `former` macro. The following logic tables and attribute definitions are the single source of truth for its behavior.
#### 2.1. Enum Variant Constructor Logic
The macro generates a static constructor method on the enum for each variant. The type of constructor is determined by the variant's structure and attributes according to the following rules:
| **1a** | Unit: `V` | `#[scalar]` or Default | Direct constructor: `Enum::v() -> Enum` |
| **1b** | Tuple: `V()` | `#[scalar]` or Default | Direct constructor: `Enum::v() -> Enum` |
| **1c** | Struct: `V {}` | `#[scalar]` | Direct constructor: `Enum::v() -> Enum` |
| **1d** | Tuple: `V(T1)` | `#[scalar]` | Scalar constructor: `Enum::v(T1) -> Enum` |
| **1e** | Struct: `V {f1:T1}` | `#[scalar]` | Scalar constructor: `Enum::v{f1:T1} -> Enum` |
| **1f** | Tuple: `V(T1, T2)` | `#[scalar]` | Scalar constructor: `Enum::v(T1, T2) -> Enum` |
| **1g** | Struct: `V {f1:T1, f2:T2}` | `#[scalar]` | Scalar constructor: `Enum::v{f1:T1, f2:T2} -> Enum` |
| **2a** | Unit: `V` | `#[subform_scalar]` | **Compile Error** |
| **2b** | Tuple: `V()` | `#[subform_scalar]` | **Compile Error** |
| **2c** | Struct: `V {}` | `#[subform_scalar]` | **Compile Error** |
| **2d** | Tuple: `V(T1)` | `#[subform_scalar]` or Default | Subformer for inner type: `Enum::v() -> T1::Former` |
| **2e** | Struct: `V {f1:T1}` | `#[subform_scalar]` or Default | Implicit variant former: `Enum::v() -> VFormer` |
| **2f** | Tuple: `V(T1, T2)` | `#[subform_scalar]` | **Compile Error** |
| **2g** | Struct: `V {f1:T1, f2:T2}` | `#[subform_scalar]` or Default | Implicit variant former: `Enum::v() -> VFormer` |
| **3c** | Struct: `V {}` | Default | **Compile Error** (Requires `#[scalar]`) |
| **3f** | Tuple: `V(T1, T2)` | Default | **Implicit variant former: `Enum::v() -> VFormer`** |
**Note on Rule 3f:** This rule is updated to reflect the implemented and tested behavior. The previous specification incorrectly stated this case would generate a scalar constructor. The actual behavior is to generate a subformer for the variant itself.
#### 2.2. Standalone Constructor Behavior
When the `#[standalone_constructors]` attribute is applied to an item, the return type of the generated top-level function(s) is determined by the usage of `#[arg_for_constructor]` on its fields:
* **Rule SC-1 (Full Construction):** If **all** fields of a struct or enum variant are marked with `#[arg_for_constructor]`, the generated standalone constructor will take all fields as arguments and return the final, constructed instance (`Self`).
* **Rule SC-2 (Partial Construction):** If **some or none** of the fields of a struct or enum variant are marked with `#[arg_for_constructor]`, the generated standalone constructor will take only the marked fields as arguments and return an instance of the `Former` (`...Former`), pre-initialized with those arguments.
#### 2.3. Attribute Reference
The following attributes control the behavior defined in the logic tables above.
##### 2.3.1. Item-Level Attributes
| `#[storage_fields(..)]` | Defines extra fields exclusive to the `...FormerStorage` struct for intermediate calculations. |
| `#[mutator(custom)]` | Disables default `FormerMutator` implementation, requiring a manual `impl` block. |
| `#[perform(fn...)]` | Specifies a method on the original struct to be called by `.perform()` after forming. |
| `#[standalone_constructors]` | Generates top-level constructor functions. |
| `#[debug]` | Prints the macro's generated code to the console at compile time. |
##### 2.3.2. Field-Level / Variant-Level Attributes
| `#[former(default = ...)]` | Provides a default value for a field if its setter is not called. |
| `#[scalar]` | Forces the generation of a simple scalar setter (e.g., `.field(value)`). |
| `#[subform_scalar]` | Generates a method returning a subformer for a nested struct. The field's type must also derive `Former`. |
| `#[subform_collection]` | Generates a method returning a specialized collection subformer (e.g., `VectorFormer`). |
| `#[subform_entry]` | Generates a method returning a subformer for a single entry of a collection. |
| `#[arg_for_constructor]` | Marks a field as a required argument for a `#[standalone_constructors]` function. |
##### 2.3.3. Attribute Precedence and Interaction Rules
1. **Subform vs. Scalar:** Subform attributes (`#[subform_scalar]`, `#[subform_collection]`, `#[subform_entry]`) take precedence over `#[scalar]`. If both are present, the subform behavior is implemented, and a scalar setter is **not** generated unless explicitly requested via `#[scalar(setter = true)]`.
2. **Setter Naming:** If a `name` is provided (e.g., `#[scalar(name = new_name)]`), it overrides the default setter name derived from the field's identifier.
3. **Setter Disabling:** `setter = false` on any attribute (`scalar`, `subform_*`) will prevent the generation of that specific user-facing setter method. Internal helper methods (e.g., `_field_subform_entry()`) are still generated to allow for manual implementation of custom setters.
4. **`#[former(default = ...)]`:** This attribute is independent and can be combined with any setter type. It provides a fallback value if a field's setter is never called.
### 3. Generated Code Architecture
The `#[derive(Former)]` macro generates a consistent set of components to implement the behavior defined in Section 2.
* **`TFormer` (The Former)**
* **Purpose:** The public-facing builder.
* **Key Components:** A `storage` field, an `on_end` field, setter methods, and a `.form()` method.
* **`TFormerStorage` (The Storage)**
* **Purpose:** Internal state container.
* **Key Components:** A public, `Option`-wrapped field for each field in `T` and any `#[storage_fields]`.
* **`TFormerDefinition` & `TFormerDefinitionTypes` (The Definition)**
* **Purpose:** To make the forming process generic and customizable.
* **Key Associated Types:** `Storage`, `Context`, `Formed`, `End`.
### 4. Diagnostics & Debugging
* **Error Handling Strategy:** The macro must produce clear, concise, and actionable compile-time errors. Errors must be associated with the specific `span` of the code that caused the issue. The `trybuild` crate must be used to create a suite of compile-fail tests to verify error-handling behavior.
* **Debugging Aids:** The `#[debug]` item-level attribute must be provided. When present, the macro will print the final generated `TokenStream` to the console during compilation.
### 5. Lifecycle & Evolution
* **Versioning Strategy:** The `former` crate must adhere to Semantic Versioning 2.0.0.
* **Deprecation Strategy:** Features or attributes planned for removal must first be marked as deprecated via `#[deprecated]` for at least one minor release cycle before being removed in a subsequent major version.
### 6. Meta-Requirements
* **Ubiquitous Language:** All terms defined in the `Key Terminology` section must be used consistently.
* **Naming Conventions:** All generated asset names must use `snake_case`. Generated functions must follow a `noun_verb` pattern.
* **Single Source of Truth:** The Git repository is the single source of truth for all project artifacts.
### 7. Deliverables
* `specification.md`: This document.
* `spec_addendum.md`: A companion document for implementation-specific details.
### 8. Conformance Check Procedure
1. **Run Full Test Suite:** Execute `cargo test --workspace`.
2. **Check Linter:** Execute `cargo clippy --workspace --all-targets -- -D warnings`.
3. **Review Attribute Coverage:** Manually verify that every rule in the logic tables has a corresponding passing test.
4. **Review Documentation:** Manually verify that the `Readme.md` and `advanced.md` documents are consistent with this specification.
***
# Specification Addendum
### Purpose
This document is a companion to the main `specification.md`. It is intended to be completed by the **Developer** during the implementation of the `former` macro. While the main specification defines the "what" and "why" of the macro's public contract, this addendum captures the "how" of the final implementation.
### Instructions for the Developer
As you implement or modify the `former_meta` crate, please fill out the sections below with the relevant details. This creates a crucial record for future maintenance, debugging, and onboarding.
---
### Internal Module Overview
*A high-level description of the key modules within the `former_meta` crate and their responsibilities.*
| `derive_former` | Top-level entry point for the `#[derive(Former)]` macro. Dispatches to struct or enum handlers. |
| `derive_former::former_struct` | Contains the primary logic for generating all code components for `struct`s. |
| `derive_former::former_enum` | Contains the primary dispatch logic for `enum`s, routing to specific variant handlers based on the rules in the specification. |
| `derive_former::former_enum::*` | Individual handler modules for each combination of enum variant type and attribute (e.g., `unit_variant_handler`, `tuple_single_field_scalar`). |
| `derive_former::field_attrs` | Defines and parses all field-level and variant-level attributes (e.g., `#[scalar]`). |
| `derive_former::struct_attrs` | Defines and parses all item-level attributes (e.g., `#[storage_fields]`). |
### Key Internal Data Structures
*List the primary internal-only structs or enums used during the macro expansion process and their purpose.*
| `ItemAttributes` | `former_meta` | Holds the parsed attributes from the top-level `struct` or `enum`. |
| `FieldAttributes` | `former_meta` | Holds the parsed attributes for a single `struct` field or `enum` variant. |
| `FormerField` | `former_meta` | A unified representation of a field, combining its `syn::Field` data with parsed `FieldAttributes`. |
| `EnumVariantHandlerContext` | `former_meta` | A context object passed to enum variant handlers, containing all necessary information for code generation (AST nodes, attributes, generics, etc.). |
### Testing Strategy
*A description of the testing methodology for the macro.*
- **UI / Snapshot Testing (`trybuild`):** The `trybuild` crate is used to create a comprehensive suite of compile-fail tests. This ensures that invalid attribute combinations and incorrect usage patterns result in the expected compile-time errors, as defined in the specification.
- **Manual vs. Derive Comparison:** This is the primary strategy for verifying correctness. For each feature, a three-file pattern is used:
1. `_manual.rs`: A file containing a hand-written, correct implementation of the code that the macro *should* generate.
2. `_derive.rs`: A file that uses `#[derive(Former)]` on an identical data structure.
3. `_only_test.rs`: A file containing only `#[test]` functions that is `include!`d by both the `_manual.rs` and `_derive.rs` files. This guarantees that the exact same assertions are run against both the hand-written and macro-generated implementations, ensuring their behavior is identical.
### Finalized Library & Tool Versions
*List the critical libraries, frameworks, or tools used and their exact locked versions from `Cargo.lock`.*
- `rustc`: `1.78.0`
- `macro_tools`: `0.15.0`
- `convert_case`: `0.6.0`