clap_logflag/lib.rs
1//! [work in progress]
2//!
3//! The [clap-logflag](https://crates.io/crates/clap-logflag) library adds a `--log` flag to clap based applications
4//! that allows CLI users to configure logging from the command line.
5//! It can log to stderr, files and syslog.
6//!
7//! # Examples
8//! ```bash
9//! # Log to a single destination
10//! $ ./your-cli --log syslog
11//! $ ./your-cli --log file:/path/to/file
12//!
13//! # Log to both stderr and a file
14//! $ ./your-cli --log stderr --log file:/path/to/file
15//!
16//! # Filter log levels
17//! $ ./your-cli --log DEBUG:stderr --log INFO:file:/path/to/file
18//!
19//! # Disable logging
20//! $ ./your-cli --log none
21//!
22//! # Use default logging setup (defined by the application developer)
23//! $ ./your-cli
24//! ```
25//!
26//! # Setup
27//! To use clap-logflag, first add [clap-logflag](https://crates.io/crates/clap-logflag), [clap](https://crates.io/crates/clap) and [log](https://crates.io/crates/log) to your `Cargo.toml`.
28//!
29//! Then, add the [LogArgs](crate::clap::LogArgs) struct to your clap definition and initialize logging with it:
30//!
31//! ```rust
32//! use clap::Parser;
33//! use clap_logflag::LoggingConfig;
34//! use log::LevelFilter;
35//!
36//! #[derive(Debug, Parser)]
37//! struct CliArgs {
38//! // Use this to add the log flags to your application
39//! #[clap(flatten)]
40//! log: clap_logflag::LogArgs,
41//!
42//! // ... your other cli args ...
43//! }
44//!
45//! fn main() {
46//! let args = CliArgs::parse();
47//!
48//! // Initialize logging with the flags from clap
49//! clap_logflag::init_logging!(
50//! args.log
51//! // If no `--log` arguments are present, disable logging.
52//! // You can change this to define the default behavior,
53//! // see the "default_logging" example.
54//! .or_default(LoggingConfig::LoggingDisabled),
55//! // Any `--log` argument that doesn't define a level filter will use the
56//! // default level filter defined here, `Info` in this example.
57//! LevelFilter::Info,
58//! );
59//!
60//! // Issue some log messages
61//! log::trace!("Some trace log");
62//! log::debug!("Some debug log");
63//! log::info!("Some info log");
64//! log::warn!("Some warn log");
65//! log::error!("Some error log");
66//! }
67//! ```
68//!
69//! # Syntax
70//! See [LogArgs](crate::clap::LogArgs) for a detailed explanation of the syntax for the `--log` argument.
71//!
72
73#![allow(clippy::needless_doctest_main)]
74#![forbid(unsafe_code)]
75// TODO #![deny(missing_docs)]
76// We need to add explicit links because our `gen_readme.sh` script requires them.
77#![allow(rustdoc::redundant_explicit_links)]
78
79mod clap;
80mod config;
81mod fern;
82mod parser;
83
84pub use clap::LogArgs;
85pub use config::{LogDestination, LogDestinationConfig, LoggingConfig};
86pub use fern::_init_logging;