blasthavers/minicrossterm
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #269 from crossterm-rs/zrzka/docs-update

Browse Source 
Documentation update
This commit is contained in:
Zrzka 2019-10-02 11:18:40 +02:00 committed by GitHub
commit 5a32fb3f78
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 218 additions and 441 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.travis.yml
View File

@ -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 language: rust
rust: rust:

6
CHANGELOG.md
View File

@ -1,3 +1,9 @@
# Version master
- Removed book link
- Deprecated warning about `crossterm_*` crates
- Documentation improved
# Version 0.11.1 # Version 0.11.1
- Maintenance release - Maintenance release

453
README.md
View File

@ -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] [![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? 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 Crossterm provides clearing, input handling, styling, cursor movement and terminal actions for both
Windows and UNIX systems. Windows and UNIX systems.
Crossterm aims to be simple and easy to call in code. Crossterm aims to be simple and easy to call in code. Through the simplicity of Crossterm, you do not have to
Through the simplicity of Crossterm, you do not have to worry about the platform you are working with. 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). see [Tested Terminals](#tested-terminals) for more info).
This crate consists of five modules that are provided behind ## Table of Contents
[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) * [Features](#features)
- [crossterm_input](https://crates.io/crates/crossterm_input) * [Tested Terminals](#tested-terminals)
- [crossterm_screen](https://crates.io/crates/crossterm_screen) * [Getting Started](#getting-started)
- [crossterm_cursor](https://crates.io/crates/crossterm_cursor) * [Feature Flags](#feature-flags)
- [crossterm_terminal](https://crates.io/crates/crossterm_terminal) * [`crossterm` vs `crossterm_*` crates](#crossterm-vs-crossterm_-crates)
* [Other Resources](#other-resources)
## Table of contents: * [Used By](#used-by)
* [Contributing](#contributing)
- [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
- Cross-platform - Cross-platform
- Multi-threaded (send, sync) - Multi-threaded (send, sync)
- Detailed Documentation - Detailed documentation
- Few Dependencies - Few dependencies
- Cursor - Cursor (feature `cursor`)
- Moving _n_ times (up, down, left, right) - Move the cursor N times (up, down, left, right)
- Position (set/get) - Set/get the cursor position
- Store cursor position and resetting to that later - Store the cursor position and restore to it later
- Hiding/Showing - Hide/show the cursor
- Blinking Cursor (supported by only some terminals) - Enable/disable cursor blinking (not all terminals do support this feature)
- Styled output - Styled output (feature `style`)
- Foreground Color (16 base colors) - Foreground color (16 base colors)
- Background Color (16 base colors) - Background color (16 base colors)
- 256 (ANSI) Color Support (Windows 10 and UNIX Only) - 256 (ANSI) color support (Windows 10 and UNIX only)
- RGB 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) - Text attributes like bold, italic, underscore, crossed, etc.
- Terminal - Terminal (feature `terminal`)
- Clearing (all lines, current line, from cursor down and up, until new line) - Clear (all lines, current line, from cursor down and up, until new line)
- Scrolling (up, down) - Scroll up, down
- Terminal Size (get/set) - Set/get the terminal size
- Alternate Screen - Exit current process
- Raw Screen - Input (feature `input`)
- Exit Current Process
- Input
- Read character - Read character
- Read line - Read line
- Read key input events (async / sync) - Read key input events (async / sync)
- Read mouse input events (press, release, position, button) - Read mouse input events (press, release, position, button)
- Screen (feature `screen`)
- Alternate screen
- Raw screen
## Examples <!--
WARNING: Do not change following heading title as it's used in the URL by other crates!
-->
These are some basic examples demonstrating how to use this crate. See the ### Tested Terminals
[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
- Windows Powershell - Windows Powershell
- Windows 10 (pro) - Windows 10 (Pro)
- Windows CMD - Windows CMD
- Windows 10 (pro) - Windows 10 (Pro)
- Windows 8.1 (N) - Windows 8.1 (N)
- Ubuntu Desktop Terminal - Ubuntu Desktop Terminal
- Ubuntu 17.10 - Ubuntu 17.10
- (Arch, Manjaro) KDE Konsole - (Arch, Manjaro) KDE Konsole
- Linux Mint - 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 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! issues, then feel free to add it to the above list - I really would appreciate it!
## Getting Started
<details>
<summary>
Click to show Cargo.toml.
</summary>
```toml
[dependencies]
crossterm = "0.11"
```
</details>
<p></p>
```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 ## Contributing
I highly appreciate it when you contribute to this crate. I highly appreciate when anyone contributes to this crate. Before you do, please,
Please visit the discord or issue list for more information read the [Contributing](docs/CONTRIBUTING.md) guidelines.
## Authors ## Authors
@ -335,15 +192,15 @@ Please visit the discord or issue list for more information
## Support ## 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) [![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 ## License
This project, crossterm and all it's sub-modules: crossterm_screen, crossterm_cursor, crossterm_style, 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 `crossterm_input`, `crossterm_terminal`, `crossterm_winapi`, `crossterm_utils` are licensed under the MIT
the [LICENSE](https://github.com/crossterm-rs/crossterm/blob/master/LICENSE) file for details 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 [s1]: https://img.shields.io/crates/v/crossterm.svg
[l1]: https://crates.io/crates/crossterm [l1]: https://crates.io/crates/crossterm

67
docs/CONTRIBUTING.md
View File

@ -2,61 +2,9 @@
I would appreciate any contributions to this crate. However, some things are handy to know. 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 ### Import Order
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
All imports are semantically grouped and ordered. The order is: 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::...`) - current module (`use self::...`)
- module declaration (`mod ...`) - module declaration (`mod ...`)
There must be an empty line between groups. There must be an empty line between groups. An example:
An example:
```rust ```rust
use crossterm_utils::{csi, write_cout, Result}; use crossterm_utils::{csi, write_cout, Result};
@ -79,7 +25,7 @@ use crate::sys::{get_cursor_position, show_cursor};
use super::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 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 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_ -> Second step can be automated via _CLion_ -> _Preferences_ ->
_Languages & Frameworks_ -> _Rust_ -> _Rustfmt_ -> _Run rustfmt on save_. _Languages & Frameworks_ -> _Rust_ -> _Rustfmt_ -> _Run rustfmt on save_.
### Max line length ### Max Line Length
| Type | 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. 120 is because of the GitHub. The editor & viewer width there is +- 123 characters.
###
### Warnings ### Warnings
The code must be warning free. It's quite hard to find an error if the build logs are polluted with 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. 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: Search for `#![deny(...)]` in the code:

4
docs/mdbook/src/SUMMARY.md
View File

@ -1,4 +1,8 @@
# Crossterm # 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. 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, 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. how to read user input and how to make using crossterm easier.

4
docs/mdbook/src/command.md
View File

@ -1,4 +1,8 @@
# Command API # 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 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: The command API offers:

3
docs/mdbook/src/feature_flags.md
View File

@ -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. 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. 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.

3
docs/mdbook/src/input.md
View File

@ -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. 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. 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.

3
docs/mdbook/src/screen.md
View File

@ -1,3 +1,6 @@
> **WARNING**: This book is deprecated, no longer maintained and will be
> removed soon.
## Screen Buffer ## Screen Buffer
A screen buffer is a two-dimensional array of characters and color data to be output in a console window. 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. A terminal can have multiple of those screen buffers, and the active screen buffer is the one that is displayed on the screen.

3
docs/mdbook/src/styling.md
View File

@ -1,5 +1,8 @@
# Styling Module # 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. Crossterm provides options for you to style your text and terminal. Take for example coloring output and applying attributes.
**Color support** **Color support**

78
src/crossterm.rs
View File

@ -1,102 +1,40 @@
use std::fmt::Display; use std::fmt::Display;
/// This type offers an easy way to use functionalities like `cursor`, `terminal`, `color`, `input`, and `styling`. // TODO Should be removed? This adds just another way to achieve the same thing.
/// /// A crossterm functionality wrapper.
/// 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.
pub struct Crossterm; pub struct Crossterm;
impl Crossterm { impl Crossterm {
/// Create a new instance of `Crossterm` /// Creates a new `Crossterm`.
pub fn new() -> Crossterm { pub fn new() -> Crossterm {
Crossterm Crossterm
} }
/// Get a `TerminalCursor` implementation whereon cursor related actions can be performed. /// Crates a new `TerminalCursor`.
///
/// ```rust
/// # use crossterm::*;
/// let crossterm = Crossterm::new();
/// let cursor = crossterm.cursor();
/// ```
#[cfg(feature = "cursor")] #[cfg(feature = "cursor")]
pub fn cursor(&self) -> crossterm_cursor::TerminalCursor { pub fn cursor(&self) -> crossterm_cursor::TerminalCursor {
crossterm_cursor::TerminalCursor::new() crossterm_cursor::TerminalCursor::new()
} }
/// Get a `TerminalInput` implementation whereon terminal related actions can be performed. /// Creates a new `TerminalInput`.
///
/// ```rust
/// # use crossterm::*;
/// let crossterm = Crossterm::new();
/// let input = crossterm.input();
/// ```
#[cfg(feature = "input")] #[cfg(feature = "input")]
pub fn input(&self) -> crossterm_input::TerminalInput { pub fn input(&self) -> crossterm_input::TerminalInput {
crossterm_input::TerminalInput::new() crossterm_input::TerminalInput::new()
} }
/// Get a `Terminal` implementation whereon terminal related actions can be performed. /// Creates a new `Terminal`.
///
/// ```rust
/// # use crossterm::*;
/// let crossterm = Crossterm::new();
/// let mut terminal = crossterm.terminal();
/// ```
#[cfg(feature = "terminal")] #[cfg(feature = "terminal")]
pub fn terminal(&self) -> crossterm_terminal::Terminal { pub fn terminal(&self) -> crossterm_terminal::Terminal {
crossterm_terminal::Terminal::new() crossterm_terminal::Terminal::new()
} }
/// Get a `TerminalColor` implementation whereon color related actions can be performed. /// Creates a new `TerminalColor`.
///
/// ```rust
/// # use crossterm::*;
/// let crossterm = Crossterm::new();
/// let mut terminal = crossterm.color();
/// ```
#[cfg(feature = "style")] #[cfg(feature = "style")]
pub fn color(&self) -> crossterm_style::TerminalColor { pub fn color(&self) -> crossterm_style::TerminalColor {
crossterm_style::TerminalColor::new() crossterm_style::TerminalColor::new()
} }
/// This could be used to style any type implementing `Display` with colors and attributes. /// Creates a new `StyledObject`.
///
/// # 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.
#[cfg(feature = "style")] #[cfg(feature = "style")]
pub fn style<D>(&self, val: D) -> crossterm_style::StyledObject<D> pub fn style<D>(&self, val: D) -> crossterm_style::StyledObject<D>
where where

25
src/lib.rs
View File

@ -1,17 +1,22 @@
//! # Crossterm
//!
//! Have you ever been disappointed when a terminal library for rust was only written for UNIX systems? //! 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. //! Crossterm aims to be simple and easy to call in code. Through the simplicity of Crossterm, you do not
//! Through the simplicity of Crossterm, you do not have to worry about the platform you are working with. //! 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. //! ## Important
//! - [Crossterm Style](https://crates.io/crates/crossterm_style) //!
//! - [Crossterm Input](https://crates.io/crates/crossterm_input) //! This crate re-exports all other `crossterm_*` crates types only. Please, consult the
//! - [Crossterm Screen](https://crates.io/crates/crossterm_screen) //! `crossterm` crate repository [README](https://github.com/crossterm-rs/crossterm/blob/master/README.md) to
//! - [Crossterm Cursor](https://crates.io/crates/crossterm_cursor) //! learn how to use features to enable/disable functionality, what's planned, etc. There will be
//! - [Crossterm Terminal](https://crates.io/crates/crossterm_terminal) //! new code organization, breaking API changes, etc.
#[cfg(feature = "cursor")] #[cfg(feature = "cursor")]
pub use crossterm_cursor::{ pub use crossterm_cursor::{