Colors & Styling

Logly-Zig provides comprehensive ANSI color support for console output, with options to enable colors in file output as well.

Platform Support

Platform	Color Support	Notes
Linux	✅ Native	Works out of the box
macOS	✅ Native	Works out of the box
Windows 10+	✅ Requires init	Call Terminal.enableAnsiColors()
VS Code Terminal	✅ Full	Works on all platforms
Windows Console	⚠️ Legacy	May need VT processing enabled

Enabling Colors

Windows Setup

On Windows, you must enable ANSI color support at the start of your program:

const logly = @import("logly");

pub fn main() !void {
    // Enable ANSI colors on Windows (no-op on Linux/macOS)
    _ = logly.Terminal.enableAnsiColors();
    
    // ... rest of your code
}

Check Color Support

if (logly.Terminal.supportsAnsiColors()) {
    // Terminal supports colors
}

Whole-Line Coloring

Logly colors the entire log line (timestamp, level, and message), not just the level tag. This provides better visual scanning:

[2024-01-15 10:30:45] [INFO] Application started      <- Entire line white
[2024-01-15 10:30:46] [WARNING] Low disk space        <- Entire line yellow
[2024-01-15 10:30:47] [ERROR] Connection failed       <- Entire line red

Built-in Level Colors

Level	Priority	ANSI Code	Color	Preview
TRACE	5	36	Cyan	\x1b[36m
DEBUG	10	34	Blue	\x1b[34m
INFO	20	37	White	\x1b[37m
SUCCESS	25	32	Green	\x1b[32m
WARNING	30	33	Yellow	\x1b[33m
ERROR	40	31	Red	\x1b[31m
FAIL	45	35	Magenta	\x1b[35m
CRITICAL	50	91	Bright Red	\x1b[91m

ANSI Color Code Reference

Basic Colors (Foreground)

Code	Color
30	Black
31	Red
32	Green
33	Yellow
34	Blue
35	Magenta
36	Cyan
37	White

Bright Colors (Foreground)

Code	Color
90	Bright Black (Gray)
91	Bright Red
92	Bright Green
93	Bright Yellow
94	Bright Blue
95	Bright Magenta
96	Bright Cyan
97	Bright White

Background Colors

Code	Color
40	Black Background
41	Red Background
42	Green Background
43	Yellow Background
44	Blue Background
45	Magenta Background
46	Cyan Background
47	White Background

Text Styles

Code	Style
0	Reset
1	Bold
2	Dim
3	Italic
4	Underline
5	Blink
7	Reverse
8	Hidden
9	Strikethrough

Combining Codes

Combine multiple codes with semicolons:

Example	Description
"31"	Red text
"31;1"	Bold red text
"31;4"	Underlined red text
"31;1;4"	Bold underlined red
"97;41"	White text on red background
"36;1"	Bold cyan
"33;7"	Yellow reverse (yellow background, black text)

Custom Level Colors

Create custom log levels with your own colors:

const logly = @import("logly");

pub fn main() !void {
    _ = logly.Terminal.enableAnsiColors();
    
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();
    
    const logger = try logly.Logger.init(allocator);
    defer logger.deinit();
    
    // Add custom levels with custom colors
    try logger.addCustomLevel("AUDIT", 35, "35");        // Magenta
    try logger.addCustomLevel("NOTICE", 22, "36;1");     // Bold Cyan
    try logger.addCustomLevel("ALERT", 48, "91;1");      // Bold Bright Red
    try logger.addCustomLevel("SECURITY", 55, "97;41"); // White on Red BG
    try logger.addCustomLevel("METRIC", 15, "32;1");     // Bold Green
    
    // Use custom levels
    try logger.custom("AUDIT", "User login event", @src());
    try logger.custom("NOTICE", "Important notice", @src());
    try logger.custom("ALERT", "High CPU usage detected", @src());
    try logger.custom("SECURITY", "Unauthorized access attempt", @src());
    try logger.customf("METRIC", "Response time: {d}ms", .{42}, @src());
}

Enhanced Color Options (v0.1.5)

Level Color Variants

Each log level now supports multiple color variants:

const Level = logly.Level;

// Default colors
const trace_color = Level.trace.defaultColor();  // "36" (Cyan)

// Bright/Bold variants
const trace_bright = Level.trace.brightColor();  // "96;1" (Bright Cyan Bold)

// Dim variants
const trace_dim = Level.trace.dimColor();        // "36;2" (Cyan Dim)

// Underline variants
const trace_underline = Level.trace.underlineColor();  // "36;4"

// 256-color variants
const trace_256 = Level.trace.color256();        // "38;5;51"

Color Constants

Use builtin color constants from Constants.Colors:

const Colors = logly.Constants.Colors;

// Foreground colors
const red = Colors.Fg.red;           // "31"
const bright_red = Colors.BrightFg.red;  // "91"

// Background colors
const red_bg = Colors.Bg.red;        // "41"
const bright_red_bg = Colors.BrightBg.red;  // "101"

// Styles
const bold = Colors.Style.bold;      // "1"
const underline = Colors.Style.underline;  // "4"
const italic = Colors.Style.italic;  // "3"
const reverse = Colors.Style.reverse;  // "7"

Theme Presets

Logly v0.1.5 includes multiple color theme presets:

const Formatter = logly.Formatter;

// Use preset themes
const default_theme = Formatter.Theme{};           // Standard colors
const bright_theme = Formatter.Theme.bright();     // Bold/bright colors
const dim_theme = Formatter.Theme.dim();           // Dim colors
const underlined_theme = Formatter.Theme.underlined(); // Underlined colors (v0.1.5)
const minimal_theme = Formatter.Theme.minimal();   // Subtle grays
const neon_theme = Formatter.Theme.neon();         // Vivid 256-colors
const pastel_theme = Formatter.Theme.pastel();     // Soft colors
const dark_theme = Formatter.Theme.dark();         // Dark terminal optimized
const light_theme = Formatter.Theme.light();       // Light terminal optimized

// Apply theme to formatter
var formatter = Formatter.init(allocator);
formatter.setTheme(Formatter.Theme.neon());

256-Color Palette

Use the extended 256-color palette:

const Colors = logly.Constants.Colors;

// Generate 256-color codes
const orange = Colors.fg256(208);     // "38;5;208"
const purple_bg = Colors.bg256(141);  // "48;5;141"

// Theme presets using 256-colors
const neon = Colors.Themes.neon;
// trace: "38;5;51", debug: "38;5;33", err: "38;5;196"

RGB Color Support

Define colors using RGB values:

const Colors = logly.Constants.Colors;

// Generate RGB color codes
const coral = Colors.fgRgb(255, 127, 80);   // "38;2;255;127;80"
const navy_bg = Colors.bgRgb(0, 0, 128);    // "48;2;0;0;128"

// Custom level with RGB
const CustomLevel = logly.CustomLevel;
const rgb_level = CustomLevel.initRgb("CUSTOM", 42, 255, 128, 64);

Advanced CustomLevel Options

Create custom levels with full color control:

const CustomLevel = logly.CustomLevel;

// Basic custom level
const audit = CustomLevel.init("AUDIT", 35, "36;1");

// Full color options
const custom = CustomLevel.initFull(
    "CUSTOM",           // name
    42,                 // priority
    "32",               // base color
    "92;1",             // bright color
    "32;2",             // dim color
    "38;5;46",          // 256-color
);

// Styled custom level
const styled = CustomLevel.initStyled("STYLED", 45, "31", "1;4");  // bold underline

// With background color
const alert = CustomLevel.initWithBackground("ALERT", 50, "97", "41");  // white on red

Color Configuration

Global Color Control

var config = logly.Config.default();

// Master switch - disables colors everywhere
config.global_color_display = false;
logger.configure(config);

// Re-enable colors
config.global_color_display = true;
config.color = true;
logger.configure(config);

Per-Sink Color Control

// Console sink with colors (default)
_ = try logger.addSink(.{
    .color = true,  // Explicitly enable colors
});

// File sink without colors (default for files)
_ = try logger.addSink(.{
    .path = "logs/app.log",
    .color = null,  // Auto-detect: false for files
});

// File sink WITH colors (for terminals that read log files)
_ = try logger.addSink(.{
    .path = "logs/colored.log",
    .color = true,  // Force colors in file
});

Colors in Different Output Formats

Console Output (Default)

Colors are enabled by default for console output:

try logger.info("White text");      // \x1b[37m...\x1b[0m
try logger.warning("Yellow text");  // \x1b[33m...\x1b[0m
try logger.err("Red text");         // \x1b[31m...\x1b[0m

JSON Output with Colors

JSON output also supports colors when enabled:

var config = logly.Config.default();
config.json = true;
config.pretty_json = true;
config.color = true;  // Enable colors for JSON
logger.configure(config);

try logger.info("Colored JSON");
try logger.warning("Yellow JSON block");

The entire JSON block will be wrapped in the level's color.

File Output

By default, file sinks disable colors. To enable:

_ = try logger.addSink(.{
    .path = "logs/colored.log",
    .color = true,  // Enable ANSI codes in file
});

Note: Files with ANSI codes will display correctly in:

• cat command on Linux/macOS
• less -R command
• VS Code with ANSI color extensions
• Modern terminal emulators

Custom Format Strings with Colors

Custom format strings also support colors:

var config = logly.Config.default();
config.log_format = "{time} | {level} | {message}";
config.color = true;
logger.configure(config);

// Output: \x1b[33m2024-01-15 10:30:45 | WARNING | Message\x1b[0m
try logger.warning("Formatted warning");

Disabling Colors

For Production/Log Aggregation

// Disable colors globally
var config = logly.Config.default();
config.color = false;
config.global_color_display = false;
logger.configure(config);

For Specific Sinks

// JSON file without colors (for log aggregation)
_ = try logger.addSink(.{
    .path = "logs/app.json",
    .json = true,
    .color = false,  // No ANSI codes
});

Complete Example

const std = @import("std");
const logly = @import("logly");

pub fn main() !void {
    // Enable Windows ANSI support
    _ = logly.Terminal.enableAnsiColors();
    
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();
    
    const logger = try logly.Logger.init(allocator);
    defer logger.deinit();
    
    // Add custom colored levels
    try logger.addCustomLevel("AUDIT", 35, "35");      // Magenta
    try logger.addCustomLevel("NOTICE", 22, "36;1");   // Bold Cyan
    try logger.addCustomLevel("HIGHLIGHT", 52, "33;7"); // Yellow Reverse
    
    // Standard levels (all colored)
    try logger.trace("Cyan trace message");
    try logger.debug("Blue debug message");
    try logger.info("White info message");
    try logger.success("Green success message");
    try logger.warning("Yellow warning message");
    try logger.err("Red error message");
    try logger.fail("Magenta fail message");
    try logger.critical("Bright red critical message");
    
    // Custom levels
    try logger.custom("AUDIT", "Magenta audit message");
    try logger.custom("NOTICE", "Bold cyan notice");
    try logger.custom("HIGHLIGHT", "Yellow reverse highlight");
    
    // Add file sink with colors
    _ = try logger.addSink(.{
        .path = "logs/colored.log",
        .color = true,
    });
    
    // Add JSON sink without colors
    _ = try logger.addSink(.{
        .path = "logs/app.json",
        .json = true,
        .color = false,
    });
    
    try logger.info("This goes to console (colored) and both files");
}