Struct 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)

Rust project automation command

Usage: cargo xtask [OPTIONS] [COMMAND]

Commands:
  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
  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
  help                   Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  More output per occurrence
  -q, --quiet...    Less output per occurrence
  -h, --help        Print help

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 group_id() -> Option<Id>

Report the ArgGroup::id for this set of arguments

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

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

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

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

impl<Subcommand> Clone for Xtask<Subcommand>

where Subcommand: Subcommand + Clone,

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

Returns a duplicate 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 command<'b>() -> Command

Build a Command that can instantiate Self.

fn command_for_update<'b>() -> Command

Build a Command that can update self.

impl<Subcommand> Debug for Xtask<Subcommand>

where Subcommand: Subcommand + Debug,

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

Formats the value using the given formatter.

impl<Subcommand> Default for Xtask<Subcommand>

where Subcommand: Subcommand + Default,

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) -> Self

where 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.