Struct spirit_cfg_helpers::CfgHelp

pub struct CfgHelp { /* fields omitted */ }

A command line options fragment to add the --help-config option.

For the user to be able to configure an application, the user needs to know what options can be configured. Usually, this is explained using an example configuration file or through a manually written documentation. However, maintaining either is a lot of work, not mentioning that various spirit crates provide configuration fragments composed from several type parameters so hunting down all the available options might be hard.

This helper uses the StructDoc trait to extract the structure and documentation of the configuration automatically. Usually, its derive will extract description from fields' doc comments. See the structdoc crate's documentation to know how to let the documentation be created semi-automatically. All the configuration fragments provided by the spirit crates implement StructDoc, unless their [cfg-help] feature is disabled.

When the --help-config is specified, this auto-generated documentation is printed and the application exits.

The fragment can be used either manually with the help method or by registering the extension within an Extensible.

Examples

use serde_derive::Deserialize;
use spirit::Spirit;
use spirit::prelude::*;
use spirit_cfg_helpers::CfgHelp;
use structdoc::StructDoc;
use structopt::StructOpt;

#[derive(Default, Deserialize, StructDoc)]
struct Cfg {
    /// A very much useless but properly documented option.
    option: Option<String>,
}

#[derive(Debug, StructOpt)]
struct Opts {
    #[structopt(flatten)]
    help: CfgHelp,
}

impl Opts {
    fn help(&self) -> &CfgHelp {
        &self.help
    }
}

fn main() {
    Spirit::<Opts, Cfg>::new()
        .with(CfgHelp::extension(Opts::help))
        .run(|_| Ok(()));
}

Implementations

impl CfgHelp

pub fn help<C: StructDoc>(&self)

Show the help and exit if it was specified as an option.

This can be called manually to check for the command line option at the right time. If it was specified, the help for the C type is printed and the application exits. If the command line was not specified, this does nothing.

Note that the C type is passed as type parameter, therefore this needs to be invoked with the turbofish syntax.

The preferred way is usually by registering the extension.

Examples

use serde_derive::Deserialize;
use spirit_cfg_helpers::CfgHelp;
use structdoc::StructDoc;
use structopt::StructOpt;

#[derive(Deserialize, StructDoc)]
struct Cfg {
    /// A very much useless but properly documented option
    option: Option<String>,
}

#[derive(StructOpt)]
struct Opts {
    #[structopt(flatten)]
    help: CfgHelp,
}

let opts = Opts::from_args();
opts.help.help::<Cfg>();

pub fn extension<O, C, F>(extract: F) -> impl Extension<Builder<O, C>> where
    F: FnOnce(&O) -> &Self + Send + 'static,
    O: Debug + StructOpt + Send + Sync + 'static,
    C: DeserializeOwned + StructDoc + Send + Sync + 'static, 

A helper to be registered within an Extensible.

The extractor should take the whole command line options structure and provide reference to just the CfgHelp instance.

Trait Implementations

impl Clone for CfgHelp

fn clone(&self) -> CfgHelp

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CfgHelp

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

Formats the value using the given formatter.

impl Default for CfgHelp

fn default() -> CfgHelp

Returns the "default value" for a type.

impl StructOpt for CfgHelp

fn clap<'a, 'b>() -> App<'a, 'b>

Returns clap::App corresponding to the struct.

fn from_clap(matches: &ArgMatches<'_>) -> Self

Builds the struct from clap::ArgMatches. It's guaranteed to succeed if matches originates from an App generated by StructOpt::clap called on the same type, otherwise it must panic.

fn from_args() -> Self

Builds the struct from the command line arguments (std::env::args_os). Calls clap::Error::exit on failure, printing the error message and aborting the program.

fn from_args_safe() -> Result<Self, Error>

Builds the struct from the command line arguments (std::env::args_os). Unlike StructOpt::from_args, returns clap::Error on failure instead of aborting the program, so calling .exit is up to you.

fn from_iter<I>(iter: I) -> Self where
    I: IntoIterator,
    <I as IntoIterator>::Item: Into<OsString>,
    <I as IntoIterator>::Item: Clone, 

Gets the struct from any iterator such as a Vec of your making. Print the error message and quit the program in case of failure.

fn from_iter_safe<I>(iter: I) -> Result<Self, Error> where
    I: IntoIterator,
    <I as IntoIterator>::Item: Into<OsString>,
    <I as IntoIterator>::Item: Clone, 

Gets the struct from any iterator such as a Vec of your making.

impl StructOptInternal for CfgHelp

fn augment_clap<'a, 'b>(app: App<'a, 'b>) -> App<'a, 'b>

fn is_subcommand() -> bool

fn from_subcommand(_sub: (&'b str, Option<&'b ArgMatches<'a>>)) -> Option<Self>