gazagnaire.org
Terminal styling and layout widgets for OCaml (tables, trees, panels, colors)
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Thomas Gazagnaire. All rights reserved.
3 SPDX-License-Identifier: MIT
4 ---------------------------------------------------------------------------*)
5
6(** Unicode-aware text width calculation.
7
8 Handles UTF-8 strings, wide characters (CJK), and ANSI escape sequences. *)
9
10val string_width : string -> int
11(** [string_width s] returns the display width of [s] in terminal columns.
12 - Handles UTF-8 encoding.
13 - Wide characters (CJK) count as 2 columns.
14 - ANSI escape sequences are ignored (0 width).
15 - Control characters are ignored. *)
16
17val truncate : int -> string -> string
18(** [truncate width s] truncates [s] to fit within [width] terminal columns.
19 Preserves ANSI escape sequences. Adds no ellipsis. *)
20
21val pad_right : int -> string -> string
22(** [pad_right width s] pads [s] with spaces on the right to reach [width]
23 columns. If [s] is already wider, returns [s] unchanged. *)
24
25val pad_left : int -> string -> string
26(** [pad_left width s] pads [s] with spaces on the left to reach [width]
27 columns. If [s] is already wider, returns [s] unchanged. *)
28
29val center : int -> string -> string
30(** [center width s] centers [s] within [width] columns by adding spaces on both
31 sides. If [s] is already wider, returns [s] unchanged. *)
32
33val wrap : ?indent:int -> int -> string -> string
34(** [wrap ?indent width text] word-wraps [text] to fit within [width] columns.
35 Lines are broken at spaces. Each line is prefixed with [indent] spaces
36 (default: 0). *)
37
38(** {1 Terminal Queries} *)
39
40val terminal_width : unit -> int
41(** [terminal_width ()] returns the terminal width in columns. Uses [tput cols]
42 and caches the result. Falls back to the [COLUMNS] environment variable,
43 then to 80 if the width cannot be determined. *)
44
45val is_tty : unit -> bool
46(** [is_tty ()] returns [true] if stdout is connected to a terminal. *)