Crate standout_render

Expand description

§Standout Render - Styled Terminal Output Library

standout-render provides a complete rendering system for styled terminal output, including template processing, theming, and adaptive color support.

This crate is the rendering foundation for the standout CLI framework, but can be used independently for any application that needs rich terminal output.

§Core Concepts

Theme: Named collection of adaptive styles that respond to light/dark mode
ColorMode: Light or dark color mode enum
OutputMode: Control output formatting (Auto/Term/Text/TermDebug/Json/Yaml)
Style syntax: Tag-based styling [name]content[/name]
Renderer: Pre-compile templates for repeated rendering
validate_template: Check templates for unknown style tags

§Quick Start

use standout_render::{render, Theme};
use console::Style;
use serde::Serialize;

#[derive(Serialize)]
struct Summary {
    title: String,
    total: usize,
}

let theme = Theme::new()
    .add("title", Style::new().bold())
    .add("count", Style::new().cyan());

let template = r#"
[title]{{ title }}[/title]
---------------------------
Total items: [count]{{ total }}[/count]
"#;

let output = render(
    template,
    &Summary { title: "Report".into(), total: 3 },
    &theme,
).unwrap();
println!("{}", output);

§Tag-Based Styling

Use tag syntax [name]content[/name] for styling both static and dynamic content:

use standout_render::{render_with_output, Theme, OutputMode};
use console::Style;
use serde::Serialize;

#[derive(Serialize)]
struct Data { name: String, count: usize }

let theme = Theme::new()
    .add("title", Style::new().bold())
    .add("count", Style::new().cyan());

let template = r#"[title]Report[/title]: [count]{{ count }}[/count] items by {{ name }}"#;

let output = render_with_output(
    template,
    &Data { name: "Alice".into(), count: 42 },
    &theme,
    OutputMode::Text,
).unwrap();

assert_eq!(output, "Report: 42 items by Alice");

§Adaptive Themes (Light & Dark)

Themes are inherently adaptive. Individual styles can define mode-specific variations that are automatically selected based on the user’s OS color mode.

use standout_render::Theme;
use console::Style;

let theme = Theme::new()
    // Non-adaptive style (same in all modes)
    .add("header", Style::new().bold().cyan())
    // Adaptive style with light/dark variants
    .add_adaptive(
        "panel",
        Style::new(),                                  // Base
        Some(Style::new().fg(console::Color::Black)), // Light mode
        Some(Style::new().fg(console::Color::White)), // Dark mode
    );

§YAML-Based Themes

Themes can be loaded from YAML files:

use standout_render::Theme;

let theme = Theme::from_yaml(r#"
header:
  fg: cyan
  bold: true
panel:
  fg: gray
  light:
    fg: black
  dark:
    fg: white
title: header
"#).unwrap();

§More Examples

use standout_render::{Renderer, Theme};
use console::Style;
use serde::Serialize;

#[derive(Serialize)]
struct Entry { label: String, value: i32 }

let theme = Theme::new()
    .add("label", Style::new().bold())
    .add("value", Style::new().green());

let mut renderer = Renderer::new(theme).unwrap();
renderer.add_template("row", "[label]{{ label }}[/label]: [value]{{ value }}[/value]").unwrap();
let rendered = renderer.render("row", &Entry { label: "Count".into(), value: 42 }).unwrap();
assert_eq!(rendered, "Count: 42");

Re-exports§

pub use style::parse_css;
pub use style::parse_stylesheet;
pub use style::ColorDef;
pub use style::StyleAttributes;
pub use style::StyleDefinition;
pub use style::StyleValidationError;
pub use style::StyleValue;
pub use style::Styles;
pub use style::StylesheetError;
pub use style::StylesheetRegistry;
pub use style::ThemeVariants;
pub use style::DEFAULT_MISSING_STYLE_INDICATOR;
pub use style::STYLESHEET_EXTENSIONS;
pub use theme::detect_color_mode;
pub use theme::set_theme_detector;
pub use theme::ColorMode;
pub use theme::Theme;
pub use output::write_binary_output;
pub use output::write_output;
pub use output::OutputDestination;
pub use output::OutputMode;
pub use template::render;
pub use template::render_auto;
pub use template::render_auto_with_context;
pub use template::render_auto_with_spec;
pub use template::render_with_context;
pub use template::render_with_mode;
pub use template::render_with_output;
pub use template::render_with_vars;
pub use template::validate_template;
pub use template::walk_template_dir;
pub use template::RegistryError;
pub use template::Renderer;
pub use template::ResolvedTemplate;
pub use template::TemplateFile;
pub use template::TemplateRegistry;
pub use template::TEMPLATE_EXTENSIONS;
pub use file_loader::build_embedded_registry;
pub use file_loader::extension_priority;
pub use file_loader::strip_extension;
pub use file_loader::walk_dir;
pub use file_loader::FileRegistry;
pub use file_loader::FileRegistryConfig;
pub use file_loader::LoadError;
pub use file_loader::LoadedEntry;
pub use file_loader::LoadedFile;

Modules§

context: Context injection for template rendering.
file_loader: File-based resource loading for templates and stylesheets.
output: Output mode control: ANSI, plain text, or structured data.
prelude: Rendering prelude for convenient imports.
style: Style system for named styles, aliases, and YAML-based stylesheets.
tabular: Unicode-aware column formatting for terminal tables.
template: Two-pass template rendering with style tag processing.
theme: Adaptive themes with automatic light/dark mode support.

Structs§

EmbeddedSource: Embedded resource source with optional debug hot-reload.
Error: Represents template errors.
StylesheetResource: Marker type for stylesheet resources.
TemplateResource: Marker type for template resources.
UnknownTagError: An error representing an unknown tag in the input.
UnknownTagErrors: A collection of unknown tag errors found during parsing.

Enums§

UnknownTagKind: The kind of unknown tag encountered.

Functions§

flatten_json_for_csv: Flattens a JSON Value into a list of records for CSV export.
rgb_to_ansi256: Converts an RGB triplet to the nearest ANSI 256-color palette index.
rgb_to_truecolor: Placeholder helper for true-color output.
truncate_to_width: Truncates a string to fit within a maximum display width, adding ellipsis if needed.

Type Aliases§

EmbeddedStyles: Type alias for embedded stylesheets.
EmbeddedTemplates: Type alias for embedded templates.