- Learn Mingling and use it to create your first command-line program -
- -## Intro - - This chapter will guide you through **Mingling** step by step. - - Before we start, let me explain what **Mingling** can do: - - Without extra features, it is a sub-command dispatch system based on `proc-macro`: it matches user input, finds & creates the corresponding data, then pushes that data into a dispatcher that continually transforms its type. When the data can no longer be transformed, the program renders the final result to the terminal. - - In other words, you need to understand a new dev paradigm: **a fully type-based dispatch system**. This may feel **frustrating** at first, but once you get the hang of it, you'll be able to write CLI apps that are super easy to modify and extend. - - - -## Creating a Basic Program - - Next I'll walk you through creating a basic program—I assume you already have an empty Rust project ready! - -#### 1. Add Dependencies - - Add the following deps to `Cargo.toml` ✏️ - -```toml -[dependencies] -mingling = "0.1.9" - -# If you want the latest, try the version hosted on Github -mingling = { git = "https://github.com/catilgrass/mingling", branch = "main" } -``` - -> [!NOTE] -> -> This version matches the **Mingling** version used when writing this doc. Check [crates.io](https://crates.io/crates/mingling) for the latest release! 😄 -> -> **Mingling** docs are actively updated to keep pace with the latest version. - - - -#### 2. Create the Program - - Now, create the program in `src/main.rs` ✏️ - -```rust -fn main() { - // Create ThisProgram and run it - ThisProgram::new().exec(); -} - -// The gen_program! macro collects *all preceding* components & types -// then generates the `ThisProgram` struct -mingling::macros::gen_program!(); -``` - -> [!TIP] -> -> When `gen_program!()` expands, it gathers info from other components & types that were expanded before it. This means you must place `gen_program!()` at the very last expansion point in the crate. -> -> I recommend putting it at the end of `main.rs` or `lib.rs`. - - - -#### 3. Create a Command - - Of course, the program currently does nothing—it won't output anything at runtime. So let's create our first command `greet` and say hi to someone ✏️ - -```rust -fn main() { - // ... -} - -// Create a dispatcher, binding GreetCommand to the "greet" sub-command -// When the user specifies this command, send GreetEntry to the dispatcher -dispatcher!("greet", GreetCommand => GreetEntry); - -// ... -gen_program!(); -``` - - Don't be scared by the sudden macro and two new types! Let me explain what this macro does: - -##### About the `dispatcher!` macro 💡 - -1. It creates a `GreetCommand` struct and implements the `Dispatcher` trait - - *This tells the framework: there's a new dispatcher that will handle a sub-command's behavior.* - -2. It implements the `Dispatcher` trait's `node(&self) -> Node` function, setting the node to `"greet"` - - *This tells the framework: this dispatcher handles the `"greet"` sub-command.* - -3. It implements the `Dispatcher` trait's `begin` function, converting the user's full input into the first type `GreetEntry` - - *This tells the framework: when this dispatcher is matched, it sends a `GreetEntry` type to the dispatcher for further processing.* - - In short: **"When user types `greet`, I create a `GreetEntry` and throw it into the dispatcher for conversion."** - - - -#### 4. Register the Command - - After creating the `Dispatcher`, we have two types: `GreetCommand` and `GreetEntry`. First, register `GreetCommand` with `ThisProgram` ✏️ - -```rust -fn main() { - let mut program = ThisProgram::new(); - - // Register the dispatcher - program.with_dispatcher(GreetCommand); - program.exec(); -} -``` - - Now `ThisProgram` recognizes the `"greet"` sub-command, but the framework still doesn't know what `"greet"` should do. That's where we implement the actual logic: - - - -#### 5. Implement Rendering Behavior - - We want `"greet"` to output `"Hello, World"`: since we're outputting to the screen, we can use another **Mingling** component, `Renderer`, which handles rendering data to the terminal ✏️ - -```rust -// ... -dispatcher!("greet", GreetCommand => GreetEntry); - -// Declare a renderer `render_greet`, specifying the previous type as `GreetEntry` -#[renderer] -fn render_greet(_prev: GreetEntry) { - r_println!("Hello, World!"); -} - -// ... -gen_program!(); // The renderer will be registered with the program -``` - - For functions marked with `#[renderer]`, **Mingling** strictly enforces only one function signature: - -```rust -#[renderer] -fn renderer_name (_prev: PreviousType) { } -``` - - The macro reads the type of the first param and tells `gen_program!` that this function renders that type. - -##### About `r_println!()` 💡 - - You might notice that the print macro used inside `#[renderer]` is `r_println!` instead of `println!`. This is because the framework's rendering logic doesn't happen inside that function: after `#[renderer]` expands, it injects a `__renderer_inner_result: &mut RenderResult` into the function; `r_println!` appends the message to the `RenderResult`, and after the dispatcher closes, the final rendered data is handed to `Program::exec` for output. - - - -#### 6. Add Execution Logic - - I bet you're already itching to implement something like `greet Alice` to output `"Hello, Alice!"`—and this section is about to do just that! - - **Mingling**'s core execution flow is `Dispatcher -> Chain -> Renderer`, and the key part is `Chain`: it converts the input data type into another type, then lets the dispatcher find the next `Chain` or `Renderer` based on the result type ✏️ - -```rust -dispatcher!("greet", GreetCommand => GreetEntry); - -// Wrap the intermediate type `ResultGreetSomeone` -pack!(ResultGreetSomeone = String); - -#[chain] -fn handle_greet_entry(prev: GreetEntry) -> Next { - let args = prev.inner; - let name = args - .first() - .cloned() - .unwrap_or_else(|| "World".to_string()); - - // Wrap into intermediate type - ResultGreetSomeone::new(name) -} - -#[renderer] -fn render_greet_someone(prev: ResultGreetSomeone) { - // Deref prev to get the raw type - r_println!("Hello, {}!", *prev); -} -``` - - Just like `#[renderer]`, we created a `#[chain]` that processes type `GreetEntry` and outputs `ResultGreetSomeone`. - - This inserts a `Chain` between the original `Dispatcher` and `Renderer`: it extracts the user's input params (or falls back to "World"), then passes them to the renderer to print to the terminal. - -##### About `Next` 💡 - - `Next` is a placeholder generated by `gen_program!()`. After `#[chain]` expands, it's replaced by a type-erased type `ChainProcess- Written by @Weicao-CatilGrass -
diff --git a/docs/pages/2-implementing-fallbacks.md b/docs/pages/2-implementing-fallbacks.md deleted file mode 100644 index 3f3cb93..0000000 --- a/docs/pages/2-implementing-fallbacks.md +++ /dev/null @@ -1,141 +0,0 @@ -- Handling error cases in your program using a fallback mechanism -
- -## Recap - - In the last post, we introduced how to develop a basic CLI program using **Mingling**: you can use the `"greet"` subcommand to output `"Hello, World!"`, or use `"greet Alice"` to output `"Hello, Alice!"` - - But what happens when the user does not enter `"greet"`? Let's type a command and find out ⌨️ - -```bash -~> your-bin hello -~> your-bin hello Alice -``` - - **It does nothing!** 👆 - - Let me explain why: **Mingling** doesn't presume to act; it will not output anything to the terminal no matter what happens (except for `panic!` under `unwind`) - - This means that if you need to actively do something when your CLI program encounters an error, you have to state it explicitly. - - Fortunately, **Mingling** provides a convenient interface for this functionality: inside the `gen_program!` macro, two `FallBack` types are generated - -|Type|When it occurs|How it occurs| -|-|-|-| -|RendererNotFound|When a renderer cannot be found for scheduling|Scheduled as a `Chain`| -|DispatcherNotFound|When a command is entered but no dispatcher matches|Scheduled as a `Chain`| - -### The `DispatcherNotFound` Type - - Let's first focus on the `DispatcherNotFound` type. It is produced as follows: - -```rust -// 1. Define the `greet` command -dispatcher!("greet", GreetCommand => GreetEntry); - -fn main() { - // ->> User enters "hello Alice" - let mut program = ThisProgram::new(); - - // 2. Import the `greet` command - program.with_dispatcher(GreetCommand); - - // 3. Execute the program - program.exec(); -} - -// ... - -// 5. Receive the DispatcherNotFound dispatch -#[renderer] -fn dispatcher_not_found(prev: DispatcherNotFound) { - // 6. Output - r_println!( - "Cannot match any command! Current input: \"{}\"", - prev.join(" ") - ); -} - -// 4. Cannot match any dispatcher named `hello` -// Forward the user's arguments as-is to DispatcherNotFound -gen_program!(); -``` - - The output of the above program is: - -```bash -~> omg hello -Cannot match any command! Current input: "hello" - -~> omg hello Alice -Cannot match any command! Current input: "hello Alice" -``` - - Now, if the user enters a command that doesn't match, **Mingling** will output the appropriate message! - -## The `RendererNotFound` Type - - `RendererNotFound` can be produced in two ways: - - 1. The type was explicitly dispatched to a `Renderer` (using the `.to_render()` function), but the type does not have a renderer implementation - 2. The type was dispatched to a `Chain`, but the type has neither a chain nor a renderer implementation - - Generally, `RendererNotFound` **should not occur in business logic**: its dispatch means your type needs to be rendered but can't be. You can use this type to pinpoint which type is missing a renderer implementation ✏️ - -```rust -dispatcher!("greet", GreetCommand => GreetEntry); - -fn main() { - let mut program = ThisProgram::new(); - - program.with_dispatcher(GreetCommand); - program.exec(); -} - -pack!(ResultGreetSomeone = String); - -#[chain] -fn handle_greet_entry(prev: GreetEntry) -> Next { - let args = prev.inner; - let name = args.first().cloned().unwrap_or_else(|| "World".to_string()); - - ResultGreetSomeone::new(name) -} - -// Let's intentionally remove the renderer implementation for `ResultGreetSomeone` -// #[renderer] -// fn render_greet_someone(prev: ResultGreetSomeone) { -// r_println!("Hello, {}!", *prev); -// } - -#[renderer] -fn renderer_not_found(prev: RendererNotFound) { - if *prev == "DispatcherNotFound" { - return; // Exclude the "DispatcherNotFound" type - } - - // Trigger `panic!` when a renderer is not found - panic!("Renderer \"{}\" not found!", *prev); -} - -gen_program!(); - -``` - - The output of the above program is: - -```bash -~> your-bin greet Alice - -thread 'main' (90772) panicked at src/bin/your-bin.rs:30:5: -Renderer "ResultGreetSomeone" not found! -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace -``` - - The above is the fallback mechanism of **Mingling**. In the next chapter, you will learn how to use `Picker` to parse complex user inputs. - -- Written by @Weicao-CatilGrass -
diff --git a/docs/pages/3-parsing-complex-arguments.md b/docs/pages/3-parsing-complex-arguments.md deleted file mode 100644 index 141c571..0000000 --- a/docs/pages/3-parsing-complex-arguments.md +++ /dev/null @@ -1,364 +0,0 @@ -- Use Mingling Picker to parse complex user input -
- -## Intro - - In the prev. example, we built a CLI app with a `"greet"` subcommand that outputs the user's first arg. - - You may have noticed the approach used was almost direct string manipulation—not very semantic, and hard to maintain long-term. - -```rust -let name = args.first().cloned().unwrap_or_else(|| "World".to_string()); -``` - - This chapter introduces a new **Mingling** feature: `Picker`. It provides a lightweight parsing solution that meshes well with **Mingling**'s typed routing. - - To enable `Picker`, edit `Cargo.toml` ✏️ - -```toml -[dependencies] -mingling = { - version = "...", - features = ["parser"] -} -``` - - Enough talk, let's get coding and rewrite the parsing logic from the prev. section ✏️ - -```rust -#[chain] -fn handle_greet_entry(prev: GreetEntry) -> Next { - // Prev. approach: - // let args = prev.inner; - // let name = args.first().cloned().unwrap_or_else(|| "World".to_string()); - - // New approach with Picker - let name = prev.pick_or((), "World").unpack(); - - ResultGreetSomeone::new(name) -} -``` - - `Picker` implements `pick`, `pick_or`, and `pick_or_route` for anything `Into- Written by @Weicao-CatilGrass -
diff --git a/docs/pages/4-implementing-help-display.md b/docs/pages/4-implementing-help-display.md deleted file mode 100644 index 625863e..0000000 --- a/docs/pages/4-implementing-help-display.md +++ /dev/null @@ -1,4 +0,0 @@ -- Implement help documentation for commands using the help macro -
diff --git a/docs/pages/5-implementing-completion.md b/docs/pages/5-implementing-completion.md deleted file mode 100644 index 7622775..0000000 --- a/docs/pages/5-implementing-completion.md +++ /dev/null @@ -1,4 +0,0 @@ -- Implementing a fully dynamic completion system using Mingling Completion -
-- cgit