vendor/nu-ansi-term/README.md

   1 # nu-ansi-term
   2
   3 > This is a copy of rust-ansi-term but with Color change to Color and light foreground colors added (90-97) as well as light background colors added (100-107).
   4
   5 This is a library for controlling colors and formatting, such as red bold text or blue underlined text, on ANSI terminals.
   6
   7 ## [View the Rustdoc](https://docs.rs/nu_ansi_term/)
   8
   9 ## Installation
  10
  11 This crate works with [Cargo](http://crates.io). Add the following to your `Cargo.toml` dependencies section:
  12
  13 ```toml
  14 [dependencies]
  15 nu_ansi_term = "0.46"
  16 ```
  17
  18 ## Basic usage
  19
  20 There are three main types in this crate that you need to be concerned with: `AnsiString`, `Style`, and `Color`.
  21
  22 A `Style` holds stylistic information: foreground and background colors, whether the text should be bold, or blinking, or other properties.
  23 The `Color` enum represents the available colors.
  24 And an `AnsiString` is a string paired with a `Style`.
  25
  26 `Color` is also available as an alias to `Color`.
  27
  28 To format a string, call the `paint` method on a `Style` or a `Color`, passing in the string you want to format as the argument.
  29 For example, here’s how to get some red text:
  30
  31 ```rust
  32 use nu_ansi_term::Color::Red;
  33
  34 println!("This is in red: {}", Red.paint("a red string"));
  35 ```
  36
  37 It’s important to note that the `paint` method does _not_ actually return a string with the ANSI control characters surrounding it.
  38 Instead, it returns an `AnsiString` value that has a `Display` implementation that, when formatted, returns the characters.
  39 This allows strings to be printed with a minimum of `String` allocations being performed behind the scenes.
  40
  41 If you _do_ want to get at the escape codes, then you can convert the `AnsiString` to a string as you would any other `Display` value:
  42
  43 ```rust
  44 use nu_ansi_term::Color::Red;
  45
  46 let red_string = Red.paint("a red string").to_string();
  47 ```
  48
  49 **Note for Windows 10 users:** On Windows 10, the application must enable ANSI support first:
  50
  51 ```rust,ignore
  52 let enabled = nu_ansi_term::enable_ansi_support();
  53 ```
  54
  55 ## Bold, underline, background, and other styles
  56
  57 For anything more complex than plain foreground color changes, you need to construct `Style` values themselves, rather than beginning with a `Color`.
  58 You can do this by chaining methods based on a new `Style`, created with `Style::new()`.
  59 Each method creates a new style that has that specific property set.
  60 For example:
  61
  62 ```rust
  63 use nu_ansi_term::Style;
  64
  65 println!("How about some {} and {}?",
  66          Style::new().bold().paint("bold"),
  67          Style::new().underline().paint("underline"));
  68 ```
  69
  70 For brevity, these methods have also been implemented for `Color` values, so you can give your styles a foreground color without having to begin with an empty `Style` value:
  71
  72 ```rust
  73 use nu_ansi_term::Color::{Blue, Yellow};
  74
  75 println!("Demonstrating {} and {}!",
  76          Blue.bold().paint("blue bold"),
  77          Yellow.underline().paint("yellow underline"));
  78
  79 println!("Yellow on blue: {}", Yellow.on(Blue).paint("wow!"));
  80 ```
  81
  82 The complete list of styles you can use are:
  83 `bold`, `dimmed`, `italic`, `underline`, `blink`, `reverse`, `hidden`, and `on` for background colors.
  84
  85 In some cases, you may find it easier to change the foreground on an existing `Style` rather than starting from the appropriate `Color`.
  86 You can do this using the `fg` method:
  87
  88 ```rust
  89 use nu_ansi_term::Style;
  90 use nu_ansi_term::Color::{Blue, Cyan, Yellow};
  91
  92 println!("Yellow on blue: {}", Style::new().on(Blue).fg(Yellow).paint("yow!"));
  93 println!("Also yellow on blue: {}", Cyan.on(Blue).fg(Yellow).paint("zow!"));
  94 ```
  95
  96 You can turn a `Color` into a `Style` with the `normal` method.
  97 This will produce the exact same `AnsiString` as if you just used the `paint` method on the `Color` directly, but it’s useful in certain cases: for example, you may have a method that returns `Styles`, and need to represent both the “red bold” and “red, but not bold” styles with values of the same type. The `Style` struct also has a `Default` implementation if you want to have a style with _nothing_ set.
  98
  99 ```rust
 100 use nu_ansi_term::Style;
 101 use nu_ansi_term::Color::Red;
 102
 103 Red.normal().paint("yet another red string");
 104 Style::default().paint("a completely regular string");
 105 ```
 106
 107 ## Extended colors
 108
 109 You can access the extended range of 256 colors by using the `Color::Fixed` variant, which takes an argument of the color number to use.
 110 This can be included wherever you would use a `Color`:
 111
 112 ```rust
 113 use nu_ansi_term::Color::Fixed;
 114
 115 Fixed(134).paint("A sort of light purple");
 116 Fixed(221).on(Fixed(124)).paint("Mustard in the ketchup");
 117 ```
 118
 119 The first sixteen of these values are the same as the normal and bold standard color variants.
 120 There’s nothing stopping you from using these as `Fixed` colors instead, but there’s nothing to be gained by doing so either.
 121
 122 You can also access full 24-bit color by using the `Color::RGB` variant, which takes separate `u8` arguments for red, green, and blue:
 123
 124 ```rust
 125 use nu_ansi_term::Color::RGB;
 126
 127 RGB(70, 130, 180).paint("Steel blue");
 128 ```
 129
 130 ## Combining successive coloured strings
 131
 132 The benefit of writing ANSI escape codes to the terminal is that they _stack_: you do not need to end every coloured string with a reset code if the text that follows it is of a similar style.
 133 For example, if you want to have some blue text followed by some blue bold text, it’s possible to send the ANSI code for blue, followed by the ANSI code for bold, and finishing with a reset code without having to have an extra one between the two strings.
 134
 135 This crate can optimise the ANSI codes that get printed in situations like this, making life easier for your terminal renderer.
 136 The `AnsiStrings` struct takes a slice of several `AnsiString` values, and will iterate over each of them, printing only the codes for the styles that need to be updated as part of its formatting routine.
 137
 138 The following code snippet uses this to enclose a binary number displayed in red bold text inside some red, but not bold, brackets:
 139
 140 ```rust
 141 use nu_ansi_term::Color::Red;
 142 use nu_ansi_term::{AnsiString, AnsiStrings};
 143
 144 let some_value = format!("{:b}", 42);
 145 let strings: &[AnsiString<'static>] = &[
 146     Red.paint("["),
 147     Red.bold().paint(some_value),
 148     Red.paint("]"),
 149 ];
 150
 151 println!("Value: {}", AnsiStrings(strings));
 152 ```
 153
 154 There are several things to note here.
 155 Firstly, the `paint` method can take _either_ an owned `String` or a borrowed `&str`.
 156 Internally, an `AnsiString` holds a copy-on-write (`Cow`) string value to deal with both owned and borrowed strings at the same time.
 157 This is used here to display a `String`, the result of the `format!` call, using the same mechanism as some statically-available `&str` slices.
 158 Secondly, that the `AnsiStrings` value works in the same way as its singular counterpart, with a `Display` implementation that only performs the formatting when required.
 159
 160 ## Byte strings
 161
 162 This library also supports formatting `[u8]` byte strings; this supports applications working with text in an unknown encoding.
 163 `Style` and `Color` support painting `[u8]` values, resulting in an `AnsiByteString`.
 164 This type does not implement `Display`, as it may not contain UTF-8, but it does provide a method `write_to` to write the result to any value that implements `Write`:
 165
 166 ```rust
 167 use nu_ansi_term::Color::Green;
 168
 169 Green.paint("user data".as_bytes()).write_to(&mut std::io::stdout()).unwrap();
 170 ```
 171
 172 Similarly, the type `AnsiByteStrings` supports writing a list of `AnsiByteString` values with minimal escape sequences:
 173
 174 ```rust
 175 use nu_ansi_term::Color::Green;
 176 use nu_ansi_term::AnsiByteStrings;
 177
 178 AnsiByteStrings(&[
 179     Green.paint("user data 1\n".as_bytes()),
 180     Green.bold().paint("user data 2\n".as_bytes()),
 181 ]).write_to(&mut std::io::stdout()).unwrap();
 182 ```