cicero_commands/

lib.rs

#![doc = include_str!("../README.md")]

use std::{process::Command, sync::OnceLock};

#[cfg(feature = "task_venv")]
pub mod venv;

mod install;


pub use cicero_core::Result;

/// Description of a crate you want to install.
#[derive(Debug)]
pub struct Crate {
    name: &'static str,
    install_args: &'static [&'static str],
}
impl Crate {
    /// Construct a `Crate` object from the given `name`.
    pub const fn new(name: &'static str) -> Self {
        Self {
            name,
            install_args: &[],
        }
    }

    /// Add arguments to pass to `cargo install` when performing the installation.
    pub const fn with_install_args(mut self, install_args: &'static [&'static str]) -> Self {
        self.install_args = install_args;
        self
    }

    /// Convert to a [Cli] object, for further configuration and later retrieving [Command] objects.
    pub const fn into_cli(self) -> Cli {
        Cli::new(CliInstallKind::Crate(self))
    }
}

/// Description of a CLI or dependency that should already be installed on the system.
pub struct ExpectProgram {
    name: &'static str,
    install_instruction: Option<&'static str>,
}
impl ExpectProgram {
    /// Expect a given program to be available via the operating system PATH.
    pub const fn new(name: &'static str) -> Self {
        Self {
            name,
            install_instruction: None,
        }
    }

    /// Add instructions to be provided to the user for how to install the expected software, if it isn't already installed on the system.
    pub const fn with_install_instruction(mut self, install_instruction: &'static str) -> Self {
        self.install_instruction = Some(install_instruction);
        self
    }

    /// Convert to a [Cli] object, for further configuration and later retrieving [Command] objects.
    pub const fn into_cli(self) -> Cli {
        Cli::new(CliInstallKind::ExpectProgram(self))
    }
}


/// Used to define the CLI you want to use.
pub struct Cli {
    install_kind: CliInstallKind,
    program_name: OnceLock<ProgramName>,
    command_fn: Option<CommandFn>,
    crate_dependencies: &'static [Crate],
    expected_dependencies: &'static [ExpectProgram],
}
enum CliInstallKind {
    Crate(Crate),
    ExpectProgram(ExpectProgram),
}

impl Cli {

    /// Command to return when calling [Cli::command].
    /// This allows you to specify arguments which should be included for all calls to this CLI.
    /// ```no_run
    ///# use cicero_commands::{Cli, Crate};
    ///#
    /// static CROSS_BUILD: Cli = Crate::new("cross")
    ///     .into_cli()
    ///     .with_base_command(&|mut command| {
    ///         command
    ///             .arg("build")
    ///             .arg("--release");
    ///         command
    ///     });
    ///
    ///
    /// // It can then be used like so:
    ///
    /// CROSS_BUILD.command()
    ///     .arg("--target=aarch64-unknown-linux-gnu")
    ///     .status();
    /// ```
    pub const fn with_base_command(mut self, command_fn: CommandFn) -> Self {
        self.command_fn = Some(command_fn);
        self
    }

    /// Additional crates to install, which are depended on by the CLI, but don't provide the CLI themselves.
    /// ```no_run
    ///# use cicero_commands::{Cli, Crate};
    ///#
    /// static MDBOOK: Cli = Crate::new("mdbook")
    ///     .into_cli()
    ///     .with_crate_dependencies(&[
    ///         Crate::new("mdbook-keeper"),
    ///         Crate::new("mdbook-plantuml").with_install_args(&["--locked"]),
    ///     ]);
    /// ```
    pub const fn with_crate_dependencies(mut self, dependency_crates: &'static [Crate]) -> Self {
        self.crate_dependencies = dependency_crates;
        self
    }

    /// Additional dependencies expected on the system, which are depended on by the CLI, but don't provide the CLI themselves.
    /// ```no_run
    ///# use cicero_commands::{Cli, Crate, ExpectProgram};
    ///#
    /// static MDBOOK: Cli = Crate::new("mdbook")
    ///     .into_cli()
    ///     .with_expected_dependencies(&[
    ///         ExpectProgram::new("mdbook-keeper"),
    ///         ExpectProgram::new("mdbook-plantuml"),
    ///     ]);
    /// ```
    pub const fn with_expected_dependencies(mut self, expected_dependencies: &'static [ExpectProgram]) -> Self {
        self.expected_dependencies = expected_dependencies;
        self
    }

    /// Constructs a new [std::process::Command] instance, from the specified default command or the crate name.
    ///
    /// This will trigger the installation, if it's needed.
    pub fn command(&self) -> Command {

        let program_name = self.program_name.get_or_init(|| {

            for expected_dependency in self.expected_dependencies {
                install::expect_command_installed(expected_dependency.name, expected_dependency.install_instruction);
            }

            for crate_dependency in self.crate_dependencies {
                install::dependency_crate(crate_dependency)
                    .unwrap_or_else(|cause| panic!("Failed to install crate dependency {}: {cause}", crate_dependency.name));
            }

            match self.install_kind {
                CliInstallKind::Crate(ref crate_to_install) => {
                    install::cli_crate(crate_to_install)
                        .unwrap_or_else(|cause| panic!("Failed to install CLI crate {}: {cause}", crate_to_install.name))
                }
                CliInstallKind::ExpectProgram(ref expect) => {
                    install::expect_command_installed(expect.name, expect.install_instruction);
                    ProgramName { value: expect.name.to_owned() }
                }
            }
        });

        let mut default_command = Command::new(&program_name.value);

        if let CliInstallKind::Crate(_) = self.install_kind {
            default_command
                .env("PATH", crate::install::calculate_PATH());
        }

        match self.command_fn {
            Some(command) => command(default_command),
            None => default_command,
        }
    }

    const fn new(install_kind: CliInstallKind) -> Self {
        Self {
            install_kind,
            program_name: OnceLock::new(),
            command_fn: None,
            crate_dependencies: &[],
            expected_dependencies: &[],
        }
    }
}

struct ProgramName { pub value: String }

type CommandFn = &'static (dyn Fn(Command) -> Command + Send + Sync);


#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn should_expect_installed() {
        ExpectProgram::new("cargo")
            .into_cli()
            .command();
    }

    #[test]
    #[should_panic]
    fn should_abort_when_expected_command_not_installed() {
        ExpectProgram::new("non-existent command")
            .into_cli()
            .command();
    }
}