diff options
27 files changed, 278 insertions, 55 deletions
diff --git a/.run/version-files.toml b/.run/version-files.toml index f00ae4c..42d9b4d 100644 --- a/.run/version-files.toml +++ b/.run/version-files.toml @@ -25,3 +25,7 @@ pattern = "version = \"{VER}\"" [[file]] file = "./mingling_picker/README.md" pattern = "mingling_picker = \"{VER}\"" + +[[file]] +file = "./mingling_picker_macros/README.md" +pattern = "version = \"{VER}\"" diff --git a/mingling/src/parser/picker.rs b/mingling/src/parser/picker.rs index 21ba9a6..601cd3f 100644 --- a/mingling/src/parser/picker.rs +++ b/mingling/src/parser/picker.rs @@ -722,6 +722,13 @@ impl_pick_with_route_next! { PickWithRoute9 PickWithRoute10 val_10 T1 val_1, T2 impl_pick_with_route_next! { PickWithRoute10 PickWithRoute11 val_11 T1 val_1, T2 val_2, T3 val_3, T4 val_4, T5 val_5, T6 val_6, T7 val_7, T8 val_8, T9 val_9, T10 val_10 } impl_pick_with_route_next! { PickWithRoute11 PickWithRoute12 val_12 T1 val_1, T2 val_2, T3 val_3, T4 val_4, T5 val_5, T6 val_6, T7 val_7, T8 val_8, T9 val_9, T10 val_10, T11 val_11 } +/// Trait for types that can be used with `Pickable` to extract enum values from command-line arguments. +/// +/// This trait combines `EnumTag` (for building an enum variant from a string name) and `Default` +/// (for providing a fallback value when the flag is not present). +/// +/// Types implementing this trait can be used with `Picker::pick`, `Picker::pick_or_route`, and +/// the chaining `.pick()` methods to extract and parse enum values from command-line arguments. pub trait PickableEnum: EnumTag + Default {} impl<T> Pickable for T diff --git a/mingling/src/parser/picker/bools.rs b/mingling/src/parser/picker/bools.rs index ede8812..0525c52 100644 --- a/mingling/src/parser/picker/bools.rs +++ b/mingling/src/parser/picker/bools.rs @@ -1,9 +1,15 @@ use crate::parser::Pickable; +/// Represents a boolean-like value with `Yes` and `No` variants. +/// +/// `Yes` can be parsed from command-line arguments using positive keywords such as `"y"` or `"yes"`, +/// and defaults to `No`. #[derive(Debug, Default)] #[repr(u8)] pub enum Yes { + /// The affirmative/positive variant. Yes, + /// The negative/default variant. #[default] No, } @@ -57,10 +63,16 @@ impl Pickable for Yes { } } +/// Represents a boolean-like value with `True` and `False` variants. +/// +/// `True` can be parsed from command-line arguments using positive keywords such as `"t"` or `"true"`, +/// and defaults to `False`. #[derive(Debug, Default)] #[repr(u8)] pub enum True { + /// The affirmative/positive variant. True, + /// The negative/default variant. #[default] False, } diff --git a/mingling_macros/src/lib.rs b/mingling_macros/src/lib.rs index 0c7aeaf..d0f603a 100644 --- a/mingling_macros/src/lib.rs +++ b/mingling_macros/src/lib.rs @@ -2,7 +2,7 @@ //! //! This crate is the **macro layer** of Mingling. Each `#[attribute]` or `!`-callable //! macro collects metadata into **compile-time global registries** (`OnceLock<Mutex<BTreeSet>>`). -//! At the end, [`gen_program!`] reads all registries and generates the final program struct +//! At the end, `gen_program!` reads all registries and generates the final program struct //! with all dispatchers, chains, renderers, and completions wired together. //! //! # How Macros Work Together @@ -47,16 +47,16 @@ //! //! | Macro | What it does | //! |-------|-------------| -//! | [`dispatcher!`] | Declares a command entry point and its argument type | -//! | [`macro@dispatcher_clap`] | Like `dispatcher!` but powered by `clap::Parser` | -//! | [`node!`] | Builds a [`Node`](https://docs.rs/mingling/latest/mingling/struct.Node.html) from a dot-separated path string | -//! | [`pack!`] | Creates a newtype wrapper around an inner type for use in Chain/Renderer | -//! | [`pack_structural!`] | Like `pack!` but also derives `StructuralData` for structured output | -//! | [`pack_err!`] | Creates an error struct with automatic `name` field | -//! | [`pack_err_structural!`] | Like `pack_err!` but also derives `StructuralData` for structured output | -//! | [`entry!`] | Creates a packed entry from string literals | +//! | `dispatcher!` | Declares a command entry point and its argument type | +//! | `dispatcher_clap!` | Like `dispatcher!` but powered by `clap::Parser` | +//! | `node!` | Builds a [`Node`](https://docs.rs/mingling/latest/mingling/struct.Node.html) from a dot-separated path string | +//! | `pack!` | Creates a newtype wrapper around an inner type for use in Chain/Renderer | +//! | `pack_structural!` | Like `pack!` but also derives `StructuralData` for structured output | +//! | `pack_err!` | Creates an error struct with automatic `name` field | +//! | `pack_err_structural!` | Like `pack_err!` but also derives `StructuralData` for structured output | +//! | `entry!` | Creates a packed entry from string literals | //! | [`#[derive(Groupped)]`](derive@Groupped) | Makes a type recognizable by the framework's type registry | -//! | [`#[derive(StructuralData)]`](derive@StructuralData) | Marks a type as eligible for structured output (JSON/YAML/etc.) | +//! | `#[derive(StructuralData)]` | Marks a type as eligible for structured output (JSON/YAML/etc.) | //! | [`#[derive(EnumTag)]`](derive@EnumTag) | Adds enum variant metadata (name, description) | //! //! ## Phase 2: Processing & Rendering Registration @@ -66,27 +66,27 @@ //! | [`#[chain]`](attr.chain.html) | Transforms a function into a chain processing step | //! | [`#[renderer]`](attr.renderer.html) | Transforms a function into a renderer for a type | //! | [`#[help]`](attr.help.html) | Defines help output for a command entry type | -//! | [`route!`] | Routes execution depending on a condition | -//! | [`empty_result!`] | Returns an empty result for early termination | +//! | `route!` | Routes execution depending on a condition | +//! | `empty_result!` | Returns an empty result for early termination | //! | [`#[completion]`](attr.completion.html) | Registers a shell completion handler | //! //! ## Phase 3: Program Generation //! //! | Macro | What it does | //! |-------|-------------| -//! | [`gen_program!`] | **Final step**: reads all registries and generates the full program | -//! | [`suggest!`] | Generates suggestion logic for a dispatcher | -//! | [`suggest_enum!`] | Generates suggestion logic for an enum dispatcher | +//! | `gen_program!` | **Final step**: reads all registries and generates the full program | +//! | `suggest!` | Generates suggestion logic for a dispatcher | +//! | `suggest_enum!` | Generates suggestion logic for an enum dispatcher | //! //! ## Internal (used by the macros above) //! //! | Macro | What it does | //! |-------|-------------| -//! | [`register_type!`] | Registers a type in the packed-type registry | -//! | [`register_chain!`] | Registers a chain mapping in the chain registry | -//! | [`register_renderer!`] | Registers a renderer mapping in the renderer registry | -//! | [`register_dispatcher!`] | Registers a dispatcher for the `dispatch_tree` feature | -//! | [`register_help!`] | Registers a help request handler | +//! | `register_type!` | Registers a type in the packed-type registry | +//! | `register_chain!` | Registers a chain mapping in the chain registry | +//! | `register_renderer!` | Registers a renderer mapping in the renderer registry | +//! | `register_dispatcher!` | Registers a dispatcher for the `dispatch_tree` feature | +//! | `register_help!` | Registers a help request handler | //! | `program_fallback_gen!` | Generates fallback error types | //! | `program_final_gen!` | Generates the `ProgramCollect` impl and `ThisProgram` struct | //! | `program_comp_gen!` | Generates completion logic | @@ -98,12 +98,12 @@ //! //! | Feature | Macros enabled | //! |---------|---------------| -//! | `clap` | [`macro@dispatcher_clap`] | -//! | `comp` | [`#[completion]`](attr.completion.html), [`suggest!`], [`suggest_enum!`] | -//! | `extra_macros` | [`entry!`], [`empty_result!`], [`route!`], [`#[program_setup]`](attr.program_setup.html), [`macro@group`] | +//! | `clap` | `dispatcher_clap!` | +//! | `comp` | [`#[completion]`](attr.completion.html), `suggest!`, `suggest_enum!` | +//! | `extra_macros` | `entry!`, `empty_result!`, `route!`, [`#[program_setup]`](attr.program_setup.html), `group!` | //! | `dispatch_tree` | `register_dispatcher!` (enables trie-based command dispatch) | -//! | `structural_renderer` | [`#[derive(StructuralData)]`](derive@StructuralData), [`pack_structural!`], [`pack_err_structural!`], [`macro@group_structural`] | -//! | `structural_renderer` + `extra_macros` | [`group_structural!`], [`pack_err_structural!`] | +//! | `structural_renderer` | `#[derive(StructuralData)]`, `pack_structural!`, `pack_err_structural!`, `group_structural!` | +//! | `structural_renderer` + `extra_macros` | `group_structural!`, `pack_err_structural!` | //! | `async` | Enables async `#[chain]` functions | //! | `repl` | Enables REPL execution loop | //! @@ -114,7 +114,7 @@ //! entries contain the **token-stream representation** of match arms, type mappings, //! and struct definitions. //! -//! When [`gen_program!`] is called, it reads all registries, concatenates their +//! When `gen_program!` is called, it reads all registries, concatenates their //! entries, and emits the complete program: //! //! ```rust,ignore @@ -599,13 +599,13 @@ pub fn route(input: TokenStream) -> TokenStream { /// crate::ResultEmpty::new(()).to_chain() /// ``` /// -/// This works because [`ResultEmpty`] is automatically generated by [`gen_program!`] +/// This works because [`ResultEmpty`] is automatically generated by `gen_program!` /// and implements the necessary trait conversions into [`ChainProcess`]. /// /// # See also /// /// - [`ResultEmpty`] — The type that represents an empty result. -/// - [`route!`] — For early-return from `Result` expressions. +/// - `route!` — For early-return from `Result` expressions. /// /// [`ResultEmpty`]: https://docs.rs/mingling/latest/mingling/type.ResultEmpty.html /// [`ChainProcess`]: https://docs.rs/mingling/latest/mingling/enum.ChainProcess.html @@ -690,8 +690,8 @@ pub fn empty_result(_input: TokenStream) -> TokenStream { /// /// # See also /// -/// - [`macro@dispatcher_clap`] — For clap-powered argument parsing. -/// - [`node!`] — For building custom [`Node`] paths. +/// - `dispatcher_clap!` — For clap-powered argument parsing. +/// - `node!` — For building custom [`Node`] paths. /// - [`#[chain]`](attr.chain.html) — For processing the dispatched entry. /// /// [`ChainProcess`]: https://docs.rs/mingling/latest/mingling/enum.ChainProcess.html @@ -1088,7 +1088,7 @@ pub fn dispatcher_clap(attr: TokenStream, item: TokenStream) -> TokenStream { /// Creates a packed entry value from a list of string literals. /// /// This is a convenience macro for constructing entry wrapper types (created -/// via [`pack!`] or [`dispatcher!`]) with test data, typically used in unit tests +/// via `pack!` or `dispatcher!`) with test data, typically used in unit tests /// or quick prototypes. /// /// # Syntax @@ -1119,8 +1119,8 @@ pub fn dispatcher_clap(attr: TokenStream, item: TokenStream) -> TokenStream { /// /// # See also /// -/// - [`pack!`] — For creating the wrapper types used with `entry!`. -/// - [`dispatcher!`] — Which implicitly creates entry types via `pack!`. +/// - `pack!` — For creating the wrapper types used with `entry!`. +/// - `dispatcher!` — Which implicitly creates entry types via `pack!`. #[cfg(feature = "extra_macros")] #[proc_macro] pub fn entry(input: TokenStream) -> TokenStream { @@ -1147,10 +1147,10 @@ pub fn register_help(input: TokenStream) -> TokenStream { /// Registers a dispatcher at compile time for the `dispatch_tree` feature. /// -/// This macro is called internally by [`dispatcher!`] when the `dispatch_tree` +/// This macro is called internally by `dispatcher!` when the `dispatch_tree` /// feature is enabled. Each call stores the node name into the global /// `COMPILE_TIME_DISPATCHERS` registry and generates a static variable for the -/// dispatcher instance. This data is later consumed by [`gen_program!`] to +/// dispatcher instance. This data is later consumed by `gen_program!` to /// generate a character-level **Trie** for efficient command dispatch. /// /// The trie dispatch works by grouping commands by their character prefix, @@ -1167,7 +1167,7 @@ pub fn register_help(input: TokenStream) -> TokenStream { /// /// # See also /// -/// - [`dispatcher!`] — The primary way to declare dispatchers (calls this internally). +/// - `dispatcher!` — The primary way to declare dispatchers (calls this internally). /// - `dispatch_tree_gen` module — The trie generation logic. #[proc_macro] pub fn register_dispatcher(input: TokenStream) -> TokenStream { @@ -1190,7 +1190,7 @@ pub fn register_dispatcher(input: TokenStream) -> TokenStream { /// 3. Keeping the original function for direct calls. /// /// Inside a `#[help]` function, you must manually create a `RenderResult` -/// and return it. Use [`writeln!`](std::fmt::writeln) on the result to +/// and return it. Use `writeln!` on the result to /// write help text. /// /// # Syntax @@ -1234,13 +1234,13 @@ pub fn register_dispatcher(input: TokenStream) -> TokenStream { /// /// - The function must have exactly one parameter (the entry type to provide help for). /// - The parameter type must be a single-segment type path (e.g., `MyEntry`, not `other::MyEntry`). -/// - The function must return [`RenderResult`]. +/// - The function must return `RenderResult`. /// - The function cannot be async. /// /// # See also /// /// - [`BasicProgramSetup`] — The setup that enables `--help` and `-h` flag processing. -/// - [`RenderResult`] — The return type for help functions. +/// - `RenderResult` — The return type for help functions. /// - [`#[chain]`](attr.chain.html) — For processing the dispatched entry after help. /// /// [`BasicProgramSetup`]: https://docs.rs/mingling/latest/mingling/setup/struct.BasicProgramSetup.html @@ -1326,7 +1326,7 @@ pub fn derive_enum_tag(input: TokenStream) -> TokenStream { enum_tag::derive_enum_tag(input) } -/// Derive macro for [`StructuralData`], marking a type as eligible for structured +/// Derive macro for `StructuralData`, marking a type as eligible for structured /// structured output (JSON / YAML / TOML / RON). /// /// The type must also implement `serde::Serialize` — the generated diff --git a/mingling_pathf/src/config.rs b/mingling_pathf/src/config.rs index 6758264..1199b2c 100644 --- a/mingling_pathf/src/config.rs +++ b/mingling_pathf/src/config.rs @@ -1,3 +1,9 @@ +//! Configuration for the module pathfinder analysis. +//! +//! This module defines [`PathfinderConfig`], which controls behavior such as +//! whether dispatch-tree related types (`__internal_dispatcher_*`) should be +//! extracted. + /// Configuration for the module pathfinder analysis. /// /// Controls behavior such as whether dispatch-tree related types diff --git a/mingling_pathf/src/error.rs b/mingling_pathf/src/error.rs index 513ec23..70a8f6e 100644 --- a/mingling_pathf/src/error.rs +++ b/mingling_pathf/src/error.rs @@ -1,3 +1,9 @@ +//! Errors that can occur during the pathfinding process for Rust module resolution. +//! +//! This module defines all possible failure modes when traversing the module graph +//! of a Rust project, including I/O failures, missing modules, invalid path +//! attributes, missing entry points, and syntax parsing errors. + use std::fmt; use std::path::PathBuf; diff --git a/mingling_pathf/src/lib.rs b/mingling_pathf/src/lib.rs index 81b2df6..557ae45 100644 --- a/mingling_pathf/src/lib.rs +++ b/mingling_pathf/src/lib.rs @@ -1,3 +1,6 @@ +#![allow(clippy::needless_doctest_main)] +#![doc = include_str!("../README.md")] + pub mod config; pub mod error; pub mod module_pathf; diff --git a/mingling_pathf/src/module_pathf.rs b/mingling_pathf/src/module_pathf.rs index c20fd82..f0a06d1 100644 --- a/mingling_pathf/src/module_pathf.rs +++ b/mingling_pathf/src/module_pathf.rs @@ -1,3 +1,9 @@ +//! A module for mapping Rust module paths to source files. +//! +//! This module provides functionality to analyze the module structure of a Rust crate +//! and determine the effective module path for each source file, taking into account +//! `pub use` re-exports that can cause modules to be hoisted to parent paths. + use std::collections::HashMap; use std::path::{Path, PathBuf}; use syn::{Item, UseTree}; diff --git a/mingling_pathf/src/pattern_analyzer.rs b/mingling_pathf/src/pattern_analyzer.rs index c4b1971..3765971 100644 --- a/mingling_pathf/src/pattern_analyzer.rs +++ b/mingling_pathf/src/pattern_analyzer.rs @@ -1,3 +1,17 @@ +//! This module defines the core pattern analysis system used to parse and extract +//! importable/referenceable items (like structs, enums, functions, etc.) from Rust source files. +//! +//! It provides a pluggable architecture via the `AnalyzePattern` trait, allowing different +//! syntactic patterns to be registered and applied. Built-in patterns cover common structures +//! such as basic structs, packs, groups, derives, chains, renderers, help, completion, and +//! dispatch patterns (both standard and clap-based). +//! +//! The entry points are: +//! - [`init()`] — creates a default `PatternAnalyzer` with all built-in patterns. +//! - [`init_with_config()`] — creates a `PatternAnalyzer` with a given `PathfinderConfig`. +//! - [`PatternAnalyzer::analyze_file()`] / [`PatternAnalyzer::analyze_file_items()`] — run +//! analysis on a single file. + use std::collections::HashSet; use std::path::Path; diff --git a/mingling_pathf/src/patterns.rs b/mingling_pathf/src/patterns.rs index d0bda5d..9801e9b 100644 --- a/mingling_pathf/src/patterns.rs +++ b/mingling_pathf/src/patterns.rs @@ -1,3 +1,5 @@ +//! Mingling path matching patterns for command routing and field mapping. + pub use basic_struct::*; pub use chain::*; pub use completion::*; diff --git a/mingling_pathf/src/patterns/basic_struct.rs b/mingling_pathf/src/patterns/basic_struct.rs index eeb665a..09e8e70 100644 --- a/mingling_pathf/src/patterns/basic_struct.rs +++ b/mingling_pathf/src/patterns/basic_struct.rs @@ -1,3 +1,7 @@ +//! The `BasicStructPattern` matches `struct` definitions in Rust source code. +//! It identifies root-level structs and structs nested inside inline modules, +//! returning their names and optional module path for analysis. + use syn::Item; use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern}; diff --git a/mingling_pathf/src/patterns/chain.rs b/mingling_pathf/src/patterns/chain.rs index d64ed3b..6393440 100644 --- a/mingling_pathf/src/patterns/chain.rs +++ b/mingling_pathf/src/patterns/chain.rs @@ -1,3 +1,7 @@ +//! The `ChainPattern` matches functions annotated with `#[chain]` and +//! extracts the generated internal struct name (e.g., `__internal_chain_<fn_name>`). +//! This is used to track chained handler functions for code generation or analysis. + use syn::Item; use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern}; diff --git a/mingling_pathf/src/patterns/completion.rs b/mingling_pathf/src/patterns/completion.rs index ff20e0f..5427b93 100644 --- a/mingling_pathf/src/patterns/completion.rs +++ b/mingling_pathf/src/patterns/completion.rs @@ -1,3 +1,7 @@ +//! The `CompletionPattern` matches functions annotated with `#[completion(T)]` and +//! extracts the generated internal struct name (e.g., `__internal_completion_<fn_name>`). +//! This is used to track completion handler functions for code generation or analysis. + use syn::Item; use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern}; diff --git a/mingling_pathf/src/patterns/dispatcher.rs b/mingling_pathf/src/patterns/dispatcher.rs index b9f147d..6796a2c 100644 --- a/mingling_pathf/src/patterns/dispatcher.rs +++ b/mingling_pathf/src/patterns/dispatcher.rs @@ -1,3 +1,16 @@ +//! The `DispatcherPattern` matches invocations of the `dispatcher!` macro and +//! extracts the generated type names from its arguments. It supports: +//! - `Entry*` — the entry type (always generated) +//! - `CMD*` — the dispatcher struct (always generated) +//! - `__internal_dispatcher_*` — the dispatch tree static (when `use_dispatch_tree` is `true`) +//! +//! Supported forms: +//! - Explicit: `dispatcher!("greet", CMDGreet => EntryGreet)` +//! - Implicit: `dispatcher!("greet")` — infers `CMDGreet` and `EntryGreet` +//! - With braces: `dispatcher! { ... }` +//! +//! This pattern is used to track dispatcher types for code generation or analysis. + use syn::Item; use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern}; diff --git a/mingling_pathf/src/patterns/dispatcher_clap.rs b/mingling_pathf/src/patterns/dispatcher_clap.rs index 2e1ec6c..1a86ad5 100644 --- a/mingling_pathf/src/patterns/dispatcher_clap.rs +++ b/mingling_pathf/src/patterns/dispatcher_clap.rs @@ -1,3 +1,17 @@ +//! The `DispatcherClapPattern` matches structs annotated with `#[dispatcher_clap(...)]` and +//! extracts key items for code generation or analysis: +//! - The entry struct name (always) +//! - The dispatcher command struct (`CMD*`, always) +//! - The error type, if `error = ErrorType` is specified +//! - The help internal struct, if `help = true` is specified +//! - The `__internal_dispatcher_*` dispatch tree static, if `use_dispatch_tree` is enabled +//! +//! Supported forms: +//! - `#[dispatcher_clap("greet", CMDGreet)] struct EntryGreet { ... }` +//! - `#[dispatcher_clap("greet", CMDGreet, error = ErrorGreet)] struct EntryGreet { ... }` +//! - `#[dispatcher_clap("greet", CMDGreet, help = true)] struct EntryGreet { ... }` +//! - `#[dispatcher_clap("greet", CMDGreet, error = ErrorGreet, help = true)] struct EntryGreet { ... }` + use syn::Item; use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern}; diff --git a/mingling_pathf/src/patterns/group.rs b/mingling_pathf/src/patterns/group.rs index 99d1137..0e4b50d 100644 --- a/mingling_pathf/src/patterns/group.rs +++ b/mingling_pathf/src/patterns/group.rs @@ -1,3 +1,7 @@ +//! The `GroupPattern` matches the `group!` and `group_structural!` macros and +//! extracts the type name or alias defined within them. +//! This is used to track type groups for code generation or analysis. + use syn::Item; use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern}; diff --git a/mingling_pathf/src/patterns/groupped_derive.rs b/mingling_pathf/src/patterns/groupped_derive.rs index 8491121..91daaef 100644 --- a/mingling_pathf/src/patterns/groupped_derive.rs +++ b/mingling_pathf/src/patterns/groupped_derive.rs @@ -1,3 +1,8 @@ +//! The `GrouppedDerivePattern` matches structs, enums, and unions annotated with +//! `#[derive(Groupped)]` or `#[derive(GrouppedSerialize)]` (or any combination +//! with other derives). It also recurses into `mod` items to find nested types. +//! This is used to track grouped items for code generation or analysis. + use syn::Item; use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern}; diff --git a/mingling_pathf/src/patterns/help.rs b/mingling_pathf/src/patterns/help.rs index 02bfa4f..628f4ac 100644 --- a/mingling_pathf/src/patterns/help.rs +++ b/mingling_pathf/src/patterns/help.rs @@ -1,3 +1,7 @@ +//! The `HelpPattern` matches functions annotated with `#[help]` and +//! extracts the generated internal struct name (e.g., `__internal_help_<fn_name>`). +//! This is used to track help functions for code generation or analysis. + use syn::Item; use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern}; diff --git a/mingling_pathf/src/patterns/pack.rs b/mingling_pathf/src/patterns/pack.rs index 83c1cee..c80fb65 100644 --- a/mingling_pathf/src/patterns/pack.rs +++ b/mingling_pathf/src/patterns/pack.rs @@ -1,3 +1,7 @@ +//! The `PackPattern` matches types defined by `pack!`, `pack_err!`, `pack_structural!`, and `pack_err_structural!` macros. +//! It extracts the registered type name (e.g., `TypeName` from `pack!(TypeName = InnerType)`). +//! This is used to track packed type definitions for code generation or analysis. + use syn::Item; use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern}; diff --git a/mingling_pathf/src/patterns/renderer.rs b/mingling_pathf/src/patterns/renderer.rs index 054769e..c2e9ca9 100644 --- a/mingling_pathf/src/patterns/renderer.rs +++ b/mingling_pathf/src/patterns/renderer.rs @@ -1,3 +1,7 @@ +//! The `RendererPattern` matches functions annotated with `#[renderer]` and +//! extracts the generated internal struct name (e.g., `__internal_renderer_<fn_name>`). +//! This is used to track rendering functions for code generation or analysis. + use syn::Item; use crate::pattern_analyzer::{AnalyzeItem, AnalyzePattern}; diff --git a/mingling_pathf/src/type_mapping_builder.rs b/mingling_pathf/src/type_mapping_builder.rs index 3422af8..0965b47 100644 --- a/mingling_pathf/src/type_mapping_builder.rs +++ b/mingling_pathf/src/type_mapping_builder.rs @@ -1,3 +1,7 @@ +//! This module contains the matching patterns for `mingling_pathf`. +//! It provides the core logic for analyzing crate types and generating +//! type mapping files used by the pathfinder system. + use std::collections::HashSet; use std::path::Path; diff --git a/mingling_picker/README.md b/mingling_picker/README.md index c83bff4..db67825 100644 --- a/mingling_picker/README.md +++ b/mingling_picker/README.md @@ -22,15 +22,20 @@ mingling_picker = "0.3.0" Provides a clean chained-call API for declaring arguments to parse: ```rust +use mingling_picker::prelude::*; + let args: Vec<&str> = vec!["--name", "Bob", "--age", "24"]; -let result = args - .pick(&flag![name: String]) + +let (name, age) = args + .pick(&arg![name: String]) .or(|| "Alice".to_string()) - .pick(&flag![age: i32]) + .pick(&arg![age: i32]) .or(|| 24) .post(|num| num.clamp(0, 120)) - .parse(); -let (name, age): (String, i32) = a.unwrap(); + .unwrap(); + +assert_eq!(name, "Bob".to_string()); +assert_eq!(age, 24); ``` ## Parsing Function Library @@ -38,5 +43,5 @@ let (name, age): (String, i32) = a.unwrap(); Provides a pure function library `parselib` for analyzing the structure of command-line arguments. ```rust -use mingling::picker::parselib::*; +use mingling_picker::parselib::*; ``` diff --git a/mingling_picker/src/lib.rs b/mingling_picker/src/lib.rs index afc7aca..ffa6e13 100644 --- a/mingling_picker/src/lib.rs +++ b/mingling_picker/src/lib.rs @@ -1,3 +1,5 @@ +#![doc = include_str!("../README.md")] + mod builtin; mod picker; @@ -12,16 +14,28 @@ pub use arg::*; mod infos; pub use infos::*; +/// Provides the specific parsing logic for command-line arguments and common utilities, +/// as well as customization of command-line argument styles. pub mod parselib; +/// Parser-provided parseable command-line types pub mod value; +/// The prelude module, which re-exports the most commonly used traits and types. +/// +/// This module is intended to be imported with a wildcard import: +/// +/// ```ignore +/// use mingling_picker::prelude::*; +/// ``` pub mod prelude { pub use crate::IntoPicker; + pub use crate::macros::arg; } +/// Re-export of the `mingling_picker_macros` crate pub mod macros { - pub use mingling_picker_macros::*; + pub use mingling_picker_macros::arg; } /// Provides the types necessary for implementing the `Pickable` trait diff --git a/mingling_picker/src/parselib/style.rs b/mingling_picker/src/parselib/style.rs index 4ea161f..3c37b2d 100644 --- a/mingling_picker/src/parselib/style.rs +++ b/mingling_picker/src/parselib/style.rs @@ -109,25 +109,58 @@ impl<'a> From<&'a String> for FlagStr<'a> { } } +/// Defines the naming convention for command-line option names. +/// +/// Each variant represents a different case format that can be applied +/// to option names (e.g., long option names) during parsing or generation. +/// +/// # Examples +/// +/// ``` +/// # use mingling_picker::IntoPicker; +/// use mingling_picker::parselib::ParserStyleNamingCase; +/// +/// let case = ParserStyleNamingCase::Kebab; +/// assert_eq!( +/// case.convert("brew_coffee".to_string()), +/// "brew-coffee".to_string() +/// ); +/// ``` #[repr(u8)] #[derive(Default, Clone, Copy, PartialEq, Eq)] pub enum ParserStyleNamingCase { - /// snake_case format (e.g., `brew_coffee`) + /// snake_case format: words are separated by underscores, all lowercase. + /// + /// Example: `brew_coffee` #[default] Snake, - /// camelCase format (e.g., `brewCoffee`) + /// camelCase format: first word is lowercase, subsequent words are capitalized. + /// + /// Example: `brewCoffee` Camel, - /// PascalCase format (e.g., `BrewCoffee`) + /// PascalCase format: every word starts with an uppercase letter. + /// + /// Example: `BrewCoffee` Pascal, - /// kebab-case format (e.g., `brew-coffee`) + /// kebab-case format: words are separated by hyphens, all lowercase. + /// + /// Example: `brew-coffee` Kebab, - /// dot.case format (e.g., `brew.coffee`) + /// dot.case format: words are separated by dots, all lowercase. + /// + /// Example: `brew.coffee` Dot, - /// Title Case format (e.g., `Brew Coffee`) + /// Title Case format: words are separated by spaces, each word capitalized. + /// + /// Example: `Brew Coffee` Title, - /// lower case format (e.g., `brew coffee`) + /// lower case format: words are separated by spaces, all lowercase. + /// + /// Example: `brew coffee` Lower, - /// UPPER CASE format (e.g., `BREW COFFEE`) + /// UPPER CASE format: words are separated by spaces, all uppercase. + /// + /// Example: `BREW COFFEE` Upper, } diff --git a/mingling_picker/src/parselib/utils.rs b/mingling_picker/src/parselib/utils.rs index 726346c..47c5b55 100644 --- a/mingling_picker/src/parselib/utils.rs +++ b/mingling_picker/src/parselib/utils.rs @@ -3,6 +3,11 @@ use crate::{ parselib::{MaskedArg, ParserStyle}, }; +/// Builds a list of possible flag strings for the given argument info +/// +/// This function generates formatted flag strings (e.g., `-h`, `--help`) from the short flag, +/// long flag, and any aliases defined in the argument info. The long flag and alias names +/// are converted according to the style's naming case convention before being formatted. #[inline(always)] pub fn build_possible_flags(style: &ParserStyle, arg_info: &PickerArgInfo) -> Vec<String> { let mut possible_flags = vec![]; diff --git a/mingling_picker_macros/README.md b/mingling_picker_macros/README.md index e69de29..5a3f220 100644 --- a/mingling_picker_macros/README.md +++ b/mingling_picker_macros/README.md @@ -0,0 +1,40 @@ +# Mingling Picker Macros + +Procedural macros for [Mingling Picker](https://github.com/mingling-rs/mingling/tree/main/mingling_picker), enabled by the `mingling/picker` feature. + +```toml +[dependencies.mingling] +version = "0.3.0" +features = [ + "picker" +] +``` + +## Provided Macros + +### Macro `arg!` + +Declares a parameter definition for use with `Picker`'s `.pick()` method: + +```rust,ignore +use mingling_picker_macros::arg; + +// Named flag with a value +let flag = arg![name: String]; + +// Named flag with short form +let flag = arg![name: String, 'n']; + +// Named flag with alias +let flag = arg![name: String, 'n', "nickname"]; + +// Positional parameter +let flag = arg![String]; + +// Flag-only parameter (boolean) +let flag = arg![verbose: Flag]; +``` + +### Macro `internal_repeat!` (Internal) + +Internal macro used by Picker to generate `PickerPattern1..=32` and their parsing logic. Not intended for direct use. diff --git a/mingling_picker_macros/src/lib.rs b/mingling_picker_macros/src/lib.rs index 33bb67d..a12e3ed 100644 --- a/mingling_picker_macros/src/lib.rs +++ b/mingling_picker_macros/src/lib.rs @@ -1,3 +1,5 @@ +#![doc = include_str!("../README.md")] + use proc_macro::TokenStream; mod arg; |