clyle-proc 0.1.0

# 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

```rust
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

```rust
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:

```rust
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:

```rust
use clyle::clyle;

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

## Examples

### Status Messages

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

### Nested Styling

```rust
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:

```rust
use clyle::clyle;
```

Alternatively, import directly from this crate:

```rust
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:

- **Apache License, Version 2.0** ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- **MIT License** ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

Choose whichever license works best for your use case.