revolver 0.2.1

A library for building REPL applications.
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
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

//! A self-help guide, outlining the available commands and how to use them.

use crate::command::{
    ApplyCommandError, ApplyOutcome, Command, Commander, Description, NamedCommandParser,
    ParseCommandError,
};
use crate::looper::Looper;
use crate::terminal::{AccessTerminalError, Terminal};
use stanza::renderer::console::{Console, Decor};
use stanza::renderer::Renderer;
use stanza::style::{Bold, Header, MaxWidth, MinWidth, Palette16, Styles, TextFg};
use stanza::table::{Cell, Col, Row, Table};
use std::borrow::{Borrow, Cow};
use std::marker::PhantomData;

/// The `help` command. The list of available commands is obtained by interrogating the [`Commander`]. The output
/// of the help command is a rendered [Stanza](https://github.com/obsidiandynamics/stanza) table, enumerating
/// each of the available commands, their name (incl. shorthand, if set) and description (incl. any examples).
pub struct Help<C, E> {
    __phantom_data: PhantomData<(C, E)>
}

impl<C, E> Default for Help<C, E> {
    fn default() -> Self {
        Self {
            __phantom_data: PhantomData::default(),
        }
    }
}

impl<C, E, T: Terminal> Command<T> for Help<C, E> {
    type Context = C;
    type Error = E;

    fn apply(
        &mut self,
        looper: &mut Looper<C, E, T>,
    ) -> Result<ApplyOutcome, ApplyCommandError<E>> {
        let (terminal, commander, _) = looper.split();
        print_commands(commander, terminal)?;
        Ok(ApplyOutcome::Applied)
    }
}

/// Parser for [`Help`].
pub struct Parser<C, E> {
    __phantom_data: PhantomData<(C, E)>
}

impl<C, E> Default for Parser<C, E> {
    fn default() -> Self {
        Self {
            __phantom_data: PhantomData::default(),
        }
    }
}

impl<C: 'static, E: 'static, T: Terminal> NamedCommandParser<T> for Parser<C, E> {
    type Context = C;
    type Error = E;

    fn parse(&self, s: &str) -> Result<Box<dyn Command<T, Context = C , Error = E>>, ParseCommandError> {
        self.parse_no_args(s, Help::default)
    }

    fn shorthand(&self) -> Option<Cow<'static, str>> {
        Some("h".into())
    }

    fn name(&self) -> Cow<'static, str> {
        "help".into()
    }

    fn description(&self) -> Description {
        Description {
            purpose: "Displays a list of commands, their usage syntax and examples.".into(),
            usage: Cow::default(),
            examples: Vec::default(),
        }
    }
}

fn commands<C, E, T: Terminal>(commander: &Commander<C, E, T>) -> Table {
    let mut table = Table::default()
        .with_cols(vec![
            Col::new(Styles::default().with(MinWidth(15))),
            Col::new(Styles::default().with(MinWidth(65)).with(MaxWidth(120))),
        ])
        .with_row(Row::new(
            Styles::default()
                .with(Header(true))
                .with(Bold(true))
                .with(TextFg(Palette16::Yellow)),
            vec!["Command".into(), "Description".into()],
        ));

    for parser in commander.parsers() {
        let mut command = String::new();
        if let Some(shorthand) = parser.shorthand() {
            command.push_str(shorthand.borrow());
            command.push_str(", ");
        }
        command.push_str(&parser.name());

        let description = parser.description();
        let mut desc_buf = String::new();
        desc_buf.push_str(&format!("{}\n", description.purpose));
        desc_buf.push_str(&format!("usage: {} {}\n", parser.name(), description.usage));
        for example in &description.examples {
            desc_buf.push_str(&format!("example - {}:\n", example.scenario));
            desc_buf.push_str(&format!("    {} {}\n", parser.name(), example.command));
        }

        table.push_row(Row::new(
            Styles::default(),
            vec![
                Cell::new(
                    Styles::default().with(TextFg(Palette16::BrightGreen)),
                    command.into(),
                ),
                Cell::new(Styles::default().with(Bold(true)), desc_buf.into()),
            ],
        ));
    }

    table
}

fn print_commands<C, E, T: Terminal>(
    commander: &Commander<C, E, T>,
    terminal: &mut T,
) -> Result<(), AccessTerminalError> {
    let renderer = Console(
        Decor::default()
            .suppress_all_lines()
            .suppress_outer_border(),
    );
    terminal.print_line(&renderer.render(&commands(commander)))
}

#[cfg(test)]
mod tests;