- Mingling's Basic Components -
- ---- - -## Intro - -`Program` is the data structure that holds the state for **Mingling** CLI programs. It manages the user's context and enables type-based dispatch. - -`Program` needs to implement the `ProgramCollect` trait, - -> but, you don't have to do this manually — - -The `mingling_macros` crate provides the `gen_program!()` macro, which can auto collect resources defined by the `dispatcher!`, `chain!`, and the `completion!` macro of the `comp` feature. - -```rust -// Define Dispatcher -dispatcher!("hello", HelloCommand => HelloEntry); - -// Define Renderer -#[renderer] -fn render_hello(_prev: HelloEntry) { - r_println!("Hello, World!") -} - -// Collect all resources here and generate ThisProgram -gen_program!(); - -// You can also explicitly declare a Program -// with a different name like this: -// gen_program!(MyProgram); -``` - -## Adding Setup - -You can use the `with_setup` function to add preset [Setup](pages/2-basic/2-setup) to your program, which provide reusable functionality. - -For example, you can use the following code to add parsing for global flags like `--confirm` / `--help` / `--quiet` to your program: - -```rust -use mingling::{ - macros::gen_program, - setup::BasicProgramSetup -}; - -fn main() { - let mut program = ThisProgram::new(); - // Add `BasicProgramSetup` - program.with_setup(BasicProgramSetup); - program.exec(); -} - -// Generate `ThisProgram` -gen_program!(); -``` - -## Adding Dispatcher - -You can use `with_dispatcher` or `with_dispatchers` to add [Dispatchers](pages/2-basic/3-dispatcher) to your program to make it work: - -```rust -// Define two Dispatchers using `dispatcher!` -dispatcher!("member.add", - AddMemberCommand => AddMemberEntry); -dispatcher!("member.rm", - RemoveMemberCommand => RemoveMemberEntry); - -fn main() { - let mut program = ThisProgram::new(); - - // Register Dispatchers - program.with_dispatcher(AddMemberCommand); - program.with_dispatcher(RemoveMemberCommand); - - // Or use `with_dispatchers` - program.with_dispatchers(( - AddMemberCommand, - RemoveMemberCommand - )); - - program.exec(); -} -``` - -## Parsing Global Args - -You can extract global arguments before the program runs to control the global state of the `Program`: - -```rust -fn main() { - let mut program = ThisProgram::new(); - - let mut output = current_dir().unwrap(); - - // Pick the "--quiet" or "-q" flag - program.global_flag(["--quiet", "-q"], |p| { - // Disable render output - p.stdout_setting.render_output = false; - }); - - // Pick the "--output" or "-O" flag, write to output - program.global_argument( - ["--output", "-O"], - |_, v| output = PathBuf::from(v) - ); - - program.exec(); -} -``` - -## 💡 Next Page -> **Basic Component** - Setup [Go](./pages/2-basic/2-setup) diff --git a/docs/pages/2-basic/2-setup.md b/docs/pages/2-basic/2-setup.md deleted file mode 100644 index 102e213..0000000 --- a/docs/pages/2-basic/2-setup.md +++ /dev/null @@ -1,150 +0,0 @@ -- Mingling's Basic Components -
- ---- - -## Intro - -`Setup` is used to organize and package the initialization process of a `Program`, making the project easier to manage. - -## Usage - -It is defined as follows: - -```rust -struct MySetup; -impl ProgramSetup- Mingling's Basic Components -
- ---- - -## Intro - -`Dispatcher` is a core concept in **Mingling**, used to dispatch user-input arguments to corresponding types, which are then handled by [Chain](pages/2-basic/4-chain) or [Renderer](pages/2-basic/5-renderer). - -To define a `Dispatcher`, it is recommended to use the `dispatcher!` macro provided by `mingling_macros`: - -```rust -// User input: your_bin hello -// Will access HelloCommand and -// dispatch arguments to HelloEntry -dispatcher!("hello", - HelloCommand => HelloEntry); - -// User input: your_bin sub foo -// Will access FooCommand and -// dispatch arguments to FooEntry -dispatcher!("sub.foo", - FooCommand => FooEntry); - -// Same as above -dispatcher!("sub.bar", - BarCommand => BarEntry); -``` - -If you explicitly specify a name in the `gen_program!` macro, for example: - -```rust -gen_program!(MyProgram); -``` - -Then when using the `dispatcher!` macro, you must also explicitly specify the [Program](pages/2-basic/1-program): - -```rust -dispatcher!(MyProgram, "hello", - HelloCommand => HelloEntry); -``` - -**Tips:** Finally, add the `Dispatcher` you created to the [Program](pages/2-basic/1-program): - -```rust -fn main() { - let mut program = ThisProgram::new(); - program.with_dispatcher(HelloCommand); - program.with_dispatcher(SubFooCommand); - program.with_dispatcher(SubBarCommand); - program.exec(); -} -``` - -## Manual Impl - -You can also manually implement the basic `Dispatcher` for more fine-grained control. However, compared to the procmacro, it is more cumbersome and cannot intelligently introduce certain traits based on the state of feature flags. - -```rust -// Define AddMemberEntry -// Use the `Groupped` derive to -// mark AddMemberEntry as a member of ThisProgram -#[derive(Debug, Groupped)] -pub struct AddMemberEntry { - // Define arguments to store user input - pub(crate) args: Vec- Mingling's Basic Components -
- ---- - -## Intro - -Like `Dispatcher`, `Chain` is also a core concept in building the entire **Mingling** framework. It is used to receive a dispatch of one type and convert it into another type. - -```rust -dispatcher!("hello", - HelloCommand => HelloEntry); - -// Define intermediate type ParsedHello, internally a String -pack!(ParsedHello = String); - -// Define chain parse_hello (expands to ParseHello) -// Declare conversion from HelloEntry -#[chain] -fn parse_hello(prev: HelloEntry) -> NextProcess { - // Take the inner reference of HelloEntry - let args = &*prev; - - // Extract the first argument, use default value "World" - // if it doesn't exist - let first = args.first().cloned().unwrap_or_else(|| "World".to_string()); - - // Pack the extracted argument into ParsedHello and - // dispatch to the next chain - ParsedHello::new(first).to_chain() -} -``` - -> [!Tip] -> `NextProcess` is a marker type in **Mingling**, from `mingling::marker`. -> -> It serves no functional purpose other than to simplify the declaration of chain functions. After the `chain!` macro expands, `NextProcess` will be replaced with `mingling::ChainProcess- Mingling's Basic Components -
- ---- - -## Intro - -`Renderer` is similar to [Chain](pages/2-basic/4-chain) in that they both handle processing for a specific type. The difference is: [Chain](pages/2-basic/4-chain) transforms the type, while `Renderer` terminates the program and prints the information of that type to the terminal. - -A type can be processed by both [Chain](pages/2-basic/4-chain) and `Renderer`. If the type is `route_chain`ed, the system will search for a [Chain](pages/2-basic/4-chain) capable of handling that type. If none is found, it will automatically be routed to the `Renderer` to print the result of that type. - -The following example demonstrates how to handle rendering logic: - -```rust -dispatcher!("hello", - HelloCommand => HelloEntry); - -pack!(ParsedHello = String); - -// It's the Chain defined in the Dispatcher chapter -#[chain] -fn parse_hello(prev: HelloEntry) -> NextProcess { - let args = &*prev; - let first = args - .first() - .cloned() - .unwrap_or_else(|| - "World".to_string() - ); - - // Distribute the type to the Renderer - ParsedHello::new(first).to_render() -} - -// Define the renderer to -// handle rendering of ParsedHello -#[renderer] -fn render_hello(prev: ParsedHello) { - // Use r_println or r_print to - // render the content of ParsedHello - r_println!("Hello, {}!", *prev) -} -``` - -> [!Tip] -> `r_print!` can only be used inside a `Renderer`. This is because after the `renderer!` macro expands, it injects `r: &mut RenderResult` into the context. -> -> And `r_print!` directly writes content to the value `r`. -> This means: if there is no `&mut RenderResult` named `r` in the context, `r_print!` cannot be used. - -## Manual Impl - -Similarly, you can also manually implement `Renderer`, - -but note that inside the `renderer!` macro, a `register_type!` macro is executed. This macro itself does not expand into any content; it is only used to inform the `gen_program` context that the type exists: - -```rust -struct RenderHello; -impl Renderer for RenderHello { - type Previous = ParsedHello; - fn render( - prev: Self::Previous, - r: &mut RenderResult - ) { - r_println!("Hello, {}!", *prev) - } -} - -// Register renderer to the context -register_renderer!(ParsedHello, RenderHello); -``` -- cgit