From 4647075aff409dfee92bfbd8c7ac8ae1f591e9c4 Mon Sep 17 00:00:00 2001 From: Benjamin Sago Date: Sat, 13 Jul 2019 17:30:53 +0100 Subject: [PATCH] More documentation tweaks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit • Link many types to their doc pages • Give Style an overall example • Stop [u8] from being turned into a link • Reword in places --- README.md | 31 +++++++------- src/display.rs | 8 ++-- src/lib.rs | 107 ++++++++++++++++++++++++++++++------------------- src/style.rs | 9 +++++ 4 files changed, 92 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 0338554..b557fee 100644 --- a/README.md +++ b/README.md @@ -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: @@ -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: @@ -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 @@ -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 @@ -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; @@ -159,12 +160,9 @@ 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; @@ -172,8 +170,7 @@ 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; diff --git a/src/display.rs b/src/display.rs index d6646c8..17c54f0 100644 --- a/src/display.rs +++ b/src/display.rs @@ -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 ::Owned: fmt::Debug { @@ -22,7 +22,7 @@ where ::Owned: fmt::Debug { /// Cloning an `ANSIGenericString` will clone its underlying string. /// -/// ### Examples +/// # Examples /// /// ``` /// use ansi_term::ANSIString; @@ -70,9 +70,9 @@ where ::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; /// diff --git a/src/lib.rs b/src/lib.rs index d1f28b7..2d2f83a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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, @@ -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; @@ -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: //! //! ``` @@ -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; @@ -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. //! //! ``` @@ -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`: //! @@ -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: //! //! ``` @@ -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. //! @@ -162,23 +163,23 @@ //! 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; @@ -186,8 +187,8 @@ //! 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; @@ -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"] @@ -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::*; diff --git a/src/style.rs b/src/style.rs index 0bb2863..1bee4d9 100644 --- a/src/style.rs +++ b/src/style.rs @@ -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 {