diff --git a/.travis.yml b/.travis.yml index 978cc69..179f097 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,3 +1,9 @@ +# Build only pushed (merged) master or any pull request. This avoids the +# pull request to be build twice. +branches: + only: + - master + language: rust rust: diff --git a/CHANGELOG.md b/CHANGELOG.md index bc1023e..b4f2854 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +# Version master + +- Removed book link +- Deprecated warning about `crossterm_*` crates +- Documentation improved + # Version 0.11.1 - Maintenance release diff --git a/README.md b/README.md index 101adb2..b4db135 100644 --- a/README.md +++ b/README.md @@ -2,332 +2,189 @@ [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=Z8QK6XU749JB2) ![Travis][s7] [![Latest Version][s1]][l1] [![MIT][s2]][l2] [![docs][s3]][l3] ![Lines of Code][s6] [![Join us on Discord][s5]][l5] -# cross-platform terminal manipulating library. +# Cross-platform Terminal Manipulation Library -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 +Have you ever been disappointed when a terminal library for the Rust language 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. +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 +This crate supports all UNIX and Windows terminals down to Windows 7 (not all terminals are tested, see [Tested Terminals](#tested-terminals) for more info). -This crate consists of five modules that are provided behind -[feature flags](https://crossterm-rs.github.io/crossterm/docs/feature_flags.html) so that you can define -which features you'd like to have; by default, all features are enabled. +## Table of Contents -- [crossterm_style](https://crates.io/crates/crossterm_style) -- [crossterm_input](https://crates.io/crates/crossterm_input) -- [crossterm_screen](https://crates.io/crates/crossterm_screen) -- [crossterm_cursor](https://crates.io/crates/crossterm_cursor) -- [crossterm_terminal](https://crates.io/crates/crossterm_terminal) - -## Table of contents: - -- [Getting started](#getting-started) -- [Useful links](#useful-links) -- [Features](#features) -- [Examples](#examples) - - [Styled Text](#styled-text) - - [Cursor](#cursor) - - [Terminal](#terminal) - - [Input Reading](#input-reading) -- [Tested Terminals](#tested-terminals) -- [Contributing](#contributing) -- [Authors](#authors) -- [License](#license) - -## Getting Started - -All [examples](https://github.com/crossterm-rs/examples) of how crossterm works can be found in the example repository. - -Add the Crossterm package to your `Cargo.toml` file. - -``` -[dependencies] -crossterm = "0.11" -``` - -### Useful Links - -- [Book](https://crossterm-rs.github.io/crossterm/docs/) -- [Documentation](https://docs.rs/crossterm/) -- [Crates.io](https://crates.io/crates/crossterm) -- [Examples](https://github.com/crossterm-rs/examples) +* [Features](#features) + * [Tested Terminals](#tested-terminals) +* [Getting Started](#getting-started) + * [Feature Flags](#feature-flags) + * [`crossterm` vs `crossterm_*` crates](#crossterm-vs-crossterm_-crates) +* [Other Resources](#other-resources) +* [Used By](#used-by) +* [Contributing](#contributing) ## Features - Cross-platform - Multi-threaded (send, sync) -- Detailed Documentation -- Few Dependencies -- Cursor - - Moving _n_ times (up, down, left, right) - - Position (set/get) - - Store cursor position and resetting to that later - - Hiding/Showing - - Blinking Cursor (supported by only some terminals) -- Styled output - - Foreground Color (16 base colors) - - Background Color (16 base colors) - - 256 (ANSI) Color Support (Windows 10 and UNIX Only) - - RGB Color Support (Windows 10 and UNIX only) - - Text Attributes: bold, italic, underscore and crossed word and [more](https://crossterm-rs.github.io/crossterm/docs//styling.html#attributes) (Windows 10 and UNIX only) -- Terminal - - Clearing (all lines, current line, from cursor down and up, until new line) - - Scrolling (up, down) - - Terminal Size (get/set) - - Alternate Screen - - Raw Screen - - Exit Current Process -- Input +- Detailed documentation +- Few dependencies +- Cursor (feature `cursor`) + - Move the cursor N times (up, down, left, right) + - Set/get the cursor position + - Store the cursor position and restore to it later + - Hide/show the cursor + - Enable/disable cursor blinking (not all terminals do support this feature) +- Styled output (feature `style`) + - Foreground color (16 base colors) + - Background color (16 base colors) + - 256 (ANSI) color support (Windows 10 and UNIX only) + - RGB color support (Windows 10 and UNIX only) + - Text attributes like bold, italic, underscore, crossed, etc. +- Terminal (feature `terminal`) + - Clear (all lines, current line, from cursor down and up, until new line) + - Scroll up, down + - Set/get the terminal size + - Exit current process +- Input (feature `input`) - Read character - Read line - Read key input events (async / sync) - Read mouse input events (press, release, position, button) +- Screen (feature `screen`) + - Alternate screen + - Raw screen -## Examples + -These are some basic examples demonstrating how to use this crate. See the -[examples](https://github.com/crossterm-rs/examples) repository. - -### Command API - -My first recommendation is to use the [command API](https://crossterm-rs.github.io/crossterm/docs/command.html) -because this might replace some of the existing API in the future. It is more convenient, faster, and easier to use. - -### Styled Text - -This module enables you to style the terminal text. - -Good documentation can be found at the following places: [docs](https://docs.rs/crossterm_style/), -[book](https://crossterm-rs.github.io/crossterm/docs/styling.html) -and [examples](https://github.com/crossterm-rs/examples/blob/master/examples/src/bin/key_events.rs). - -_style text with attributes_ - -```rust -use crossterm::{Colored, Color, Colorize, Styler, Attribute}; - -// pass any `Attribute` value to the formatting braces. -println!("{} Underlined {} No Underline", Attribute::Underlined, Attribute::NoUnderline); - -// you could also call different attribute methods on a `&str` and keep on chaining if needed. -let styled_text = "Bold Underlined".bold().underlined(); -println!("{}", styled_text); -``` - -_style text with colors_ - -```rust -println!("{} Red foreground color", Colored::Fg(Color::Red)); -println!("{} Blue background color", Colored::Bg(Color::Blue)); - -// you can also call different coloring methods on a `&str`. -let styled_text = "Bold Underlined".red().on_blue(); -println!("{}", styled_text); -``` - -_style text with RGB and ANSI Value_ - -```rust -// custom rgb value (Windows 10 and UNIX systems) -println!("{} some colored text", Colored::Fg(Color::Rgb { - r: 10, - g: 10, - b: 10 -})); - -// custom ansi color value (Windows 10 and UNIX systems) -println!("{} some colored text", Colored::Fg(Color::AnsiValue(10))); -``` - -### Cursor - -This module enables you to work with the terminal cursor. - -Good documentation could be found on the following places: [docs](https://docs.rs/crossterm_cursor/) and -[examples](https://github.com/crossterm-rs/examples). - -```rust -use crossterm::cursor; - -let mut cursor = cursor(); - -/// Moving the cursor -// Set the cursor to position X: 10, Y: 5 in the terminal -cursor.goto(10,5); - -// Move the cursor up,right,down,left 3 cells. -cursor.move_up(3); -cursor.move_right(3); -cursor.move_down(3); -cursor.move_left(3); - -/// Safe the current cursor position to recall later -// Goto X: 5 Y: 5 -cursor.goto(5,5); -// Safe cursor position: X: 5 Y: 5 -cursor.save_position(); -// Goto X: 5 Y: 20 -cursor.goto(5,20); -// Print at X: 5 Y: 20. -print!("Yea!"); -// Reset back to X: 5 Y: 5. -cursor.restore_position(); -// Print 'Back' at X: 5 Y: 5. -print!("Back"); - -// hide cursor -cursor.hide(); -// show cursor -cursor.show(); -// blink or not blinking of the cursor (not widely supported) -cursor.blink(true) -``` - -### Terminal - -This module enables you to work with the terminal in general. - -Good documentation could be found on the following places: [docs](https://docs.rs/crossterm_terminal/) and -[examples](https://github.com/crossterm-rs/examples). - -```rust -use crossterm::{terminal,ClearType}; - -let mut terminal = terminal(); - -// Clear all lines in terminal; -terminal.clear(ClearType::All); -// Clear all cells from current cursor position down. -terminal.clear(ClearType::FromCursorDown); -// Clear all cells from current cursor position down. -terminal.clear(ClearType::FromCursorUp); -// Clear current line cells. -terminal.clear(ClearType::CurrentLine); -// Clear all the cells until next line. -terminal.clear(ClearType::UntilNewLine); - -// Get terminal size -let (width, height) = terminal.terminal_size(); -print!("X: {}, y: {}", width, height); - -// Scroll down, up 10 lines. -terminal.scroll_down(10); -terminal.scroll_up(10); - -// Set terminal size (width, height) -terminal.set_size(10,10); - -// exit the current process. -terminal.exit(); - -// write to the terminal whether you are on the main screen or alternate screen. -terminal.write("Some text\n Some text on new line"); -``` - -### Input Reading - -This module enables you to read user input events. - -Good documentation could be found on the following places: [docs](https://docs.rs/crossterm_input/), -[book](https://crossterm-rs.github.io/crossterm/docs/input.html) and -[examples](https://github.com/crossterm-rs/examples). - -_available imports_ -```rust -use crossterm_input::{ - input, InputEvent, KeyEvent, MouseButton, MouseEvent, TerminalInput, AsyncReader, SyncReader, Screen -}; -``` - -_Simple Readings_ - -```rust -let mut input = input(); - - match input.read_char() { - Ok(s) => println!("char typed: {}", s), - Err(e) => println!("char error : {}", e), - } - - match input.read_line() { - Ok(s) => println!("string typed: {}", s), - Err(e) => println!("error: {}", e), - } -``` - -_Read input events synchronously or asynchronously._ - -```rust -// make sure to enable raw mode, this will make sure key events won't be handled by the terminal it's -// self and allows crossterm to read the input and pass it back to you. -let screen = RawScreen::into_raw_mode(); - -let mut input = input(); - -// either read the input synchronously -let stdin = input.read_sync(); - -// or asynchronously -let stdin = input.read_async(); - -if let Some(key_event) = stdin.next() { - match key_event { - InputEvent::Keyboard(event: KeyEvent) => match event { /* check key event */ } - InputEvent::Mouse(event: MouseEvent) => match event { /* check mouse event */ } - } - } -``` - -_Enable mouse input events._ - -```rust -let input = input(); - -// enable mouse events to be captured. -input.enable_mouse_mode().unwrap(); - -// disable mouse events to be captured. -input.disable_mouse_mode().unwrap(); -``` - -### Alternate and Raw Screen - -These concepts are a little more complex and would take over the README, please check out -the [docs](https://docs.rs/crossterm_screen/), [book](https://crossterm-rs.github.io/crossterm/docs/screen.html) -and [examples](https://github.com/crossterm-rs/examples). - -## Used by - -- [Broot](https://dystroy.org/broot/) -- [Cursive](https://github.com/gyscos/Cursive) -- [TUI](https://github.com/fdehau/tui-rs) -- [Rust-sloth](https://github.com/jonathandturner/rust-sloth/tree/crossterm-port) - -## Tested terminals +### Tested Terminals - Windows Powershell - - Windows 10 (pro) + - Windows 10 (Pro) - Windows CMD - - Windows 10 (pro) + - Windows 10 (Pro) - Windows 8.1 (N) - Ubuntu Desktop Terminal - Ubuntu 17.10 - (Arch, Manjaro) KDE Konsole - Linux Mint -This crate supports all Unix terminals and Windows terminals down to Windows 7; however, not all of the +This crate supports all UNIX terminals and Windows terminals down to Windows 7; however, not all of the terminals have been tested. If you have used this library for a terminal other than the above list without issues, then feel free to add it to the above list - I really would appreciate it! +## Getting Started + +
+ +Click to show Cargo.toml. + + +```toml +[dependencies] +crossterm = "0.11" +``` + +
+

+ +```rust +use std::io::{stdout, Write}; + +use crossterm::{execute, Attribute, Color, Output, ResetColor, Result, SetBg, SetFg}; + +fn main() -> Result<()> { + execute!( + stdout(), + // Blue foreground + SetFg(Color::Blue), + // Red background + SetBg(Color::Red), + Output("Styled text here.".to_string()), + // Reset to default colors + ResetColor + ) +} +``` + +### Feature Flags + +All features are enabled by default. You can disable default features and enable some of them only. + +```toml +[dependencies.crossterm] +version = "0.11" +default-features = false # Disable default features +features = ["cursor", "screen"] # Enable required features only +``` + +| Feature | Description | Links | +| :-- | :-- | :-- | +| `input` | Sync/Async input readers | [API documentation](https://docs.rs/crossterm_input), [crates.io](https://crates.io/crates/crossterm_input), [GitHub](https://github.com/crossterm-rs/crossterm-input) | +| `cursor` | Cursor manipulation | [API documentation](https://docs.rs/crossterm_cursor), [crates.io](https://crates.io/crates/crossterm_cursor), [GitHub](https://github.com/crossterm-rs/crossterm-cursor) | +| `screen` | Alternate screen & raw mode | [API documentation](https://docs.rs/crossterm_screen), [crates.io](https://crates.io/crates/crossterm_screen), [GitHub](https://github.com/crossterm-rs/crossterm-screen) | +| `terminal` | Size, clear, scroll | [API documentation](https://docs.rs/crossterm_terminal), [crates.io](https://crates.io/crates/crossterm_terminal), [GitHub](https://github.com/crossterm-rs/crossterm-terminal) | +| `style` | Colors, text attributes | [API documentation](https://docs.rs/crossterm_style), [crates.io](https://crates.io/crates/crossterm_style), [GitHub](https://github.com/crossterm-rs/crossterm-style) | + +### `crossterm` vs `crossterm_*` crates + +There're two ways how to use the Crossterm library: + +* `crossterm` crate with the `cursor` feature flag, +* `crossterm_cursor` crate. + +Both provide same functionality, the only difference is the namespace (`crossterm` vs `crossterm_cursor`). + +The first way (`crossterm` crate with feature flags) is preferred. The second way will be +deprecated and no longer supported soon. The `crossterm_*` crates will be marked as deprecated and +repositories archived on the GitHub. See the +[Merge sub-crates to the crossterm crate](https://github.com/crossterm-rs/crossterm/issues/265) +for more details. + +#### `crossterm` crate: + +```toml +[dependencies.crossterm] +version = "0.11" +default-features = false # Disable default features +features = ["cursor"] # Enable cursor feature only +``` + +```rust +use crossterm::cursor; +``` + +#### `crossterm_curosr` crate: + +```toml +[dependencies] +crossterm_cursor = "0.3" +``` + +```rust +use crossterm_cursor::cursor; +``` + +### Other Resources + +- [API documentation](https://docs.rs/crossterm/) +- [Examples repository](https://github.com/crossterm-rs/examples) + +## Used By + +- [Broot](https://dystroy.org/broot/) +- [Cursive](https://github.com/gyscos/Cursive) +- [TUI](https://github.com/fdehau/tui-rs) +- [Rust-sloth](https://github.com/jonathandturner/rust-sloth/tree/crossterm-port) + ## Contributing -I highly appreciate it when you contribute to this crate. -Please visit the discord or issue list for more information +I highly appreciate when anyone contributes to this crate. Before you do, please, +read the [Contributing](docs/CONTRIBUTING.md) guidelines. ## Authors @@ -335,15 +192,15 @@ Please visit the discord or issue list for more information ## Support -Would you like crossterm to be even more gorgeous and beautiful? You can help with this by donating. +Would you like Crossterm to be even more gorgeous and beautiful? You can help with this by donating. [![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=Z8QK6XU749JB2) ## License -This project, crossterm and all it's sub-modules: crossterm_screen, crossterm_cursor, crossterm_style, -crossterm_input, crossterm_terminal, crossterm_winapi, crossterm_utils are licensed under the MIT License - see -the [LICENSE](https://github.com/crossterm-rs/crossterm/blob/master/LICENSE) file for details +This project, `crossterm` and all it's sub-crates: `crossterm_screen`, `crossterm_cursor`, `crossterm_style`, +`crossterm_input`, `crossterm_terminal`, `crossterm_winapi`, `crossterm_utils` are licensed under the MIT +License - see the [LICENSE](https://github.com/crossterm-rs/crossterm/blob/master/LICENSE) file for details. [s1]: https://img.shields.io/crates/v/crossterm.svg [l1]: https://crates.io/crates/crossterm diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 3439126..9492ac5 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -2,61 +2,9 @@ I would appreciate any contributions to this crate. However, some things are handy to know. -## Architecture +## Code Style -Crossterm is using ANSI escape codes by default for both Unix and for Windows systems except -for Windows versions lower than 10. Crossterm uses WinAPI in this case. - -### Crates - -The `crossterm` crate consists of 7 crates: - -* [cursor](https://github.com/crossterm-rs/crossterm-cursor) -* [input](https://github.com/crossterm-rs/crossterm-input) -* [style](https://github.com/crossterm-rs/crossterm-style) -* [terminal](https://github.com/crossterm-rs/crossterm-terminal) -* [screen](https://github.com/crossterm-rs/crossterm-screen) -* [utils](https://github.com/crossterm-rs/crossterm-utils) -* [winapi](https://github.com/crossterm-rs/crossterm-winapi) - -### Module structure - -If you would like to contribute, then please follow the existing structure. For -example, the cursor crate has the following file structure: - -```text -└── src - ├── cursor - │   ├── ansi.rs - │   └── windows.rs - ├── cursor.rs - ├── lib.rs - ├── sys - │   ├── unix.rs - │   └── windows.rs - └── sys.rs -``` - -* `src/lib.rs` - public interface of the crate (for example `TerminalCursor` struct) -* `src/cursor.rs` - `Cursor` trait, which must be implement by all platform specific cursors -* `src/cursor/ansi.rs` - `AnsiCursor` structure implementing the `Cursor` trait -* `src/cursor/windows.rs` - `WinApiCursor` structure implementing the `Cursor` trait -* `src/sys` - platform specific logic - -The above structure is followed by other crates. - -Why I have chosen this design: - -* You can easily add new platform by implementing the trait -* You can keep the functionality for different platforms separated -* You have one API the user can call like in the `src/lib.rs` - -Try to avoid changing `src/lib.rs` a lot, because it contains API for -the end-user. - -## Code style - -### Import order +### Import Order All imports are semantically grouped and ordered. The order is: @@ -67,9 +15,7 @@ All imports are semantically grouped and ordered. The order is: - current module (`use self::...`) - module declaration (`mod ...`) -There must be an empty line between groups. - -An example: +There must be an empty line between groups. An example: ```rust use crossterm_utils::{csi, write_cout, Result}; @@ -79,7 +25,7 @@ use crate::sys::{get_cursor_position, show_cursor}; use super::Cursor; ``` -#### CLion tips +#### CLion Tips The CLion IDE does this for you (_Menu_ -> _Code_ -> _Optimize Imports_). Be aware that the CLion sorts imports in a group in a different way when compared to the `rustfmt`. It's effectively two steps operation @@ -91,7 +37,7 @@ to get proper grouping & sorting: Second step can be automated via _CLion_ -> _Preferences_ -> _Languages & Frameworks_ -> _Rust_ -> _Rustfmt_ -> _Run rustfmt on save_. -### Max line length +### Max Line Length | Type | Max line length | | :--- | ---: | @@ -104,7 +50,6 @@ default value. 120 is because of the GitHub. The editor & viewer width there is +- 123 characters. -### ### Warnings The code must be warning free. It's quite hard to find an error if the build logs are polluted with warnings. @@ -112,7 +57,7 @@ If you decide to silent a warning with (`#[allow(...)]`), please add a comment w Always consult the [Travis CI](https://travis-ci.org/crossterm-rs/crossterm/pull_requests) build logs. -### Disallowed warnings +### Forbidden Warnings Search for `#![deny(...)]` in the code: diff --git a/docs/mdbook/src/SUMMARY.md b/docs/mdbook/src/SUMMARY.md index c3e7fc7..94519db 100644 --- a/docs/mdbook/src/SUMMARY.md +++ b/docs/mdbook/src/SUMMARY.md @@ -1,4 +1,8 @@ # Crossterm + +> **WARNING**: This book is deprecated, no longer maintained and will be +> removed soon. + This book explains how crossterm works, and how you can use different functionalities. We look at how to turn feature flags features on and off, how to style the terminal with colors and attributes, how to read user input and how to make using crossterm easier. diff --git a/docs/mdbook/src/command.md b/docs/mdbook/src/command.md index 1f17564..f99d376 100644 --- a/docs/mdbook/src/command.md +++ b/docs/mdbook/src/command.md @@ -1,4 +1,8 @@ # Command API + +> **WARNING**: This book is deprecated, no longer maintained and will be +> removed soon. + The command API makes the use of crossterm much easier and offers more control over when and how a command such as moving the cursor is executed. The command API offers: @@ -161,4 +165,4 @@ for y in 0..40 { } stdout.flush(); } - ``` \ No newline at end of file + ``` diff --git a/docs/mdbook/src/feature_flags.md b/docs/mdbook/src/feature_flags.md index c6ee0f6..c201315 100644 --- a/docs/mdbook/src/feature_flags.md +++ b/docs/mdbook/src/feature_flags.md @@ -1,3 +1,6 @@ +> **WARNING**: This book is deprecated, no longer maintained and will be +> removed soon. + From `crossterm 0.6` you are able to use feature flags. With feature flags, you can pick the features you want which reduces the size of the library and could prevent you from having unnecessary dependencies. diff --git a/docs/mdbook/src/input.md b/docs/mdbook/src/input.md index eb74db8..db26492 100644 --- a/docs/mdbook/src/input.md +++ b/docs/mdbook/src/input.md @@ -1,3 +1,6 @@ +> **WARNING**: This book is deprecated, no longer maintained and will be +> removed soon. + Crossterm provides a way to work with the terminal input. We will not cover the basic usage but instead asynchronous and synchronous reading of input. Please check out these [examples](https://github.com/crossterm-rs/crossterm/blob/master/examples/input.rs) for reading a line or a character from the user. diff --git a/docs/mdbook/src/screen.md b/docs/mdbook/src/screen.md index 18218d9..9962539 100644 --- a/docs/mdbook/src/screen.md +++ b/docs/mdbook/src/screen.md @@ -1,3 +1,6 @@ +> **WARNING**: This book is deprecated, no longer maintained and will be +> removed soon. + ## Screen Buffer A screen buffer is a two-dimensional array of characters and color data to be output in a console window. A terminal can have multiple of those screen buffers, and the active screen buffer is the one that is displayed on the screen. @@ -40,4 +43,4 @@ _example of what I mean_ To start at the beginning of the next line, use `\n\r`. --------------------------------------------------------------------------------------------------------------------------------------------- -More examples could be found [over here](https://github.com/crossterm-rs/crossterm/blob/master/examples/). \ No newline at end of file +More examples could be found [over here](https://github.com/crossterm-rs/crossterm/blob/master/examples/). diff --git a/docs/mdbook/src/styling.md b/docs/mdbook/src/styling.md index 4b42416..5be8b80 100644 --- a/docs/mdbook/src/styling.md +++ b/docs/mdbook/src/styling.md @@ -1,5 +1,8 @@ # Styling Module +> **WARNING**: This book is deprecated, no longer maintained and will be +> removed soon. + Crossterm provides options for you to style your text and terminal. Take for example coloring output and applying attributes. **Color support** diff --git a/src/crossterm.rs b/src/crossterm.rs index f87a70a..16e8604 100644 --- a/src/crossterm.rs +++ b/src/crossterm.rs @@ -1,102 +1,40 @@ use std::fmt::Display; -/// This type offers an easy way to use functionalities like `cursor`, `terminal`, `color`, `input`, and `styling`. -/// -/// To get a cursor instance to perform cursor related actions, you can do the following: -/// -/// ```rust -/// # use crossterm::*; -/// let crossterm = Crossterm::new(); -/// let cursor = crossterm.cursor(); -/// let color = crossterm.color(); -/// let terminal = crossterm.terminal(); -/// let terminal = crossterm.input(); -/// let style = crossterm -/// .style(format!("{} {}", 0, "Black text on green background")) -/// .with(Color::Black) -/// .on(Color::Green); -/// ``` -/// -/// # Remark -/// - depending on the feature flags you've enabled you are able to call methods of this type. -/// - checkout the crossterm book for more information about feature flags or alternate screen. +// TODO Should be removed? This adds just another way to achieve the same thing. +/// A crossterm functionality wrapper. pub struct Crossterm; impl Crossterm { - /// Create a new instance of `Crossterm` + /// Creates a new `Crossterm`. pub fn new() -> Crossterm { Crossterm } - /// Get a `TerminalCursor` implementation whereon cursor related actions can be performed. - /// - /// ```rust - /// # use crossterm::*; - /// let crossterm = Crossterm::new(); - /// let cursor = crossterm.cursor(); - /// ``` + /// Crates a new `TerminalCursor`. #[cfg(feature = "cursor")] pub fn cursor(&self) -> crossterm_cursor::TerminalCursor { crossterm_cursor::TerminalCursor::new() } - /// Get a `TerminalInput` implementation whereon terminal related actions can be performed. - /// - /// ```rust - /// # use crossterm::*; - /// let crossterm = Crossterm::new(); - /// let input = crossterm.input(); - /// ``` + /// Creates a new `TerminalInput`. #[cfg(feature = "input")] pub fn input(&self) -> crossterm_input::TerminalInput { crossterm_input::TerminalInput::new() } - /// Get a `Terminal` implementation whereon terminal related actions can be performed. - /// - /// ```rust - /// # use crossterm::*; - /// let crossterm = Crossterm::new(); - /// let mut terminal = crossterm.terminal(); - /// ``` + /// Creates a new `Terminal`. #[cfg(feature = "terminal")] pub fn terminal(&self) -> crossterm_terminal::Terminal { crossterm_terminal::Terminal::new() } - /// Get a `TerminalColor` implementation whereon color related actions can be performed. - /// - /// ```rust - /// # use crossterm::*; - /// let crossterm = Crossterm::new(); - /// let mut terminal = crossterm.color(); - /// ``` + /// Creates a new `TerminalColor`. #[cfg(feature = "style")] pub fn color(&self) -> crossterm_style::TerminalColor { crossterm_style::TerminalColor::new() } - /// This could be used to style any type implementing `Display` with colors and attributes. - /// - /// # Example - /// ```rust - /// # use crossterm::*; - /// let crossterm = Crossterm::new(); - /// - /// // get an styled object which could be painted to the terminal. - /// let styled_object = crossterm.style("Some Blue colored text on black background") - /// .with(Color::Blue) - /// .on(Color::Black); - /// - /// // print the styled text * times to the current screen. - /// for i in 1..10 - /// { - /// println!("{}", styled_object); - /// } - /// ``` - /// - /// # Remark - /// `val`: any type implementing Display e.g. string. + /// Creates a new `StyledObject`. #[cfg(feature = "style")] pub fn style(&self, val: D) -> crossterm_style::StyledObject where diff --git a/src/lib.rs b/src/lib.rs index 44d439a..84bdae2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,17 +1,22 @@ +//! # 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 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. +//! 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](#tested-terminals) for more info). +//! 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). //! -//! This crate consists of five modules that are provided behind [feature flags](https://crossterm-rs.github.io/crossterm/docs/feature_flags.html) so that you can define which features you'd like to have; by default, all features are enabled. -//! - [Crossterm Style](https://crates.io/crates/crossterm_style) -//! - [Crossterm Input](https://crates.io/crates/crossterm_input) -//! - [Crossterm Screen](https://crates.io/crates/crossterm_screen) -//! - [Crossterm Cursor](https://crates.io/crates/crossterm_cursor) -//! - [Crossterm Terminal](https://crates.io/crates/crossterm_terminal) +//! ## Important +//! +//! This crate re-exports all other `crossterm_*` crates types only. Please, consult the +//! `crossterm` crate repository [README](https://github.com/crossterm-rs/crossterm/blob/master/README.md) to +//! learn how to use features to enable/disable functionality, what's planned, etc. There will be +//! new code organization, breaking API changes, etc. #[cfg(feature = "cursor")] pub use crossterm_cursor::{