clyle-proc 0.1.0

Command Line Styling using HTML
Documentation

Clyle Procedural Macros

Compile-time styling for terminal output using HTML-like syntax. This crate provides the [clyle!] procedural macro, which processes styling markup at compile time, resulting in zero runtime overhead compared to manually writing ANSI escape sequences.

The clyle! Macro

The primary export is the [clyle!] macro, which takes a string literal containing HTML-style markup and returns a &'static str with the processed ANSI escape sequences.

Usage

use clyle::clyle;
fn main() {
    // Instant compile-time evaluation
    let message = clyle!("<fg=red bold>Error:</> {}", "Something went wrong");
    println!("{}", message);
}

Why Use clyle! Over try_clyle()?

  • Zero Runtime Overhead: Styling is processed at compile time
  • Early Error Detection: Invalid markup fails at compile time, not runtime
  • Optimized Output: The compiler can optimize static strings
  • Simpler API: No need for error handling in most cases

Syntax Guide

Color Syntax

  • Standard ANSI colors (16 colors):

    • Lowercase: black, red, green, yellow, blue, magenta, cyan, white
    • Short form: k, r, g, y, b, m, c, w
    • Bright variants (uppercase): Black, Red, Green, Yellow, Blue, Magenta, Cyan, White
    • Bright variants short form: K, R, G, Y, B, M, C, W

  • 256-Color Palette: palette(0) through palette(255)

  • True RGB Colors:

    • Hex format: #FF00FF (magenta)
    • RGB format: rgb(255,0,255) (magenta)

Use the fg= attribute for background colors and the bg= attribute for background colors.

Example

use clyle::clyle;

fn main() {
    println!("{}", clyle!("<bg=blue>Blue background</>"));
    println!("{}", clyle!("<fg=white bg=red>Red background with white text</>"));
    println!("{}", clyle!("<bg=#00FF00>RGB green background</>"));
}

Text Effects

  • bold or b — Bold text
  • dim or d — Dimmed/faint text
  • italic or i — Italic text
  • under or u — Underlined text
  • strike or s — Strikethrough text
  • blink or k — Blinking text
  • reverse or r — Inverted foreground and background
  • hidden or h — Hidden text (not visible)

Effects can be combined in a single tag:

use clyle::clyle;

fn main() {
    println!("{}", clyle!("<bold>Bold text</bold>"));
    println!("{}", clyle!("<italic dim>Dimmed italic</italic>"));
    println!("{}", clyle!("<fg=cyan bold under>Cyan, bold, underlined</>"));
}

Tag Nesting and Closing

Tags are closed with </> or </TAG-NAME> which removes all active styling. You can nest tags:

use clyle::clyle;

fn main() {
    println!("{}", clyle!("<fg=red>Red <bold>and bold</> just red</>"));
}

Examples

Status Messages

use clyle::clyle;
fn print_status() {
    println!("{}", clyle!("<fg=green>✓</> Success"));
    println!("{}", clyle!("<fg=yellow>!</> Warning"));
    println!("{}", clyle!("<fg=red>✗</> Error"));
}

Nested Styling

use clyle::clyle;
fn main() {
    println!("{}", clyle!("<fg=cyan>Info:</> <bold>Important</bold> message"));
}

Compile-Time vs Runtime

Use this macro when:

  • You have fixed styling strings (literals)
  • You want zero runtime overhead
  • You prefer early error detection Use [clyle_core::try_clyle] when:
  • You need to style dynamically generated strings
  • You need to handle styling errors at runtime
  • You're processing user input or external data

Integration with clyle Crate

The clyle crate re-exports this macro for convenient use:

use clyle::clyle;

Alternatively, import directly from this crate:

use clyle_proc::clyle;

Terminal Support

Clyle works on any terminal supporting ANSI escape sequences:

  • ✅ Most modern terminals (bash, zsh, PowerShell 7+, etc.)
  • ✅ Windows 10+ (with ANSI support enabled or Windows Terminal)
  • ✅ macOS Terminal and iTerm2
  • ℹ️ Always test on your target platform to ensure color support

License

Clyle is dual-licensed under either of:

Choose whichever license works best for your use case.