Struct Styles

Source

pub struct Styles { /* private fields */ }

Expand description

A collection of named styles.

Styles are registered by name and applied via the style filter in templates. Styles can be concrete (with actual formatting) or aliases to other styles, enabling layered styling (semantic -> presentation -> visual).

When a style name is not found, a configurable indicator is prepended to the text to help catch typos in templates (defaults to (!?)).

§Example

use standout::Styles;
use console::Style;

let styles = Styles::new()
    // Concrete styles
    .add("error", Style::new().bold().red())
    .add("warning", Style::new().yellow())
    .add("dim", Style::new().dim())
    // Alias styles
    .add("muted", "dim");

// Apply a style (returns styled string)
let styled = styles.apply("error", "Something went wrong");

// Aliases resolve to their target
let muted = styles.apply("muted", "Quiet");  // Uses "dim" style

// Unknown style shows indicator
let unknown = styles.apply("typo", "Hello");
assert!(unknown.starts_with("(!?)"));

Implementations§

Source §

impl Styles

Source

pub fn new() -> Self

Creates an empty style registry with the default missing style indicator.

Source

pub fn missing_indicator(self, indicator: &str) -> Self

Sets a custom indicator to prepend when a style name is not found.

This helps catch typos in templates. Set to empty string to disable.

§Example

use standout::Styles;

let styles = Styles::new()
    .missing_indicator("[MISSING]")
    .add("ok", console::Style::new().green());

// Typo in style name
let output = styles.apply("typo", "Hello");
assert_eq!(output, "[MISSING] Hello");

Source

pub fn add<V: Into<StyleValue>>(self, name: &str, value: V) -> Self

Adds a named style. Returns self for chaining.

The value can be either a concrete Style or a &str/String alias to another style name.

§Example

use standout::Styles;
use console::Style;

let styles = Styles::new()
    .add("dim", Style::new().dim())      // Concrete style
    .add("muted", "dim");                 // Alias to "dim"

If a style with the same name exists, it is replaced.

Source

pub fn validate(&self) -> Result<(), StyleValidationError>

Validates that all style aliases resolve correctly.

Returns Ok(()) if all aliases point to existing styles with no cycles. Returns an error describing the first problem found.

§Example

use standout::{Styles, StyleValidationError};
use console::Style;

// Valid: alias chain resolves
let valid = Styles::new()
    .add("dim", Style::new().dim())
    .add("muted", "dim");
assert!(valid.validate().is_ok());

// Invalid: dangling alias
let dangling = Styles::new()
    .add("orphan", "nonexistent");
assert!(matches!(
    dangling.validate(),
    Err(StyleValidationError::UnresolvedAlias { .. })
));

// Invalid: cycle
let cycle = Styles::new()
    .add("a", "b")
    .add("b", "a");
assert!(matches!(
    cycle.validate(),
    Err(StyleValidationError::CycleDetected { .. })
));

Source

pub fn apply(&self, name: &str, text: &str) -> String

Applies a named style to text.

Resolves aliases to find the concrete style, then applies it. If the style doesn’t exist or can’t be resolved, prepends the missing indicator.

Source

pub fn apply_plain(&self, name: &str, text: &str) -> String

Applies style checking without ANSI codes (plain text mode).

If the style exists and resolves, returns the text unchanged. If not found or unresolvable, prepends the missing indicator (unless it’s empty).

Source

pub fn apply_with_mode(&self, name: &str, text: &str, use_color: bool) -> String

Applies a style based on the output mode.

Term - Applies ANSI styling
Text - Returns plain text (no ANSI codes)
Auto - Should be resolved before calling this method

Note: For Auto mode, call OutputMode::should_use_color() first to determine whether to use Term or Text.

Source

pub fn apply_debug(&self, name: &str, text: &str) -> String

Applies a style in debug mode, rendering as bracket tags.

Returns [name]text[/name] for styles that resolve correctly, or applies the missing indicator for unknown/unresolvable styles.

§Example

use standout::Styles;
use console::Style;

let styles = Styles::new()
    .add("bold", Style::new().bold())
    .add("emphasis", "bold");  // Alias

// Direct style renders as bracket tags
assert_eq!(styles.apply_debug("bold", "hello"), "[bold]hello[/bold]");

// Alias also renders with its own name (not the target)
assert_eq!(styles.apply_debug("emphasis", "hello"), "[emphasis]hello[/emphasis]");

// Unknown style shows indicator
assert_eq!(styles.apply_debug("unknown", "hello"), "(!?) hello");

Source

pub fn has(&self, name: &str) -> bool

Returns true if a style with the given name exists (concrete or alias).

Source

pub fn len(&self) -> usize

Returns the number of registered styles (both concrete and aliases).

Source

pub fn is_empty(&self) -> bool

Returns true if no styles are registered.

Source

pub fn to_resolved_map(&self) -> HashMap<String, Style>

Returns a map of all style names to their resolved concrete styles.

This is useful for passing styles to external processors like BBParser. Aliases are resolved to their target concrete styles, and styles that cannot be resolved (cycles, dangling aliases) are omitted.

§Example

use standout::Styles;
use console::Style;

let styles = Styles::new()
    .add("bold", Style::new().bold())
    .add("emphasis", "bold");  // Alias

let resolved = styles.to_resolved_map();
assert!(resolved.contains_key("bold"));
assert!(resolved.contains_key("emphasis"));
assert_eq!(resolved.len(), 2);