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