Merge #27256

27256: pretty: make the code clearer and faster r=knz a=knz

```
name           old time/op    new time/op    delta
PrettyData-16     1.79s ±31%     0.13s ± 3%  -92.50%  (p=0.008 n=5+5)

name           old alloc/op   new alloc/op   delta
PrettyData-16     630MB ± 1%      24MB ± 0%  -96.15%  (p=0.008 n=5+5)

name           old allocs/op  new allocs/op  delta
PrettyData-16     4.27M ± 0%     0.01M ± 0%  -99.74%  (p=0.008 n=5+5)
```


Co-authored-by: Raphael 'kena' Poss <knz@cockroachlabs.com>

Author: craig[bot]

pkg/util/pretty/document.go

@@ -28,17 +28,20 @@
 // side. The paper then describes various performance improvements that reduce
 // the search space of the best function such that it can complete in O(n)
 // instead of O(n^2) time, where n is the number of nodes.
+//
+// For example code with SQL to experiment further, refer to
+// https://github.com/knz/prettier/
+//
 package pretty
 
 import (
 	"fmt"
 )
 
-// Doc represents a document as described by the referenced paper.
+// Doc represents a document as described by the type "DOC" in the
+// referenced paper. This is the abstract representation constructed
+// by the pretty-printing code.
 type Doc interface {
-	// All Docs can uniquely convert themselves into a string so they can be
-	// memoized during better calculation.
-	String() string
 	isDoc()
 }
 
@@ -48,81 +51,70 @@ func (nilDoc) isDoc() {}
 func (concat) isDoc() {}
 func (nest) isDoc()   {}
 func (union) isDoc()  {}
-func (textX) isDoc()  {}
-func (lineX) isDoc()  {}
-
-func (d text) String() string   { return fmt.Sprintf("(%q)", string(d)) }
-func (line) String() string     { return "LINE" }
-func (nilDoc) String() string   { return "NIL" }
-func (d concat) String() string { return fmt.Sprintf("(%s :<> %s)", d.a, d.b) }
-func (d nest) String() string   { return fmt.Sprintf("(NEST %d %s)", d.n, d.d) }
-func (d union) String() string  { return fmt.Sprintf("(%s :<|> %s)", d.x, d.y) }
-func (d textX) String() string  { return fmt.Sprintf("(%q TEXTX %s)", d.s, d.d) }
-func (d lineX) String() string  { return fmt.Sprintf("(%q LINEX %s)", d.s, d.d) }
 
+//
+// Implementations of Doc ("DOC" in paper).
+//
+
+// nilDoc represents NIL :: DOC -- the empty doc.
 type nilDoc struct{}
 
-// Nil is the empty Doc.
+// Nil is the NIL constructor.
 var Nil nilDoc
 
+// text represents (TEXT s) :: DOC -- a simple text string.
 type text string
 
-// Text creates a string Doc.
+// Text is the TEXT constructor.
 func Text(s string) Doc {
 	return text(s)
 }
 
+// line represents LINE :: DOC -- a "soft line" that can be flattened to a space.
 type line struct{}
 
-// Line is either a newline or a space if flattened onto a single line.
+// Line is the LINE constructor.
 var Line line
 
+// concat represents (DOC <> DOC) :: DOC -- the concatenation of two docs.
 type concat struct {
 	a, b Doc
 }
 
-// fnNotNil runs returns fn(a, b). nil (the Go value) is converted to Nil (the
-// Doc). If either Doc is Nil, the other Doc is returned without invoking fn.
-func concatFn(a, b Doc, fn func(Doc, Doc) Doc) Doc {
-	if a == nil {
-		a = Nil
-	}
-	if b == nil {
-		b = Nil
-	}
-	if a == Nil {
-		return b
-	}
-	if b == Nil {
-		return a
-	}
-	return fn(a, b)
+// Concat is the <> constructor.
+// This uses simplifyNil to avoid actually inserting NIL docs
+// in the abstract tree.
+func Concat(a, b Doc) Doc {
+	return simplifyNil(a, b, func(a, b Doc) Doc { return concat{a, b} })
 }
 
-// Concat concatenates two Docs.
-func Concat(a, b Doc) Doc {
-	return concatFn(a, b, func(a, b Doc) Doc {
-		return concat{a, b}
-	})
+// nest represents (NEST Int DOC) :: DOC -- nesting a doc "under" another.
+// NEST indents d by s at effective length n. len(s) does not have to be
+// n. This allows s to be a tab character and n can be a tab width.
+type nest struct {
+	n int
+	s string
+	d Doc
 }
 
-// Fill concatenates a list of docs with spaces if possible,
-// otherwise with newlines.
-// See linked paper pp 14-15.
-// func Fill(d ...Doc) Doc {
-// 	switch len(d) {
-// 	case 0:
-// 		return Nil
-// 	case 1:
-// 		return d[0]
-// 	default:
-// 		rest := Fill(d[1:]...)
-// 		return union{
-// 			ConcatSpace(flatten(d[0]), rest),
-// 			ConcatLine(d[0], rest),
-// 		}
-// 	}
-// }
+// Nest is the NEST constructor.
+func Nest(n int, s string, d Doc) Doc {
+	return nest{n, s, d}
+}
+
+// union represents (DOC <|> DOC) :: DOC -- the union of two docs.
+// <|> is really the union of two sets of layouts. x and y must flatten to the
+// same layout. Additionally, no first line of a document in x is shorter
+// than some first line of a document in y; or, equivalently, every first
+// line in x is at least as long as every first line in y.
+//
+// The main use of the union is via the Group operator defined below.
+//
+// We do not provide a public constructor as this type is not
+// exported.
+type union struct {
+	x, y Doc
+}
 
 // Group will format d on one line if possible.
 func Group(d Doc) Doc {
@@ -149,35 +141,3 @@ func flatten(d Doc) Doc {
 		panic(fmt.Errorf("unknown type: %T", d))
 	}
 }
-
-type nest struct {
-	n int
-	s string
-	d Doc
-}
-
-// Nest indents d by s at effective length n. len(s) does not have to be
-// n. This allows s to be a tab character and n can be a tab width.
-func Nest(n int, s string, d Doc) Doc {
-	return nest{n, s, d}
-}
-
-// Doc types below are not directly accessible to users.
-
-// union is the union of two sets of layouts. x and y must flatten to the
-// same layout. Additionally, no first line of a document in x is shorter
-// than some first line of a document in y; or, equivalently, every first
-// line in x is at least as long as every first line in y.
-type union struct {
-	x, y Doc
-}
-
-type textX struct {
-	s string
-	d Doc
-}
-
-type lineX struct {
-	s string
-	d Doc
-}