Shellfish

https://docs.rs/shellfish/latest/
Admin
Shellfish is a Rust crate providing utilities for building command-line applications, including...
Tokens:74,814
Snippets:725
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Help String

Source: https://docs.rs/shellfish/latest/shellfish/command/struct.Command.html

An example of a help string for a command, illustrating the character limit.

```rust
prints the arguments to the output.
```

--------------------------------

### Example Usage of clap_command Macro

Source: https://docs.rs/shellfish/latest/shellfish/macro.clap_command.html

Demonstrates how to use the clap_command macro to register synchronous and asynchronous commands with a shell. Requires the 'clap' feature flag.

```rust
#[derive(Parser, Debug)]
#[clap(author, version, about)]
struct Args {
    // - snip
}

shell.commands.insert("greet", clap_command!((), Args, greet));
shell.commands.insert("greet-async", clap_command!((), Args, async greet_async));

fn greet(_state: &mut (), args: Args) -> Result<(), Box<dyn std::error::Error>> {
    // - snip
}

async fn greet_async(_state: &mut (), args: Args) -> Result<(), Box<std::io::Error>> {
    // - snip
}
```

--------------------------------

### Create New Painted Instance

Source: https://docs.rs/shellfish/latest/shellfish/input_handler/enum.InputResult.html

Creates a new `Painted` instance with a default style. This is the starting point for applying various text styles.

```rust
fn new(self) -> Painted<Self>
where Self: Sized,
Create a new `Painted` with a default `Style`. Read more
```

--------------------------------

### Shell::run

Source: https://docs.rs/shellfish/latest/shellfish/shell/struct.Shell.html

Starts running the synchronous shell, processing commands and events until completion. Returns a Result indicating success or failure.

```APIDOC
## Shell::run

### Description
Starts running the shell.

### Method
Instance Method

### Signature
`pub fn run(&mut self) -> Result<()>`

### Returns
`Result<()>` - Ok(()) on success, or an error if the shell fails to run.
```

--------------------------------

### Shell::run_async

Source: https://docs.rs/shellfish/latest/shellfish/shell/struct.Shell.html

Starts running the asynchronous shell, processing commands and events until completion. This method is `async` and requires an `await`. Available only when the `async` crate feature is enabled.

```APIDOC
## Shell::run_async

### Description
Starts running the shell. Available on `async` crate feature only.

### Method
Instance Method

### Signature
`pub async fn run_async(&mut self) -> Result<()>`

### Returns
`Result<()>` - Ok(()) on success, or an error if the shell fails to run.
```

--------------------------------

### Shellfish with Clap Argument Parsing

Source: https://docs.rs/shellfish/latest/shellfish/command/index.html

Integrates Shellfish with the 'clap' crate for robust command-line argument parsing. This example shows a 'greet' command that accepts 'name', 'age', and 'formal' options.

```rust
// ... imports ...

/// Simple command to greet a person
///
/// This command will greet the person based of a multitide
/// of option flags, see below.
#[derive(Parser, Debug)]
#[clap(author, version, about)]
struct GreetArgs {
    /// Name of the person to greet
    name: String,

    /// Age of the person to greet
    #[clap(short, long)]
    age: Option<u8>,

    /// Whether to be formal or note
    #[clap(short, long)]
    formal: bool,
}

#[async_std::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Define a shell
    let mut shell = Shell::new_with_async_handler(
        (),
        "<[Shellfish Example]>-$ ",
        DefaultAsyncHandler::default(),
        DefaultEditor::new()?,
    );
    shell
        .commands
        .insert("greet", clap_command!((), GreetArgs, greet));
    shell.run_async().await?;

    Ok(())
}

fn greet(
    _state: &mut (),
    args: GreetArgs,
) -> Result<(), Box<dyn std::error::Error>> {

    // .. snip .. /
    
    Ok(())
}

```

--------------------------------

### Shellfish clap_command! Macro Usage Example

Source: https://docs.rs/shellfish/latest/src/shellfish/clap_command.rs.html

Demonstrates how to define a clap parser and use the clap_command! macro to register both synchronous and asynchronous commands with Shellfish. Requires the 'async' feature for async commands.

```rust
use shellfish::clap_command;
use clap::Parser;
use std::error::Error;

#[derive(Parser, Debug)]
#[clap(author, version, about)]
struct Args {
    // - snip
}

// Example for synchronous command
// shell.commands.insert("greet", clap_command!((), Args, greet));

// Example for asynchronous command
// shell.commands.insert("greet-async", clap_command!((), Args, async greet_async));

fn greet(_state: &mut (), args: Args) -> Result<(), Box<dyn Error>> {
    // - snip
    Ok(())
}

async fn greet_async(_state: &mut (), args: Args) -> Result<(), Box<dyn Error>> {
    // - snip
    Ok(())
}

```

--------------------------------

### fn type_id(&self) -> TypeId

Source: https://docs.rs/shellfish/latest/shellfish/shell/struct.Shell.html

Gets the TypeId of the current object. This is part of the Any trait implementation.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`. This method is part of the `Any` trait implementation.

### Returns
- `TypeId`: The unique identifier for the type of `self`.
```

--------------------------------

### App::new

Source: https://docs.rs/shellfish/latest/shellfish/app/struct.App.html

Creates a new App instance with initial state and project name.

```rust
pub fn new(state: T, project_name: String) -> Result<Self, Box<dyn Error>>
```

--------------------------------

### App::new

Source: https://docs.rs/shellfish/latest/shellfish/app/struct.App.html

Creates a new App instance with a given state and project name. This is a constructor for the App struct.

```APIDOC
## pub fn new(state: T, project_name: String) -> Result<Self, Box<dyn Error>>

### Description
Creates a new shell.

### Parameters
* **state** (T) - The initial state of the application.
* **project_name** (String) - The name of the project.
```

--------------------------------

### Create a new App with default handler

Source: https://docs.rs/shellfish/latest/src/shellfish/app.rs.html

Initializes a new App instance with a default command-line handler. The project name is used for cache file naming. State is loaded from the cache if available.

```rust
impl<T: Serialize + for<'a> Deserialize<'a>>
    App<'_, T, DefaultCommandLineHandler>
{
    /// Creates a new shell
    pub fn new(state: T, project_name: String) -> Result<Self, Box<dyn Error>> {
        let mut this = Self {
            commands: HashMap::new(),
            state,
            handler: DefaultCommandLineHandler {
                proj_name: Some(project_name),
            },
            description: String::new(),
        };
        this.load_cache()?;
        Ok(this)
    }
}
```

--------------------------------

### new

Source: https://docs.rs/shellfish/latest/shellfish/handler/app/struct.DefaultCommandLineHandler.html

Create a new `Painted` with a default `Style`. Read more.

```APIDOC
## new

### Description
Create a new `Painted` with a default `Style`.

### Method
`new()`

### Constraints
`Self: Sized`
```

--------------------------------

### Conditionally Apply Styling

Source: https://docs.rs/shellfish/latest/shellfish/input_handler/struct.IO.html

Conditionally applies styling based on a `Condition`. This method replaces any previous condition. Example shows styling only when stdout and stderr are TTYs.

```rust
use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
```

--------------------------------

### new

Source: https://docs.rs/shellfish/latest/shellfish/handler/asynchronous/struct.DefaultAsyncHandler.html

Create a new `Painted` with a default `Style`. Read more.

```APIDOC
## new

### Description
Create a new `Painted` with a default `Style`.

### Method
`new()`

### Parameters
None

### Response
Returns a new `Painted<Self>`.

### Request Example
```
let painted = Painted::new();
```
```

--------------------------------

### Creating a Synchronous Command

Source: https://docs.rs/shellfish/latest/shellfish/command/struct.Command.html

Demonstrates how to create and insert a synchronous command into a Shell instance.

```rust
use shellfish::*
use std::error::Error;

fn greet(_state: &mut (), args: Vec<String>) -> Result<(), Box<dyn Error>> {
    //--snip--
}

fn main() {
    // Creates a shell
    let mut shell = Shell::new((), "[Shell]-$");

    // Creates a command
    shell.commands.insert(
        "greet",
        Command::new("greets_you".to_string(), greet),
    );
}
```

--------------------------------

### Get Cache Path

Source: https://docs.rs/shellfish/latest/src/shellfish/handler/app.rs.html

Determines the cache file path based on the operating system (Linux, Windows, MacOS). Returns None if the home directory cannot be found.

```rust
fn get_cache(&self) -> Option<PathBuf> {
        let mut path = home::home_dir()?;
        #[cfg(target_os = "windows")]
        {
            path.push("AppData");
            path.push("Local");
        }
        #[cfg(target_os = "linux")]
        {
            path.push(".cache");
        }
        #[cfg(target_os = "macos")]
        {
            path.push("Library Support");
        }
        path.push(self.proj_name.as_ref().unwrap_or(&env::args().next()?));
        path.push("shellfish.json");
        Some(path)
    }
```

--------------------------------

### new

Source: https://docs.rs/shellfish/latest/shellfish/command/enum.CommandType.html

Create a new Painted with a default Style.

```APIDOC
## new

### Description
Create a new `Painted` with a default `Style`.
Read more

### Method
`new(self) -> Painted<Self>`

### Constraints
`where Self: Sized`
```

--------------------------------

### Run Shell Asynchronously

Source: https://docs.rs/shellfish/latest/src/shellfish/shell.rs.html

Starts the shell's main loop, reading and processing commands asynchronously. Handles input, command execution, and exit conditions.

```rust
pub async fn run_async(&mut self) -> io::Result<()> {
        '_shell: loop {
            // Read a line
            let line =
                match self.input_handler.read(&self.prompt.to_string())? {
                    InputResult::S(line) => line,
                    InputResult::Interrupted => continue '_shell,
                    InputResult::EOF => break '_shell,
                };

            // Runs the line
            match Self::unescape(line.trim()) {
                Ok(line) => {
                    if self
                        .handler
                        .handle_async(
                            line,
                            &self.commands,
                            &mut self.state,
                            &self.description,
                        )
                        .await
                    {
                        break '_shell;
                    }
                }
                Err(e) => eprintln!("{}", Paint::red(&e.to_string())),
            }
        }
        Ok(())
    }
```

--------------------------------

### Creating an Asynchronous Command

Source: https://docs.rs/shellfish/latest/shellfish/command/struct.Command.html

Shows how to create and insert an asynchronous command using `Command::new_async` and `async_fn!`.

```rust
use shellfish::*
use std::error::Error;

async fn greet(_state: &mut (), args: Vec<String>) -> Result<(), Box<dyn Error>> {
    //--snip--
}

async fn async_main() {
    // Creates a shell
    let mut shell = Shell::new((), "[Shell]-$");

    // Creates a command
    shell.commands.insert(
        "greet",
        Command::new_async("greets_you".to_string(), async_fn!((), greet)),
    );
}
```

--------------------------------

### Command::new

Source: https://docs.rs/shellfish/latest/shellfish/command/struct.Command.html

Creates a new synchronous `Command` instance. This method takes a help string and a command function pointer as arguments.

```APIDOC
## Command::new

### Description
Creates a new synchronous `Command`.

### Method
`pub fn new(help: String, command: CommandFn<T>) -> Self`

### Parameters
* **help** (String) - Description for the command.
* **command** (CommandFn<T>) - The function pointer for the command.

### Example
```rust
use shellfish::*
use std::error::Error;

fn greet(_state: &mut (), args: Vec<String>) -> Result<(), Box<dyn Error>> {
    //--snip--
    Ok(())
}

fn main() {
    let mut shell = Shell::new((), "[Shell]-$");
    shell.commands.insert(
        "greet",
        Command::new("greets_you".to_string(), greet),
    );
}
```
```

--------------------------------

### new

Source: https://docs.rs/shellfish/latest/shellfish/input_handler/enum.InputResult.html

Creates a new `Painted` object with a default style.

```APIDOC
## new

### Description
Create a new `Painted` with a default `Style`.

### Method
`new()`

### Parameters
None

### Response
Returns a new `Painted<Self>` object.

### Request Example
```
let painted = Painted::new();
```
```

--------------------------------

### new

Source: https://docs.rs/shellfish/latest/shellfish/handler/async_app/struct.DefaultAsyncCLIHandler.html

Creates a new `Painted` object with a default style.

```APIDOC
## new

### Description
Create a new `Painted` with a default `Style`. Read more

### Method
This is a constructor method.

### Endpoint
N/A

### Parameters
* **self** - The object to create a `Painted` version of.

### Request Example
```
// Assuming 'value' is of a type that can be converted into Painted
let painted_value = value.new();
```

### Response
#### Success Response
Returns a new `Painted<Self>` object.

#### Response Example
```
// A new Painted object
```
```

--------------------------------

### Create a new App with a custom handler

Source: https://docs.rs/shellfish/latest/src/shellfish/app.rs.html

Initializes a new App instance with a provided command-line handler. This is useful when a custom handler is needed that can manage CLI arguments, as the first argument is expected to be the binary name.

```rust
impl<T: Serialize + for<'a> Deserialize<'a>, H: CommandLineHandler>
    App<'_, T, H>
{
    /// Creates a new shell with the given handler.
    ///
    /// **Note that this should be a handler which can deal with cli
    /// arguments, as in the FIRST ARGUMENT is the BINARY name.**
    pub fn new_with_handler(
        state: T,
        handler: H,
    ) -> Result<Self, Box<dyn Error>> {
        let mut this = Self {
            commands: HashMap::new(),
            state,
            handler,
            description: String::new(),
        };
        this.load_cache()?;
        Ok(this)
    }
}
```

--------------------------------

### new

Source: https://docs.rs/shellfish/latest/shellfish/shell/enum.UnescapeError.html

Create a new `Painted` with a default `Style`.

```APIDOC
## new

### Description
Create a new `Painted` with a default `Style`.

### Method
`new()`

### Parameters
* **self** - The object to create a new `Painted` from.

### Response
Returns a new `Painted<Self>` object.

### Example
(No example provided in source)
```

--------------------------------

### new

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Create a new `Painted` with a default `Style`.

```APIDOC
## new

### Description
Create a new `Painted` with a default `Style`.

### Method
This is a constructor method, not an HTTP endpoint.

### Endpoint
N/A

### Parameters
N/A

### Request Example
```
Painted::new()
```

### Response
#### Success Response
Returns a new `Painted<Self>` object.

#### Response Example
N/A
```

--------------------------------

### Enable Wrapping using wrap()

Source: https://docs.rs/shellfish/latest/shellfish/input_handler/struct.IO.html

Demonstrates the preferred method for enabling text wrapping using the `.wrap()` builder method.

```rust
use yansi::Paint;

painted.wrap();
```

--------------------------------

### Set Background Color using bg() and on_red()

Source: https://docs.rs/shellfish/latest/shellfish/input_handler/struct.IO.html

Demonstrates setting the background color. The `bg()` method is rarely used; prefer specific methods like `on_red()` for clarity and conciseness.

```rust
use yansi::{Paint, Color};

painted.bg(Color::Red);
```

```rust
use yansi::Paint;

painted.on_red();
```

--------------------------------

### App::try_from_async

Source: https://docs.rs/shellfish/latest/shellfish/app/struct.App.html

Creates an App instance from a Shell for asynchronous command handling. Requires `async` feature.

```rust
pub fn try_from_async<M: Display, H: AsyncHandler<T>, I: InputHandler>( shell: Shell<'f, T, M, H, I>, ) -> Result<Self, Box<dyn Error>>
```

--------------------------------

### Basic Shellfish Commands

Source: https://docs.rs/shellfish/latest/shellfish/command/index.html

Creates a Shellfish instance with custom commands: greet, echo, count, and cat. Supports both interactive and non-interactive modes based on command-line arguments.

```rust
use std::error::Error;
use std::fmt;
use std::ops::AddAssign;

use async_std::prelude::*;
use rustyline::DefaultEditor;
use shellfish::{app, handler::DefaultAsyncHandler, Command, Shell};

#[macro_use] 
extern crate shellfish;

#[async_std::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Define a shell
    let mut shell = Shell::new_with_async_handler(
        0_u64,
        "<[Shellfish Example]>-$ ",
        DefaultAsyncHandler::default(),
        DefaultEditor::new()?,
    );

    // Add some commands
    shell
        .commands
        .insert("greet", Command::new("greets you.".to_string(), greet));

    shell
        .commands
        .insert("echo", Command::new("prints the input.".to_string(), echo));

    shell.commands.insert(
        "count",
        Command::new("increments a counter.".to_string(), count),
    );

    shell.commands.insert(
        "cat",
        Command::new_async(
            "Displays a plaintext file.".to_string(),
            async_fn!(u64, cat),
        ),
    );

    // Check if we have > 2 args, if so no need for interactive shell
    let mut args = std::env::args();
    if args.nth(1).is_some() {
        // Create the app from the shell.
        let mut app = app::App::try_from_async(shell)?;

        // Set the binary name
        app.handler.proj_name = Some("shellfish-example".to_string());
        app.load_cache()?;

        // Run it
        app.run_args_async().await?;
    } else {
        // Run the shell
        shell.run_async().await?;
    }
    Ok(())
}

/// Greets the user
fn greet(_state: &mut u64, args: Vec<String>) -> Result<(), Box<dyn Error>> {
    let arg = args.get(1).ok_or_else(|| Box::new(GreetingError))?;
    println!("Greetings {}, my good friend.", arg);
    Ok(())
}

/// Echos the input
fn echo(_state: &mut u64, args: Vec<String>) -> Result<(), Box<dyn Error>> {
    let mut args = args.iter();
    args.next();
    for arg in args {
        print!("{} ", arg);
    }
    println!();
    Ok(())
}

/// Acts as a counter
fn count(state: &mut u64, _args: Vec<String>) -> Result<(), Box<dyn Error>> {
    state.add_assign(1);
    println!("You have used this counter {} times", state);
    Ok(())
}

/// Asynchronously reads a file
async fn cat(
    _state: &mut u64,
    args: Vec<String>,
) -> Result<(), Box<dyn Error>> {
    use async_std::fs;

    if let Some(file) = args.get(1) {
        let mut contents = String::new();
        let mut file = fs::File::open(file).await?;
        file.read_to_string(&mut contents).await?;
        println!("{}", contents);
    }

    Ok(())
}

/// Greeting error
#[derive(Debug)]
pub struct GreetingError;

impl fmt::Display for GreetingError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "No name specified")
    }
}

impl Error for GreetingError {}

```

--------------------------------

### App::new_with_handler

Source: https://docs.rs/shellfish/latest/shellfish/app/struct.App.html

Creates a new App instance with a given state and a command line handler. The handler must be capable of processing CLI arguments.

```APIDOC
## pub fn new_with_handler(state: T, handler: H) -> Result<Self, Box<dyn Error>>

### Description
Creates a new shell with the given handler.

### Parameters
* **state** (T) - The initial state of the application.
* **handler** (H) - The command line handler.
```

--------------------------------

### Creating a Synchronous Shellfish Command

Source: https://docs.rs/shellfish/latest/src/shellfish/command.rs.html

Demonstrates how to create a new synchronous command for a Shellfish shell. This involves defining a function that matches the `CommandFn` signature and then using `Command::new` to register it.

```rust
use shellfish::*
use std::error::Error;

fn greet(_state: &mut (), args: Vec<String>) -> Result<(), Box<dyn Error>> {
    //--snip--
    # Ok(())
}

fn main() {
    // Creates a shell
    let mut shell = Shell::new((), "[Shell]-$");

    // Creates a command
    shell.commands.insert(
        "greet",
        Command::new("greets_you".to_string(), greet),
    );
}
```

--------------------------------

### paint

Source: https://docs.rs/shellfish/latest/shellfish/shell/enum.UnescapeError.html

Apply a style wholesale to `self`. Any previous style is replaced.

```APIDOC
## paint

### Description
Apply a style wholesale to `self`. Any previous style is replaced.

### Method
(Implicitly called on an object)

### Parameters
* **style** (S: Into<Style>) - Required - The style to apply.

### Response
Returns a `Painted<&Self>` object with the specified style applied.

### Example
(No example provided in source)
```

--------------------------------

### paint

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Apply a style wholesale to `self`. Any previous style is replaced.

```APIDOC
## paint

### Description
Apply a style wholesale to `self`. Any previous style is replaced.

### Method
This is a method call on an existing object, not an HTTP endpoint.

### Endpoint
N/A

### Parameters
- **style** (`S where S: Into<Style>`) - Required - The style to apply.

### Request Example
```
painted.paint(yansi::Style::new().red().bold());
```

### Response
#### Success Response
Returns a `Painted<&Self>` object with the specified style applied.

#### Response Example
N/A
```

--------------------------------

### try_from

Source: https://docs.rs/shellfish/latest/shellfish/shell/enum.UnescapeError.html

Performs the conversion.

```APIDOC
## try_from

### Description
Performs the conversion.

### Method
`try_from(value: U)`

### Parameters
* **value** (U: Into<T>) - Required - The value to convert.

### Response
Returns a `Result<T, <T as TryFrom<U>>::Error>`.

### Error Type
`Error = Infallible`

### Example
(No example provided in source)
```

--------------------------------

### Creating an Asynchronous Shellfish Command

Source: https://docs.rs/shellfish/latest/src/shellfish/command.rs.html

Illustrates the creation of an asynchronous command for Shellfish. This requires using the `async_fn!` macro to prepare the async function and then `Command::new_async` to register it with the shell.

```rust
use shellfish::*
use std::error::Error;

async fn greet(_state: &mut (), args: Vec<String>) -> Result<(), Box<dyn Error>> {
    //--snip--
    # Ok(())
}

async fn async_main() {
    // Creates a shell
    let mut shell = Shell::new((), "[Shell]-$");

    // Creates a command
    shell.commands.insert(
        "greet",
        Command::new_async("greets_you".to_string(), async_fn!((), greet)),
    );
}
```

--------------------------------

### Apply Quirk and Wrap

Source: https://docs.rs/shellfish/latest/shellfish/handler/app/struct.DefaultCommandLineHandler.html

Demonstrates applying the Quirk::Wrap using both the generic `quirk` method and the specific `wrap` builder method. Prefer `wrap()` for clarity.

```rust
use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);
```

```rust
use yansi::Paint;

painted.wrap();
```

--------------------------------

### App::try_from_async

Source: https://docs.rs/shellfish/latest/shellfish/app/struct.App.html

Creates a new App instance for asynchronous operations from a Shell. This method is available only when the 'async' feature is enabled.

```APIDOC
## pub fn try_from_async<M: Display, H: AsyncHandler<T>, I: InputHandler>( shell: Shell<'f, T, M, H, I> ) -> Result<Self, Box<dyn Error>>

### Description
Creates a new App instance for asynchronous operations from a Shell.

### Available Features
* async

### Parameters
* **shell** (Shell<'f, T, M, H, I>) - The shell object to create the App from.
```

--------------------------------

### App::run_args_async

Source: https://docs.rs/shellfish/latest/shellfish/app/struct.App.html

Asynchronously runs commands based on the environment arguments. This method is available only when the 'async' feature is enabled.

```APIDOC
## pub async fn run_args_async(&mut self) -> Result<bool>

### Description
Runs from the env args.

### Available Features
* async

### Returns
* Result<bool> - A boolean indicating whether to quit the application.
```

--------------------------------

### try_from

Source: https://docs.rs/shellfish/latest/shellfish/handler/asynchronous/struct.DefaultAsyncHandler.html

Performs the conversion. Read more.

```APIDOC
## try_from

### Description
Performs the conversion from type `U` to type `T`.

### Method
`try_from(value: U)` where `U: Into<T>`

### Parameters
* **value** (U) - The value to convert.

### Response
A `Result<T, <T as TryFrom<U>>::Error>` containing the converted value or an error.

### Request Example
```
let value_u: U = ...;
match T::try_from(value_u) {
    Ok(t) => println!("Successfully converted: {:?}", t),
    Err(e) => println!("Conversion error: {:?}", e),
}
```
```

--------------------------------

### New Async Shell Constructor (Default Async Handler)

Source: https://docs.rs/shellfish/latest/src/shellfish/shell.rs.html

Creates a new asynchronous shell instance with the default async handler and IO input handler. Use `new_with_async_handler` for custom async handlers.

```rust
#[cfg(feature = "async")]
impl<'a, T, M: Display> Shell<'a, T, M, handler::DefaultAsyncHandler, IO> {
    /// Creates a new shell
    ///
    /// If you have the `rustyline` feature enabled use [`new_with_async_handler`]
    /// to use the `rustyline` editor.
    pub fn new_async(state: T, prompt: M) -> Self {
        Shell {
            prompt,
            commands: HashMap::new(),
            state,
            handler: handler::DefaultAsyncHandler(),
            description: String::new(),
            input_handler: IO,
        }
    }
}
```

--------------------------------

### paint

Source: https://docs.rs/shellfish/latest/shellfish/command/enum.CommandType.html

Apply a style wholesale to self. Any previous style is replaced.

```APIDOC
## paint

### Description
Apply a style wholesale to `self`. Any previous style is replaced.
Read more

### Method
`paint<S>(&self, style: S) -> Painted<&Self>`

### Constraints
`where S: Into<Style>`
```

--------------------------------

### fn on_bright_green(&self) -> Painted<&T>

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Sets the background color to `Color::BrightGreen`.

```APIDOC
## fn on_bright_green(&self) -> Painted<&T>

### Description
Returns `self` with the `bg()` set to [`Color :: BrightGreen`].

### Example
```rust
println!("{}", value.on_bright_green());
```
```

--------------------------------

### App::new_with_handler

Source: https://docs.rs/shellfish/latest/shellfish/app/struct.App.html

Creates a new App instance with a custom command-line handler. The first argument to the handler is expected to be the binary name.

```rust
pub fn new_with_handler(state: T, handler: H) -> Result<Self, Box<dyn Error>>
```

--------------------------------

### Shell::new

Source: https://docs.rs/shellfish/latest/shellfish/shell/struct.Shell.html

Creates a new synchronous shell instance with a default handler and IO. If the `rustyline` feature is enabled, consider using `new_with_handler` for editor integration.

```APIDOC
## Shell::new

### Description
Creates a new shell with a default handler and IO.

### Method
Associated Function

### Signature
`pub fn new(state: T, prompt: M) -> Self`

### Parameters
* **state** (T) - The initial state for the shell.
* **prompt** (M) - The displayable prompt for the shell.
```

--------------------------------

### Try to convert Shell to App with default handler

Source: https://docs.rs/shellfish/latest/src/shellfish/app.rs.html

Attempts to convert a Shell instance into an App instance that uses the DefaultCommandLineHandler. This process involves transferring commands, state, and description, and then loading the cache.

```rust
impl<'f: 't, 't, T: Serialize + for<'a> Deserialize<'a>, M: Display, H: Handler<T>, I: InputHandler> TryFrom<Shell<'f, T, M, H, I>> for App<'t, T, DefaultCommandLineHandler>
{
    type Error = Box<dyn Error>;

    fn try_from(shell: Shell<'f, T, M, H, I>) -> Result<Self, Box<dyn Error>> {
        let mut this = Self {
            commands: shell.commands,
            state: shell.state,
            handler: DefaultCommandLineHandler { proj_name: None },
            description: shell.description,
        };
        this.load_cache()?;
        Ok(this)
    }
}
```

--------------------------------

### fn on_bright_white(&self) -> Painted<&T>

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Sets the background color to `Color::BrightWhite`.

```APIDOC
## fn on_bright_white(&self) -> Painted<&T>

### Description
Returns `self` with the `bg()` set to [`Color :: BrightWhite`].

### Example
```rust
println!("{}", value.on_bright_white());
```
```

--------------------------------

### Set Foreground Color using white()

Source: https://docs.rs/shellfish/latest/shellfish/input_handler/struct.IO.html

Demonstrates setting the foreground color to white using the `white()` builder method. This is the preferred method over `fg()` for specific colors.

```rust
use yansi::Paint;

painted.white();
```

--------------------------------

### paint

Source: https://docs.rs/shellfish/latest/shellfish/handler/app/struct.DefaultCommandLineHandler.html

Apply a style wholesale to `self`. Any previous style is replaced. Read more.

```APIDOC
## paint

### Description
Apply a style wholesale to `self`. Any previous style is replaced.

### Method
`paint<S>(&self, style: S) -> Painted<&Self>`

### Parameters
#### Path Parameters
- **style** (S) - Description: The style to apply. `S` must implement `Into<Style>`.

### Constraints
`S: Into<Style>`
```

--------------------------------

### paint

Source: https://docs.rs/shellfish/latest/shellfish/handler/asynchronous/struct.DefaultAsyncHandler.html

Apply a style wholesale to `self`. Any previous style is replaced. Read more.

```APIDOC
## paint

### Description
Apply a style wholesale to `self`. Any previous style is replaced.

### Method
`paint<S>(style: S)` where `S: Into<Style>`

### Parameters
* **style** (S) - The style to apply, which can be converted into a `Style`.

### Response
Returns a `Painted<&Self>` with the specified style applied.

### Request Example
```
let styled_painted = painted.paint(Style::new().bold());
```
```

--------------------------------

### fn on_bright_cyan(&self) -> Painted<&T>

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Sets the background color to `Color::BrightCyan`.

```APIDOC
## fn on_bright_cyan(&self) -> Painted<&T>

### Description
Returns `self` with the `bg()` set to [`Color :: BrightCyan`].

### Example
```rust
println!("{}", value.on_bright_cyan());
```
```

--------------------------------

### App::run_args

Source: https://docs.rs/shellfish/latest/shellfish/app/struct.App.html

Runs commands based on the environment arguments. Returns a boolean indicating if the application should quit.

```APIDOC
## pub fn run_args(&mut self) -> Result<bool>

### Description
Runs from the env args.

### Returns
* Result<bool> - A boolean indicating whether to quit the application.
```

--------------------------------

### bg

Source: https://docs.rs/shellfish/latest/shellfish/shell/struct.Shell.html

Sets the background color to a specified Color value. Prefer specific `on_color()` methods.

```APIDOC
## bg

### Description
Returns a styled value derived from `self` with the background set to `value`. This method should be used rarely. Instead, prefer to use color-specific builder methods like `on_red()` and `on_green()`, which have the same functionality but are pithier.

### Method
This is a builder method, implying a method call on an object.

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **value** (Color) - Required - The color to set the background to.

### Request Example
```rust
use yansi::{Paint, Color};

painted.bg(Color::Red);
```

### Response
Returns a `Painted<&T>` object with the specified background color.
```

--------------------------------

### fn on_bright_black(&self) -> Painted<&T>

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Sets the background color to `Color::BrightBlack`.

```APIDOC
## fn on_bright_black(&self) -> Painted<&T>

### Description
Returns `self` with the `bg()` set to [`Color :: BrightBlack`].

### Example
```rust
println!("{}", value.on_bright_black());
```
```

--------------------------------

### fn on_white(&self) -> Painted<&T>

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Sets the background color to `Color::White`.

```APIDOC
## fn on_white(&self) -> Painted<&T>

### Description
Returns `self` with the `bg()` set to [`Color :: White`].

### Example
```rust
println!("{}", value.on_white());
```
```

--------------------------------

### Enable Wrapping using Quirk

Source: https://docs.rs/shellfish/latest/shellfish/input_handler/struct.IO.html

Demonstrates enabling text wrapping using the `.quirk()` method with `Quirk::Wrap`. This is a less preferred method compared to `wrap()`.

```rust
use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);
```

--------------------------------

### fn on_bright_blue(&self) -> Painted<&T>

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Sets the background color to `Color::BrightBlue`.

```APIDOC
## fn on_bright_blue(&self) -> Painted<&T>

### Description
Returns `self` with the `bg()` set to [`Color :: BrightBlue`].

### Example
```rust
println!("{}", value.on_bright_blue());
```
```

--------------------------------

### Try to convert Shell to App with async handler

Source: https://docs.rs/shellfish/latest/src/shellfish/app.rs.html

Asynchronously converts a Shell instance into an App instance using the DefaultAsyncCLIHandler. This is an alternative to the synchronous conversion, suitable for async environments.

```rust

#[cfg(feature = "async")]
impl<'f: 't, 't, T: Serialize + for<'a> Deserialize<'a> + Send>
    App<'t, T, DefaultAsyncCLIHandler>
{
    pub fn try_from_async<M: Display, H: AsyncHandler<T>, I: InputHandler>(
        shell: Shell<'f, T, M, H, I>,
    ) -> Result<Self, Box<dyn Error>> {
        let mut this = Self {
            commands: shell.commands,
            state: shell.state,
            handler: DefaultAsyncCLIHandler { proj_name: None },
            description: shell.description,
        };
        this.load_cache()?;
        Ok(this)
    }
}
```

--------------------------------

### fn on_cyan(&self) -> Painted<&T>

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Sets the background color to `Color::Cyan`.

```APIDOC
## fn on_cyan(&self) -> Painted<&T>

### Description
Returns `self` with the `bg()` set to [`Color :: Cyan`].

### Example
```rust
println!("{}", value.on_cyan());
```
```

--------------------------------

### try_into

Source: https://docs.rs/shellfish/latest/shellfish/shell/enum.UnescapeError.html

Performs the conversion.

```APIDOC
## try_into

### Description
Performs the conversion.

### Method
`try_into(self)`

### Parameters
* **self** - The value to convert.

### Response
Returns a `Result<U, <U as TryFrom<T>>::Error>`.

### Error Type
`Error = <U as TryFrom<T>>::Error`

### Example
(No example provided in source)
```

--------------------------------

### fn on_blue(&self) -> Painted<&T>

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Sets the background color to `Color::Blue`.

```APIDOC
## fn on_blue(&self) -> Painted<&T>

### Description
Returns `self` with the `bg()` set to [`Color :: Blue`].

### Example
```rust
println!("{}", value.on_blue());
```
```

--------------------------------

### Paint Methods

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Provides methods for applying foreground colors to text. These methods allow for setting specific colors like red, blue, green, and more, or using predefined color constants.

```APIDOC
## fg(&self, value: Color) -> Painted<&T>

### Description
Returns a styled value derived from `self` with the foreground set to `value`.
This method should be used rarely. Instead, prefer to use color-specific builder methods like `red()` and `green()`, which have the same functionality but are pithier.

### Method
`fg`

### Parameters
- `value` (Color) - Description: The color to set for the foreground.

### Response
- `Painted<&T>` - A styled value with the foreground color set.

### Example
```rust
use yansi::{Paint, Color};

painted.fg(Color::White);
```
```

```APIDOC
## primary(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: Primary`].

### Method
`primary`

### Response
- `Painted<&T>` - A styled value with the primary foreground color set.

### Example
```rust
println!("{}", value.primary());
```
```

```APIDOC
## fixed(&self, color: u8) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: Fixed`].

### Method
`fixed`

### Parameters
- `color` (u8) - Description: The fixed color value.

### Response
- `Painted<&T>` - A styled value with the fixed foreground color set.

### Example
```rust
println!("{}", value.fixed(color));
```
```

```APIDOC
## rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: Rgb`].

### Method
`rgb`

### Parameters
- `r` (u8) - Description: The red component of the RGB color.
- `g` (u8) - Description: The green component of the RGB color.
- `b` (u8) - Description: The blue component of the RGB color.

### Response
- `Painted<&T>` - A styled value with the RGB foreground color set.

### Example
```rust
println!("{}", value.rgb(r, g, b));
```
```

```APIDOC
## black(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: Black`].

### Method
`black`

### Response
- `Painted<&T>` - A styled value with the black foreground color set.

### Example
```rust
println!("{}", value.black());
```
```

```APIDOC
## red(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: Red`].

### Method
`red`

### Response
- `Painted<&T>` - A styled value with the red foreground color set.

### Example
```rust
println!("{}", value.red());
```
```

```APIDOC
## green(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: Green`].

### Method
`green`

### Response
- `Painted<&T>` - A styled value with the green foreground color set.

### Example
```rust
println!("{}", value.green());
```
```

```APIDOC
## yellow(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: Yellow`].

### Method
`yellow`

### Response
- `Painted<&T>` - A styled value with the yellow foreground color set.

### Example
```rust
println!("{}", value.yellow());
```
```

```APIDOC
## blue(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: Blue`].

### Method
`blue`

### Response
- `Painted<&T>` - A styled value with the blue foreground color set.

### Example
```rust
println!("{}", value.blue());
```
```

```APIDOC
## magenta(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: Magenta`].

### Method
`magenta`

### Response
- `Painted<&T>` - A styled value with the magenta foreground color set.

### Example
```rust
println!("{}", value.magenta());
```
```

```APIDOC
## cyan(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: Cyan`].

### Method
`cyan`

### Response
- `Painted<&T>` - A styled value with the cyan foreground color set.

### Example
```rust
println!("{}", value.cyan());
```
```

```APIDOC
## white(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: White`].

### Method
`white`

### Response
- `Painted<&T>` - A styled value with the white foreground color set.

### Example
```rust
println!("{}", value.white());
```
```

```APIDOC
## bright_black(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: BrightBlack`].

### Method
`bright_black`

### Response
- `Painted<&T>` - A styled value with the bright black foreground color set.

### Example
```rust
println!("{}", value.bright_black());
```
```

```APIDOC
## bright_red(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: BrightRed`].

### Method
`bright_red`

### Response
- `Painted<&T>` - A styled value with the bright red foreground color set.

### Example
```rust
println!("{}", value.bright_red());
```
```

```APIDOC
## bright_green(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: BrightGreen`].

### Method
`bright_green`

### Response
- `Painted<&T>` - A styled value with the bright green foreground color set.

### Example
```rust
println!("{}", value.bright_green());
```
```

```APIDOC
## bright_yellow(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: BrightYellow`].

### Method
`bright_yellow`

### Response
- `Painted<&T>` - A styled value with the bright yellow foreground color set.

### Example
```rust
println!("{}", value.bright_yellow());
```
```

```APIDOC
## bright_blue(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: BrightBlue`].

### Method
`bright_blue`

### Response
- `Painted<&T>` - A styled value with the bright blue foreground color set.

### Example
```rust
println!("{}", value.bright_blue());
```
```

```APIDOC
## bright_magenta(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: BrightMagenta`].

### Method
`bright_magenta`

### Response
- `Painted<&T>` - A styled value with the bright magenta foreground color set.

### Example
```rust
println!("{}", value.bright_magenta());
```
```

```APIDOC
## bright_cyan(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: BrightCyan`].

### Method
`bright_cyan`

### Response
- `Painted<&T>` - A styled value with the bright cyan foreground color set.

### Example
```rust
println!("{}", value.bright_cyan());
```
```

```APIDOC
## bright_white(&self) -> Painted<&T>

### Description
Returns `self` with the `fg()` set to [`Color :: BrightWhite`].

### Method
`bright_white`

### Response
- `Painted<&T>` - A styled value with the bright white foreground color set.

### Example
```rust
println!("{}", value.bright_white());
```
```

--------------------------------

### fn on_bright_red(&self) -> Painted<&T>

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Sets the background color to `Color::BrightRed`.

```APIDOC
## fn on_bright_red(&self) -> Painted<&T>

### Description
Returns `self` with the `bg()` set to [`Color :: BrightRed`].

### Example
```rust
println!("{}", value.on_bright_red());
```
```

--------------------------------

### New Shell Constructor (Default Handler)

Source: https://docs.rs/shellfish/latest/src/shellfish/shell.rs.html

Creates a new shell instance with the default handler and IO input handler. Use `new_with_handler` for custom handlers.

```rust
impl<'a, T, M: Display> Shell<'a, T, M, handler::DefaultHandler, IO> {
    /// Creates a new shell
    ///
    /// If you have the `rustyline` feature enabled use [`new_with_handler`]
    /// to use the `rustyline` editor.
    pub fn new(state: T, prompt: M) -> Self {
        Shell {
            prompt,
            commands: HashMap::new(),
            state,
            handler: handler::DefaultHandler(),
            description: String::new(),
            input_handler: IO,
        }
    }
}
```

--------------------------------

### try_into

Source: https://docs.rs/shellfish/latest/shellfish/handler/asynchronous/struct.DefaultAsyncHandler.html

Performs the conversion. Read more.

```APIDOC
## try_into

### Description
Performs the conversion from type `T` to type `U`.

### Method
`try_into(self)` where `U: TryFrom<T>`

### Parameters
None (consumes `self`).

### Response
A `Result<U, <U as TryFrom<T>>::Error>` containing the converted value or an error.

### Request Example
```
let value_t: T = ...;
match value_t.try_into() {
    Ok(u) => println!("Successfully converted: {:?}", u),
    Err(e) => println!("Conversion error: {:?}", e),
}
```
```

--------------------------------

### fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Source: https://docs.rs/shellfish/latest/shellfish/handler/default/struct.DefaultHandler.html

Sets the background color to `Color::Rgb` using specified red, green, and blue values.

```APIDOC
## fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

### Description
Returns `self` with the `bg()` set to [`Color :: Rgb`].

### Parameters
#### Path Parameters
- **r** (u8) - Required - The red component of the RGB color.
- **g** (u8) - Required - The green component of the RGB color.
- **b** (u8) - Required - The blue component of the RGB color.

### Example
```rust
println!("{}", value.on_rgb(r, g, b));
```
```

--------------------------------

### try_from

Source: https://docs.rs/shellfish/latest/shellfish/input_handler/enum.InputResult.html

Performs a conversion from one type to another, returning a Result.

```APIDOC
## try_from

### Description
Performs the conversion.

### Method
`try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` where `U: Into<T>`

### Parameters
* **value** (U) - The value to convert.

### Response
A `Result` containing the converted value or an error.

### Error Type
`type Error = Infallible`
```
Tokens:
Raw