internal/ascii: new package

Add a simple whiteboard package (inspired by datadriven/diagram.Whiteboard) for
writing ASCII within a two-dimensional buffer.

Author: jbowens

internal/ascii/testdata/ascii_board

@@ -0,0 +1,60 @@
+make w=8 h=8
+----
+
+write
+0  1  hello
+1  1  world
+----
+ hello
+ world
+
+write
+0 0 .
+1 6 !
+----
+.hello
+ world!
+
+write
+0 24 1234567890
+----
+.hello                  1234567890
+ world!
+
+write
+9 0 boop!
+----
+----
+.hello                  1234567890
+ world!
+
+
+
+
+
+
+
+boop!
+----
+----
+
+make w=1 h=1
+----
+
+write
+1 1 X
+0 2 O
+0 0 X
+2 2 O
+----
+X O
+ X
+  O
+
+write
+1 2 X
+1 0 O
+----
+X O
+OXX
+  O

internal/ascii/whiteboard.go

@@ -0,0 +1,190 @@
+// Copyright 2025 The LevelDB-Go and Pebble Authors. All rights reserved. Use
+// of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
+
+package ascii
+
+import (
+	"bytes"
+	"fmt"
+	"strings"
+)
+
+// Board is a simple ASCII-based board for rendering ASCII text diagrams.
+type Board struct {
+	buf   []byte
+	width int
+}
+
+// Make returns a new Board with the given initial width and height.
+func Make(w, h int) Board {
+	buf := make([]byte, 0, w*h)
+	return Board{buf: buf, width: w}
+}
+
+// At returns a position at the given coordinates.
+func (b *Board) At(r, c int) Cursor {
+	if r >= b.lines() {
+		b.buf = append(b.buf, bytes.Repeat([]byte{' '}, (r-b.lines()+1)*b.width)...)
+	}
+	return Cursor{b: b, r: r, c: c}
+}
+
+// NewLine appends a new line to the board and returns a position at the
+// beginning of the line.
+func (b *Board) NewLine() Cursor {
+	return b.At(b.lines(), 0)
+}
+
+// String returns the Board as a string.
+func (b *Board) String() string {
+	return b.Render("")
+}
+
+// Render returns the Board as a string, with every line prefixed by
+// indent.
+func (b *Board) Render(indent string) string {
+	var buf bytes.Buffer
+	for r := 0; r < b.lines(); r++ {
+		if r > 0 {
+			buf.WriteByte('\n')
+		}
+		buf.WriteString(indent)
+		buf.Write(bytes.TrimRight(b.row(r), " "))
+	}
+	return buf.String()
+}
+
+// Reset resets the board to the given width and clears the contents.
+func (b *Board) Reset(w int) {
+	b.buf = b.buf[:0]
+	b.width = w
+}
+
+func (b *Board) write(r, c int, s string) {
+	if c+len(s) > b.width {
+		b.growWidth(c + len(s))
+	}
+	row := b.row(r)
+	for i := 0; i < len(s); i++ {
+		row[c+i] = s[i]
+	}
+}
+
+func (b *Board) repeat(r, c int, n int, ch byte) {
+	if c+n > b.width {
+		b.growWidth(c + n)
+	}
+	row := b.row(r)
+	for i := 0; i < n; i++ {
+		row[c+i] = ch
+	}
+}
+
+func (b *Board) growWidth(w int) {
+	buf := bytes.Repeat([]byte{' '}, w*b.lines())
+	for i := 0; i < b.lines(); i++ {
+		copy(buf[i*w:(i+1)*w], b.buf[i*b.width:(i+1)*b.width])
+	}
+	b.buf = buf
+	b.width = w
+}
+
+func (b *Board) lines() int {
+	return len(b.buf) / b.width
+}
+
+func (b *Board) row(r int) []byte {
+	if sz := (r + 1) * b.width; sz > len(b.buf) {
+		b.buf = append(b.buf, bytes.Repeat([]byte{' '}, sz-len(b.buf))...)
+	}
+	return b.buf[r*b.width : (r+1)*b.width]
+}
+
+// Cursor is a position on a Board.
+type Cursor struct {
+	b    *Board
+	r, c int
+	// carriageReturnCol is the column to which newlines will return.  It is set
+	// by SetCarriageReturnPosition. It's used when writing text in a column,
+	// and newlines should return to the same column position.
+	carriageReturnCol int
+}
+
+// Offset returns a new cursor with the given offset from the current cursor.
+func (c Cursor) Offset(dr, dc int) Cursor {
+	c.r += dr
+	c.c += dc
+	return c
+}
+
+// SetCarriageReturnPosition returns a copy of the cursor, but with a carriage
+// return position set so that newlines written to the resulting Cursor will
+// return to the current column.
+func (c Cursor) SetCarriageReturnPosition() Cursor {
+	c.carriageReturnCol = c.c
+	return c
+}
+
+// Row returns the row of the current position.
+func (c Cursor) Row() int {
+	return c.r
+}
+
+// Column returns the column of the current position.
+func (c Cursor) Column() int {
+	return c.c
+}
+
+// SetRow returns a copy of the cursor, but with the row set to the given value.
+func (c Cursor) SetRow(row int) Cursor {
+	c.r = row
+	return c
+}
+
+// SetColumn returns a copy of the cursor, but with the column set to the given
+// value.
+func (c Cursor) SetColumn(col int) Cursor {
+	c.c = col
+	return c
+}
+
+// Printf writes the formatted string to cursor, returning a cursor where the
+// written text ends.
+func (c Cursor) Printf(format string, args ...interface{}) Cursor {
+	return c.WriteString(fmt.Sprintf(format, args...))
+}
+
+// WriteString writes the provided string starting at the cursor, returning a
+// cursor where the written text ends. Newlines in the string break to the next
+// row, with the column reset to the cursor's carriage return column.
+func (c Cursor) WriteString(s string) Cursor {
+	for len(s) > 0 {
+		i := strings.IndexByte(s, '\n')
+		if i >= 0 {
+			c.b.write(c.r, c.c, s[:i])
+			c = c.NewlineReturn()
+			s = s[i+1:]
+		} else {
+			c.b.write(c.r, c.c, s)
+			c.c += len(s)
+			break
+		}
+	}
+	return c
+}
+
+// RepeatByte writes the given byte n times starting at the cursor, returning a
+// cursor where the written bytes end.
+func (c Cursor) RepeatByte(n int, b byte) Cursor {
+	c.b.repeat(c.r, c.c, n, b)
+	return c.Offset(0, n)
+}
+
+// NewlineReturn returns a cursor at the next line, with the column set to the
+// cursor's carriage return column.
+func (c Cursor) NewlineReturn() Cursor {
+	c.r += 1
+	c.c = c.carriageReturnCol
+	return c
+}

internal/ascii/whiteboard_test.go

@@ -0,0 +1,62 @@
+// Copyright 2025 The LevelDB-Go and Pebble Authors. All rights reserved. Use
+// of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
+
+package ascii
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/cockroachdb/datadriven"
+	"github.com/cockroachdb/pebble/internal/strparse"
+	"github.com/stretchr/testify/require"
+)
+
+func TestASCIIBoardDatadriven(t *testing.T) {
+	var board Board
+	datadriven.RunTest(t, "testdata/ascii_board", func(t *testing.T, td *datadriven.TestData) string {
+		switch td.Cmd {
+		case "make":
+			var w, h int
+			td.ScanArgs(t, "w", &w)
+			td.ScanArgs(t, "h", &h)
+			board = Make(w, h)
+			return board.String()
+		case "write":
+			for _, line := range strings.Split(td.Input, "\n") {
+				p := strparse.MakeParser(" ", line)
+				r := p.Int()
+				c := p.Int()
+				board.At(r, c).WriteString(p.Remaining())
+			}
+			return board.String()
+		default:
+			return fmt.Sprintf("unknown command: %s", td.Cmd)
+		}
+	})
+}
+
+func TestASCIIBoard(t *testing.T) {
+	board := Make(10, 2)
+	board.At(0, 0).Printf("Hello\nworld!")
+	require.Equal(t, `Hello
+world!`, board.String())
+
+	board.Reset(10)
+	cur := board.At(1, 5).SetCarriageReturnPosition().Printf("a\nb\nc\nd\ne\nf\ng\nh\ni\nj\n")
+	require.Equal(t, 11, cur.Row())
+	require.Equal(t, 5, cur.Column())
+	require.Equal(t, `
+     a
+     b
+     c
+     d
+     e
+     f
+     g
+     h
+     i
+     j`, board.String())
+}