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

Remove the crossterm book

Browse Source 
Signed-off-by: Robert Vojta <rvojta@me.com>
This commit is contained in:
Robert Vojta 2019-10-02 11:52:27 +02:00
parent 5a32fb3f78
commit 196ba589d6
No known key found for this signature in database
GPG Key ID: 082AAEA8854E3D88
8 changed files with 2 additions and 566 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGELOG.md
View File

@ -1,8 +1,9 @@
# Version master # Version master
- Removed book link
- Deprecated warning about `crossterm_*` crates - Deprecated warning about `crossterm_*` crates
- Documentation improved - Documentation improved
- Remove all references to the crossterm book
- Remove the crossterm book
# Version 0.11.1 # Version 0.11.1

4
docs/mdbook/book.toml
View File

@ -1,4 +0,0 @@
[book]
authors = ["T. Post"]
multilingual = false
src = "src"

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

@ -1,14 +0,0 @@
# 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.
- [Feature Flags](feature_flags.md)
- [Command API](command.md)
- [Styling Output](styling.md)
- [Reading Input Events](input.md)
- [Alternate, Raw Screen](screen.md)

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

@ -1,168 +0,0 @@
# 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:
- 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:
- By using functions
The 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.
- By using macros
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.
## Commands
Crossterm provides the following commands that can be used to perform actions with:
_cursor commands_
- Goto (x, y)
- UP (number of time)
- Down (number of time)
- Left (number of time)
- Right (number of time)
- SavePos
- ResetPos
- Hide
- Show
- Blink On
- Blink Off
_style commands_
- SetFg (Color)
- SetBg (Color)
- SetAttr (attr)
- Print Styled Text (text)
_terminal command_
- Clear (ClearType)
- Scroll Up (number of time)
- Scroll Down (number of time)
- SetSize (width, height)
_other_
- Output (text)
Each crossterm crate provides its command when using crossterm you can use them all at once.
When using a single crate or a feature flag, you can only use certain commands.
Before crossterm 10.0 was released, crossterm had some performance issues. It did a `flush` after each command (cursor movement).
A `flush` is heavy action on the terminal, and if it is done more often the performance will go down quickly.
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.
### Imports
```rust
use crossterm::{execute, queue, ExecutableCommand, QueueableCommand};
```
### Lazy Execution
Because `flush` is a heavy system call we can instead `write` the commands to the `stdout` without flushing.
When can do a `flush` we do want to execute the commands.
If you create a terminal editor or TUI, it is wise to use this option.
For example, you can write commands to the terminal `stdout` and flush the `stdout` at every frame.
By doing this you can make efficient use of the terminal buffer and get better performance because you are not calling `flush` after every command.
#### Examples
_functions_
```rust
let mut stdout = stdout();
stdout.queue(Goto(5,5))?;
// some other code ...
stdout.flush();
```
The `queue` function returns itself, therefore you can use this to queue another command.
Like `stdout.queue(Goto(5,5)).queue(Clear(ClearType::All))`
_macro's_
```rust
let mut stdout = stdout();
queue!(stdout, Goto(5, 5));
// some other code ...
// flush when you want to execute the 'queued' commands
stdout.flush();
```
You can pass more than one command into the macro like: `queue!(stdout, Goto(5, 5), Clear(ClearType::All));`; they will be executed in the given order from left to right.
### Direct Execution
If you want to execute commands directly, this is also possible. You don't have to flush the 'stdout', as described above.
This is fine if you are not executing lots of commands.
_functions_
```rust
stdout().execute(Goto(5,5))?;
```
The `execute` function returns it self, therefore you are able to use this to execute another command
like `stdout.execute(Goto(5,5))?.execute(Clear(ClearType::All))?`
_macro's_
```rust
execute!(stdout, Goto(5, 5));
```
You can pass more than one command into the macro like: `queue!(stdout, Goto(5, 5), Clear(ClearType::All));`; they will be executed in the given order from left to right.
## Short Examples
Print a rectangle colored with magenta and use both direct execution and lazy execution.
_rectangle with command functions_
```rust
use crossterm::{ExecutableCommand, QueueableCommand, Color, PrintStyledFont, Colorize};
use std::io::stdout();
let mut stdout = stdout();
stdout.execute(Clear(ClearType::All))?;
for y in 0..40 {
for x in 0..150 {
if (y == 0 || y == 40 - 1) || (x == 0 || x == 150 - 1) {
stdout
.queue(Goto(x,y))?
.queue(PrintStyledFont( "█".magenta()))?;
}
}
stdout.flush();
}
```
_rectangle with the macros_
```rust
use crossterm::{execute, queue, Color, PrintStyledFont, Colorize};
use std::io::stdout();
let mut stdout = stdout();
execute!(stdout, Clear(ClearType::All));
for y in 0..40 {
for x in 0..150 {
if (y == 0 || y == 40 - 1) || (x == 0 || x == 150 - 1) {
queue!(stdout, Goto(x,y), PrintStyledFont( "█".magenta()));
}
}
stdout.flush();
}
```

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

@ -1,44 +0,0 @@
> **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.
Crossterm provides the following feature flags:
- input ; reading input events
- terminal ; terminal actions like resizing
- style ; styling of the terminal
- cursor ; moving the terminal cursor
- screen ; alternate and raw screen
By default, all of those will be enabled.
_Cargo.toml_
```
[dependencies]
crossterm = { version="0.9", default-features = false, features = ["screen", "terminal", "cursor", "style", "input"] }
```
By default all flags are enabled, the types and functions available to use depend on the specified flags.
```rust
"cursor" => cursor, BlinkOff, BlinkOn, Down, Goto, Hide, Left, ResetPos, Right, SavePos, Show, TerminalCursor, Up,
"input" => input, AsyncReader, InputEvent, KeyEvent, MouseButton, MouseEvent, SyncReader, TerminalInput
"screen" => AlternateScreen, IntoRawMode, RawScreen
"style" => style, Attribute, Color, Colored, Colorize, ObjectStyle, StyledObject, Styler, color, PrintStyledFont, SetAttr, SetBg, SetFg, TerminalColor
"terminal" => terminal, Clear, ClearType, ScrollDown, ScrollUp, SetSize, Terminal
```
All modules export types for the ability to use the command api, those are: `execute, queue, Command, ExecutableCommand, QueueableCommand`
You can also use all the crossterm modules individually by directly referencing the crate.
- [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)

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

@ -1,134 +0,0 @@
> **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.
## Differences Synchronous and Asynchronous
Crossterm provides two ways to read user input, synchronous and asynchronous.
### Synchronous reading
Read the input synchronously from the user, the reads performed will be blocking calls.
Using synchronous over asynchronous reading has the benefit that it is using fewer resources than the asynchronous because background thread and queues are left away.
You can get asynchronous event reader by calling: `TerminalInput::read_sync`.
### Asynchronous reading
Read the input asynchronously, input events are gathered in the background and will be queued for you to read.
Using asynchronous reading has the benefit that input events are queued until you read them. You can poll for occurred events, and the reads won't block your program.
You can get a synchronous event reader by calling: `TerminalInput::read_async`, `TerminalInput::read_async_until`.
### Technical details
On UNIX systems crossterm reads from the TTY, on Windows, it uses `ReadConsoleInputW`.
For asynchronous reading, a background thread will be fired up to read input events,
occurred events will be queued on an MPSC-channel, and the user can iterate over those events.
The terminal has to be in raw mode, raw mode prevents the input of the user to be displayed on the terminal screen, see [screen](./screen.md) for more info.
# Example
In the following example, we will create a small program that will listen for mouse and keyboard input.
On the press of the 'escape' key, the program will be stopped.
So let's start by setting up the basics.
```
use std::{thread, time::Duration};
use crossterm::{input, InputEvent, KeyEvent};
fn main() {
println!("Press 'ESC' to quit.");
/* next code here */
}
```
Next, we need to put the terminal into raw mode. We do this because we don't want the user input to be printed to the terminal screen.
```rust
// enable raw mode
let screen = RawScreen::into_raw_mode();
// create a input from our screen
let input = input();
/* next code here */
```
Now that we constructed a `TerminalInput` instance we can go ahead an start the reading.
Do this by calling `input.read_async()`, which returns an [AsyncReader](https://docs.rs/crossterm/0.8.0/crossterm/struct.AsyncReader.html).
This is an iterator over the input events that you could as any other iterator.
```rust
let mut async_stdin = input.read_async();
loop {
if let Some(key_event) = async_stdin.next() {
/* next code here */
}
thread::sleep(Duration::from_millis(50));
}
```
The [AsyncReader](https://docs.rs/crossterm/0.8.0/crossterm/struct.AsyncReader.html) iterator will return `None` when nothing is there to read, `Some(InputEvent)` if there are events to read.
I use a thread delay to prevent spamming the iterator.
Next up we can start pattern matching to see if there are input events we'd like to catch.
In our case, we want to catch the `Escape Key`.
```rust
match key_event {
InputEvent::Keyboard(event) => match event {
KeyEvent::Esc => {
println!("Program closing ...");
break
}
_ => println!("Key {:?} was pressed!", event)
}
InputEvent::Mouse(event) => { /* Mouse Event */ }
_ => { }
}
```
As you see, we check if the `KeyEvent::Esc` was pressed, if that's true we stop the program by breaking out of the loop.
_final code_
```rust
use std::{thread, time::Duration};
use crossterm::{input, InputEvent, KeyEvent, RawScreen};
fn main() {
println!("Press 'ESC' to quit.");
// enable raw mode
let screen = RawScreen::into_raw_mode();
// create a input from our screen.
let input = input();
// create async reader
let mut async_stdin = input.read_async();
loop {
// try to get the next input event.
if let Some(key_event) = async_stdin.next() {
match key_event {
InputEvent::Keyboard(event) => match event {
KeyEvent::Esc => {
println!("Program closing ...");
break
}
_ => println!("Key {:?} was pressed!", event)
}
InputEvent::Mouse(event) => { /* Mouse Event */ }
_ => { }
}
}
thread::sleep(Duration::from_millis(50));
}
} // <=== background reader will be disposed when dropped.s
```
---------------------------------------------------------------------------------------------------------------------------------------------
More robust and complete examples on all input aspects like mouse, keys could be found [here](https://github.com/crossterm-rs/crossterm/tree/master/examples/).

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

@ -1,46 +0,0 @@
> **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.
Crossterm allows you to switch between those buffers; the screen you are working in is called the 'main screen'. We call the other screen the 'alternate screen'.
One note to take is that crossterm does not support the creation and switching between several buffers.
### Alternate Screen
Normally you are working on the main screen but an alternate screen is somewhat different from a normal screen.
For example, it has the exact dimensions of the terminal window, without any scrollback region. An example of this is vim when it is launched from bash.
Vim uses the entirety of the screen to edit the file, then exits to bash leaving the original buffer unchanged.
Crossterm provides the ability to switch to the alternate screen, make some changes, and then go back to the main screen.
The main screen will still have its original data since we made all the edits on the alternate screen.
## Raw screen
To understand the concept of a 'raw screen' let's look at the following points:
**No line buffering.**
Normally the terminals use line buffering. This means that the input will be sent to the terminal line by line. With raw mode, the input will send one byte at a time.
**Input**
All input has to be written to the screen buffer manually by the programmer.
**Characters**
The characters are not processed by the terminal driver. Also, special character has no meaning. For example, backspace will not be interpreted as backspace but instead will be sent directly to the terminal.
**Escape Characters**
Note that in raw mode `\n` `\r` will move the cursor to a new line but it will be at the same position as it was on the previous line.
_example of what I mean_
```
some text
some text
```
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/).

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

@ -1,155 +0,0 @@
# 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**
Windows systems with versions less than 10 will only have support for 16 colors and don't have any support for attributes. Most UNIX-terminal is supporting lots of colors and attributes.
## Colors
There are 16 base colors which available for almost all terminals even windows 7 and 8.
| Light Variant | Dark Variant |
| :-------------| :------------- |
| Grey | Black |
| Red | DarkRed |
| Green | DarkGreen |
| Yellow | DarkYellow |
| Blue | DarkBlue |
| Magenta | DarkMagenta|
| Cyan | DarkCyan |
| White | DarkWhite |
In addition to 16 colors, most UNIX terminals and Windows 10 consoles are also supporting more colors.
Those colors could be: [True color (24-bit)](https://en.wikipedia.org/wiki/Color_depth#True_color_(24-bit)) coloring scheme, which allows you to use [RGB](https://nl.wikipedia.org/wiki/RGB-kleursysteem), and [256 (Xterm, 8-bit)](https://jonasjacek.github.io/colors/) colors.
Checkout the [examples](https://github.com/crossterm-rs/crossterm/blob/master/examples/style.rs) on how to use this feature.
## Attributes
Only UNIX and Windows 10 terminals are supporting attributes on top of the text. Crossterm allows you to add attributes to the text.
Not all attributes are widely supported for all terminals, keep that in mind when working with this.
Crossterm implements almost all attributes shown in this [Wikipedia-list](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters).
| Attribute | Support | Note |
| :-------------: | :-------------: | :-------------: |
| Reset | Windows, UNIX | This will reset all current set attributes. |
| Bold | Windows, UNIX | This will increase the text sensitivity also known as bold. |
| Dim | Windows, UNIX | This will decrease the text sensitivity also known as bold. |
| Italic | Not widely supported, sometimes treated as inverse. | This will make the text italic. |
| Underlined | Windows, UNIX | A line under a word, especially in order to show its importance. |
| SlowBlink | Not widely supported, sometimes treated as inverse. | less than 150 per minute |
| RapidBlink | Not widely supported | MS-DOS ANSI.SYS; 150+ per minute; |
| Reverse | Windows, UNIX | foreground and background colors |
| Hidden | Windows, UNIX | | Also known as 'Conceal'
| Fraktur | UNIX | characters legible, but marked for deletion. |
| DefaultForegroundColor | Unknown | Implementation defined (according to standard) |
| DefaultBackgroundColor | Unknown | Implementation defined (according to standard) |
| Framed | Not widely supported | Framed text.
| Encircled | Unknown | This will turn on the encircled attribute. |
| OverLined | Unknown | This will draw a line at the top of the text. |
(There are a few attributes who disable one of the above attributes, I did not write those down to keep the list short).
Now we have covered the basics of styling lets go over to some examples.
# Example
_setup the basics_
```rust
use crossterm::{Colored, Color, Attribute, Styler, Colorize};
fn main() {
/* your code here */
}
```
There are a couple of ways to style the terminal output with crossterm. The most important part of the styling module is `StyledObject`.
A `StyledObject` is just a wrapper crossterm uses to store the text and style together.
A `StyledObject` implements `Display` and thus you could use it inside `print!`, `println!` etc.
Without further ado let's get straight into it.
## Coloring
There are a few ways to do the coloring, the first one is by using the `Colored` enum.
### Using Enum
```rust
println!("{} Red foreground color", Colored::Fg(Color::Red));
println!("{} Blue background color", Colored::Bg(Color::Blue));
```
`Colored::Bg` will set the background color, and `Colored::Fg` will set the foreground color to the provided color.
The provided color is of type `Color` and has a bunch of enum values you could choose out.
Because `Colored` implements `Display` you are able to use it inside any write statement.
### Using Methods
You can do the same as the above in a slightly different way. Instead of enabling it for all text you could also color the only piece of text.
(Make sure to include the `crossterm::Coloring` trait).
```rust
let styled_text = "Red forground color on blue background.".red().on_blue();
println!("{}", styled_text);
```
As you see in the above example you could call coloring methods on a string. How is this possible you might ask..?
Well, the trait `Coloring`, who you need to include, is implemented for `&'static str`.
When calling a method on this string crossterm transforms it into a `StyledObject` who you could use in your write statements.
### RGB
Most UNIX terminals and all Windows 10 consoles are supporting [True color(24-bit)](https://en.wikipedia.org/wiki/Color_depth#True_color_(24-bit)) coloring scheme.
You can set the color of the terminal by using `Color::RGB(r,g,b)`.
```
// custom rgb value (Windows 10 and UNIX systems)
println!("{}{} 'Light green' text on 'Black' background", Colored::Fg(Color::Rgb { r: 0, g: 255, b: 128 }), Colored::Bg(Color::Rgb {r: 0, g: 0, b: 0}));
```
This will print some light green text on black background.
### Custom ANSI color value
When working on UNIX or Windows 10 you could also specify a custom ANSI value ranging up from 0 to 256.
See [256 (Xterm, 8-bit) colors](https://jonasjacek.github.io/colors/) for more information.
```
// custom ansi color value (Windows 10 and UNIX systems)
println!("{} some colored text", Colored::Fg(Color::AnsiValue(10)));
```
## Attributes
When working with UNIX or Windows 10 terminals you could also use attributes to style your text. For example, you could cross your text with a line and make it bold.
See [this](styling.md#Attributes) for more information.
### Using Enum
You could use the `Attribute` enum for styling text with attributes.
`Attribute` implements `Display`, thus crossterm will enable the attribute style when using it in any writing operation.
```
println!(
"{} Underlined {} No Underline",
Attribute::Underlined,
Attribute::NoUnderline
);
```
### Using Method
You can do the same as the above in a slightly different way. Instead of enabling it for all text you could also style only one piece of text.
(Make sure to include the `crossterm::Styler` trait).
```
println!("{}", "Bold text".bold();
println!("{}", "Underlined text".underlined();
println!("{}", "Negative text".negative();
```
As you see in the above example you could call attributes methods on a string. How is this possible you might ask..?
Well, the trait `Styling`, who you need to include, is implemented for `&'static str`.
When calling a method on any string crossterm transforms will transform it into a `StyledObject` who you could use in your write statements.
---------------------------------------------------------------------------------------------------------------------------------------------
More examples could be found at this [link](https://github.com/crossterm-rs/crossterm/blob/master/examples/style.rs).