You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Rewrite to support generic Display types inside of ANSIString
Motivation here was to make ANSIString work with arbitrary Display
types such that values don’t need to be first converted into a String.
For example, in the past one would have to write something along the
lines of:
let (red, green, blue) = (255, 248, 231);
let red = Red.paint(format!("{red:02x}");
let green = Green.paint(format!("{green:02x}");
let blue = Blue.paint(format!("{blue:02x}");
let latte = format!("#{red}{green}{blue}");
This of course works but results in three String allocations. Those
can now be avoided since ANSIString can take any Display type and
postpone formatting to when the entire string is formatted:
let (red, green, blue) = (255, 248, 231);
let red = Red.paint(red);
let green = Green.paint(green);
let blue = Blue.paint(blue);
let latte = format!("#{red:02x}{green:02x}{blue:02x}");
Adding this feature lead to a rabbit hole of changing a lot of other
interfaces around ANSIString type.
Most notably, ANSIGenericString and ANSIByteString types no longer
exists. ANSIString is now the only type. Implementation of Display
trait and write_to method are now limited by the bounds on the generic
argument rather than on the type being ANSIString or ANSIByteString.
Similarly, there’s now just one ANSIStrings type which points at
a slice of strings.
Furthermore, util::substring now works on generic types and doesn’t
perform allocations on its own. E.g. when doing a substring over
Strings or Cows, the resulting substring borrows from the underlying
strings.
Lastly, how strings and bytes are written out has been completely
refactored. This is just an internal change though not observable by
the user.
**Note for Windows 10 users:** On Windows 10, the application must enable ANSI support first:
68
+
If you want to get at the escape codes, you can convert an `ANSIString` to
69
+
a string with `to_string` method as you would any other `Display` value:
50
70
51
-
```rust,ignore
52
-
let enabled = ansi_term::enable_ansi_support();
71
+
```rustrust
72
+
use ansi_term::Colour::Red;
73
+
74
+
let red_string = Red.paint("a red string").to_string();
53
75
```
54
76
55
77
## Bold, underline, background, and other styles
56
78
57
-
For anything more complex than plain foreground colour changes, you need to construct `Style` values themselves, rather than beginning with a `Colour`.
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:
79
+
For anything more complex than plain foreground colour changes, you need to
80
+
construct `Style` values. You can do this by chaining methods based on
81
+
a object created with `Style::new`. Each method creates a new style that
82
+
has that specific property set. For example:
61
83
62
84
```rust
63
85
useansi_term::Style;
@@ -67,7 +89,9 @@ println!("How about some {} and {}?",
67
89
Style::new().underline().paint("underline"));
68
90
```
69
91
70
-
For brevity, these methods have also been implemented for `Colour` values, so you can give your styles a foreground colour without having to begin with an empty `Style` value:
92
+
For brevity, these methods have also been implemented for `Colour` values,
93
+
so you can give your styles a foreground colour without having to begin with
94
+
an empty `Style` value:
71
95
72
96
```rust
73
97
useansi_term::Colour::{Blue, Yellow};
@@ -79,10 +103,12 @@ println!("Demonstrating {} and {}!",
79
103
println!("Yellow on blue: {}", Yellow.on(Blue).paint("wow!"));
80
104
```
81
105
82
-
The complete list of styles you can use are:
83
-
`bold`, `dimmed`, `italic`, `underline`, `blink`, `reverse`, `hidden`, and `on` for background colours.
106
+
The complete list of styles you can use are: `bold`, `dimmed`, `italic`,
107
+
`underline`, `blink`, `reverse`, `hidden`, `strikethrough`, and `on` for
108
+
background colours.
84
109
85
-
In some cases, you may find it easier to change the foreground on an existing `Style` rather than starting from the appropriate `Colour`.
110
+
In some cases, you may find it easier to change the foreground on an
111
+
existing `Style` rather than starting from the appropriate `Colour`.
86
112
You can do this using the `fg` method:
87
113
88
114
```rust
@@ -93,8 +119,10 @@ println!("Yellow on blue: {}", Style::new().on(Blue).fg(Yellow).paint("yow!"));
93
119
println!("Also yellow on blue: {}", Cyan.on(Blue).fg(Yellow).paint("zow!"));
94
120
```
95
121
96
-
You can turn a `Colour` 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 `Colour` 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.
122
+
You can turn a `Colour` into a `Style` with the `normal` method. This
123
+
produces the exact same `ANSIString` as if you just used the
124
+
`Colour::paint` method directly, but it’s useful if you need to represent
125
+
both the “red bold” and “red, but not bold” with values of the same type.
98
126
99
127
```rust
100
128
useansi_term::Style;
@@ -104,11 +132,11 @@ Red.normal().paint("yet another red string");
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.
134
-
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.
159
+
The benefit of writing ANSI escape codes to the terminal is that they
160
+
*stack*: you do not need to end every coloured string with a reset code if
161
+
the text that follows it is of a similar style. For example, if you want to
162
+
have some blue text followed by some blue bold text, it’s possible to send
163
+
the ANSI code for blue, followed by the ANSI code for bold, and finishing
164
+
with a reset code without having to have an extra one between the two
165
+
strings.
135
166
136
-
This crate can optimise the ANSI codes that get printed in situations like this, making life easier for your terminal renderer.
137
-
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.
167
+
This crate can optimise the ANSI codes that get printed in situations like
168
+
this, making life easier for your terminal renderer. The `ANSIStrings`
169
+
type takes a slice of several `ANSIString` values, and will iterate over
170
+
each of them, printing only the codes for the styles that need to be updated
171
+
as part of its formatting routine.
138
172
139
-
The following code snippet uses this to enclose a binary number displayed in red bold text inside some red, but not bold, brackets:
173
+
The following code snippet uses this to enclose a binary number displayed in
174
+
red bold text inside some red, but not bold, brackets:
140
175
141
176
```rust
142
177
useansi_term::Colour::Red;
143
178
useansi_term::{ANSIString, ANSIStrings};
144
179
145
180
letsome_value=format!("{:b}", 42);
146
-
letstrings:&[ANSIString<'static>] =&[
147
-
Red.paint("["),
148
-
Red.bold().paint(some_value),
149
-
Red.paint("]"),
181
+
letstrings:&[ANSIString<_>] =&[
182
+
Red.paint_cow("["),
183
+
Red.bold().paint_cow(some_value),
184
+
Red.paint_cow("]"),
150
185
];
151
186
152
187
println!("Value: {}", ANSIStrings(strings));
153
188
```
154
189
155
-
There are several things to note here.
156
-
Firstly, the `paint` method can take *either* an owned `String` or a borrowed `&str`.
157
-
Internally, an `ANSIString` holds a copy-on-write (`Cow`) string value to deal with both owned and borrowed strings at the same time.
158
-
This is used here to display a `String`, the result of the `format!` call, using the same mechanism as some statically-available `&str` slices.
159
-
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.
190
+
In this example, the `paint_cow` method can take *either* an owned `String`
191
+
or a borrowed `&str` value. It converts the argument into a copy-on-write
192
+
string (`Cow`) and wraps that inside of an `ANSIString`.
160
193
161
-
## Byte strings
194
+
The `ANSIStrings` value works in the same way as its singular counterpart,
195
+
with a `Display` implementation that only performs the formatting when
196
+
required.
162
197
163
-
This library also supports formatting `[u8]` byte strings; this supports applications working with text in an unknown encoding.
164
-
`Style` and `Colour` support painting `[u8]` values, resulting in an `ANSIByteString`.
165
-
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`:
0 commit comments