214 lines
9.6 KiB
Factor
214 lines
9.6 KiB
Factor
USING: prettyprint io kernel help.markup help.syntax
|
|
prettyprint.config words hashtables math
|
|
strings definitions ;
|
|
IN: prettyprint.sections
|
|
|
|
HELP: position
|
|
{ $var-description "The prettyprinter's current character position." } ;
|
|
|
|
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-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 " { $link output-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: soft
|
|
{ $description "Possible input parameter to " { $link line-break } "." } ;
|
|
|
|
HELP: hard
|
|
{ $description "Possible input parameter to " { $link line-break } "." } ;
|
|
|
|
{ soft hard } related-words
|
|
|
|
HELP: section-fits?
|
|
{ $values { "section" section } { "?" "a boolean" } }
|
|
{ $contract "Tests if a section fits in the space that remains on the current line." } ;
|
|
|
|
HELP: short-section
|
|
{ $values { "section" section } }
|
|
{ $contract "Prints a section which fits in the current line. This should use a layout strategy maximizing line length and minimizing white space." } ;
|
|
|
|
HELP: long-section
|
|
{ $values { "section" section } }
|
|
{ $contract "Prints a section which spans multiple lines. This should use a layout strategy maximizing readability and minimizing line length." } ;
|
|
|
|
HELP: indent-section?
|
|
{ $values { "section" section } { "?" "a boolean" } }
|
|
{ $contract "Outputs a boolean indicating if the indent level should be increased when printing this section as a " { $link long-section } ". Default implementation outputs " { $link f } "." } ;
|
|
|
|
HELP: unindent-first-line?
|
|
{ $values { "section" section } { "?" "a boolean" } }
|
|
{ $contract "Outputs a boolean indicating if the indent level should only be increased for lines after the first line when printing this section as a " { $link long-section } ". Default implementation outputs " { $link f } "." }
|
|
{ $notes "This is used to format " { $link colon } " sections because of the colon definition formatting convention." } ;
|
|
|
|
HELP: newline-after?
|
|
{ $values { "section" section } { "?" "a boolean" } }
|
|
{ $contract "Outputs a boolean indicating if a newline should be output after printing this section as a " { $link long-section } ". Default implementation outputs " { $link f } "." } ;
|
|
|
|
HELP: short-section?
|
|
{ $values { "section" section } { "?" "a boolean" } }
|
|
{ $contract "Tests if a section should be output as a " { $link short-section } ". The default implementation calls " { $link section-fits? } " but this behavior can be cutomized." } ;
|
|
|
|
HELP: section
|
|
{ $class-description "A piece of prettyprinter output. Instances of this class are not used directly, instead one instantiates various subclasses of this class:"
|
|
{ $list
|
|
{ $link text }
|
|
{ $link line-break }
|
|
{ $link block }
|
|
{ $link inset }
|
|
{ $link flow }
|
|
{ $link colon }
|
|
}
|
|
"Instances of this class have the following slots:"
|
|
{ $list
|
|
{ { $snippet "start" } " - the start of the section, measured in characters from the beginning of the prettyprinted output" }
|
|
{ { $snippet "end" } " - the end of the section, measured in characters from the beginning of the prettyprinted output" }
|
|
{ { $snippet "start-group?" } " - see " { $link start-group } }
|
|
{ { $snippet "end-group?" } " - see " { $link end-group } }
|
|
{ { $snippet "style" } " - character and/or paragraph styles to use when outputting this section. See " { $link "styles" } }
|
|
{ { $snippet "overhang" } " - number of columns which must be left blank before the wrap margin for the prettyprinter to consider emitting this section as a " { $link short-section } ". Avoids lone hanging closing brackets" }
|
|
} } ;
|
|
|
|
HELP: new-section
|
|
{ $values { "length" integer } { "class" "a subclass of " { $link section } } { "section" section } }
|
|
{ $description "Creates a new section with the given length starting from " { $link position } ", advancing " { $link position } "." } ;
|
|
|
|
HELP: <indent
|
|
{ $values { "section" section } }
|
|
{ $description "Increases indentation by the " { $link tab-size } " if requested by the section." } ;
|
|
|
|
HELP: indent>
|
|
{ $values { "section" section } }
|
|
{ $description "Decreases indentation by the " { $link tab-size } " if requested by the section." } ;
|
|
|
|
HELP: <fresh-line
|
|
{ $values { "section" section } }
|
|
{ $description "Prints a line break before the section start." } ;
|
|
|
|
HELP: fresh-line>
|
|
{ $values { "section" section } }
|
|
{ $description "Prints a line break after the section end if requested by the section." } ;
|
|
|
|
HELP: <long-section
|
|
{ $values { "section" section } }
|
|
{ $description "Begins printing a long section, taking " { $link indent-section? } " and " { $link unindent-first-line? } " into account." } ;
|
|
|
|
HELP: long-section>
|
|
{ $values { "section" section } }
|
|
{ $description "Ends printing a long section, taking " { $link indent-section? } " and " { $link newline-after? } " into account." } ;
|
|
|
|
HELP: pprint-section
|
|
{ $values { "section" section } }
|
|
{ $contract "Prints a section, performing wrapping and indentation using available formatting information." }
|
|
$prettyprinting-note ;
|
|
|
|
HELP: line-break
|
|
{ $values { "type" { $link soft } " or " { $link hard } } }
|
|
{ $description "Adds a section introducing a line break to the current block. If the block is output as a " { $link short-section } ", all breaks are ignored. Otherwise, hard breaks introduce unconditional newlines, and soft breaks introduce a newline if the position is more than half of the " { $link margin } "." }
|
|
$prettyprinting-note ;
|
|
|
|
HELP: block
|
|
{ $class-description "A block is a section containing child sections. Blocks are introduced by calling " { $link <block } " and " { $link block> } "." } ;
|
|
|
|
HELP: pprinter-block
|
|
{ $values { "block" "a block section" } }
|
|
{ $description "Outputs the block currently being constructed." }
|
|
$prettyprinting-note ;
|
|
|
|
HELP: add-section
|
|
{ $values { "section" "a section" } }
|
|
{ $description "Adds a section to the current block." }
|
|
$prettyprinting-note ;
|
|
|
|
HELP: start-group
|
|
{ $description "Marks the start of a group. Sections inside a group are output on one line if possible." } ;
|
|
|
|
HELP: end-group
|
|
{ $description "Marks the end of a group. Sections inside a group are output on one line if possible." } ;
|
|
|
|
HELP: advance
|
|
{ $values { "section" section } }
|
|
{ $description "Emits whitespace between sections." }
|
|
$prettyprinting-note ;
|
|
|
|
HELP: save-end-position
|
|
{ $values { "block" block } }
|
|
{ $description "Save the current position as the end position of the block." } ;
|
|
|
|
HELP: pprint-sections
|
|
{ $values { "block" block } { "advancer" { $quotation "( block -- )" } } }
|
|
{ $description "Prints child sections of a block, ignoring any " { $link line-break } " sections. The " { $snippet "advancer" } " quotation is called between every pair of sections." } ;
|
|
|
|
HELP: do-break
|
|
{ $values { "break" line-break } }
|
|
{ $description "Prints a break section as per the policy outlined in " { $link line-break } "." } ;
|
|
|
|
HELP: empty-block?
|
|
{ $values { "block" block } { "?" "a boolean" } }
|
|
{ $description "Tests if the block has no child sections." } ;
|
|
|
|
HELP: if-nonempty
|
|
{ $values { "block" block } { "quot" { $quotation "( block -- )" } } }
|
|
{ $description "If the block has child sections, calls the quotation, otherwise does nothing." } ;
|
|
|
|
HELP: (<block)
|
|
{ $values { "block" block } }
|
|
{ $description "Begins constructing a nested block." } ;
|
|
|
|
HELP: <block
|
|
{ $description "Begins a plain block." } ;
|
|
|
|
HELP: <text>
|
|
{ $values { "string" string } { "style" hashtable } { "text" "a new text section" } }
|
|
{ $description "Creates a text section." } ;
|
|
|
|
HELP: text
|
|
{ $values { "string" string } }
|
|
{ $description "Adds a string to the current block." }
|
|
$prettyprinting-note ;
|
|
|
|
HELP: styled-text
|
|
{ $values { "string" string } { "style" hashtable } }
|
|
{ $description "Adds a styled string to the current block." }
|
|
$prettyprinting-note ;
|
|
|
|
HELP: inset
|
|
{ $class-description "A " { $link block } " section which indents every line when printed as a " { $link long-section } "." } ;
|
|
|
|
HELP: <inset
|
|
{ $values { "narrow?" "a boolean" } }
|
|
{ $description "Begins an " { $link inset } " section. When printed as a " { $link long-section } ", the output format is determined by the " { $snippet "narrow?" } " flag. If it is " { $link f } ", then longer lines are favored, wrapping at the " { $link margin } ". Otherwise, every child section is printed on its own line." }
|
|
{ $examples
|
|
"Compare the output of printing a long quotation versus a hashtable. Quotations are printed with " { $snippet "narrow?" } " set to " { $link f } ", and hashtables are printed with " { $snippet "narrow?" } " set to " { $link t } "."
|
|
} ;
|
|
|
|
HELP: flow
|
|
{ $class-description "A " { $link block } " section printed on its own line if it can fit entirely on one line." } ;
|
|
|
|
HELP: <flow
|
|
{ $description "Begins a " { $link flow } " section. " } ;
|
|
|
|
HELP: colon
|
|
{ $class-description "A " { $link block } " section. When printed as a " { $link long-section } ", indents every line except the first." }
|
|
{ $notes "Colon sections are used to enclose word definitions printed by " { $link see } "." } ;
|
|
|
|
HELP: <colon
|
|
{ $description "Begins a " { $link colon } " section." } ;
|
|
|
|
HELP: block>
|
|
{ $description "Adds the current block to its containing block." }
|
|
$prettyprinting-note ;
|
|
|
|
HELP: do-pprint
|
|
{ $values { "block" block } }
|
|
{ $description "Recursively output all children of the given block. The continuation is restored and output terminates if the line length is exceeded; this test is performed in " { $link fresh-line } "." } ;
|