CommandLineToolkit

1
import Logging
2

3
/// Should be used all over the tool to provide consistent CLI experience
4
public protocol ConsoleHandler {
5
    var isAtTTY: Bool { get }
6
    var isInteractive: Bool { get }
7
    var verbositySettings: ConsoleVerbositySettings { get }
8

9
    /// Ask user to input some string
10
    /// - Parameters:
11
    ///   - title: question to ask
12
    ///   - defaultValue: default value, user can hit enter to select it
13
    /// - Returns: User's input
14
    func input(
15
        title: String,
16
        defaultValue: String?,
17
        file: StaticString,
18
        line: UInt
19
    ) async throws -> String
20

21
    /// Ask user a question
22
    /// - Parameters:
23
    ///   - title: question to ask
24
    ///   - defaultAnswer: default answer, yser can just hit enter
25
    /// - Returns: boolean answer
26
    func question(
27
        title: String,
28
        defaultAnswer: Bool,
29
        file: StaticString,
30
        line: UInt
31
    ) async throws -> Bool
32

33
    /// Select values from a list
34
    /// - Parameters:
35
    ///   - title: describes what user selects
36
    ///   - values: list of possible values
37
    ///   - options: possible selection options
38
    /// - Returns: array of selected values
39
    func select<Value>(
40
        title: String,
41
        values: [Selectable<Value>],
42
        mode: SelectionMode,
43
        options: SelectionOptions,
44
        file: StaticString,
45
        line: UInt
46
    ) async throws -> [Value]
47

48
    /// Runs a chunk of work in a separate Console trace
49
    ///
50
    /// This version provides ``TraceProgressUpdator``, so traces operation can report its progress
51
    ///
52
    /// - Parameters:
53
    ///   - level: Trace level, works the same as level in `Logger`
54
    ///   - name: Name of trace to display
55
    ///   - mode: Mode in which to run trace, specific modes allow to cleanup nested finished traces
56
    ///   - work: Work to be performed inside of a trace
57
    /// - Returns: Value returned form `work` closure
58
    func trace<Value: Sendable>(
59
        level: Logger.Level,
60
        name: String,
61
        options: TraceOptions,
62
        file: StaticString,
63
        line: UInt,
64
        work: (TraceProgressUpdator) async throws -> Value
65
    ) async throws -> Value
66

67
    /// Renders log, definition the same as in `LogHandler`
68
    func log(
69
        level: Logger.Level,
70
        message: Logger.Message,
71
        metadata: Logger.Metadata,
72
        source: String,
73
        file: String,
74
        function: String,
75
        line: UInt
76
    )
77

78
    /// Creates a log sink and allows to stream logs from underlying command line instrument
79
    ///
80
    /// Should always run in a trace
81
    ///
82
    /// - Parameters:
83
    ///   - level: Log level
84
    ///   - name: Name of stream
85
    /// - Returns: ``LogSink`` — an object which receives new log lines and appends those to the stream
86
    func logStream(
87
        level: Logger.Level,
88
        name: String,
89
        renderTail: Int,
90
        file: StaticString,
91
        line: UInt
92
    ) -> LogSink
93
}
94