๐ Storyteller
A library for working with user output
Table of contents
- ๐ Introduction
- ๐ผ Visualized introduction
- ๐ Examples
- โ Origins
- ๐ Contributions & Feedback
- ๐งพ License
Introduction
This library is intended to be used by tools, such as cli's, which have multiple user interface options through which they can communicate, while also having various separate commands (or flows) which require each to carefully specify their own output formatting.
The library consists of three primary building blocks, and a default implementation on top of these building blocks. It helps you setup your program architecture
The three building blocks are:
-
EventHandler
: The event handler which deals with the user output, for example:- A handler which formats events as json-lines, and prints them to stderr
- A handler which updates a progress bar
- A handler which collects events for software testing
- A handler which sends websocket messages for each event
- A handler which updates a user interface
-
EventReporter
: Called during your program logic. Used to communicate user output to a user. The reporter is invoked with an Event during the programs logic, so you don't have to deal with formatting and display details in the middle of the program flow. -
EventListener
: Receives events, send by a reporter and runs theEventHandler
. Usually spins upa separate thread so it won't block.
On top of these building blocks, a channel based implementation is provided which runs the EventHandler
in a separate thread. To use this implementation, consult the docs for the ChannelReporter
, and the
ChannelEventListener
.
In addition to these provided elements, you have to:
- Define a type which can be used as Event
- Define one or more EventHandlers (i.e.
impl EventHandler<Event = YourEventType>
).
Visualized introduction
Click here for a larger version.
(light svg, dark svg, light png, dark png)
Examples
Real-world Example
Storyteller is used by cargo-msrv since v0.16
. To preview how events are specified, you could click around in its event module. In the handler module, several handlers can be found, such as one which writes JSON, one which prints pretty human readable output, one which prints minimal final result output used by shell commands, one which discards output and one which is used for integration testing.
A taste of storyteller
use RefCell;
use Hasher;
use ;
use ;
use ;
use Duration;
use ;
use ;
use ;
;
// See the test function `bar` in src/tests.rs for an example where the handler is a progress bar.
static SEED: AtomicU32 = new;
Origins
This library is a refined implementation based on an earlier experiment. It is intended to be used by, and was developed because of, cargo-msrv which has outgrown its current user output implementation.
Contributions
Contributions, feedback or other correspondence are more than welcome! Feel free to send a message or create an issue ๐.
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.