ocli

一个简单、有观点的命令行工具日志记录器

ocli 旨在实现一个非常简单的事情：正确完成CLI工具的日志记录。它使用 log crate 和 ansi_term crate 进行颜色处理。它提供的配置非常少——目前只包括期望的日志级别。

特性

将所有内容记录到 stderr

CLI工具应在管道中使用。在这种情况下，针对用户的消息必须写入 stderr，以便用户有机会读取，无论日志级别如何。旨在与管道一起使用的程序输出不应通过日志系统，而是直接打印到 stdout，例如使用 println!。

以纯文本无颜色形式显示 Info 消息

Info 预期是正常日志级别，用于显示不强调问题且不会使工具标准使用过于冗长的消息。因为它是用于与正常情况相关的消息，所以该级别的消息不以日志级别开头。

对于除 Info 以外的任何级别，都以前缀它们的彩色日志级别来显示消息

颜色取决于日志级别，允许快速定位特定日志级别的消息

当配置为 Trace 日志级别时，显示模块路径和行

对于所有消息，即使它们不是 Trace 日志级别。使用 Trace 日志级别是为了帮助开发者了解消息的来源，以及显示更多消息。

如果 stderr 不是 tty，则禁用所有颜色化

这样，当 stderr 转换到文件时，输出就不会被不可读的字符污染。

Info 日志级别的示例

#[macro_use] extern crate log;

fn main() {
     ocli::init(log::Level::Info).unwrap();

     error!("This is printed to stderr, with the 'error: ' prefix colored in red");
     warn!("This is printed to stderr, with the 'warn: ' prefix colored in yellow");
     info!("This is printed to stderr, without prefix or color");
     debug!("This is not printed");
     trace!("This is not printed");
}

使用 Trace 日志级别的示例

#[macro_use] extern crate log;

fn main() {
     ocli::init(log::Level::Trace).unwrap();

     error!("This is printed to stderr, with the 'path(line): error: ' prefix colored in red");
     warn!("This is printed to stderr, with the 'path(line): warn: ' prefix colored in yellow");
     info!("This is printed to stderr, with the 'path(line): info: ' prefix");
     debug!("This is printed to stderr, with the 'path(line): debug: ' prefix colored in blue");
     trace!("This is printed to stderr, with the 'path(line): trace: ' prefix colored in magenta");
}

以及一个更真实的示例，使用了 hld

与 clap 集成的示例

可以使用命令行参数配置日志级别，使用 clap crate。尝试运行 cargo run --example cli -- --log-level trace 并更改日志级别以查看差异。

#[macro_use]
extern crate log;

use clap::Parser;

/// A demo of ocli with clap
#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
pub struct Config {
    /// Log level
    #[arg(short, long, default_value_t = log::Level::Info)]
    pub log_level: log::Level,
}

fn main() {
    let config = Config::parse();
    ocli::init(config.log_level).unwrap();

    println!("this is on stdout — try to pipe it to another command like `grep` or `wc`");
    error!("log at error level on stderr");
    warn!("log at warn level on stderr");
    info!("log at info level on stderr");
    debug!("log at debug level on stderr");
    trace!("log at trace level on stderr");
    info!("the logs at any level are meant to inform the user");
    info!("while still being able to pipe stdout");
}

与 clap-verbosity-flag 集成的示例

可以使用命令行参数配置日志级别，使用 clap-verbosity-flag crate。尝试运行 cargo run --example verbosity -- -vv 或 cargo run --example verbosity -- -q。更改 -v 或 -q 的数量会更改日志级别。

#[macro_use]
extern crate log;

use clap::Parser;
use clap_verbosity_flag::{InfoLevel, Verbosity};

/// A demo of ocli with clap
#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
pub struct Config {
    /// Log level
    #[command(flatten)]
    pub verbose: Verbosity<InfoLevel>,
}

fn main() {
    let config = Config::parse();
    if let Some(level) = config.verbose.log_level() {
        ocli::init(level).unwrap();
    }
    println!("this is on stdout — try to pipe it to another command like `grep` or `wc`");
    error!("log at error level on stderr");
    warn!("log at warn level on stderr");
    info!("log at info level on stderr");
    debug!("log at debug level on stderr");
    trace!("log at trace level on stderr");
    info!("the logs at any level are meant to inform the user");
    info!("while still being able to pipe stdout");
}

许可证

ocli 在 MIT 许可证的条款下分发。

有关详细信息，请参阅 LICENSE。