Features

• Cursor positioning and movement
• Screen and line erasure
• Terminal reset operations
• Easy-to-use, lightweight API

Installation

1. Run the following command to fetch the ansi-escape.zig package:

   zig fetch https://github.com/hendriknielaender/ansi-escape.zig/archive/<COMMIT>.tar.gz --save
   

   Using zig fetch simplifies managing dependencies by automatically handling the package hash, ensuring your build.zig.zon file is up to date.

2. Add the module in build.zig:

   const std = @import("std");
   
   pub fn build(b: *std.Build) void {
       const target = b.standardTargetOptions(.{});
       const optimize = b.standardOptimizeOption(.{});
   
   +   const opts = .{ .target = target, .optimize = optimize };
   +   const ansi_module = b.dependency("ansi-escape", opts).module("ansi-escape");
   
       const exe = b.addExecutable(.{
           .name = "test",
           .root_source_file = b.path("src/main.zig"),
           .target = target,
           .optimize = optimize,
       });
   +   exe.root_module.addImport("ansi-escape", ansi_module);
       exe.install();
       ...
   }
   

Quick Start

const std = @import("std");
const ansi = @import("ansi-escape").ansi;

pub fn main() !void {
    const stdout = std.io.getStdOut().writer();

    // Print initial lines
    try stdout.print("Line 1\nLine 2\nLine 3\n", .{});

    // Move up one line, clear it, and replace it
    try ansi.cursor.up(stdout, 1);
    try ansi.erase.line(stdout);
    try stdout.print("Updated Line 2\n", .{});

    // Hide cursor, wait for user, and then restore
    try ansi.cursor.hide(stdout);
    try std.time.sleep(1_000_000_000); // 1 second
    try ansi.cursor.show(stdout);
}

API

The ansi-escape.zig library offers a structured API organized into several key components: Cursor, Scroll, Erase, and Clear. Each component provides a set of functions to perform specific terminal manipulations. The Cursor struct allows precise control over cursor positioning and movement, including absolute and relative movements, hiding/showing the cursor, and saving/restoring cursor positions. The Scroll struct enables scrolling the terminal content up or down by a specified number of lines. The Erase struct provides functions to clear parts of the screen or lines, such as erasing the entire screen, clearing lines, or removing content above or below the cursor. Finally, the Clear struct includes functions to reset the terminal to its default state. Together, these components offer a flexible and powerful API for managing terminal behavior through ANSI escape codes.