Struct cli_xtask::Xtask

#[non_exhaustive]
pub struct Xtask<Subcommand = Subcommand>where
    Subcommand: Subcommand,{
    pub verbosity: Verbosity,
    pub subcommand: Option<Subcommand>,
}

Command line interface definition for cargo xtask command.

cargo-xtask(1)

cargo-xtask 
Rust project automation command

USAGE:
    cargo xtask [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -h, --help       Print help information
    -q, --quiet      Less output per occurrence
    -v, --verbose    More output per occurrence

SUBCOMMANDS:
    build                    `cargo build` with options useful for testing and continuous
                                 integration
    clippy                   `cargo clippy` with options useful for tesing and continuous
                                 integration
    dist                     Build the artifacs and create the archive file for distribution
    dist-archive             Create the archive file for distribution
    dist-build               Build all artifacts for distribution
    dist-build-bin           Build the release binaries for distribution
    dist-build-completion    Build the shell completion files for distribution
    dist-build-doc           Build the documentation for distribution
    dist-build-license       Build the license files for distribution
    dist-build-man           Build the man pages for distribution
    dist-build-readme        Build the readme files for distribution
    dist-clean               Remove the artifacts and archives for distribution
    doc                      `cargo doc` with options useful for testing and continuous
                                 integration
    docsrs                   `cargo doc` with docs.rs specific options
    exec                     Run commands on all workspaces in the current directory and
                                 subdirectories
    fmt                      `cargo fmt` with options useful for testing and continuous
                                 integration
    help                     Print this message or the help of the given subcommand(s)
    lint                     Run lint commands at once
    pre-release              Run pre-release checks
    sync-rdme                `cargo sync-rdme` with options useful for testing and continuous
                                 integration
    test                     `cargo test` with options useful for testing and continuous
                                 integration
    tidy                     Fix the package problems
    udeps                    `cargo udeps` with options useful for testing and continuous
                                 integration

Examples

Use the premade entry point function with default configuration (main feature is required):

use cli_xtask::{Result, Xtask};

fn main() -> Result<()> {
    <Xtask>::main()
}

Use the premade entry point function and custom configuration (main feature is required):

use cli_xtask::{config::Config, Result, Xtask};

fn main() -> Result<()> {
    <Xtask>::main_with_config(|| Ok(Config::new()))
}

If you don’t want to use the main feature, write the main function as follows:

use cli_xtask::{clap::Parser, config::Config, error_handler, logger, Result, Xtask};

fn main() -> Result<()> {
    // Parse command line arguments
    let command = <Xtask>::parse();

    // Setup error handler and logger
    error_handler::install()?; // `error-handler` feature is required
    logger::install(command.verbosity.get())?; // `logger` feature is required

    // Run the subcommand specified by the command line arguments
    command.run(&Config::new())?;

    Ok(())
}

If you want to define your own subcommands, declare the type that implements clap::Subcommand and Run, then use Xtask<YourOwnSubcommand> instead of Xtask.

use cli_xtask::{
    clap::{self, Parser},
    config::Config,
    subcommand, Result, Run, Xtask,
};

// Define your own subcommand arguments
#[derive(Debug, clap::Subcommand)]
enum YourOwnSubcommand {
    #[clap(flatten)]
    Predefined(subcommand::Subcommand),
    /// Run foo function.
    Foo,
    /// Run bar function
    Bar,
}

impl Run for YourOwnSubcommand {
    fn run(&self, config: &Config) -> Result<()> {
        match self {
            Self::Predefined(subcommand) => subcommand.run(config)?,
            Self::Foo => println!("foo!"),
            Self::Bar => println!("bar!"),
        }
        Ok(())
    }

    fn into_any(self: Box<Self>) -> Box<dyn std::any::Any> {
        self
    }

    fn as_any(&self) -> &dyn std::any::Any {
        self
    }

    fn as_any_mut(&mut self) -> &mut dyn std::any::Any {
        self
    }
}

fn main() -> Result<()> {
    Xtask::<YourOwnSubcommand>::main()
}

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

verbosity: Verbosity

Verbosity level

subcommand: Option<Subcommand>

Subcommand to run

Implementations

impl<Subcommand> Xtask<Subcommand>where
    Subcommand: Subcommand + Run,

pub fn main() -> Result<()>

Available on crate feature main only.

Entry point for xtask crate.

This function initializes error handler and logger, then runs the subcommand. Default configuration will be passed to subcommand.

Examples

use cli_xtask::{Result, Xtask};

fn main() -> Result<()> {
    <Xtask>::main()
}

pub fn main_with_config<'a>(
    config: impl FnOnce() -> Result<Config<'a>>
) -> Result<()>

Available on crate feature main only.

Entry point for xtask crate.

This function initializes error handler and logger, then runs the subcommand. Generated configuration by config argument will be passed to subcommand.

Examples

use cli_xtask::{config::Config, Result, Xtask};

fn main() -> Result<()> {
    <Xtask>::main_with_config(|| Ok(Config::new()))
}

impl<Subcommand> Xtask<Subcommand>where
    Subcommand: Subcommand,

pub fn run(&self, config: &Config<'_>) -> Result<()>where
    Subcommand: Run,

Runs the subcommand specified by the command line arguments.

Examples

use cli_xtask::{clap::Parser, config::Config, error_handler, logger, Result, Xtask};

fn main() -> Result<()> {
    // Parse command line arguments
    let command = <Xtask>::parse();

    // Setup error handler and logger
    error_handler::install()?; // `error-handler` feature is required
    logger::install(command.verbosity.get())?; // `logger` feature is required

    // Run the subcommand specified by the command line arguments
    command.run(&Config::new())?;

    Ok(())
}

Trait Implementations

impl<Subcommand> Args for Xtask<Subcommand>where
    Subcommand: Subcommand,

fn augment_args<'b>(__clap_app: Command<'b>) -> Command<'b>

Append to Command so it can instantiate Self.

fn augment_args_for_update<'b>(__clap_app: Command<'b>) -> Command<'b>

Append to Command so it can update self.

impl<Subcommand: Clone> Clone for Xtask<Subcommand>where
    Subcommand: Subcommand,

fn clone(&self) -> Xtask<Subcommand>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Subcommand> CommandFactory for Xtask<Subcommand>where
    Subcommand: Subcommand,

fn into_app<'b>() -> Command<'b>

Deprecated, replaced with CommandFactory::command

fn into_app_for_update<'b>() -> Command<'b>

Deprecated, replaced with CommandFactory::command_for_update

fn command<'help>() -> App<'help>

Build a Command that can instantiate Self.

fn command_for_update<'help>() -> App<'help>

Build a Command that can update self.

impl<Subcommand: Debug> Debug for Xtask<Subcommand>where
    Subcommand: Subcommand,

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

Formats the value using the given formatter.

impl<Subcommand: Default> Default for Xtask<Subcommand>where
    Subcommand: Subcommand,

fn default() -> Xtask<Subcommand>

Returns the “default value” for a type.

impl<Subcommand> FromArgMatches for Xtask<Subcommand>where
    Subcommand: Subcommand,

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut(
    __clap_arg_matches: &mut ArgMatches
) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches(
    &mut self,
    __clap_arg_matches: &ArgMatches
) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut(
    &mut self,
    __clap_arg_matches: &mut ArgMatches
) -> Result<(), Error>

Assign values from ArgMatches to self.

impl<Subcommand> Parser for Xtask<Subcommand>where
    Subcommand: Subcommand,

fn parse() -> Self

Parse from std::env::args_os(), exit on error

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

Parse from std::env::args_os(), return Err on error.

fn parse_from<I, T>(itr: I) -> Selfwhere
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone,

Parse from iterator, exit on error

fn try_parse_from<I, T>(itr: I) -> Result<Self, Error>where
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone,

Parse from iterator, return Err on error.

fn update_from<I, T>(&mut self, itr: I)where
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone,

Update from iterator, exit on error

fn try_update_from<I, T>(&mut self, itr: I) -> Result<(), Error>where
    I: IntoIterator<Item = T>,
    T: Into<OsString> + Clone,

Update from iterator, return Err on error.