Skip to content
This repository has been archived by the owner on Oct 22, 2019. It is now read-only.

Sync documentation style #3

Merged
merged 16 commits into from
Sep 30, 2019
Merged

Sync documentation style #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
b394218
Update README.md
zrzka Sep 30, 2019
64625cf
Update Color documentation
zrzka Sep 30, 2019
7bb96b5
Update Attribute documentation
zrzka Sep 30, 2019
110c9bf
Fix heading level
zrzka Sep 30, 2019
669b76d
Update documentation
zrzka Sep 30, 2019
254f71c
Fix test errors
zrzka Sep 30, 2019
ef3ddd2
Fix formatting
zrzka Sep 30, 2019
16e5088
Fix what this crate is about
zrzka Sep 30, 2019
770f455
Remove spaces around /
zrzka Sep 30, 2019
806d9ad
Gets -> Returns
zrzka Sep 30, 2019
3dc5e81
Text -> Content
zrzka Sep 30, 2019
229acd4
Various docstring updates
zrzka Sep 30, 2019
368d19f
Unix -> UNIX
zrzka Sep 30, 2019
30e2aeb
Capitalize headings
zrzka Sep 30, 2019
6702e75
Remove text
zrzka Sep 30, 2019
6001f81
Remove space around /
zrzka Sep 30, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 38 additions & 66 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

# Crossterm Style

This crate allows you to style the terminal cross-platform.
It 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 allows you to work with the terminal colors and text attributes. It supports all UNIX
and Windows terminals down to Windows 7 (not all terminals are tested, see the
[Tested Terminals](https://github.com/crossterm-rs/crossterm/blob/master/README.md#tested-terminals) for more info).

`crossterm_style` is a sub-crate of the [crossterm](https://crates.io/crates/crossterm) crate. You can use it
directly, but it's **highly recommended** to use the [crossterm](https://crates.io/crates/crossterm) crate with
Expand All @@ -19,62 +19,42 @@ for more info).

Issues in this repository are disabled for the same reason. Please, report all issues in the
[crossterm-rs/crossterm](https://github.com/crossterm-rs/crossterm/issues) repository.

## Table of contents:
- [Getting started](#getting-started)
- [Useful links](#useful-links)
- [Features](#features)
- [Examples](#examples)
- [Tested Terminals](#tested-terminals)
- [Authors](#authors)
- [License](#license)

## Getting Started

All examples of how `crossterm_style` works can be found in the [examples](https://github.com/crossterm-rs/examples)
repository. Add the `crossterm_style` package to your `Cargo.toml` file.

```
[dependencies]
crossterm_style = "0.5"
```

And import the `crossterm_style` modules you want to use.

```rust
pub use crossterm_style::{color, style, Attribute, Color, ObjectStyle, StyledObject, TerminalColor, Colorize, Styler};
```

### Useful Links

- [Documentation](https://docs.rs/crossterm_input/)
- [Crates.io](https://crates.io/crates/crossterm_input)
- [Book](https://crossterm-rs.github.io/crossterm/docs/styling.html)
- [Examples](https://github.com/crossterm-rs/examples)

## Features

These are the features of this crate:

- Cross-platform
- Multi-threaded (send, sync)
- Detailed Documentation
- Few Dependencies
- Detailed documentation
- Few dependencies
- 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)
- 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
- [More attributes](https://crossterm-rs.github.io/crossterm/docs/styling.html#attributes) (Windows 10 and UNIX only)

## Getting Started

## Examples
<details>
<summary>
Click to show Cargo.toml.
</summary>

The [examples](https://github.com/crossterm-rs/examples) repository has more complete and verbose examples.
```toml
[dependencies]
# All crossterm features are enabled by default.
crossterm = "0.11"
```

</details>
<p></p>

_style text with attributes_
### Attributes

```rust
use crossterm_style::{Colored, Color, Colorize, Styler, Attribute};
use crossterm::{Colored, Color, Colorize, Styler, Attribute};

// pass any `Attribute` value to the formatting braces.
println!("{} Underlined {} No Underline", Attribute::Underlined, Attribute::NoUnderline);
Expand All @@ -87,10 +67,10 @@ println!("{}", styled_text);
let styled_text = style("Bold Underlined").bold().underlined();
```

_style text with colors_
### Colors

```rust
use crossterm_style::{Colored, Color, Colorize};
use crossterm::{Colored, Color, Colorize};

println!("{} Red foreground color", Colored::Fg(Color::Red));
println!("{} Blue background color", Colored::Bg(Color::Blue));
Expand All @@ -103,9 +83,11 @@ println!("{}", styled_text);
let styled_text = style("Bold Underlined").with(Color::Red).on(Color::Blue);
```

_style text with RGB and ANSI Value_
### RGB Colors and ANSI Values

```rust
use crossterm::{Colored, Color, Colorize};

// custom rgb value (Windows 10 and UNIX systems)
println!("{} some colored text", Colored::Fg(Color::Rgb {
r: 10,
Expand All @@ -117,29 +99,19 @@ println!("{} some colored text", Colored::Fg(Color::Rgb {
println!("{} some colored text", Colored::Fg(Color::AnsiValue(10)));
```

## Tested terminals

- Windows Powershell
- Windows 10 (pro)
- Windows CMD
- Windows 10 (pro)
- Windows 8.1 (N)
- Ubuntu Desktop Terminal
- Ubuntu 17.10
- (Arch, Manjaro) KDE Konsole
- Linux Mint
## Other Resources

This crate supports all Unix terminals and windows terminals down to Windows 7 but not all of them have been tested.
If you have used this library for a terminal other than the above list without issues feel free to add it
to the above list, I really would appreciate it.
- [API documentation](https://docs.rs/crossterm_style/) (with other examples)
- [Examples repository](https://github.com/crossterm-rs/examples)
- [The Book](https://crossterm-rs.github.io/crossterm/docs/index.html)

## Authors

* **Timon Post** - *Project Owner & creator*

## License

This project is licensed under the MIT License - see the [LICENSE.md](./LICENSE) file for details
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details

[s1]: https://img.shields.io/crates/v/crossterm_style.svg
[l1]: https://crates.io/crates/crossterm_style
Expand Down
143 changes: 57 additions & 86 deletions src/enums/attribute.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,36 @@ use serde::{Deserialize, Serialize};

use crate::SetAttr;

/// Enum with the different attributes to style your test.
/// Represents an attribute.
///
/// There are few things to note:
/// - Not all attributes are supported, some of them are only supported on Windows some only on Unix,
/// and some are only very rarely supported.
/// - I got those attributes, descriptions, supportability from here: https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
/// - Take note of the fact that when running your program cross-platform that some attributes might not work because of their support.
/// - When an attribute is not supported nothing will happen with the terminal state.
/// # Platform-specific Notes
///
/// # Example
/// You can use an attribute in a write statement to apply the attribute to the terminal output.
/// * Only UNIX and Windows 10 terminals do support text attributes.
/// * Keep in mind that not all terminals support all attributes.
/// * Crossterm implements almost all attributes listed in the
/// [SGR parameters](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters).
///
/// | Attribute | Windows | UNIX | Notes |
/// | :-- | :--: | :--: | :-- |
/// | `Reset` | ✓ | ✓ | |
/// | `Bold` | ✓ | ✓ | |
/// | `Dim` | ✓ | ✓ | |
/// | `Italic` | ? | ? | Not widely supported, sometimes treated as inverse. |
/// | `Underlined` | ✓ | ✓ | |
/// | `SlowBlink` | ? | ? | Not widely supported, sometimes treated as inverse. |
/// | `RapidBlink` | ? | ? | Not widely supported. MS-DOS ANSI.SYS; 150+ per minute. |
/// | `Reverse` | ✓ | ✓ | |
/// | `Hidden` | ✓ | ✓ | Also known as Conceal. |
/// | `Fraktur` | ✗ | ✓ | Legible characters, but marked for deletion. |
/// | `DefaultForegroundColor` | ? | ? | Implementation specific (according to standard). |
/// | `DefaultBackgroundColor` | ? | ? | Implementation specific (according to standard). |
/// | `Framed` | ? | ? | Not widely supported. |
/// | `Encircled` | ? | ? | This should turn on the encircled attribute. |
/// | `OverLined` | ? | ? | This should draw a line at the top of the text. |
///
/// # Examples
///
/// Basic usage:
///
/// ```no_run
/// use crossterm_style::Attribute;
Expand All @@ -27,7 +46,8 @@ use crate::SetAttr;
/// );
/// ```
///
/// You can also call attribute functions on a `&'static str`:
/// Style existing text:
///
/// ```no_run
/// use crossterm_style::Styler;
///
Expand All @@ -38,104 +58,55 @@ use crate::SetAttr;
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[derive(Copy, Clone, Debug, PartialEq, Eq, Ord, PartialOrd, Hash)]
pub enum Attribute {
/// All attributes off
/// [info]: This will reset all current set attributes.
/// [Supportability]: Windows, UNIX.
/// Resets all the attributes.
Reset = 0,
/// Increased Intensity
/// [info]: This will increase the text sensitivity also known as bold.
/// [Supportability]: Windows, UNIX.
/// Increases the text intensity.
Bold = 1,
/// Decreased Intensity
/// [info]: This will decrease the text sensitivity also known as bold.
/// [Supportability]: Windows, UNIX.
/// Decreases the text intensity.
Dim = 2,
/// Italic Text
/// [info]: This will make the text italic.
/// [Supportability]: Not widely supported, sometimes treated as inverse.
/// Emphasises the text.
Italic = 3,
/// This will draw a line under the text.
/// [info]: An line under a word, especially in order to show its importance.
/// [Supportability]: Windows, UNIX
/// Underlines the text.
Underlined = 4,
/// Slow Blinking Text
/// [info]: Blink Less than 150 per minute.
/// [Supportability]: UNIX
/// Makes the text blinking (< 150 per minute).
SlowBlink = 5,
/// Slow Blinking Text
/// [info]: MS-DOS ANSI.SYS; 150+ per minute;
/// [Supportability]: Not widely supported
/// Makes the text blinking (>= 150 per minute).
RapidBlink = 6,
/// Swap foreground and background colors
/// [info]: swap foreground and background colors
/// [Supportability]: Windows, UNIX
/// Swaps foreground and background colors.
Reverse = 7,
/// Hide text
/// [info]:
/// - This will make the text hidden.
/// - Also known as 'Conceal'
/// [Supportability]: Windows, UNIX
/// Hides the text (also known as Conceal).
Hidden = 8,
/// Cross-out text
/// [info]: Characters legible, but marked for deletion.
/// [Supportability]: UNIX
/// Crosses the text.
CrossedOut = 9,
/// The Fraktur is a typeface belonging to the group of Gothic typefaces.
/// [info]: https://nl.wikipedia.org/wiki/Fraktur
/// [Supportability]: Rarely supported
/// Sets the [Fraktur](https://en.wikipedia.org/wiki/Fraktur) typeface.
///
/// Mostly used for [mathematical alphanumeric symbols](https://en.wikipedia.org/wiki/Mathematical_Alphanumeric_Symbols).
Fraktur = 20,
/// This will turn off the bold attribute.
/// [info]:
/// - Double-underline per ECMA-48.
/// - WikiPedia: https://en.wikipedia.org/wiki/Talk:ANSI_escape_code#SGR_21%E2%80%94%60Bold_off%60_not_widely_supported
/// - Opposite of `Bold`(1)
/// [Supportability]: not widely supported
/// Turns off the `Bold` attribute.
NoBold = 21,
/// Normal color or intensity
/// Neither bold nor faint
/// Switches the text back to normal intensity (no bold, italic).
NormalIntensity = 22,
/// This will turn off the italic attribute.
/// [info]:
/// - Not italic, not Fraktur
/// - Opposite of `Italic`(3)
/// [Supportability]: Windows, UNIX
/// Turns off the `Italic` attribute.
NoItalic = 23,
/// This will turn off the underline attribute.
/// [info]:
/// - Not singly or doubly underlined will be turned off.
/// - Opposite of `Underlined.`(4)
/// [Supportability]: Windows, UNIX
/// Turns off the `Underlined` attribute.
NoUnderline = 24,
/// This will turn off the blinking attribute
/// [info]: Opposite of `Slow and Rapid blink.`(5,6)
/// [Supportability]: Unknown
/// Turns off the text blinking (`SlowBlink` or `RapidBlink`).
NoBlink = 25,
/// This will turn off the reverse attribute.
/// [info]: Opposite of `Reverse`(7)
/// [Supportability]: Windows, unknown
NoInverse = 27,
/// This will make the text visible.
/// [info]: Opposite of `Hidden`(8)
/// [Supportability]: Unknown
/// Turns off the `Reverse` attribute.
NoInverse = 27, // TODO Shouldn't we rename this to `NoReverse`? Or `Reverse` to `Inverse`?
/// Turns off the `Hidden` attribute.
NoHidden = 28,
/// This will turn off the crossed out attribute.
/// [info]: Opposite of `CrossedOut`(9)
/// [Supportability]: Not widely supported
/// Turns off the `CrossedOut` attribute.
NotCrossedOut = 29,
/// Framed text.
/// [Supportability]: Not widely supported
/// Makes the text framed.
Framed = 51,
/// This will turn on the encircled attribute.
/// Makes the text encircled.
Encircled = 52,
/// This will draw a line at the top of the text.
/// [info]: Implementation defined (according to standard)
/// [Supportability]: Unknown
/// Draws a line at the top of the text.
OverLined = 53,
/// This will turn off the framed or encircled attribute.
/// Turns off the `Frame` and `Encircled` attributes.
NotFramedOrEncircled = 54,
/// This will turn off the overLined attribute.
/// [info]: Opposite of `OverLined`(7)
/// [Supportability]: Windows, unknown
/// Turns off the `OverLined` attribute.
NotOverLined = 55,

#[doc(hidden)]
Expand Down
Loading