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

Commit

Permalink
Sync documentation style
Browse files Browse the repository at this point in the history
  • Loading branch information
@TimonPost
TimonPost authored Sep 30, 2019
2 parents 5386732 + 6001f81 commit 43552a1
Show file tree
Hide file tree
Showing 8 changed files with 334 additions and 377 deletions.
104 changes: 38 additions & 66 deletions README.md
View file
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
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

0 comments on commit 43552a1

Please sign in to comment.