1# Colored
2
3[![Build
4Status](https://travis-ci.org/mackwic/colored.svg?branch=master)](https://travis-ci.org/mackwic/colored) [![Crates.io](https://img.shields.io/crates/v/colored.svg?maxAge=2592000)](https://crates.io/crates/colored) [![Crates.io](https://img.shields.io/crates/l/colored.svg?maxAge=2592000)](https://github.com/mackwic/colored/blob/master/LICENSE)
5
6Coloring terminal so simple, you already know how to do it!
7
8```rust
9    "this is blue".blue();
10    "this is red".red();
11    "this is red on blue".red().on_blue();
12    "this is also red on blue".on_blue().red();
13    "bright colors are welcome as well".on_bright_blue().bright_red();
14    "you can also make bold comments".bold();
15    println!("{} {} {}", "or use".cyan(), "any".italic().yellow(), "string type".cyan());
16    "or change advice. This is red".yellow().blue().red();
17    "or clear things up. This is default color and style".red().bold().clear();
18    "purple and magenta are the same".purple().magenta();
19    "and so are normal and clear".normal().clear();
20    "you can specify color by string".color("blue").on_color("red");
21    String::from("this also works!").green().bold();
22    format!("{:30}", "format works as expected. This will be padded".blue());
23    format!("{:.3}", "and this will be green but truncated to 3 chars".green());
24```
25
26## How to use
27
28Add this in your `Cargo.toml`:
29
30```toml
31[dependencies]
32colored = "1.9"
33```
34
35and add this to your `lib.rs` or `main.rs`:
36
37```rust
38    extern crate colored; // not needed in Rust 2018
39
40    use colored::*;
41
42    // test the example with `cargo run --example most_simple`
43    fn main() {
44        // TADAA!
45        println!("{} {} !", "it".green(), "works".blue().bold());
46    }
47```
48
49## Features
50
51- Safe rust, easy to use, minimal dependencies, complete test suite
52- Respect the `CLICOLOR`/`CLICOLOR_FORCE` behavior (see [the specs](http://bixense.com/clicolors/))
53- Respect the `NO_COLOR` behavior (see [the specs](https://no-color.org/))
54- Works on Linux, MacOS, and Windows (Powershell)
55
56#### Colors:
57
58- black
59- red
60- green
61- yellow
62- blue
63- magenta (or purple)
64- cyan
65- white
66
67Bright colors: prepend the color by `bright_`. So easy.
68Background colors: prepend the color by `on_`. Simple as that.
69Bright Background colors: prepend the color by `on_bright_`. Not hard at all.
70
71#### Styles:
72
73- bold
74- underline
75- italic
76- dimmed
77- reversed
78- blink
79- hidden
80- strikethrough
81
82You can clear color _and_ style anytime by using `normal()` or `clear()`
83
84#### Advanced Control:
85
86##### Dynamic color from str
87
88As `Color` implements `FromStr`, `From<&str>`, and `From<String>`, you can easily cast a string into a color like that:
89
90```rust
91// the easy way
92"blue string yo".color("blue");
93
94// this will default to white
95"white string".color("zorglub");
96
97// the safer way via a Result
98let color_res : Result<Color, ()> = "zorglub".parse();
99"red string".color(color_res.unwrap_or(Color::Red));
100```
101
102
103##### Colorization control
104
105If you want to disable any coloring at compile time, you can simply do so by
106using the `no-color` feature.
107
108For example, you can do this in your `Cargo.toml` to disable color in tests:
109
110```toml
111[features]
112# this effectively enable the feature `no-color` of colored when testing with
113# `cargo test --feature dumb_terminal`
114dumb_terminal = ["colored/no-color"]
115```
116
117You can use have even finer control by using the
118`colored::control::set_override` method.
119
120## Build with Docker
121
122### Install Docker
123
124Use the install instructions located [here](https://docs.docker.com/v17.12/install/)
125
126### Build the Docker image
127
128```docker build -t colored_image .```
129
130### Build the library
131
132```docker run --rm -it -v "$PWD":/src -u `id -u`:`id -g` colored_image /bin/bash -c "cargo build"```
133
134### Test the library
135
136```docker run --rm -it -v "$PWD":/src -u `id -u`:`id -g` colored_image /bin/bash -c "cargo test"```
137
138
139## Todo
140
141- **More tests ?**: We always welcome more tests! Please contribute!
142
143## Credits
144
145This library wouldn't have been the same without the marvelous ruby gem [colored](https://github.com/defunkt/colored).
146
147Thanks for the [ansi\_term crate](https://github.com/ogham/rust-ansi-term) for
148providing a reference implementation, which greatly helped making this crate
149output correct strings.
150
151## License
152
153[Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/2.0/). See the
154[LICENSE](https://github.com/mackwic/colored/blob/master/LICENSE) file at the
155root of the repository.
156
157In non legal terms it means that:
158- if you fix a bug, you MUST give me the code of the fix (it's only fair)
159- if you change/extend the API, you MUST give me the code you changed in the
160  files under MPL2.
161- you CAN'T sue me for anything about this code
162- apart from that, you can do almost whatever you want. See the LICENSE file
163  for details.
164
165## Contributors
166
167- Thomas Wickham: [@mackwic](https://github.com/mackwic)
168- Corey "See More" Richardson: [@cmr](https://github.com/cmr)
169- Iban Eguia: [@Razican](https://github.com/Razican)
170- Alexis "Horgix" Chotard: [@horgix](https://github.com/horgix)
171- Keith Yeung: [@KiChjang](https://github.com/KiChjang)
172- Kyle Galloway: [@kylegalloway](https://github.com/kylegalloway)
173- Luke Hsiao: [@lukehsiao](https://github.com/lukehsiao)
174- kurtlawrence: [@kurtlawrence](https://github.com/kurtlawrence)
175
176