在 Crystal 中使用 ANSI 转义码 —— \e、Colorize 标准库、term-cursor

# Crystal "..." string literals accept five ESC forms.
# Pick whichever your team reads fastest — they all
# compile to the same single byte (0x1b).
#
#   "\e"       — ESC escape (most readable)
#   "\033"     — octal (1, 2, or 3 digits)
#   "\x1b"     — hex (exactly 2 digits)
#   "\u001b"   — Unicode (exactly 4 hex digits)
#   "\u{1b}"   — Unicode variable width

puts "\e[1;31merror:\e[0m permission denied"
puts "\033[33mwarn:\033[0m deprecated flag"
puts "\x1b[32mok:\x1b[0m 142 tests passed"
puts "\u001b[36minfo:\u001b[0m skipping cache"
puts "\u{1b}[35mdebug:\u{1b}[0m checkpoint hit"

# Truecolor — 38;2;R;G;B
puts "\e[38;2;255;128;0morange truecolor\e[0m"

# 256-palette — 38;5;n  (n = 0..255)
puts "\e[38;5;196mbright red\e[0m"

# Reusable helper — works without any shard:
def esc(sgr : String, text : String) : String
  "\e[#{sgr}m#{text}\e[0m"
end

puts esc("1;31", "FATAL") + " server crashed"
puts esc("32",   "ok:")    + " 142 tests passed"
puts esc("38;2;255;128;0", "truecolor orange")

# Ships with the compiler — no shard needed.
require "colorize"

# Named SGR colours — chain methods left-to-right:
puts "error: ".colorize.red.bold.to_s + "permission denied"
puts "ok: ".colorize.green.to_s        + "142 tests passed"
puts " CAUTION ".colorize.black.on_yellow.to_s + " brakes wet"

# Symbol form — equivalent, sometimes nicer in data-driven code:
levels = {error: :red, warn: :yellow, ok: :green, info: :cyan}
levels.each do |lvl, colour|
  puts "#{lvl.to_s.upcase.colorize(colour).bold}: example message"
end

# Truecolor — 38;2;R;G;B via .fore(r, g, b):
puts "hot pink".colorize.fore(255, 80, 200)
puts "deep teal".colorize.fore(0, 110, 130).bold

# 256-palette — .fore(n) with n in 0..255:
(0..255).step(16) do |n|
  print "#{n.to_s.rjust(3)} ".colorize.fore(n)
end
puts

# Background + mode chaining:
puts "selected".colorize.fore(:white).back(:blue).mode(:underline)

# Auto-disabled when stdout is redirected — try:
#   crystal run example.cr | cat
# Colorize.enabled? returns false; no escapes emitted.
puts "ok".colorize.green  # writes "ok" plain when piped

# shard.yml:
#   dependencies:
#     term-cursor:
#       github: crystal-term/cursor
#     term-screen:
#       github: crystal-term/screen
#
# Then `shards install` and require below:

require "term-cursor"
require "term-screen"

# Term::Cursor methods return plain Strings (the raw
# escape sequence) — print them to apply, or concat:
print Term::Cursor.clear_screen
print Term::Cursor.move(0, 0)

# Right-aligned status bar pinned to bottom row:
rows, cols = Term::Screen.size
status = " 142 tests passed  "
print Term::Cursor.save
print Term::Cursor.move(0, rows - 1)
print status.rjust(cols)
print Term::Cursor.restore

# Spinner — hide cursor, animate, restore:
frames = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏]
print Term::Cursor.hide
begin
  10.times do |i|
    print "\r#{frames[i % frames.size]} working..."
    sleep 0.08.seconds
  end
ensure
  print "\r"
  print Term::Cursor.clear_line
  print Term::Cursor.show
  puts "done"
end

# Term::Screen.size handles every fallback chain:
#   TIOCGWINSZ ioctl  →  GetConsoleScreenBufferInfo
#   →  $LINES / $COLUMNS  →  24×80 default
puts "terminal: #{Term::Screen.width}×#{Term::Screen.height}"

# Capability gating in Crystal:
#   STDOUT.tty?               — stdlib, returns false when piped/redirected
#   ENV["NO_COLOR"]?          — universal opt-out env var
#   ENV["FORCE_COLOR"]?       — universal opt-in env var
#   Colorize.enabled = false  — global force-disable for the Colorize module
#
# Colorize auto-respects STDOUT.tty?, so most apps need
# nothing more than the require. Manual gating is for code
# that emits ANSI without going through Colorize.

require "colorize"

def ansi_capable? : Bool
  return false if ENV["NO_COLOR"]?
  return true  if ENV["FORCE_COLOR"]?
  STDOUT.tty?
end

# Honour the env vars in Colorize too — Colorize doesn't
# look at NO_COLOR on its own, so wire it explicitly:
Colorize.enabled = ansi_capable?

def styled(text : String, sgr : String) : String
  return text unless ansi_capable?
  "\e[#{sgr}m#{text}\e[0m"
end

puts styled("OK",   "32")
puts styled("FAIL", "1;31")

# Windows VT enable — pre-Conhost-1709 builds need an
# explicit SetConsoleMode call. The {% if flag?(:win32) %}
# macro guards the libc binding so the same source file
# compiles cleanly on Linux/macOS without the import.
{% if flag?(:win32) %}
  lib LibC
    ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004_u32
    STD_OUTPUT_HANDLE                  = -11_i32

    fun GetStdHandle(nStdHandle : Int32) : Void*
    fun GetConsoleMode(hConsoleHandle : Void*, lpMode : UInt32*) : Int32
    fun SetConsoleMode(hConsoleHandle : Void*, dwMode : UInt32) : Int32
  end

  def enable_vt_on_windows
    handle = LibC.GetStdHandle(LibC::STD_OUTPUT_HANDLE)
    mode = uninitialized UInt32
    LibC.GetConsoleMode(handle, pointerof(mode))
    LibC.SetConsoleMode(handle, mode | LibC::ENABLE_VIRTUAL_TERMINAL_PROCESSING)
  end

  enable_vt_on_windows
{% end %}