requestty_ui/
lib.rs

1//! A widget based terminal ui rendering library.
2//!
3//! This crate provides an abstraction over terminal manipulation in the form of the [`Widget`]
4//! trait. It also provides some default widgets available in [`widgets`].
5//!
6//! While this crate was built for the  [`requestty`] crate and other crates which implement the
7//! [`Prompt`] trait in [`requestty`], it can be used otherwise as well.
8//!
9//! [`requestty`]: https://crates.io/crates/requestty
10//! [`Prompt`]: https://docs.rs/requestty/latest/requestty/prompt/trait.Prompt.html
11//!
12//! # Backends
13//!
14//! This crate currently supports 2 backends:
15//! - [`crossterm`](https://crates.io/crates/crossterm)
16//! - [`termion`](https://crates.io/crates/termion)
17//!
18//! The different backends can be enabled using the features of the same name.
19#![deny(
20    missing_docs,
21    missing_debug_implementations,
22    unreachable_pub,
23    rustdoc::broken_intra_doc_links
24)]
25#![warn(rust_2018_idioms)]
26#![cfg_attr(docsrs, feature(doc_cfg))]
27
28pub use error::{ErrorKind, Result};
29pub use input::{Input, OnEsc, Prompt, Validation};
30pub use widgets::Widget;
31
32pub mod backend;
33mod char_input;
34mod error;
35pub mod events;
36mod input;
37pub mod layout;
38mod prompt;
39mod select;
40mod string_input;
41pub mod style;
42pub mod symbols;
43mod text;
44pub mod widgets;
45
46#[doc(hidden)]
47pub mod features {
48    #[cfg(feature = "crossterm")]
49    pub const SNAPSHOT_PATH: &str = "crossterm-snapshots";
50
51    // XXX: Only works when crossterm and termion are the only two available backends
52    //
53    // Instead of directly checking for termion, we check for not crossterm so that compiling
54    // (documentation) with both features enabled will not error
55    #[cfg(not(feature = "crossterm"))]
56    pub const SNAPSHOT_PATH: &str = "termion-snapshots";
57}
58
59/// A testing utility to assert visual equality with [`TestBackend`](backend::TestBackend).
60///
61/// It is a simple wrapper around [`insta::assert_display_snapshot`] which puts the snapshots in
62/// `$CARGO_MANIFEST_DIR/{crossterm/termion}-snapshots`.
63///
64/// [`insta::assert_display_snapshot`]: https://docs.rs/insta/1.11.0/insta/macro.assert_display_snapshot.html
65#[cfg(any(feature = "crossterm", feature = "termion"))]
66#[cfg_attr(docsrs, doc(cfg(any(feature = "crossterm", feature = "termion"))))]
67#[macro_export]
68macro_rules! assert_backend_snapshot {
69    ($value:expr, @$snapshot:literal) => {
70        $crate::assert_backend_snapshot_impl!(::insta::assert_display_snapshot!($value, @$snapshot))
71    };
72    ($name:expr, $value:expr) => {
73        $crate::assert_backend_snapshot_impl!(::insta::assert_display_snapshot!($name, $value))
74    };
75    ($value:expr) => {
76        $crate::assert_backend_snapshot_impl!(::insta::assert_display_snapshot!($value))
77    };
78
79}
80
81#[doc(hidden)]
82#[macro_export]
83macro_rules! assert_backend_snapshot_impl {
84    ($($tt:tt)*) => {{
85        ::insta::with_settings!({
86            snapshot_path => ::std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join($crate::features::SNAPSHOT_PATH)
87        }, {
88            $($tt)*
89        })
90    }}
91}
92
93#[cfg(test)]
94mod test_consts {
95    /// ASCII placeholder text with 470 characters
96    pub(crate) static LOREM: &str = "Lorem ipsum dolor sit amet, consectetuer \
97        adipiscing elit. Aenean commodo ligula e get dolor. Aenean massa. Cum sociis \
98        natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. \
99        Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla \
100        consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, \
101        vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, \
102        justo. Nullam dictum felis eu pede mollis pretium.";
103
104    /// Unicode placeholder text with 470 characters
105    pub(crate) static UNICODE: &str = "ǹɕǶǽũ ȥűǷŀȷÂǦǨÏNJ ýǡƎƭǃÁžƖţŝŬœĶ ɳƙŁŵŃŋŗ dzÆŅɜŴô ħIJǗɧÝÙĝɸÿ \
106        ǝƬDŽƫɌñÄç ɎƷɔȲƧ éďŅǒƿŅ üIJƪɮúǚijǓɔÏǙǟ ǃóıÄ×ȤøŌɘŬ ȃŜʈǑƱļ ȶė÷ƝȣŞýş óɭǽƎȮ ŏŀƔȾřŞȩ \
107        ĚïƝƦʀƕĥǡǎÌʅ ĻɠȞīĈưĭÓĢÑ LJĦƷűǐ¾đ ŊǂȘŰƒ ēɄɟɍƬč ɼ·ȄĶȸŦɉ ţĥŐʼnŭ ãɹƠƲɼŒǜ ȹúƄdžȆ ȡǞȐǖŁƀ \
108        ėýŭȇȹı ɹûØùž ïȕĆßĀȭ ÍȖȟũȍ ȼƦŚɀʆ ĖDZŞȅŎ ţÎǓŏï ȃāÖćźȀȿ Īŝłƒťƌȇ ǘůńNJļ ǂȄȐǐǻ Ȳɵ¾ǕÉ \
109        ɛȃǾȚDZÚ ķĘƄɜÉ êɷƐŻɌ ɐțǼÏƐȄ òɫɥƸâɈ ĄȫĞîĖƿſú¹ ǐȊÜÉį ȬDzɩŎǩĮ ĂȷĎǶŐ ÍɼƔÌűÉĎƣ ÃÜȯƪLJ \
110        ȋDzŹǀŊȻ Ɍ¾ȓƃĝ êɊDŽɕÈ ÿ¸ȧȣíÚɁƺ ȏǖŷȡȬ ȍǕȁɜğʆ ƨɺȨƠŇȱƕ ȊÑļɧģŷIJ ʈźçƣƑ ƀǼŌéǔÀ ȊŅɂƵǝ¾ \
111        ēɩīűŃɖąɔɳ ȁõıĚņ ȦɂȄƄȥɣŴűǎǃ";
112}