Add width layout modes (#36)

* wip

* wip

* wip

* wip

* wip

* Refine width layout docs

* wip

Author: gurgeous

AGENTS.md

@@ -1,34 +1,27 @@
-# AGENTS
-
 ## Project
 
 - Small Zig CLI for rendering CSV as terminal tables.
-- Keep modules narrow: `args` parses CLI, `main` owns process flow, `render` owns output, `util` holds shared helpers.
-- Prefer simple value types and explicit ownership.
 
-## CLI
+## Important
 
-- `Args.init(alloc, argv)` returns structured control flow.
-- Use `Action` for early exits: `banner`, `fatal`, `help`, `version`.
-- Fatal CLI/setup errors should return owned `err_str`; `main` prints and picks the exit code.
+- Branch names: `^[a-z_]+$`
+- COMMIT: include all current changes by default
+- PR bodies: 1-2 bullets max, use --body-file, no backticks
 
-## I/O
+## Zig Style
 
-- Use `/dev/tty` only for terminal probing such as width or background detection.
-- Do not mix terminal probing with stdin table input.
 - Use `util.stdout` and `util.stderr` for shared buffered output.
-
-## Memory
-
 - Never return slices into stack buffers.
 - Allocate any string that must outlive the current scope.
+- In `src/*.zig`, add a one-line comment to each struct and function.
+- Keep imports sorted at the bottom of each file.
 
 ## Tests
 
 - Prefer `just llm`. Run `just check` before commits and after larger refactors.
 - Keep tests deterministic. Force `--width 80` where layout matters.
-- Prefer table-driven tests and tiny helpers in `test_support` or the local test section when they reduce repetition.
-- This is partly for token reduction, colllapse if clarity stays good
+- Prefer table-driven tests and tiny helpers in `test_support`, reduce repetition.
+- This is partly for token reduction, collapse if clarity stays good
 - In `src/*.zig`, if a file has tests, add:
   `//`
   `// testing`
@@ -37,9 +30,5 @@
 ## Style
 
 - Keep files and APIs small and direct.
-- Prefer straightforward Zig control flow.
-- In `src/*.zig`, add a one-line comment to each struct and function.
-- Keep imports sorted at the bottom of each file.
-- Branch names should match `^[a-z_]+$`.
-- When the user says `commit`, commit all current changes by default, including unrelated local edits.
+- Prefer simple value types and explicit ownership.
 - With `gh pr create`, never use unescaped backticks; prefer `--body-file`.

README.md

@@ -49,6 +49,7 @@ $ zig build
   -n, --row-numbers          Turn on row numbers
   -t, --title <string>       Add a title to the table
       --border <border>      Table border style (rounded|thin|double|...)
+  -p, --pager                Send output through $PAGER or less
       --peek                 Show csv shape, sample, and handy stats
       --zebra                Turn on zebra stripes
 
@@ -66,11 +67,10 @@ $ zig build
       --color <color>        Turn color off and on (on|off|auto)
       --delimiter <char>     Set CSV delim (can be any char or "tab")
       --digits <int>         Digits after decimal for float columns
-  -p, --pager                Send output through $PAGER or less
       --table <table>        Select the db table (for sqlite)
       --theme <theme>        Select color theme (auto|dark|light)
       --vanilla              Disable numeric formatting
-      --width <int>          Set max table width in chars
+      --width <width>        Set table width, or try (min|max)
 
       --completion <shell>   Print shell completion (bash|zsh)
       --help                 Get help
@@ -88,10 +88,12 @@ Tennis works fine with Unicode and emoji content. Calculating non-ASCII display
 
 ### Colors, Themes, Appearance
 
-Tennis picks a color theme based on the color of your terminal. Color is on by default. It also honors `NO_COLOR=1`. See `--color` and `--theme`. Max terminal width is pulled from your terminal, or defaults to 80 if we can't figure it out. See `--width` if you need to override it or want something predictable for CI/tests.
+Tennis picks a color theme based on the color of your terminal. Color is on by default. It also honors `NO_COLOR=1`. Terminal width is pulled from your terminal, or defaults to 80 if we can't figure it out. See `--width` if you want to override layout.
 
 Use `--border`, `--row-numbers`, `--title`, and `--zebra` for more bling. Tennis supports the same borders as `nushell`.
 
+It's common to use `--pager` to send output through $PAGER or less.
+
 <img src="./bling.png" width="60%">
 
 ### Data, Selection, Order
@@ -127,9 +129,8 @@ We love CSV tools and use them all the time! Here are a few that we rely on:
 
 #### 0.5.0 (unreleased)
 
-- detect and justify percent cols
-- idea: max col width and/or better layout controls, this is driving me nuts
-- idea: better output for "list of columns" on col arg errors
+- `--width min` to layout based on header width, or `--width max` to disable truncation
+- percent columns are justified (thanks @nkriege)
 
 #### 0.4.0 (Apr '26)
 

extra/_tennis

@@ -7,6 +7,8 @@ _tennis() {
     '-t[Add a title to the table]:string:' \
     '--title[Add a title to the table]:string:' \
     '--border[Table border style (rounded|thin|double|...)]:border:(ascii_rounded basic basic_compact compact compact_double dots double heavy light markdown none psql reinforced restructured rounded single thin with_love)' \
+    '-p[Send output through $PAGER or less]' \
+    '--pager[Send output through $PAGER or less]' \
     '--peek[Show csv shape, sample, and handy stats]' \
     '--zebra[Turn on zebra stripes]' \
     '--deselect[De-select comma-separated headers]:headers:' \
@@ -22,12 +24,10 @@ _tennis() {
     '--color[Turn color off and on (on|off|auto)]:color:(auto off on)' \
     '--delimiter[Set CSV delim (can be any char or "tab")]:char:(tab , \; \|)' \
     '--digits[Digits after decimal for float columns]:int:(1 2 3 4 5 6)' \
-    '-p[Send output through $PAGER or less]' \
-    '--pager[Send output through $PAGER or less]' \
     '--table[Select the db table (for sqlite)]:table:' \
     '--theme[Select color theme (auto|dark|light)]:theme:(auto dark light)' \
     '--vanilla[Disable numeric formatting]' \
-    '--width[Set max table width in chars]:int:' \
+    '--width[Set table width, or try (min|max)]:width:(min max)' \
     '--completion[Print shell completion (bash|zsh)]:shell:(bash zsh)' \
     '--help[Get help]' \
     '--version[Show version number and exit]' \

extra/tennis.1

@@ -5,7 +5,7 @@
 .nh
 .ad l
 .\" Begin generated content:
-.TH "tennis" "1" "2026-04-07"
+.TH "tennis" "1" "2026-04-08"
 .P
 .SH NAME
 .P
@@ -62,6 +62,12 @@ Show the shape, some sample rows, and compact per-column stats.\&
 Show row numbers.\&
 .P
 .RE
+\fB-p\fR, \fB--pager\fR
+.RS 4
+Send output through \fB$PAGER\fR or \fBless\fR.\& If \fBLESS\fR is unset, it defaults to
+\fBFRX\fR.\&
+.P
+.RE
 \fB-t\fR, \fB--title\fR <string>
 .RS 4
 Add a title above the table.\&
@@ -141,12 +147,6 @@ Set the number of digits after the decimal for float columns.\& Valid values
 \fB1\fR through \fB6\fR, the default is \fB3\fR.\&
 .P
 .RE
-\fB--pager\fR
-.RS 4
-Send output through \fB$PAGER\fR or \fBless\fR.\& If \fBLESS\fR is unset, it defaults to
-\fBFRX\fR.\&
-.P
-.RE
 \fB--theme\fR <theme>
 .RS 4
 Select the color theme.\& Valid values: \fBauto\fR, \fBdark\fR, \fBlight\fR.\& The default
@@ -158,10 +158,15 @@ is \fBauto\fR.\&
 Disable type inference and numeric formatting.\&
 .P
 .RE
-\fB--width\fR <int>
+\fB--width\fR <width>
+.P
 .RS 4
-Set the maximum table width in characters.\& By default, \fBtennis\fR uses the
-current terminal width or \fB80\fR if it can'\&t be detected.\&
+Set the table width.\& If you specify an integer, it will be used as the
+max table width and tennis will truncate to fit if necessary.\& By default,
+\fBtennis\fR uses the current terminal width or \fB80\fR if it can'\&t be detected.\&
+.P
+Also supports two special values - \fBmin\fR to layout based on header
+width, \fBmax\fR to disable truncation entirely.\&
 .P
 .RE
 .SH BORDERS

extra/tennis.bash

@@ -18,12 +18,12 @@ _tennis() {
     --digits) COMPREPLY=($(compgen -W "1 2 3 4 5 6" -- "${cur}")) ; return ;;
     --table) COMPREPLY=() ; return ;;
     --theme) COMPREPLY=($(compgen -W "auto dark light" -- "${cur}")) ; return ;;
-    --width) COMPREPLY=() ; return ;;
+    --width) COMPREPLY=($(compgen -W "min max" -- "${cur}")) ; return ;;
     --completion) COMPREPLY=($(compgen -W "bash zsh" -- "${cur}")) ; return ;;
   esac
 
   if [[ "${cur}" == -* ]]; then
-    COMPREPLY=($(compgen -W "-n --row-numbers -t --title --border --peek --zebra --deselect --select --sort -r --reverse --shuffle --shuf --head --tail --filter --color --delimiter --digits -p --pager --table --theme --vanilla --width --completion --help --version " -- "${cur}"))
+    COMPREPLY=($(compgen -W "-n --row-numbers -t --title --border -p --pager --peek --zebra --deselect --select --sort -r --reverse --shuffle --shuf --head --tail --filter --color --delimiter --digits --table --theme --vanilla --width --completion --help --version " -- "${cur}"))
   else
     _filedir csv
     [[ ${#COMPREPLY[@]} -eq 0 ]] && _filedir

extra/tennis.scd

@@ -47,6 +47,10 @@ $ tennis diamonds.csv
 *-n*, *--row-numbers*
 	Show row numbers.
 
+*-p*, *--pager*
+	Send output through *$PAGER* or *less*. If *LESS* is unset, it defaults to
+	*FRX*.
+
 *-t*, *--title* <string>
 	Add a title above the table.
 
@@ -98,20 +102,21 @@ $ tennis diamonds.csv
 	Set the number of digits after the decimal for float columns. Valid values
 	*1* through *6*, the default is *3*.
 
-*--pager*
-	Send output through *$PAGER* or *less*. If *LESS* is unset, it defaults to
-	*FRX*.
-
 *--theme* <theme>
 	Select the color theme. Valid values: *auto*, *dark*, *light*. The default
 	is *auto*.
 
 *--vanilla*
 	Disable type inference and numeric formatting.
 
-*--width* <int>
-	Set the maximum table width in characters. By default, *tennis* uses the
-	current terminal width or *80* if it can't be detected.
+*--width* <width>
+
+	Set the table width. If you specify an integer, it will be used as the
+	max table width and tennis will truncate to fit if necessary. By default,
+	*tennis* uses the current terminal width or *80* if it can't be detected.
+
+	Also supports two special values - *min* to layout based on header
+	width, *max* to disable truncation entirely.
 
 # BORDERS
 

src/args.zig

@@ -12,6 +12,7 @@ pub const Args = struct {
         \\  -n, --row-numbers          Turn on row numbers
         \\  -t, --title <string>       Add a title to the table
         \\      --border <border>      Table border style (rounded|thin|double|...)
+        \\  -p, --pager                Send output through $PAGER or less
         \\      --peek                 Show csv shape, sample, and handy stats
         \\      --zebra                Turn on zebra stripes
         \\
@@ -29,11 +30,10 @@ pub const Args = struct {
         \\      --color <color>        Turn color off and on (on|off|auto)
         \\      --delimiter <char>     Set CSV delim (can be any char or "tab")
         \\      --digits <int>         Digits after decimal for float columns
-        \\  -p, --pager                Send output through $PAGER or less
         \\      --table <table>        Select the db table (for sqlite)
         \\      --theme <theme>        Select color theme (auto|dark|light)
         \\      --vanilla              Disable numeric formatting
-        \\      --width <int>          Set max table width in chars
+        \\      --width <width>        Set table width, or try (min|max)
         \\
         \\      --completion <shell>   Print shell completion (bash|zsh)
         \\      --help                 Get help
@@ -59,7 +59,7 @@ pub const Args = struct {
         \\    --tail <INT>
         \\    --theme <THEME>
         \\    --vanilla
-        \\    --width <INT>
+        \\    --width <WIDTH>
         \\-d, --delimiter <CHAR>
         \\-h, --help
         \\-n, --row-numbers
@@ -80,6 +80,7 @@ pub const Args = struct {
         .SHELL = clap.parsers.enumeration(types.CompletionShell),
         .STRING = clap.parsers.string,
         .THEME = clap.parsers.enumeration(types.Theme),
+        .WIDTH = parseWidth,
     };
 
     // Parse a delimiter argument into one ASCII byte.
@@ -90,6 +91,15 @@ pub const Args = struct {
         return error.InvalidArgument;
     }
 
+    // Parse one width mode argument.
+    fn parseWidth(input: []const u8) error{InvalidArgument}!types.Width {
+        if (std.mem.eql(u8, input, "min")) return .min;
+        if (std.mem.eql(u8, input, "max")) return .max;
+        const value = std.fmt.parseInt(usize, input, 10) catch return error.InvalidArgument;
+        if (value == 0) return .auto;
+        return .{ .chars = value };
+    }
+
     // Parse argv into one top-level main event.
     pub fn init(alloc: std.mem.Allocator, argv: []const []const u8) !MainEvent {
         var diagnostics: clap.Diagnostic = .{};
@@ -262,7 +272,7 @@ test "parse option config case" {
     try testing.expectEqual(types.Theme.light, out.run.theme);
     try testing.expectEqualStrings("foo", out.run.title);
     try testing.expect(out.run.vanilla);
-    try testing.expectEqual(80, out.run.width);
+    try testing.expectEqual(types.Width{ .chars = 80 }, out.run.width);
     try testing.expect(out.run.row_numbers);
     try testing.expectEqualStrings("-", out.run.filename.?);
 }
@@ -288,6 +298,9 @@ test "parse option event cases" {
         .{ .argv = &.{ "--shuf", "-" } },
         .{ .argv = &.{ "--sort", "score,name", "-" } },
         .{ .argv = &.{ "--table", "players", "-" } },
+        .{ .argv = &.{ "--width", "min", "-" } },
+        .{ .argv = &.{ "--width", "max", "-" } },
+        .{ .argv = &.{ "--width", "80", "-" } },
         .{ .argv = &.{ "--completion", "zsh" }, .event = .{ .completion = .zsh } },
         .{ .argv = &.{"--help"}, .event = .help },
         .{ .argv = &.{"--version"}, .event = .version },
@@ -306,6 +319,9 @@ test "parse option event cases" {
             try testing.expect(parsed.run.shuffle);
         }
         if (std.mem.eql(u8, tc.argv[0], "--table")) try testing.expectEqualStrings("players", parsed.run.table);
+        if (std.mem.eql(u8, tc.argv[0], "--width") and std.mem.eql(u8, tc.argv[1], "min")) try testing.expectEqual(types.Width.min, parsed.run.width);
+        if (std.mem.eql(u8, tc.argv[0], "--width") and std.mem.eql(u8, tc.argv[1], "max")) try testing.expectEqual(types.Width.max, parsed.run.width);
+        if (std.mem.eql(u8, tc.argv[0], "--width") and std.mem.eql(u8, tc.argv[1], "80")) try testing.expectEqual(types.Width{ .chars = 80 }, parsed.run.width);
         if (std.mem.eql(u8, tc.argv[0], "--zebra")) try testing.expect(parsed.run.zebra);
         if (tc.event) |event| try testing.expectEqual(event, parsed);
     }
@@ -344,6 +360,7 @@ test "parse reject cases" {
         .{ .argv = &.{ "--head", "1", "--tail", "1" }, .err = error.InvalidHeadTail },
         .{ .argv = &.{ "--head", "0" }, .err = error.InvalidHeadValue },
         .{ .argv = &.{ "--tail", "0" }, .err = error.InvalidTailValue },
+        .{ .argv = &.{ "--width", "bogus" }, .err = error.InvalidArgument },
     };
 
     for (cases) |tc| try expectParseError(tc.err, tc.argv);

src/completion.zig

@@ -188,6 +188,7 @@ fn valuesFor(shell: types.CompletionShell, long: []const u8) ?[]const u8 {
     }
     if (std.mem.eql(u8, long, "--digits")) return "1 2 3 4 5 6";
     if (std.mem.eql(u8, long, "--theme")) return enumValues(types.Theme);
+    if (std.mem.eql(u8, long, "--width")) return "min max";
     return null;
 }