pretty

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 20, 2023 License: Apache-2.0 Imports: 2 Imported by: 0

Documentation

Overview

Package pretty prints documents based on a target line width.

See: https://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf

The paper describes a simple algorithm for printing a document tree with a single layout defined by text, newlines, and indentation. This concept is then expanded for documents that have more than one possible layout using a union type of two documents where both documents reduce to the same document, but one document has been flattened to a single line. A method ("best") is described that chooses the best of these two layouts (i.e., it removes all union types from a document tree). It works by tracking the desired and current line length and choosing either the flattened side of a union if it fits on the current line, or else the non-flattened 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/

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Pretty

func Pretty(d Doc, n int, useTabs bool, tabWidth int, keywordTransform func(string) string) string

Pretty returns a pretty-printed string for the Doc d at line length n and tab width t. Keyword Docs are filtered through keywordTransform if not nil. keywordTransform must not change the visible length of its argument. It can, for example, add invisible characters like control codes (colors, etc.).

Types

type Doc

type Doc interface {
	// contains filtered or unexported methods
}

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.

var HardLine Doc = hardline{}

HardLine is a newline and cannot be flattened.

var Line Doc = line{}

Line is a newline and is flattened to a space.

var Nil Doc = nilDoc{}

Nil is the NIL constructor.

var SoftBreak Doc = softbreak{}

SoftBreak is a newline and is flattened to an empty string.

func Align

func Align(d Doc) Doc

Align renders document d with the space-based nesting level set to the current column.

func AlignUnder

func AlignUnder(head, nested Doc) Doc

AlignUnder aligns nested to the right of head, and, if this does not fit on the line, nests nested under head.

func BracketDoc

func BracketDoc(l, x, r Doc) Doc

BracketDoc is like Bracket except it accepts Docs instead of strings.

func Concat

func Concat(a, b Doc) Doc

Concat is the <> constructor. This uses simplifyNil to avoid actually inserting NIL docs in the abstract tree.

func ConcatDoc

func ConcatDoc(a, b, between Doc) Doc

ConcatDoc concatenates two Docs with between.

func ConcatLine

func ConcatLine(a, b Doc) Doc

ConcatLine concatenates two Docs with a Line.

func ConcatSpace

func ConcatSpace(a, b Doc) Doc

ConcatSpace concatenates two Docs with a space.

func Fillwords

func Fillwords(d ...Doc) Doc

Fillwords fills lines with as many docs as will fit joined with a space or line.

func Fold

func Fold(f func(a, b Doc) Doc, d ...Doc) Doc

Fold applies f recursively to all Docs in d.

func FoldMap

func FoldMap(f func(a, b Doc) Doc, g func(Doc) Doc, d ...Doc) Doc

FoldMap applies f recursively to all Docs in d processed through g.

func Group

func Group(d Doc) Doc

Group will format d on one line if possible.

func Join

func Join(s string, d ...Doc) Doc

Join joins Docs d with string s and Line. There is no space between each item in d and the subsequent instance of s.

func JoinDoc

func JoinDoc(s Doc, d ...Doc) Doc

JoinDoc joins Docs d with Doc s.

func JoinGroupAligned

func JoinGroupAligned(head, divider string, d ...Doc) Doc

JoinGroupAligned nests joined d with divider under head.

func JoinNestedOuter

func JoinNestedOuter(lbl string, docFn func(string) Doc, d ...Doc) Doc

JoinNestedOuter attempts to de-indent the items after the first so that the operator appears in the right margin. This replacement is only done if there are enough "simple spaces" (as per previous uses of Align) to de-indent. No attempt is made to de-indent hard tabs, otherwise alignment may break on output devices with a different physical tab width. docFn should be set to Text or Keyword and will be used when converting lbl to a Doc.

func JoinNestedRight

func JoinNestedRight(sep Doc, nested ...Doc) Doc

JoinNestedRight nests nested with string s. Every item after the first is indented. For example: aaaa <sep> bbb

bbb

<sep> ccc

ccc

func Keyword

func Keyword(s string) Doc

Keyword is identical to Text except they are filtered by keywordTransform. The computed width is always len(s), regardless of the result of the result of the transform. This allows for things like coloring and other control characters in the output.

func NestS

func NestS(n int16, d Doc) Doc

NestS is the NESTS constructor.

func NestT

func NestT(d Doc) Doc

NestT is the NESTT constructor.

func NestUnder

func NestUnder(head, nested Doc) Doc

NestUnder nests nested under head.

func Stack

func Stack(d ...Doc) Doc

Stack concats Docs with a Line between each.

func Table

func Table(alignment TableAlignment, docFn func(string) Doc, rows ...TableRow) Doc

Table defines a document that formats a list of pairs of items either:

  • as a 2-column table, with the two columns aligned for example: SELECT aaa bbb FROM ccc
  • as sections, for example: SELECT aaa bbb FROM ccc

We restrict the left value in each list item to be a one-line string to make the width computation efficient.

For convenience, the function also skips over rows with a nil pointer as doc.

docFn should be set to Text or Keyword and will be used when converting TableRow label's to Docs.

func Text

func Text(s string) Doc

Text is the TEXT constructor.

type TableAlignment

type TableAlignment int

TableAlignment should be used as first argument to Table().

const (
	// TableNoAlign does not use alignment and instead uses NestUnder.
	TableNoAlign TableAlignment = iota
	// TableRightAlignFirstColumn right-aligns (left-pads) the first column.
	TableRightAlignFirstColumn
	// TableLeftAlignFirstColumn left-aligns (right-pads) the first column.
	TableLeftAlignFirstColumn
)

type TableRow

type TableRow struct {
	Label string
	Doc   Doc
}

TableRow is the data for one row of a RLTable (see below).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL