Crate standout_render

Expand description

§Standout Render - Styled Terminal Output Library

standout-render combines templating, theming, and adaptive color handling so you can ship consistent terminal UI without re-implementing styling utilities. Although it powers the standout CLI framework, the crate is fully usable as a stand-alone renderer for any Rust application that needs rich TTY output.

§Core Concepts

Theme: Named, adaptive styles that automatically respect ColorMode
Renderer: Compile and reuse templates for fast repeated rendering
validate_template: Surface typos or unknown tags before you ship templates
OutputMode: Control how content is emitted (Auto/Term/Text/TermDebug/Json/Yaml)
Style syntax: Tag-based [name]content[/name] markup for inline styling

§Quick Start

Create a Theme, pass serializable data, and call render to produce a styled String that you can print, persist, or feed into other systems:

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

Templates use lightweight [name]content[/name] tags, so you can mix static text and template variables without sprinkling manual console::Style calls. The renderer resolves each tag to the appropriate entry in your Theme:

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)

Styles automatically adapt to the current ColorMode. Provide explicit overrides for light and dark variants, or rely on a shared default when you do not need per-mode differences:

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

Ship themes alongside your application or allow users to bring their own. The Theme::from_yaml helper loads named styles (and adaptive overrides) directly from a YAML definition:

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();

§Renderer Example

For larger applications, use Renderer to register templates once and render them repeatedly without reparsing:

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_engine;
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::MiniJinjaEngine;
pub use template::RegistryError;
pub use template::Renderer;
pub use template::ResolvedTemplate;
pub use template::TemplateEngine;
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.
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§

RenderError: Error type for template rendering operations.
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.