cnf_lib/

lib.rs

// SPDX-License-Identifier: GPL-3.0-or-later
// SPDX-FileCopyrightText: (C) 2023 Andreas Hartmann <hartan@7x.de>
// This file is part of cnf-lib, available at <https://gitlab.com/hartang/rust/cnf>

//! # cnf-lib - Library code for `cnf`
//!
//! The code contained here serves three main purposes.
//!
//!
//! ## Handling environments
//!
//! An "environment" is anything that offers one or more "providers" (see below). All supported
//! environments are listed in the [`Environment`] enum.
//!
//! It is often desirable to temporarily escape one environment for the sake of executing a single
//! command. There are usually controlled mechanisms to perform this task. This crate aims to
//! transparently manage the command translation necessary in order to, for example, execute `htop`
//! inside a Toolbx container while working on the host. All of this is implemented in the
//! [`Environment`] type and [`IsEnvironment`] trait.
//!
//! Take a look at the documentation and code in [`environment`] if you want to know more about this
//! command translation.
//!
//!
//! ## Handling providers
//!
//! A "provider" is anything that offers executable software. This includes for example the system
//! `$PATH` (where executables are usually located and can be executed immediately), but extends to
//! regular package managers such as `dnf`, usually requiring installation of commands before they
//! can be executed. All supported providers are listed in the [`Provider`] enum.
//!
//! Providers can be searched for a command and return a list of zero or more possible candidates
//! matching the search term. All of this is implemented in the [`Provider`] type and [`IsProvider`]
//! trait.
//!
//! Take a look at the documentation and code in [`provider`] if you want to know more about this
//! and for detailed instructions about implementing new providers.
//!
//!
//! ## Handling command invocations
//!
//! Translating regular command lines between environments has a few pitfalls with respect to e.g.
//! privilege escalation and correctly reading stdout/stderr. The [`CommandLine`] type provides the
//! necessary abstractions to allow seamless command execution without having to wonder how
//! privilege escalation in the target environment works, for example.

pub mod environment;
pub mod error;
pub mod provider;
#[cfg(any(test, doc))]
pub mod test;
pub mod util;

// Quicker access to modules
pub use environment as env;
pub use provider as prov;

pub use env::{Environment, Error as EnvironmentError, ExecutionError, IsEnvironment};
pub use prov::{
    Actions, Candidate, Error as ProviderError, IsProvider, Provider, Query, search_in,
};
pub use util::CommandLine;

/// Public prelude.
pub mod prelude {
    pub use super::{
        CommandLine, Environment, EnvironmentError, IsEnvironment, IsProvider, Provider,
        ProviderError, Query, search_in,
    };
}