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