cata 0.1.1

toolkit for building large CLIs
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
87

//! Structured output for commands.
//!
//! When implemented, users of a CLI can choose what type of structured output
//! they would like from the CLI. JSON, YAML and pretty are currently supported.
//! This can be added as part of a root command and then any subcommands are
//! able to output correctly.
//!
//! Any type being output is required to implement [`serde::Serialize`] in
//! addition to [`tabled::Tabled`]. `Tabled` requires that every field
//! implements `Display`. The [`cata::output::tabled`] module provides some
//! helpers.
//!
//! # Examples
//! For a more complete example, see [examples/output].
//!
//! ```
//! use cata::{Command, output::Format};
//!
//! #[derive(serde::Serialize, tabled::Tabled)]
//! struct MyType {
//!    field: String,
//! }
//!
//! #[derive(clap::Parser, cata::Container)]
//! struct Cmd {
//!   #[arg(short, long, value_enum)]
//!   output: Format,
//! }
//!
//! #[async_trait::async_trait]
//! impl Command for Cmd {
//!   async fn run(&self) -> eyre::Result<()> {
//!     self.output.item(&MyType { field: "value".into() })
//!   }
//! }
//! ```
//!
//! [examples/output]: https://github.com/grampelberg/cata/blob/main/examples/output/src/main.rs
pub mod tabled;

use ::tabled::{Table, Tabled};
use clap::ValueEnum;
use eyre::Result;
use serde::Serialize;

/// Argument for specifying the output format of structured data.
///
/// See the module documentation for usage.
#[derive(ValueEnum, Debug, Default, Clone, Serialize)]
#[serde(rename_all = "kebab-case")]
pub enum Format {
    #[default]
    /// Pretty print the output, results in a table format. Single items are
    /// tables with one row.
    Pretty,
    /// Prints the output as JSON.
    Json,
    /// Prints the output as YAML.
    Yaml,
}

impl Format {
    /// Print a list of items to the console.
    pub fn list(&self, data: &[impl Serialize + Tabled]) -> Result<()> {
        match self {
            Format::Pretty => println!("{}", Table::new(data)),
            Format::Json => println!("{}", serde_json::to_string_pretty(&data)?),
            Format::Yaml => println!("{}", serde_yaml::to_string(&data)?),
        }

        Ok(())
    }

    /// Print a single item to the console.
    ///
    /// This allows format implementations to produce different outputs
    /// depending based on the number of items.
    pub fn item(&self, data: &(impl Serialize + Tabled)) -> Result<()> {
        match self {
            Format::Pretty => self.list(&[data])?,
            Format::Json => println!("{}", serde_json::to_string_pretty(data)?),
            Format::Yaml => println!("{}", serde_yaml::to_string(data)?),
        }

        Ok(())
    }
}