Skip to main content

Crate clyle_proc

Crate clyle_proc 

Source
Expand description

§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.

Macros§

clyle
Compile-time styling for terminal output using HTML-like syntax.
eprint
Print a styled string to stderr at compile time. Combines clyle! styling with eprint! functionality.
eprintln
Print a styled string to stderr with newline at compile time. Combines clyle! styling with eprintln! functionality.
format
Format a styled string with arguments at compile time. Combines clyle! styling with format! functionality.
print
Print a styled string to stdout at compile time. Combines clyle! styling with print! functionality.
println
Print a styled string to stdout with newline at compile time. Combines clyle! styling with println! functionality.
write
Write a styled string to a writer at compile time. Combines clyle! styling with write! functionality.
writeln
Write a styled string to a writer with newline at compile time. Combines clyle! styling with writeln! functionality.