1 //! console is a library for Rust that provides access to various terminal
2 //! features so you can build nicer looking command line interfaces.  It
3 //! comes with various tools and utilities for working with Terminals and
4 //! formatting text.
5 //!
6 //! Best paired with other libraries in the family:
7 //!
8 //! * [dialoguer](https://docs.rs/dialoguer)
9 //! * [indicatif](https://docs.rs/indicatif)
10 //!
11 //! # Terminal Access
12 //!
13 //! The terminal is abstracted through the `console::Term` type.  It can
14 //! either directly provide access to the connected terminal or by buffering
15 //! up commands.  A buffered terminal will however not be completely buffered
16 //! on windows where cursor movements are currently directly passed through.
17 //!
18 //! Example usage:
19 //!
20 //! ```
21 //! # fn test() -> Result<(), Box<dyn std::error::Error>> {
22 //! use std::thread;
23 //! use std::time::Duration;
24 //!
25 //! use console::Term;
26 //!
27 //! let term = Term::stdout();
28 //! term.write_line("Hello World!")?;
29 //! thread::sleep(Duration::from_millis(2000));
30 //! term.clear_line()?;
31 //! # Ok(()) } test().unwrap();
32 //! ```
33 //!
34 //! # Colors and Styles
35 //!
36 //! `console` uses `clicolors-control` to control colors.  It also
37 //! provides higher level wrappers for styling text and other things
38 //! that can be displayed with the `style` function and utility types.
39 //!
40 //! Example usage:
41 //!
42 //! ```
43 //! use console::style;
44 //!
45 //! println!("This is {} neat", style("quite").cyan());
46 //! ```
47 //!
48 //! You can also store styles and apply them to text later:
49 //!
50 //! ```
51 //! use console::Style;
52 //!
53 //! let cyan = Style::new().cyan();
54 //! println!("This is {} neat", cyan.apply_to("quite"));
55 //! ```
56 //!
57 //! # Working with ANSI Codes
58 //!
59 //! The crate provids the function `strip_ansi_codes` to remove ANSI codes
60 //! from a string as well as `measure_text_width` to calculate the width of a
61 //! string as it would be displayed by the terminal.  Both of those together
62 //! are useful for more complex formatting.
63 //!
64 //! # Unicode Width Support
65 //!
66 //! By default this crate depends on the `unicode-width` crate to calculate
67 //! the width of terminal characters.  If you do not need this you can disable
68 //! the `unicode-width` feature which will cut down on dependencies.
69 //!
70 //! # Features
71 //!
72 //! By default all features are enabled.  The following features exist:
73 //!
74 //! * `unicode-width`: adds support for unicode width calculations
75 //! * `ansi-parsing`: adds support for parsing ansi codes (this adds support
76 //!   for stripping and taking ansi escape codes into account for length
77 //!   calculations).
78 
79 pub use crate::kb::Key;
80 pub use crate::term::{
81     user_attended, user_attended_stderr, Term, TermFamily, TermFeatures, TermTarget,
82 };
83 pub use crate::utils::{
84     colors_enabled, colors_enabled_stderr, measure_text_width, pad_str, set_colors_enabled,
85     set_colors_enabled_stderr, style, truncate_str, Alignment, Attribute, Color, Emoji, Style,
86     StyledObject,
87 };
88 
89 #[cfg(feature = "ansi-parsing")]
90 pub use crate::ansi::{strip_ansi_codes, AnsiCodeIterator};
91 
92 mod common_term;
93 mod kb;
94 mod term;
95 #[cfg(unix)]
96 mod unix_term;
97 mod utils;
98 #[cfg(target_arch = "wasm32")]
99 mod wasm_term;
100 #[cfg(windows)]
101 mod windows_term;
102 
103 #[cfg(feature = "ansi-parsing")]
104 mod ansi;
105