Skip to content

Commit

Permalink
More documentation tweaks
Browse files Browse the repository at this point in the history 
• Link many types to their doc pages
• Give Style an overall example
• Stop [u8] from being turned into a link
• Reword in places
  • Loading branch information
@ogham
ogham committed Jul 13, 2019
1 parent 2f44aa9 commit 4647075
Show file tree
Hide file tree
Showing 4 changed files with 92 additions and 63 deletions.
31 changes: 14 additions & 17 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,13 @@ ansi_term = "0.11"

## Basic usage

There are two main data structures in this crate that you need to be concerned with: `ANSIString` and `Style`.
A `Style` holds stylistic information: colours, whether the text should be bold, or blinking, or whatever.
There are also `Colour` variants that represent simple foreground colour styles.
An `ANSIString` is a string paired with a `Style`.
There are three main types in this crate that you need to be concerned with: `ANSIString`, `Style`, and `Colour`.

(Yes, it’s British English, but you won’t have to write “colour” very often. `Style` is used the majority of the time.)
A `Style` holds stylistic information: foreground and background colours, whether the text should be bold, or blinking, or other properties.
The `Colour` enum represents the available colours.
And an `ANSIString` is a string paired with a `Style`.

`Color` is also available as an alias to `Colour`.

To format a string, call the `paint` method on a `Style` or a `Colour`, passing in the string you want to format as the argument.
For example, here’s how to get some red text:
Expand Down Expand Up @@ -53,7 +54,7 @@ let enabled = ansi_term::enable_ansi_support();

## Bold, underline, background, and other styles

For anything more complex than plain foreground colour changes, you need to construct `Style` objects themselves, rather than beginning with a `Colour`.
For anything more complex than plain foreground colour changes, you need to construct `Style` values themselves, rather than beginning with a `Colour`.
You can do this by chaining methods based on a new `Style`, created with `Style::new()`.
Each method creates a new style that has that specific property set.
For example:
Expand Down Expand Up @@ -92,7 +93,7 @@ println!("Yellow on blue: {}", Style::new().on(Blue).fg(Yellow).paint("yow!"));
println!("Also yellow on blue: {}", Cyan.on(Blue).fg(Yellow).paint("zow!"));
```

Finally, you can turn a `Colour` into a `Style` with the `normal` method.
You can turn a `Colour` into a `Style` with the `normal` method.
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.

```rust
Expand All @@ -106,7 +107,7 @@ Style::default().paint("a completely regular string");

## Extended colours

You can access the extended range of 256 colours by using the `Fixed` colour variant, which takes an argument of the colour number to use.
You can access the extended range of 256 colours by using the `Colour::Fixed` variant, which takes an argument of the colour number to use.
This can be included wherever you would use a `Colour`:

```rust
Expand All @@ -119,7 +120,7 @@ Fixed(221).on(Fixed(124)).paint("Mustard in the ketchup");
The first sixteen of these values are the same as the normal and bold standard colour variants.
There’s nothing stopping you from using these as `Fixed` colours instead, but there’s nothing to be gained by doing so either.

You can also access full 24-bit color by using the `RGB` colour variant, which takes separate `u8` arguments for red, green, and blue:
You can also access full 24-bit colour by using the `Colour::RGB` variant, which takes separate `u8` arguments for red, green, and blue:

```rust
use ansi_term::Colour::RGB;
Expand Down Expand Up @@ -159,21 +160,17 @@ Secondly, that the `ANSIStrings` value works in the same way as its singular cou

## Byte strings

This library also supports formatting `[u8]` byte strings; this supports
applications working with text in an unknown encoding. `Style` and
`Color` support painting `[u8]` values, resulting in an `ANSIByteString`.
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
`io::Write`:
This library also supports formatting `[u8]` byte strings; this supports applications working with text in an unknown encoding.
`Style` and `Colour` support painting `[u8]` values, resulting in an `ANSIByteString`.
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`:

```rust
use ansi_term::Colour::Green;

Green.paint("user data".as_bytes()).write_to(&mut std::io::stdout()).unwrap();
```

Similarly, the type `ANSIByteStrings` supports writing a list of
`ANSIByteString` values with minimal escape sequences:
Similarly, the type `ANSIByteStrings` supports writing a list of `ANSIByteString` values with minimal escape sequences:

```rust
use ansi_term::Colour::Green;
Expand Down
8 changes: 4 additions & 4 deletions src/display.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ use write::AnyWrite;

/// An `ANSIGenericString` includes a generic string type and a `Style` to
/// display that string. `ANSIString` and `ANSIByteString` are aliases for
/// this type on `str` and `[u8]`, respectively.
/// this type on `str` and `\[u8]`, respectively.
#[derive(PartialEq, Debug)]
pub struct ANSIGenericString<'a, S: 'a + ToOwned + ?Sized>
where <S as ToOwned>::Owned: fmt::Debug {
Expand All @@ -22,7 +22,7 @@ where <S as ToOwned>::Owned: fmt::Debug {

/// Cloning an `ANSIGenericString` will clone its underlying string.
///
/// ### Examples
/// # Examples
///
/// ```
/// use ansi_term::ANSIString;
Expand Down Expand Up @@ -70,9 +70,9 @@ where <S as ToOwned>::Owned: fmt::Debug {
/// Although not technically a string itself, it can be turned into
/// one with the `to_string` method.
///
/// ### Examples
/// # Examples
///
/// ```no_run
/// ```
/// use ansi_term::ANSIString;
/// use ansi_term::Colour::Red;
///
Expand Down
107 changes: 65 additions & 42 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,15 @@
//!
//! ## Basic usage
//!
//! There are two main data structures in this crate that you need to be
//! concerned with: `ANSIString` and `Style`. A `Style` holds stylistic
//! information: colours, whether the text should be bold, or blinking, or
//! whatever. There are also `Colour` variants that represent simple foreground
//! colour styles. An `ANSIString` is a string paired with a `Style`.
//! There are three main types in this crate that you need to be
//! concerned with: [`ANSIString`], [`Style`], and [`Colour`].
//!
//! (Yes, it’s British English, but you won’t have to write “colour” very often.
//! `Style` is used the majority of the time.)
//! A `Style` holds stylistic information: foreground and background colours,
//! whether the text should be bold, or blinking, or other properties. The
//! [`Colour`] enum represents the available colours. And an [`ANSIString`] is a
//! string paired with a [`Style`].
//!
//! [`Color`] is also available as an alias to `Colour`.
//!
//! To format a string, call the `paint` method on a `Style` or a `Colour`,
//! passing in the string you want to format as the argument. For example,
Expand All @@ -25,12 +26,12 @@
//!
//! It’s important to note that the `paint` method does *not* actually return a
//! string with the ANSI control characters surrounding it. Instead, it returns
//! an `ANSIString` value that has a `Display` implementation that, when
//! an [`ANSIString`] value that has a [`Display`] implementation that, when
//! formatted, returns the characters. This allows strings to be printed with a
//! minimum of `String` allocations being performed behind the scenes.
//! minimum of [`String`] allocations being performed behind the scenes.
//!
//! 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:
//! [`ANSIString`] to a string as you would any other `Display` value:
//!
//! ```
//! use ansi_term::Colour::Red;
Expand All @@ -42,9 +43,9 @@
//! ## Bold, underline, background, and other styles
//!
//! For anything more complex than plain foreground colour changes, you need to
//! construct `Style` objects themselves, rather than beginning with a `Colour`.
//! construct `Style` values themselves, rather than beginning with a `Colour`.
//! You can do this by chaining methods based on a new `Style`, created with
//! `Style::new()`. Each method creates a new style that has that specific
//! [`Style::new()`]. Each method creates a new style that has that specific
//! property set. For example:
//!
//! ```
Expand All @@ -69,13 +70,13 @@
//! println!("Yellow on blue: {}", Yellow.on(Blue).paint("wow!"));
//! ```
//!
//! The complete list of styles you can use are: `bold`, `dimmed`, `italic`,
//! `underline`, `blink`, `reverse`, `hidden`, `strikethrough`, and `on` for
//! The complete list of styles you can use are: [`bold`], [`dimmed`], [`italic`],
//! [`underline`], [`blink`], [`reverse`], [`hidden`], [`strikethrough`], and [`on`] for
//! background colours.
//!
//! In some cases, you may find it easier to change the foreground on an
//! existing `Style` rather than starting from the appropriate `Colour`.
//! You can do this using the `fg` method:
//! You can do this using the [`fg`] method:
//!
//! ```
//! use ansi_term::Style;
Expand All @@ -85,12 +86,12 @@
//! println!("Also yellow on blue: {}", Cyan.on(Blue).fg(Yellow).paint("zow!"));
//! ```
//!
//! Finally, you can turn a `Colour` into a `Style` with the `normal` method.
//! You can turn a `Colour` into a `Style` with the [`normal`] method.
//! 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
//! the same type. The `Style` struct also has a [`Default`] implementation if you
//! want to have a style with *nothing* set.
//!
//! ```
Expand All @@ -104,7 +105,7 @@
//!
//! ## Extended colours
//!
//! You can access the extended range of 256 colours by using the `Fixed` colour
//! You can access the extended range of 256 colours by using the `Colour::Fixed`
//! variant, which takes an argument of the colour number to use. This can be
//! included wherever you would use a `Colour`:
//!
Expand All @@ -120,7 +121,7 @@
//! `Fixed` colours instead, but there’s nothing to be gained by doing so
//! either.
//!
//! You can also access full 24-bit color by using the `RGB` colour variant,
//! You can also access full 24-bit colour by using the `Colour::RGB` variant,
//! which takes separate `u8` arguments for red, green, and blue:
//!
//! ```
Expand All @@ -140,8 +141,8 @@
//! strings.
//!
//! This crate can optimise the ANSI codes that get printed in situations like
//! this, making life easier for your terminal renderer. The `ANSIStrings`
//! struct takes a slice of several `ANSIString` values, and will iterate over
//! this, making life easier for your terminal renderer. The [`ANSIStrings`]
//! type 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.
//!
Expand All @@ -162,32 +163,32 @@
//! println!("Value: {}", ANSIStrings(strings));
//! ```
//!
//! There are several things to note here. Firstly, the `paint` method can take
//! *either* an owned `String` or a borrowed `&str`. Internally, an `ANSIString`
//! holds a copy-on-write (`Cow`) string value to deal with both owned and
//! There are several things to note here. Firstly, the [`paint`] method can take
//! *either* an owned [`String`] or a borrowed [`&str`]. Internally, an [`ANSIString`]
//! holds a copy-on-write ([`Cow`]) string value to deal with both owned and
//! borrowed strings at the same time. This is used here to display a `String`,
//! the result of the `format!` call, using the same mechanism as some
//! statically-available `&str` slices. Secondly, that the `ANSIStrings` value
//! works in the same way as its singular counterpart, with a `Display`
//! statically-available `&str` slices. 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.
//!
//! ## Byte strings
//!
//! This library also supports formatting `[u8]` byte strings; this supports
//! applications working with text in an unknown encoding. `Style` and
//! `Color` support painting `[u8]` values, resulting in an `ANSIByteString`.
//! 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
//! `io::Write`:
//! This library also supports formatting `\[u8]` byte strings; this supports
//! applications working with text in an unknown encoding. [`Style`] and
//! [`Colour`] support painting `\[u8]` values, resulting in an [`ANSIByteString`].
//! 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`]:
//!
//! ```
//! use ansi_term::Colour::Green;
//!
//! Green.paint("user data".as_bytes()).write_to(&mut std::io::stdout()).unwrap();
//! ```
//!
//! Similarly, the type `ANSIByteStrings` supports writing a list of
//! `ANSIByteString` values with minimal escape sequences:
//! Similarly, the type [`ANSIByteStrings`] supports writing a list of
//! [`ANSIByteString`] values with minimal escape sequences:
//!
//! ```
//! use ansi_term::Colour::Green;
Expand All @@ -198,7 +199,35 @@
//! Green.bold().paint("user data 2\n".as_bytes()),
//! ]).write_to(&mut std::io::stdout()).unwrap();
//! ```

//!
//! [`Cow`]: https://doc.rust-lang.org/std/borrow/enum.Cow.html
//! [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
//! [`Default`]: https://doc.rust-lang.org/std/default/trait.Default.html
//! [`String`]: https://doc.rust-lang.org/std/string/struct.String.html
//! [`&str`]: https://doc.rust-lang.org/std/primitive.str.html
//! [`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
//! [`Style`]: struct.Style.html
//! [`Style::new()`]: struct.Style.html#method.new
//! [`Color`]: enum.Color.html
//! [`Colour`]: enum.Colour.html
//! [`ANSIString`]: type.ANSIString.html
//! [`ANSIStrings`]: type.ANSIStrings.html
//! [`ANSIByteString`]: type.ANSIByteString.html
//! [`ANSIByteStrings`]: type.ANSIByteStrings.html
//! [`write_to`]: type.ANSIByteString.html#method.write_to
//! [`paint`]: type.ANSIByteString.html#method.write_to
//! [`normal`]: enum.Colour.html#method.normal
//!
//! [`bold`]: struct.Style.html#method.bold
//! [`dimmed`]: struct.Style.html#method.dimmed
//! [`italic`]: struct.Style.html#method.italic
//! [`underline`]: struct.Style.html#method.underline
//! [`blink`]: struct.Style.html#method.blink
//! [`reverse`]: struct.Style.html#method.reverse
//! [`hidden`]: struct.Style.html#method.hidden
//! [`strikethrough`]: struct.Style.html#method.strikethrough
//! [`fg`]: struct.Style.html#method.fg
//! [`on`]: struct.Style.html#method.on

#![crate_name = "ansi_term"]
#![crate_type = "rlib"]
Expand All @@ -224,15 +253,9 @@ pub use ansi::{Prefix, Infix, Suffix};
mod style;
pub use style::{Colour, Style};

/// Color is a type alias for Colour for those who can't be bothered.
/// Color is a type alias for `Colour`.
pub use Colour as Color;

// I'm not beyond calling Colour Colour, rather than Color, but I did
// purposefully name this crate 'ansi-term' so people wouldn't get
// confused when they tried to install it.
//
// Only *after* they'd installed it.

mod difference;
mod display;
pub use display::*;
Expand Down
9 changes: 9 additions & 0 deletions src/style.rs
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
/// A style is a collection of properties that can format a string
/// using ANSI escape codes.
///
/// # Examples
///
/// ```
/// use ansi_term::{Style, Colour};
///
/// let style = Style::new().bold().on(Colour::Black);
/// println!("{}", style.paint("Bold on black"));
/// ```
#[derive(PartialEq, Clone, Copy)]
#[cfg_attr(feature = "derive_serde_style", derive(serde::Deserialize, serde::Serialize))]
pub struct Style {
Expand Down

0 comments on commit 4647075

Please sign in to comment.