USING: help io kernel prettyprint words ;

IN: help

: $prettyprinting-note
    drop {
        "This word should only be called from inside the "
        { $link with-pprint } " combinator."
    } $notes ;

HELP: position
{ $var-description "The prettyprinter's current character position." } ;

HELP: last-newline
{ $var-description "The character position of the last newline output by the prettyprinter." } ;

HELP: recursion-check
{ $var-description "The current nesting of collections being output by the prettyprinter, used to detect circularity and prevent infinite recursion." } ;

HELP: line-count
{ $var-description "The number of lines output by the prettyprinter so far, used for line limiting (see " { $link line-limit } ")." } ;

HELP: end-printing
{ $var-description "A continuation captured by " { $link do-pprint } " that breaks out of the printer." } ;

HELP: indent
{ $var-description "The prettyprinter's current indent level." } ;

HELP: pprinter-stack
{ $var-description "A stack of " { $link block } " objects currently being constructed by the prettyprinter." } ;

HELP: tab-size
{ $var-description "Prettyprinter tab size. Indent nesting is always a multiple of the tab size. The default is 4." } ;

HELP: margin
{ $var-description "The maximum line length, in characters. Lines longer than the margin are wrapped. The default is 64." } ;

HELP: nesting-limit
{ $var-description "The maximum nesting level. Structures that nest further than this will simply print as a pound sign (#). The default is " { $link f } ", denoting unlimited nesting depth." } ;

HELP: length-limit
{ $var-description "The maximum printed sequence length. Sequences longer than this are truncated, and \"...\" is output in place of remaining elements. The default is " { $link f } ", denoting unlimited sequence length." } ;

HELP: line-limit
{ $var-description "The maximum number of lines output by the prettyprinter before output is truncated with \"...\". The default is " { $link f } ", denoting unlimited line count." } ;

HELP: string-limit
{ $var-description "Toggles whenever printed strings are truncated to the margin." } ;

HELP: pprint-section*
{ $values { "section" "a section" } }
{ $contract "Prettyprints an object delegating to an instance of " { $link section } ", performing wrapping and indentation using the formatting information in the section." } ;

HELP: section
{ $class-description "A section represents a run of text with a known length and indentation level." } ;

HELP: line-limit?
{ $values { "?" "a boolean" } }
{ $description "Tests if the line number limit has been reached, and thus if prettyprinting should stop." } ;

HELP: do-indent
{ $description "Outputs the current indent nesting to the default stream." } ;

HELP: fresh-line
{ $values { "n" "the current column position" } }
{ $description "Advances the prettyprinter by one line unless the current line is empty. If the line limit is exceeded, escapes the prettyprinter by restoring a continuation captured in " { $link do-pprint } "." } ;

HELP: <text>
{ $values { "string" "a string" } { "style" "a hashtable" } { "text" "a new text section" } }
{ $description "Creates a text section." } ;

HELP: block
{ $class-description "A block is a section consisting of whitespace-separated child sections." } ;

HELP: pprinter-block
{ $values { "block" "a block section" } }
{ $description "Outputs the block currently being constructed." }
$prettyprinting-note ;

HELP: block-empty?
{ $values { "section" "a section" } { "?" "a boolean" } }
{ $description "Tests if a section is empty. A section is empty if it is a block with no children." } ;

HELP: add-section
{ $values { "section" "a section" } }
{ $description "Adds a section to the current block." }
$prettyprinting-note ;

HELP: text
{ $values { "string" "a string" } }
{ $description "Adds a section consisting of a single string to the current block. The current style on the style stack is used; see " { $link with-style } "." }
$prettyprinting-note ;

HELP: <indent
{ $values { "section" "a section" } }
{ $description "Increases indent level by the indent level of the section." }
$prettyprinting-note ;

HELP: indent>
{ $values { "section" "a section" } }
{ $description "Decreases indent level by the indent level of the section." }
$prettyprinting-note ;

HELP: inset-section
{ $values { "section" "a section" } }
{ $description "Prints a section surrounded by line breaks and with increased indent." } ;

HELP: section-fits?
{ $values { "section" "a section" } { "?" "a boolean" } }
{ $description "Tests if a section should be printed on the current line." } ;

HELP: pprint-section
{ $values { "section" "a section" } }
{ $description "Prints a section, with a line break and increase in indent level if necessary." } ;

HELP: newline
{ $description "Adds a section introducing an unconditional line break to the current block." }
$prettyprinting-note ;

HELP: advance
{ $values { "section" "a section" } }
{ $description "Emits a space unless the section is the first section on the line." } ;

HELP: <block
{ $values { "style" "a style" } }
{ $description "Begins a nested block." }
$prettyprinting-note ;

HELP: end-block
{ $values { "block" "a block" } }
{ $description "Save the current position as the end position of the block." } ;

HELP: (block>)
{ $description "Adds the current block to its containing block." }
$prettyprinting-note ;

HELP: last-block?
{ $values { "?" "a boolean" } }
{ $description "Tests if the current block is the top-level block." }
$prettyprinting-note ;

HELP: block>
{ $description "Adds the current block to its containing block, unless the current block is the top-level block in which case it does nothing." }
{ $notes "This word is used to end blocks in order for the prettyprinter to be forgiving in the case of mismatched begin/end pairs (this can happen when printing parsing words)." }
$prettyprinting-note ;

HELP: block;
{ $description "Adds the current block to its containing block. The current block will be terminated by an unconditional newline." }
$prettyprinting-note ;

HELP: end-blocks
{ $description "Unwind all prettyprinter state to the top level block." }
$prettyprinting-note ;

HELP: do-pprint
{ $description "Recursively output all children of the top-level block. The continuation is restored and output terminates if the line length is exceeded; this test is performed in " { $link fresh-line } "." } ;

HELP: pprint*
{ $values { "obj" "an object" } }
{ $contract "Adds sections to the current block corresponding to the prettyprinted representation of the object." }
$prettyprinting-note
{ $see-also text newline <block block> block; } ;

HELP: pprint-word
{ $values { "word" "a word" } }
{ $description "Adds a text section for the word. Unlike the " { $link word } " method of " { $link pprint* } ", this does not add a " { $link POSTPONE: POSTPONE: } " prefix to parsing words." }
$prettyprinting-note ;

HELP: ch>ascii-escape
{ $values { "ch" "a character" } { "str" "a string" } }
{ $description "Converts a character to an escape code." } ;

HELP: ch>unicode-escape
{ $values { "ch" "a character" } { "str" "a string" } }
{ $description "Converts a character to a Unicode escape code (" { $snippet "\\u1234"} ")." } ;

HELP: unparse-ch
{ $values { "ch" "a character" } }
{ $description "Adds the character to the sequence being constructed (see " { $link "namespaces-make" } "). If the character can appear in a string literal, it is added directly, otherwise an escape code is added." } ;

HELP: do-string-limit
{ $values { "str" "a string" } { "trimmed" "a possibly trimmed string" } }
{ $description "If " { $link string-limit } " is on, trims the string such that it does not exceed the margin, appending \"...\" if trimming took place." } ;

HELP: pprint-string
{ $values { "str" "a string" } { "prefix" "a prefix string" } }
{ $description "Outputs a text section consisting of the prefix, the string, and a final quote (\")." }
$prettyprinting-note ;

HELP: nesting-limit?
{ $values { "?" "a boolean" } }
{ $description "Tests if the " { $link nesting-limit } " has been reached." }
$prettyprinting-note ;

HELP: check-recursion
{ $values { "obj" "an object" } { "quot" "a quotation with stack effect " { $snippet "( obj -- )" } } }
{ $description "If the object is already being printed, that is, if the prettyprinter has encountered a cycle in the object graph, or if the maximum nesting depth has been reached, outputs a dummy string. Otherwise applies the quotation to the object." }
$prettyprinting-note ;

HELP: length-limit?
{ $values { "seq" "a sequence" } { "trimmed" "a trimmed sequence" } { "?" "a boolean indicating if trimming took place" } }
{ $description "If the " { $link length-limit } " is set, trims the sequence if necessary, and outputs a boolean indicating if \"...\" should be output." }
$prettyprinting-note ;

HELP: pprint-element
{ $values { "obj" "an object" } }
{ $description "Prettyprints a sequence element." }
$prettyprinting-note ;

HELP: pprint-elements
{ $values { "seq" "a sequence" } }
{ $description "Prettyprints the elements of a sequence, trimming the sequence to " { $link length-limit } " if necessary." }
$prettyprinting-note ;

HELP: pprint-sequence
{ $values { "seq" "a sequence" } { "start" "a word" } { "end" "a word" } }
{ $description "Prettyprints a sequence." }
$prettyprinting-note ;

HELP: with-pprint
{ $values { "quot" "a quotation" } }
{ $description "Sets up the prettyprinter and calls the quotation in a new scope. The quotation should add sections to the top-level block. When the quotation returns, the top-level block is printed to the default stream." } ;

HELP: pprint
{ $values { "obj" "an object" } }
{ $description "Prettyprints an object to the default stream. Output is influenced by many variables; see " { $link "prettyprint-variables" } "." } ;

HELP: .
{ $values { "obj" "an object" } }
{ $description "Prettyprints an object to the default stream with a trailing line break. Output is influenced by many variables; see " { $link "prettyprint-variables" } "." } ;

HELP: unparse
{ $values { "obj" "an object" } { "str" "Factor source string" } }
{ $description "Outputs a prettyprinted string representation of an object. Output is influenced by many variables; see " { $link "prettyprint-variables" } "." } ;

HELP: pprint-short
{ $values { "obj" "an object" } }
{ $description "Prettyprints an object to the default stream. This word rebinds printer control variables to enforce ``shorter'' output. See " { $link "prettyprint-variables" } "." } ;

HELP: short.
{ $values { "obj" "an object" } }
{ $description "Prettyprints an object to the default stream with a trailing line break. This word rebinds printer control variables to enforce ``shorter'' output." } ;

HELP: unparse-short
{ $values { "obj" "an object" } { "str" "Factor source string" } }
{ $description "Outputs a prettyprinted string representation of an object. This word rebinds printer control variables to enforce ``shorter'' output. See " { $link "prettyprint-variables" } "." } ;

HELP: .b
{ $values { "n" "an integer" } }
{ $description "Outputs an integer in binary." } ;

HELP: .o
{ $values { "n" "an integer" } }
{ $description "Outputs an integer in octal." } ;

HELP: .h
{ $values { "n" "an integer" } }
{ $description "Outputs an integer in hexadecimal." } ;

HELP: define-open
{ $values { "word" "a word" } }
{ $description "Marks up the word so that it begins a nested block when prettyprinted. Usually only used for parsing words." } ;

HELP: define-close
{ $values { "word" "a word" } }
{ $description "Marks up the word so that it ends a nested block when prettyprinted. Usually only used for parsing words." } ;