clap-logflag 0.0.3

Adds a `--log` flag to clap based applications to allow CLI users to configure logging from the command line. Can log to stderr, files and syslog.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

[![Build Status](https://github.com/smessmer/clap-logflag/actions/workflows/ci.yml/badge.svg)](https://github.com/smessmer/clap-logflag/actions/workflows/ci.yml)
[![Latest Version](https://img.shields.io/crates/v/clap-logflag.svg)](https://crates.io/crates/clap-logflag)
[![docs.rs](https://docs.rs/clap-logflag/badge.svg)](https://docs.rs/clap-logflag)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/smessmer/clap-logflag/blob/master/LICENSE-MIT)
[![License](https://img.shields.io/badge/license-APACHE-blue.svg)](https://github.com/smessmer/clap-logflag/blob/master/LICENSE-APACHE)
[![codecov](https://codecov.io/gh/smessmer/clap-logflag/branch/master/graph/badge.svg?token=FRSBH7YYA9)](https://codecov.io/gh/smessmer/clap-logflag)
[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)

# clap-logflag

<!-- cargo-rdme start -->

[work in progress]

The [clap-logflag](https://crates.io/crates/clap-logflag) library adds a `--log` flag to clap based applications
that allows CLI users to configure logging from the command line.
It can log to stderr, files and syslog.

## Examples
```bash
# Log to a single destination
$ ./your-cli --log syslog
$ ./your-cli --log file:/path/to/file

# Log to both stderr and a file
$ ./your-cli --log stderr --log file:/path/to/file

# Filter log levels
$ ./your-cli --log DEBUG:stderr --log INFO:file:/path/to/file

# Disable logging
$ ./your-cli --log none

# Use default logging setup (defined by the application developer)
$ ./your-cli
```

## Setup
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`.

Then, add the [LogArgs](https://docs.rs/clap-logflag/latest/clap_logflag/clap/struct.LogArgs.html) struct to your clap definition and initialize logging with it:

```rust
use clap::Parser;
use clap_logflag::LoggingConfig;
use log::LevelFilter;

#[derive(Debug, Parser)]
struct CliArgs {
    // Use this to add the log flags to your application
    #[clap(flatten)]
    log: clap_logflag::LogArgs,
    
    // ... your other cli args ...
}

fn main() {
    let args = CliArgs::parse();

    // Initialize logging with the flags from clap
    clap_logflag::init_logging!(
        args.log
            // If no `--log` arguments are present, disable logging.
            // You can change this to define the default behavior,
            // see the "default_logging" example.
            .or_default(LoggingConfig::LoggingDisabled),
        // Any `--log` argument that doesn't define a level filter will use the
        // default level filter defined here, `Info` in this example.
        LevelFilter::Info,
    );

    // Issue some log messages
    log::trace!("Some trace log");
    log::debug!("Some debug log");
    log::info!("Some info log");
    log::warn!("Some warn log");
    log::error!("Some error log");
}
```

## Syntax
See [LogArgs](https://docs.rs/clap-logflag/latest/clap_logflag/clap/struct.LogArgs.html) for a detailed explanation of the syntax for the `--log` argument.

<!-- cargo-rdme end -->

License: MIT OR Apache-2.0