Struct DriverOutcome 

pub struct DriverOutcome<T>(/* private fields */);

The result of running the figue driver — either a parsed value or an early exit.

Why this type exists

When a CLI user passes --help or --version, the program should print the relevant text and exit with code 0 (success). But these cases flow through the error path of the driver, since no config value T was produced. If DriverOutcome were just a Result, calling .unwrap() would panic on --help, and using ? would propagate it as an error (exit code 1 instead of 0).

DriverOutcome solves this by providing an .unwrap() method that does the right thing for every case:

• Parsed successfully → returns T
• --help / --version / --completions → prints to stdout, exits with code 0
• Parse error → prints diagnostics to stderr, exits with code 1

This type intentionally does NOT implement Try, so you cannot use ? on it accidentally.

Usage

For most CLI programs, just call .unwrap():

use facet::Facet;
use figue::{self as args, FigueBuiltins};

#[derive(Facet)]
struct Args {
    #[facet(args::positional)]
    file: String,

    #[facet(flatten)]
    builtins: FigueBuiltins,
}

fn main() {
    // If the user passes --help, this prints help and exits with code 0.
    // If the user passes invalid args, this prints an error and exits with code 1.
    // Otherwise, it returns the parsed Args.
    let args: Args = figue::from_std_args().unwrap();
    println!("Processing: {}", args.file);
}

For tests or custom handling, use .into_result() to get a Result<DriverOutput<T>, DriverError>:

use facet::Facet;
use figue::{self as args, FigueBuiltins, DriverError};

#[derive(Facet)]
struct Args {
    #[facet(args::positional, default)]
    file: Option<String>,

    #[facet(flatten)]
    builtins: FigueBuiltins,
}

// --help produces a DriverError::Help (exit code 0, not a "real" error)
let outcome = figue::from_slice::<Args>(&["--help"]);
let err = outcome.unwrap_err();
assert!(err.is_help());
assert_eq!(err.exit_code(), 0);

// Successful parse returns DriverOutput containing the value
let outcome = figue::from_slice::<Args>(&["input.txt"]);
let output = outcome.into_result().unwrap();
assert_eq!(output.value.file.as_deref(), Some("input.txt"));

Implementations

impl<T> DriverOutcome<T>

pub fn ok(output: DriverOutput<T>) -> Self

Create a successful outcome.

pub fn err(error: DriverError) -> Self

Create an error outcome.

pub fn into_result(self) -> Result<DriverOutput<T>, DriverError>

Convert to a standard Result for manual handling.

Use this when you need to inspect the error yourself (e.g., in tests, or to implement custom exit behavior). For most CLI programs, prefer .unwrap() instead.

Warning: Don’t blindly use ? on this result — early exits like Help and Version will propagate as errors and cause exit code 1 instead of 0.

pub fn is_ok(&self) -> bool

Returns true if this is a successful parse (not help/version/error).

pub fn is_err(&self) -> bool

Returns true if this is an error or early exit request.

pub fn unwrap(self) -> T

Get the parsed value, handling all early-exit cases automatically.

This is the primary way to use figue. It does exactly what a well-behaved CLI should do:

Case	Behavior
Parse succeeded	Prints warnings to stderr, returns T
--help passed	Prints help to stdout, exits with code 0
--version passed	Prints version to stdout, exits with code 0
--completions passed	Prints shell script to stdout, exits with code 0
Parse failed	Prints diagnostics to stderr, exits with code 1

Example

use facet::Facet;
use figue::{self as args, FigueBuiltins};

#[derive(Facet)]
struct Args {
    #[facet(args::positional)]
    file: String,

    #[facet(flatten)]
    builtins: FigueBuiltins,
}

// In your main():
let args: Args = figue::from_std_args().unwrap();
// If we get here, args were parsed successfully.
// --help and --version already exited before this line.
println!("Processing: {}", args.file);

pub fn unwrap_err(self) -> DriverError

Unwrap the error, panicking if this is a success.

Useful for testing error cases.

Panics

Panics if this is a successful parse.

Trait Implementations

impl<T: Debug> Debug for DriverOutcome<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.