Struct Ansi

Source

pub struct Ansi { /* private fields */ }

Expand description

Represents an arbitrary combination of ANSI Effects and foreground/background Colours.

Additionally, provides a mechanism for preventing any/all of these attributes from being changed in the Ansi that results from combining two Ansi instances. See protect_attrs()

Note: this struct is designed to be immutable and const

Implementations§

Source §

impl Ansi

Source

pub const fn attrs(&self) -> Attrs

Gets the set of Attrs of this instance that are specified.

Source

pub const fn protected_attrs(&self) -> Attrs

Gets the set of Attrs of this instance that are protected.

Source

pub const fn is_no_ansi(&self) -> bool

True if this instance is NoAnsi - see no_ansi()

Source

pub const fn is_unspecified(&self) -> bool

True if this instance is Unspecified - see unspecified()

Source

pub const fn is_unprotected(&self) -> bool

True if this instance is Unprotected - see unprotect()

Source

pub const fn is_empty(&self) -> bool

True if this instance is_unspecified and is_unprotected.

Source

pub const fn is_reset(&self) -> bool

True if this instance is Reset - see reset()

Source

pub const fn is_only(&self) -> bool

True if this instance is Only - see only()

Source

pub const fn no_ansi() -> Ansi

Creates an Ansi instance whose Effects and Colours are Unspecified, which means they do not represent any specific ANSI codes and so render an empty string when formatted.

The resulting Ansi’s attributes are all protected.

This is used primarily for disabling ANSI codes from being rendered entirely. See Styled<T> for details.

Source

pub const fn unspecified() -> Ansi

Creates an Ansi instance whose Effects and Colours are Unspecified, which means they do not represent any specific ANSI codes and so render an empty string when formatted.

The resulting Ansi’s attributes are unprotected.

Source

pub const fn reset() -> Ansi

Creates an Ansi instance whose Effects and Colours are Reset, which means they would render ANSI reset codes for all attributes when each formatted individually.

For brevity, the returned instance simply renders the universal ANSI reset "\x1B[0m" when formatted.

The resulting Ansi’s attributes are unprotected.

Source

pub const fn add(&self, other: Ansi) -> Ansi

Creates an Ansi instance by adding another Ansi’s Effects and Colours to self’s.

In the absence of protected attributes in either self or other, the resulting Ansi is the union of self’s and other’s attributes, with other’s attributes replacing self’s in the event of overlap.

In the event of protected attributes in either self or other, these attributes are preserved in the result, except where the same attributes are protected in both instances, in which case self’s take precedence.

The resulting Ansi’s protected attributes are the union of those of both instances.

Source

pub const fn remove(&self, other: Ansi) -> Ansi

Creates an Ansi instance by removing another Ansi’s Effects and Colours from self’s.

In the absence of protected attributes in self, the resulting Ansi is comprised of self’s attributes excluding any attributes that exist in other.

In the event of protected attributes in self, these attributes are preserved in the result.

The resulting Ansi’s protected attributes are those of self.

Source

pub fn transition(&self, to_other: Ansi) -> Ansi

Creates an Ansi instance whose Effects and Colours will, when formatted, render the minimum ANSI codes necessary to transition from this instance’s ANSI style to that of another instance.

The resulting Ansi’s attributes are unprotected.

Source

pub const fn not(&self) -> Ansi

Creates an Ansi instance whose Effects and Colours, will, when formatted, render the ANSI codes necessary to reset this instance’s ANSI style.

For example, Effect::Bold becomes Effect::NotBold and Colour::Red becomes Colour::Reset.

The resulting Ansi’s protected attributes are those of self.

Source

pub const fn filter(&self, attrs: Attrs) -> Ansi

Creates an Ansi instance by including only the Effects and Colours of self that are selected by the given Attrs.

The resulting Ansi’s protected attributes are the intersection of self’s with those of the attrs parameter.

Source

pub const fn only(&self) -> Ansi

Creates an Ansi instance using this instance’s Effects and Colours but with protection enabled for all Attrs, including the Unspecified ones.

See protect_attrs() for further details and examples.

Source

pub const fn protect(&self) -> Ansi

Creates an Ansi instance using this instance’s Effects and Colours, but with protection enabled for any Attrs that are specified.

See protect_attrs() for further details and examples.

Source

pub const fn unprotect(&self) -> Ansi

Creates an Ansi instance using this instance’s Effects and Colours, but with protection disabled for all Attrs, including the Unspecified ones.

Source

pub const fn protect_attrs(&self, attrs: Attrs) -> Ansi

Creates an Ansi instance using this instance’s Effects and Colours, but with protection enabled for the given Attrs.

Protected Attrs are not changed in the Ansi that results from combining this instance with another Ansi instance.

This is particularly useful when dealing with formatting nested Ansi instances. We may want to prevent all ANSI codes from being displayed, or we may want to, for example, prevent nested Ansi instances from changing the colour.

§Examples

use ansiconst::{*, Effect::{Bold, Italic}, Colour::{Blue, Red}};

const BLUE_BOLD:  Ansi = ansi!(Blue, Bold  ).protect_attrs(Attrs::Foreground);
const RED_ITALIC: Ansi = ansi!(Red,  Italic).protect_attrs(Attrs::effects());

assert_eq!(
    styled_format_args!(BLUE_BOLD, "This is blue/bold, and {}",
        styled_format_args!(RED_ITALIC, "this is blue/italic")
    ).to_string(),
    "\x1B[1;34mThis is blue/bold, and \x1B[22;3mthis is blue/italic\x1B[23;1m\x1B[22;39m"
);