Doc (api-compiler 0.0.5 API)

java.lang.Object
- com.google.api.tools.framework.snippet.Doc

```
public abstract class Doc
extends java.lang.Object
```
A Java implementation of a Wadler-Lindig pretty printer.
The pretty printer takes documents formed using a small set of operators, and formats them as strings suitable for display in a fixed number of columns.
A pretty-printer document (or Doc) is an immutable object that represents a piece of formatted text. A programmer can use the combinators EMPTY and text() to construct documents, and can concatenate documents with append(). For example:
```
 append(text("Good"), text("Morning"), text("World"))
 
```
pretty-prints as:
```
 GoodMorningWorld
 
```
Line breaking is controlled using the BREAK and group() combinators. Within a group() combinator, all breaks are printed using a common breaking policy, described using a Doc.GroupKind. For example:
```
 group(HORIZONTAL, append(text("Good"), BREAK, text("Morning"), BREAK, text("World"))
 
```
pretty-prints as
```
 Good Morning World
 
```
whereas
```
 group(VERTICAL, append(text("Good"), BREAK, text("Morning"), BREAK, text("World"))
 
```
pretty-prints as:
```
 Good
 Morning
 World
 
```
A key reason for the pretty-printer's expressive power is the automatic group kind (Doc.GroupKind.AUTO), which allows us to specify pretty-printing alternatives. Breaks in an automatic group are all printed as spaces, if the result would not overflow a single line, or as newlines, otherwise; the pretty-printer makes the appropriate choice at layout time depending on the space available.
The combinators nest(), align(), and hang() control indentation. For instance, the nest() combinator increases the indentation on new-lines by a number of columns. For example:
```
 nest(2, group(VERTICAL, append(text("Good"), BREAK, text("Morning"), BREAK, text("World")))
 
```
pretty-prints as:
```
 Good
   Morning
   World
 
```
Many methods of this class come in two variants:
- a static method, written Doc.group(xyz), and
- an instance method, written xyz.group().
The two may be used interchangeably, although the prefix (static) version usually leads to more readable code.
Wadler's original pretty printer is implemented in Haskell [1]. The original Wadler version relies on lazy evaluation, which Java does not have, so this implementation is based on Lindig's strict version in Objective Caml [2].
References:
- [1] Philip Wadler. "A Prettier Printer". Journal of Functional Programming, 1999.
- [2] Christian Lindig. "Strictly Pretty".
This library is thread-safe.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Doc.AnsiColor` ANSI color codes.
`static class`	`Doc.BlockBuilder` A builder for block-like constructs.
`static class`	`Doc.GroupKind` Describes how the breaks within a `group()` should be printed.

Field Summary

Fields
Modifier and Type	Field and Description
`static Doc`	`BREAK` The default break, which is printed either as a space in horizontal mode, or as a newline in vertical mode.
`static Doc`	`COMMA`
`static int`	`DEFAULT_INDENT` Size of the default indentation step in characters.
`static int`	`DEFAULT_WIDTH` The default number of columns to format for if no width is specified.
`static Doc`	`EMPTY` The empty document, which prints as `""` (the empty string).
`static Doc`	`LANGLE`
`static Doc`	`LBRACE`
`static Doc`	`LBRACKET`
`static Doc`	`LPAREN`
`static Doc`	`RANGLE`
`static Doc`	`RBRACE`
`static Doc`	`RBRACKET`
`static Doc`	`RPAREN`
`static Doc`	`SEMI`
`static Doc`	`SOFT_BREAK` A break that is printed either as the empty string in horizontal mode, or as a newline in vertical mode.

Constructor Summary

Constructors
Constructor and Description

Doc()

Constructors
Constructor and Description
`Doc()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`Doc`	`add(Doc that)` Appends document `that` to the document, with no breaks between documents.
`Doc`	`align()` Aligns breaks in the document at the current column.
`static Doc`	`align(Doc child)` Aligns breaks in document `child` at the current column.
`Doc`	`angles()` Wraps the document in angle brackets.
`static Doc`	`angles(Doc child)` Wraps document `child` in angle brackets.
`static Doc`	`append(Doc... docs)` Appends a list of documents, with no breaks between documents.
`static Doc`	`append(java.lang.Iterable<Doc> docs)` Appends a list of documents, with no breaks between documents.
`static Doc`	`binary(Doc left, Doc operator, Doc right)` Builds a binary with indentation of 4.
`static Doc`	`binary(int indent, Doc left, Doc operator, Doc right)` Build a binary operator invocation as
`static Doc.BlockBuilder`	`blockBuilder(Doc header)` Returns a builder for a block with indentation of 2.
`static Doc.BlockBuilder`	`blockBuilder(Doc header, int indent)` Returns a builder for a block which breaks vertically as
`Doc`	`braces()` Wraps the document in braces.
`static Doc`	`braces(Doc child)` Wraps document `child` in braces.
`Doc`	`brackets()` Wraps the document in brackets.
`static Doc`	`brackets(Doc child)` Wraps document `child` in brackets.
`static Doc`	`breakWith(java.lang.String representation)` Returns a break, which will be printed according to the policy of the closest enclosing group.
`Doc`	`color(Doc.AnsiColor c)` Colors the document using the specified ANSI color code.
`static Doc`	`color(Doc.AnsiColor c, Doc child)` Colors document `child` using the specified ANSI color code.
`Doc`	`fgroup()` Encloses the document in an `Doc.GroupKind.FILL` group.
`static Doc`	`fgroup(Doc child)` Encloses document `child` in an `Doc.GroupKind.FILL` group.
`protected abstract void`	`fits(com.google.api.tools.framework.snippet.Doc.LayoutMode mode, com.google.api.tools.framework.snippet.Doc.FitsState state)` Determines if this document fits in `state.width` columns, up to the next newline.
`protected abstract int`	`format(java.lang.StringBuilder builder, java.util.Deque<com.google.api.tools.framework.snippet.Doc.Agendum> agenda, int width, int indentation, int consumed, com.google.api.tools.framework.snippet.Doc.LayoutMode mode)` Pretty-print a document into a `StringBuilder`.
`Doc`	`group()` Encloses the document in an `Doc.GroupKind.AUTO` group.
`Doc`	`group(Doc.GroupKind kind)` Encloses the document in an group of a given `kind`.
`static Doc`	`group(Doc.GroupKind kind, Doc child)` Encloses document `child` in a group.
`static Doc`	`group(Doc child)` Encloses document `child` in an `Doc.GroupKind.AUTO` group.
`Doc`	`hang()` Performs a hanging indentation of the document with an indent of `DEFAULT_INDENT` spaces.
`static Doc`	`hang(Doc child)` Performs a hanging indentation of document `child` with an indent of `DEFAULT_INDENT` spaces.
`Doc`	`hang(int indent)` Performs a hanging indentation of the document with an indent of `indent` spaces.
`static Doc`	`hang(int indent, Doc child)` Performs a hanging indentation of document `child` with an indent of `indent` spaces.
`Doc`	`hgroup()` Encloses the document in an `Doc.GroupKind.HORIZONTAL` group.
`static Doc`	`hgroup(Doc child)` Encloses document `child` in an `Doc.GroupKind.HORIZONTAL` group.
`Doc`	`indentAt(int indent)` Sets the indentation level of the document to `indent` columns.
`static Doc`	`indentAt(int indent, Doc child)` Sets the indentation level of document `child` to `indent` columns.
`static Doc`	`invocation(Doc function, java.lang.Iterable<Doc> arguments)` Build a function invocation with indentation of 4 for arguments.
`static Doc`	`invocation(int indent, Doc function, java.lang.Iterable<Doc> arguments)` Build a function invocation as
`abstract boolean`	`isWhitespace()` Determines whether the document is empty except of whitespace.
`static Doc`	`join(Doc... docs)` Appends documents, placing a `BREAK` between adjacent documents.
`static Doc`	`join(java.lang.Iterable<Doc> docs)` Appends documents, placing a `BREAK` between adjacent documents.
`static Doc`	`joinWith(Doc separator, Doc... docs)` Appends documents, placing the separator `separator` between adjacent documents.
`static Doc`	`joinWith(Doc separator, java.lang.Iterable<Doc> docs)` Appends documents, placing the separator `separator` between adjacent documents.
`Doc`	`nest()` Increase the indentation level of the document by `DEFAULT_INDENT` spaces.
`static Doc`	`nest(Doc child)` Increase the indentation level of document `child` by `DEFAULT_INDENT` spaces.
`Doc`	`nest(int indent)` Increases the indentation level of the document by `indent` columns.
`static Doc`	`nest(int indent, Doc child)` Increases the indentation level of document `child` by `indent` columns.
`Doc`	`parens()` Wraps the document in parentheses.
`static Doc`	`parens(Doc child)` Wraps document `child` in parentheses.
`java.lang.String`	`prettyPrint()` Pretty prints the document, formatted for `DEFAULT_WIDTH` columns.
`java.lang.String`	`prettyPrint(int width)` Pretty prints the document, formatted for `width` columns.
`void`	`prettyPrint(java.lang.StringBuilder builder)` Pretty prints the document into a `StringBuilder`, formatted for `DEFAULT_WIDTH` columns.
`void`	`prettyPrint(java.lang.StringBuilder builder, int width)` Pretty prints the document into a `StringBuilder`, formatted for `width` columns.
`static java.util.List<Doc>`	`punctuate(Doc separator, java.util.List<Doc> docs)` Appends a separator to all documents except the last one in a list.
`static Doc`	`text(java.lang.String text)` Returns a document representing the literal text `text`.
`static java.util.List<Doc>`	`texts(java.lang.Iterable<java.lang.String> strings)` Applies the `text()` combinator to a sequence of strings.
`static java.util.List<Doc>`	`texts(java.lang.String... strings)` Applies the `text()` combinator to a sequence of strings.
`java.lang.String`	`toString()`
`Doc`	`vgroup()` Encloses the document in an `Doc.GroupKind.VERTICAL` group.
`static Doc`	`vgroup(Doc child)` Encloses document `child` in an `Doc.GroupKind.VERTICAL` group.
`static Doc`	`words(java.lang.String input)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT_INDENT
```
public static final int DEFAULT_INDENT
```
    Size of the default indentation step in characters.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_WIDTH
```
public static final int DEFAULT_WIDTH
```
    The default number of columns to format for if no width is specified.
    
    See Also:
    
    Constant Field Values
  - EMPTY
```
public static final Doc EMPTY
```
    The empty document, which prints as "" (the empty string).
  - COMMA
```
public static final Doc COMMA
```
  - LBRACKET
```
public static final Doc LBRACKET
```
  - RBRACKET
```
public static final Doc RBRACKET
```
  - LPAREN
```
public static final Doc LPAREN
```
  - RPAREN
```
public static final Doc RPAREN
```
  - LBRACE
```
public static final Doc LBRACE
```
  - RBRACE
```
public static final Doc RBRACE
```
  - LANGLE
```
public static final Doc LANGLE
```
  - RANGLE
```
public static final Doc RANGLE
```
  - SEMI
```
public static final Doc SEMI
```
  - BREAK
```
public static final Doc BREAK
```
    The default break, which is printed either as a space in horizontal mode, or as a newline in vertical mode. For example:
    - group(HORIZONTAL, BREAK) prints as " "
    - group(VERTICAL, BREAK) prints as "\n"
  - SOFT_BREAK
```
public static final Doc SOFT_BREAK
```
    A break that is printed either as the empty string in horizontal mode, or as a newline in vertical mode.
    - group(HORIZONTAL, SOFT_BREAK) prints as ""
    - group(VERTICAL, SOFT_BREAK) prints as "\n"
- Constructor Detail
  - Doc
```
public Doc()
```
- Method Detail
  - text
```
public static Doc text(java.lang.String text)
```
    Returns a document representing the literal text text. Assumes that there are no newline characters in the representation. (If there are new-line characters the pretty-printer will print them as-is, usually leading to poorly formatted output.) For example, text("hello") prints as "hello".
  - texts
```
public static java.util.List<Doc> texts(java.lang.Iterable<java.lang.String> strings)
```
    Applies the text() combinator to a sequence of strings.
  - texts
```
public static java.util.List<Doc> texts(java.lang.String... strings)
```
    Applies the text() combinator to a sequence of strings.
  - words
```
public static Doc words(java.lang.String input)
```
  - breakWith
```
public static Doc breakWith(java.lang.String representation)
```
    Returns a break, which will be printed according to the policy of the closest enclosing group.
    The representation argument describes how the break should be printed in horizontal mode; the representation is ignored in vertical mode. Assumes that there are no newline characters in the representation. For example:
    - group(HORIZONTAL, breakWith("-")) prints as "-"
    - group(VERTICAL, breakWith("-")) prints as "\n"
  - add
```
public Doc add(Doc that)
```
    Appends document that to the document, with no breaks between documents. For example, text("a").add(text("b c")) prints as "ab c".
  - append
```
public static Doc append(Doc... docs)
```
    Appends a list of documents, with no breaks between documents.
  - append
```
public static Doc append(java.lang.Iterable<Doc> docs)
```
    Appends a list of documents, with no breaks between documents.
  - joinWith
```
public static Doc joinWith(Doc separator,
                           Doc... docs)
```
    Appends documents, placing the separator separator between adjacent documents. For example,
```
 joinWith(append(COMMA, BREAK), text("a"), text("b"), text("c")))
 
```
    prints as "a, b, c" in horizontal mode, or as "a,\nb,\nc" in vertical mode.
  - joinWith
```
public static Doc joinWith(Doc separator,
                           java.lang.Iterable<Doc> docs)
```
    Appends documents, placing the separator separator between adjacent documents.
  - join
```
public static Doc join(Doc... docs)
```
    Appends documents, placing a BREAK between adjacent documents.
  - join
```
public static Doc join(java.lang.Iterable<Doc> docs)
```
    Appends documents, placing a BREAK between adjacent documents.
  - group
```
public static Doc group(Doc.GroupKind kind,
                        Doc child)
```
    Encloses document child in a group. Breaks are formatted according to the policy of the closest enclosing group.
    For example, consider formatting the document
```
 group(p, join(break(), text("xx"), text("yy"), text("zz"), text("ww")))
 
```
    under different policies p for different column widths. Under policy Doc.GroupKind.HORIZONTAL, all breaks in a group are printed as spaces, regardless of whether that leads to an overflow:
    - Width 3: "xx yy zz ww"
    - Width 80: "xx yy zz ww"
    Under policy Doc.GroupKind.VERTICAL, all breaks are printed as newlines:
    - Width 3: "xx\nyy\nzz\nww"
    - Width 80: "xx\nyy\nzz\nww"
    Under policy Doc.GroupKind.AUTO, all breaks in the group are printed as spaces if the result would not overflow a line, or as newlines, otherwise:
    - Width 3: "xx\nyy\nzz\nww"
    - Width 80: "xx yy zz ww"
    Under policy Doc.GroupKind.FILL, each break is printed as a space if that would not lead to overflow, or as a newline, otherwise. Unlike Doc.GroupKind.AUTO, a separate decision is made for each break.
    - Width 3: "xx\nyy\nzz\nww"
    - Width 5: "xx yy\nzz ww"
    - Width 80: "xx yy zz ww"
  - group
```
public static Doc group(Doc child)
```
    Encloses document child in an Doc.GroupKind.AUTO group.
  - vgroup
```
public static Doc vgroup(Doc child)
```
    Encloses document child in an Doc.GroupKind.VERTICAL group.
  - hgroup
```
public static Doc hgroup(Doc child)
```
    Encloses document child in an Doc.GroupKind.HORIZONTAL group.
  - fgroup
```
public static Doc fgroup(Doc child)
```
    Encloses document child in an Doc.GroupKind.FILL group.
  - group
```
public Doc group()
```
    Encloses the document in an Doc.GroupKind.AUTO group.
  - vgroup
```
public Doc vgroup()
```
    Encloses the document in an Doc.GroupKind.VERTICAL group.
  - hgroup
```
public Doc hgroup()
```
    Encloses the document in an Doc.GroupKind.HORIZONTAL group.
  - fgroup
```
public Doc fgroup()
```
    Encloses the document in an Doc.GroupKind.FILL group.
  - group
```
public Doc group(Doc.GroupKind kind)
```
    Encloses the document in an group of a given kind.
  - nest
```
public static Doc nest(int indent,
                       Doc child)
```
    Increases the indentation level of document child by indent columns.
    After each vertical break, a number of spaces equal to the current indentation level is added. For example:
```
 nest(2, group(VERTICAL, join(BREAK, text("x"), text("y"), text("z"))))
 
```
    prints as:
```
 x
   y
   z
 
```
    Note that indentation is only relevant for vertical breaks; for example
```
 nest(2, group(HORIZONTAL, join(BREAK, text("x"), text("y"), text("z"))))
 
```
    prints as:
```
 x y z
 
```
    Indentation is cumulative, for example:
```
 nest(2, nest(2, group(VERTICAL,
                       join(BREAK, text("x"), text("y"), text("z")))))
 
```
    prints as:
```
 x
     y
     z
 
```
  - nest
```
public Doc nest(int indent)
```
    Increases the indentation level of the document by indent columns.
  - nest
```
public static Doc nest(Doc child)
```
    Increase the indentation level of document child by DEFAULT_INDENT spaces.
  - nest
```
public Doc nest()
```
    Increase the indentation level of the document by DEFAULT_INDENT spaces.
  - align
```
public static Doc align(Doc child)
```
    Aligns breaks in document child at the current column. For example:
```
 append(text("alist = ["),
        align(join(append(text(","), BREAK),
                   text("x"), text("y"), text("z"))),
        text("]"))
 
```
    prints in horizontal mode as:
```
 alist = [x, y, z]
 
```
    and prints in vertical mode as:
```
 alist = [x,
          y,
          z]
 
```
  - align
```
public Doc align()
```
    Aligns breaks in the document at the current column.
  - hang
```
public static Doc hang(int indent,
                       Doc child)
```
    Performs a hanging indentation of document child with an indent of indent spaces. For example
```
 append(text("alist = ["),
        hang(join(append(text(","), BREAK),
                  text("x"), text("y"), text("z"))),
        text("]"))
 
```
    prints in vertical mode as:
```
 alist = [x,
            y,
            z]
 
```
    hang(indent, child) is a shorthand for align(nest(indent, child)).
  - hang
```
public static Doc hang(Doc child)
```
    Performs a hanging indentation of document child with an indent of DEFAULT_INDENT spaces.
  - hang
```
public Doc hang(int indent)
```
    Performs a hanging indentation of the document with an indent of indent spaces.
  - hang
```
public Doc hang()
```
    Performs a hanging indentation of the document with an indent of DEFAULT_INDENT spaces.
  - indentAt
```
public static Doc indentAt(int indent,
                           Doc child)
```
    Sets the indentation level of document child to indent columns.
  - indentAt
```
public Doc indentAt(int indent)
```
    Sets the indentation level of the document to indent columns.
  - brackets
```
public static Doc brackets(Doc child)
```
    Wraps document child in brackets. For example, brackets(text("x")) prints as "[x]".
  - brackets
```
public Doc brackets()
```
    Wraps the document in brackets.
  - parens
```
public static Doc parens(Doc child)
```
    Wraps document child in parentheses. For example, parens(text("x")) prints as "(x)".
  - parens
```
public Doc parens()
```
    Wraps the document in parentheses.
  - braces
```
public static Doc braces(Doc child)
```
    Wraps document child in braces. For example, braces(text("x")) prints as "{x}".
  - braces
```
public Doc braces()
```
    Wraps the document in braces.
  - angles
```
public static Doc angles(Doc child)
```
    Wraps document child in angle brackets. For example, angles(text("x")) prints as "<x>".
  - angles
```
public Doc angles()
```
    Wraps the document in angle brackets.
  - color
```
public static Doc color(Doc.AnsiColor c,
                        Doc child)
```
    Colors document child using the specified ANSI color code. TODO(user): nested colors do not work.
  - color
```
public Doc color(Doc.AnsiColor c)
```
    Colors the document using the specified ANSI color code.
  - punctuate
```
public static java.util.List<Doc> punctuate(Doc separator,
                                            java.util.List<Doc> docs)
```
    Appends a separator to all documents except the last one in a list.
  - blockBuilder
```
public static Doc.BlockBuilder blockBuilder(Doc header,
                                            int indent)
```
    Returns a builder for a block which breaks vertically as
```
   header
     line
     line
     ...
   [footer]
 
```
  - blockBuilder
```
public static Doc.BlockBuilder blockBuilder(Doc header)
```
    Returns a builder for a block with indentation of 2.
  - invocation
```
public static Doc invocation(int indent,
                             Doc function,
                             java.lang.Iterable<Doc> arguments)
```
    Build a function invocation as
```
   function ( arg1, BREAK arg2, BREAK ... argn )
 
```
    i.e. a break is only allowed after the first argument and before the last argument.
  - invocation
```
public static Doc invocation(Doc function,
                             java.lang.Iterable<Doc> arguments)
```
    Build a function invocation with indentation of 4 for arguments.
  - binary
```
public static Doc binary(int indent,
                         Doc left,
                         Doc operator,
                         Doc right)
```
    Build a binary operator invocation as
```
   left BREAK operator SPACE right
 
```
  - binary
```
public static Doc binary(Doc left,
                         Doc operator,
                         Doc right)
```
    Builds a binary with indentation of 4.
  - isWhitespace
```
public abstract boolean isWhitespace()
```
    Determines whether the document is empty except of whitespace.
  - prettyPrint
```
public void prettyPrint(java.lang.StringBuilder builder,
                        int width)
```
    Pretty prints the document into a StringBuilder, formatted for width columns.
  - prettyPrint
```
public void prettyPrint(java.lang.StringBuilder builder)
```
    Pretty prints the document into a StringBuilder, formatted for DEFAULT_WIDTH columns.
  - prettyPrint
```
public java.lang.String prettyPrint(int width)
```
    Pretty prints the document, formatted for width columns. Returns the result as a string.
  - prettyPrint
```
public java.lang.String prettyPrint()
```
    Pretty prints the document, formatted for DEFAULT_WIDTH columns. Returns the result as a string.
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - fits
```
protected abstract void fits(com.google.api.tools.framework.snippet.Doc.LayoutMode mode,
                             com.google.api.tools.framework.snippet.Doc.FitsState state)
```
    Determines if this document fits in state.width columns, up to the next newline. Updates state.width to the new number of columns, and sets state.done to true if a newline is encountered or the line overflows.
  - format
```
protected abstract int format(java.lang.StringBuilder builder,
                              java.util.Deque<com.google.api.tools.framework.snippet.Doc.Agendum> agenda,
                              int width,
                              int indentation,
                              int consumed,
                              com.google.api.tools.framework.snippet.Doc.LayoutMode mode)
```
    Pretty-print a document into a StringBuilder. Updates the agenda, and returns an updated number of consumed characters.
    
    Parameters:
    
    agenda - the document layout worklist.
    
    width - number of columns in the target layout (e.g., 80)
    
    indentation - current number of columns of indentation.
    
    consumed - number of columns already used in the current line.
    
    mode - the current layout mode.
    
    Returns:
    
    an updated number of consumed characters.

Class Doc

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_INDENT

DEFAULT_WIDTH

EMPTY

COMMA

LBRACKET

RBRACKET

LPAREN

RPAREN

LBRACE

RBRACE

LANGLE

RANGLE

SEMI

BREAK

SOFT_BREAK

Constructor Detail

Doc

Method Detail

text

texts

texts

words

breakWith

add

append

append

joinWith

joinWith

join

join

group

group

vgroup

hgroup

fgroup

group

vgroup

hgroup

fgroup

group

nest

nest

nest

nest

align

align

hang

hang

hang

hang

indentAt

indentAt

brackets

brackets

parens

parens

braces

braces

angles

angles

color

color

punctuate

blockBuilder

blockBuilder

invocation

invocation

binary

binary

isWhitespace

prettyPrint

prettyPrint

prettyPrint