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 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249
#![deny(unused_imports, unused_must_use)] //! # Crossterm //! //! Have you ever been disappointed when a terminal library for rust was only written for UNIX systems? //! Crossterm provides clearing, input handling, styling, cursor movement, and terminal actions for both //! Windows and UNIX systems. //! //! Crossterm aims to be simple and easy to call in code. Through the simplicity of Crossterm, you do not //! have to worry about the platform you are working with. //! //! This crate supports all UNIX and Windows terminals down to Windows 7 (not all terminals are tested //! see [Tested Terminals](https://github.com/crossterm-rs/crossterm/tree/zrzka/docs-update#tested-terminals) //! for more info). //! //! ## Command API //! //! The command API makes the use of `crossterm` much easier and offers more control over when and how a //! command is executed. An command is just an action you can perform on the terminal e.g. cursor movement. //! //! The command API offers: //! //! * Better Performance. //! * Complete control over when to flush. //! * Complete control over where the ANSI escape commands are executed to. //! * Way easier and nicer API. //! //! There are two ways to use the API command: //! //! * Functions can execute commands on types that implement Write. Functions are easier to use and debug. //! There is a disadvantage, and that is that there is a boilerplate code involved. //! * Macros are generally seen as more difficult but offer an API with less boilerplate code. If you are //! not afraid of macros, this is a recommendation. //! //! Linux and Windows 10 systems support ANSI escape codes. Those ANSI escape codes are strings or rather a //! byte sequence. When we `write` and `flush` those to the terminal we can perform some action. //! For older windows systems a WinApi call is made. //! //! ### Supported Commands //! //!| *Command Name* | *Description* | //!| :------------------------------ | :---------------------------- | //!| **crossterm::cursor module** | | //!| `cursor::DisableBlinking` | disables blinking of the terminal cursor. | //!| `cursor::EnableBlinking` | enables blinking of the terminal cursor. | //!| `cursor::Hide` | hides the terminal cursor. | //!| `cursor::MoveDown` | moves the terminal cursor a given number of rows down. | //!| `cursor::MoveLeft` | moves the terminal cursor a given number of columns to the left. | //!| `cursor::MoveRight` | moves the terminal cursor a given number of columns to the right. | //!| `cursor::MoveTo` | moves the terminal cursor to the given position (column, row). | //!| `cursor::MoveUp` | moves the terminal cursor a given number of rows up. | //!| `cursor::RestorePosition` | restores the saved terminal cursor position. | //!| `cursor::SavePosition` | saves the current terminal cursor position. | //!| `cursor::Show` | shows the terminal cursor. | //!| **crossterm::input module** | | //!| `input::DisableMouseCapture` | disables mouse event monitoring. | //!| `input::EnableMouseCapture` | enables mouse mode | //!| | | //!| `screen::EnterAlternateScreen` | switches to the alternate screen. | //!| `screen::LeaveAlternateScreen` | switches back to the main screen. | //!| **crossterm::style module** | | //!| `style::PrintStyledContent` | prints styled content. | //!| `style::ResetColor` | resets the colors back to default. | //!| `style::SetAttribute` | sets an attribute. | //!| `style::SetBackgroundColor` | sets the the background color. | //!| `style::SetForegroundColor` | sets the the foreground color. | //!| **crossterm::terminal module** | | //!| `terminal::Clear` | clears the terminal screen buffer. | //!| `terminal::ScrollDown` | scrolls the terminal screen a given number of rows down. | //!| `terminal::ScrollUp` | scrolls the terminal screen a given number of rows up. | //!| `terminal::SetSize` | sets the terminal size (columns, rows). | //! //! There are two different way's to execute commands. //! * [Lazy Execution](#lazy-execution) //! * [Direct Execution](#direct-execution) //! //! ## Lazy Execution //! //! Flushing bytes to the terminal buffer is a heavy system call. If we perform a lot of actions with the terminal, //! we want to do this periodically - like with a TUI editor - so that we can flush more data to the terminal buffer at the same time. //! //! Crossterm offers the possibility to do this with `queue`. //! With `queue` you can queue commands, and when you call [Write::flush][flush] these commands will be executed. //! //! You can pass a custom buffer implementing [std::io::Write][write] to this `queue` operation. //! The commands will be executed on that buffer. //! The most common buffer is [std::io::stdout][stdout] however, [std::io::stderr][stderr] is used sometimes as well. //! //! ### Examples //! A simple demonstration that shows the command API in action with cursor commands. //! //! **Functions** //! //! ```no_run //! use std::io::{Write, stdout}; //! use crossterm::{QueueableCommand, cursor}; //! //! let mut stdout = stdout(); //! stdout.queue(cursor::MoveTo(5,5)); //! //! // some other code ... //! //! stdout.flush(); //! ``` //! //! The [queue](./trait.QueueableCommand.html) function returns itself, therefore you can use this to queue another command. Like //! `stdout.queue(Goto(5,5)).queue(Clear(ClearType::All))`. //! //! **Macros** //! //! ```no_run //! use std::io::{Write, stdout}; //! use crossterm::{queue, QueueableCommand, cursor}; //! //! let mut stdout = stdout(); //! queue!(stdout, cursor::MoveTo(5, 5)); //! //! // some other code ... //! //! // move operation is performed only if we flush the buffer. //! stdout.flush(); //! ``` //! //! You can pass more than one command into the [queue](./macro.queue.html) macro like `queue!(stdout, MoveTo(5, 5), Clear(ClearType::All))` and //! they will be executed in the given order from left to right. //! //! ## Direct Execution //! //! For many applications it is not at all important to be efficient with 'flush' operations. //! For this use case there is the `execute` operation. //! This operation executes the command immediately, and calls the `flush` under water. //! //! You can pass a custom buffer implementing [std::io::Write][write] to this `execute` operation. //! The commands will be executed on that buffer. //! The most common buffer is [std::io::stdout][stdout] however, [std::io::stderr][stderr] is used sometimes as well. //! //! ### Examples //! //! **Functions** //! //! ```no_run //! use std::io::{Write, stdout}; //! use crossterm::{ExecutableCommand, cursor}; //! //! let mut stdout = stdout(); //! stdout.execute(cursor::MoveTo(5,5)); //! ``` //! The [execute](./trait.ExecutableCommand.html) function returns itself, therefore you can use this to queue another command. Like //! `stdout.queue(Goto(5,5)).queue(Clear(ClearType::All))`. //! //! **Macros** //! //! ```no_run //! use std::io::{Write, stdout}; //! use crossterm::{execute, ExecutableCommand, cursor}; //! //! let mut stdout = stdout(); //! execute!(stdout, cursor::MoveTo(5, 5)); //! ``` //! You can pass more than one command into the [execute](./macro.execute.html) macro like `execute!(stdout, MoveTo(5, 5), Clear(ClearType::All))` and //! they will be executed in the given order from left to right. //! //! ## Examples //! //! Print a rectangle colored with magenta and use both direct execution and lazy execution. //! //! **Functions** //! //! ```no_run //! use std::io::{stdout, Write}; //! use crossterm::{ //! ExecutableCommand, QueueableCommand, //! terminal, cursor, style::{self, Colorize}, Result //! }; //! //! fn main() -> Result<()> { //! let mut stdout = stdout(); //! //! stdout.execute(terminal::Clear(terminal::ClearType::All))?; //! //! for y in 0..40 { //! for x in 0..150 { //! if (y == 0 || y == 40 - 1) || (x == 0 || x == 150 - 1) { //! // in this loop we are more efficient by not flushing the buffer. //! stdout //! .queue(cursor::MoveTo(x,y))? //! .queue(style::PrintStyledContent( "█".magenta()))?; //! } //! } //! } //! stdout.flush()?; //! Ok(()) //! } //! ``` //! //! **Macros:** //! //! ```no_run //! use std::io::{stdout, Write}; //! use crossterm::{ //! execute, queue, //! style::{self, Colorize}, cursor, terminal, Result //! }; //! //! fn main() -> Result<()> { //! let mut stdout = stdout(); //! //! execute!(stdout, terminal::Clear(terminal::ClearType::All))?; //! //! for y in 0..40 { //! for x in 0..150 { //! if (y == 0 || y == 40 - 1) || (x == 0 || x == 150 - 1) { //! // in this loop we are more efficient by not flushing the buffer. //! queue!(stdout, cursor::MoveTo(x,y), style::PrintStyledContent( "█".magenta()))?; //! } //! } //! } //! stdout.flush()?; //! Ok(()) //! } //!``` //! //! [write]: https://doc.rust-lang.org/std/io/trait.Write.html //! [stdout]: https://doc.rust-lang.org/std/io/fn.stdout.html //! [stderr]: https://doc.rust-lang.org/std/io/fn.stderr.html //! [flush]: https://doc.rust-lang.org/std/io/trait.Write.html#tymethod.flush pub use utils::{Command, ErrorKind, ExecutableCommand, Output, QueueableCommand, Result}; #[cfg(windows)] pub use utils::functions::supports_ansi; /// A module to work with the terminal cursor #[cfg(feature = "cursor")] pub mod cursor; /// A module to read the input events. #[cfg(feature = "input")] pub mod input; /// A module to work with the terminal screen. #[cfg(feature = "screen")] pub mod screen; /// A module to apply attributes and colors on your text. #[cfg(feature = "style")] pub mod style; /// A module to work with the terminal. #[cfg(feature = "terminal")] pub mod terminal; /// Shared utilities. pub mod utils;