basis/prettyprint/sections/sections-docs.factor

   1 USING: prettyprint io kernel help.markup help.syntax
   2 prettyprint.config words hashtables math
   3 strings definitions ;
   4 IN: prettyprint.sections
   5
   6 HELP: position
   7 { $var-description "The prettyprinter's current character position." } ;
   8
   9 HELP: recursion-check
  10 { $var-description "The current nesting of collections being output by the prettyprinter, used to detect circularity and prevent infinite recursion." } ;
  11
  12 HELP: line-limit?
  13 { $values { "?" "a boolean" } }
  14 { $description "Tests if the line number limit has been reached, and thus if prettyprinting should stop." } ;
  15
  16
  17 HELP: do-indent
  18 { $description "Outputs the current indent nesting to " { $link output-stream } "." } ;
  19
  20 HELP: fresh-line
  21 { $values { "n" "the current column position" } }
  22 { $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 } "." } ;
  23
  24 HELP: soft
  25 { $description "Possible input parameter to " { $link line-break } "." } ;
  26
  27 HELP: hard
  28 { $description "Possible input parameter to " { $link line-break } "." } ;
  29
  30 { soft hard } related-words
  31
  32 HELP: section-fits?
  33 { $values { "section" section } { "?" "a boolean" } }
  34 { $contract "Tests if a section fits in the space that remains on the current line." } ;
  35
  36 HELP: short-section
  37 { $values { "section" section } }
  38 { $contract "Prints a section which fits in the current line. This should use a layout strategy maximizing line length and minimizing white space." } ;
  39
  40 HELP: long-section
  41 { $values { "section" section } }
  42 { $contract "Prints a section which spans multiple lines. This should use a layout strategy maximizing readability and minimizing line length." } ;
  43
  44 HELP: indent-section?
  45 { $values { "section" section } { "?" "a boolean" } }
  46 { $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 } "." } ;
  47
  48 HELP: unindent-first-line?
  49 { $values { "section" section } { "?" "a boolean" } }
  50 { $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 } "." }
  51 { $notes "This is used to format " { $link colon } " sections because of the colon definition formatting convention." } ;
  52
  53 HELP: newline-after?
  54 { $values { "section" section } { "?" "a boolean" } }
  55 { $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 } "." } ;
  56
  57 HELP: short-section?
  58 { $values { "section" section } { "?" "a boolean" } }
  59 { $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." } ;
  60
  61 HELP: section
  62 { $class-description "A piece of prettyprinter output. Instances of this class are not used directly, instead one instantiates various subclasses of this class:"
  63 { $list
  64     { $link text }
  65     { $link line-break }
  66     { $link block }
  67     { $link inset }
  68     { $link flow }
  69     { $link colon }
  70 }
  71 "Instances of this class have the following slots:"
  72 { $list
  73     { { $snippet "start" } " - the start of the section, measured in characters from the beginning of the prettyprinted output" }
  74     { { $snippet "end" } " - the end of the section, measured in characters from the beginning of the prettyprinted output" }
  75     { { $snippet "start-group?" } " - see " { $link start-group } }
  76     { { $snippet "end-group?" } " - see " { $link end-group } }
  77     { { $snippet "style" } " - character and/or paragraph styles to use when outputting this section. See " { $link "styles" } }
  78     { { $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" }
  79 } } ;
  80
  81 HELP: new-section
  82 { $values { "length" integer } { "class" "a subclass of " { $link section } } { "section" section } }
  83 { $description "Creates a new section with the given length starting from " { $link position } ", advancing " { $link position } "." } ;
  84
  85 HELP: <indent
  86 { $values { "section" section } }
  87 { $description "Increases indentation by the " { $link tab-size } " if requested by the section." } ;
  88
  89 HELP: indent>
  90 { $values { "section" section } }
  91 { $description "Decreases indentation by the " { $link tab-size } " if requested by the section." } ;
  92
  93 HELP: <fresh-line
  94 { $values { "section" section } }
  95 { $description "Prints a line break before the section start." } ;
  96
  97 HELP: fresh-line>
  98 { $values { "section" section } }
  99 { $description "Prints a line break after the section end if requested by the section." } ;
 100
 101 HELP: <long-section
 102 { $values { "section" section } }
 103 { $description "Begins printing a long section, taking " { $link indent-section? } " and " { $link unindent-first-line? } " into account." } ;
 104
 105 HELP: long-section>
 106 { $values { "section" section } }
 107 { $description "Ends printing a long section, taking " { $link indent-section? } " and " { $link newline-after? } " into account." } ;
 108
 109 HELP: pprint-section
 110 { $values { "section" section } }
 111 { $contract "Prints a section, performing wrapping and indentation using available formatting information." }
 112 $prettyprinting-note ;
 113
 114 HELP: line-break
 115 { $values { "type" { $link soft } " or " { $link hard } } }
 116 { $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 } "." }
 117 $prettyprinting-note ;
 118
 119 HELP: block
 120 { $class-description "A block is a section containing child sections. Blocks are introduced by calling " { $link <block } " and " { $link block> } "." } ;
 121
 122 HELP: pprinter-block
 123 { $values { "block" "a block section" } }
 124 { $description "Outputs the block currently being constructed." }
 125 $prettyprinting-note ;
 126
 127 HELP: add-section
 128 { $values { "section" "a section" } }
 129 { $description "Adds a section to the current block." }
 130 $prettyprinting-note ;
 131
 132 HELP: start-group
 133 { $description "Marks the start of a group. Sections inside a group are output on one line if possible." } ;
 134
 135 HELP: end-group
 136 { $description "Marks the end of a group. Sections inside a group are output on one line if possible." } ;
 137
 138 HELP: advance
 139 { $values { "section" section } }
 140 { $description "Emits whitespace between sections." }
 141 $prettyprinting-note ;
 142
 143 HELP: save-end-position
 144 { $values { "block" block } }
 145 { $description "Save the current position as the end position of the block." } ;
 146
 147 HELP: pprint-sections
 148 { $values { "block" block } { "advancer" "a quotation with stack effect " { $snippet "( block -- )" } } }
 149 { $description "Prints child sections of a block, ignoring any " { $link line-break } " sections. The " { $snippet "advancer" } " quotation is called between every pair of sections." } ;
 150
 151 HELP: do-break
 152 { $values { "break" line-break } }
 153 { $description "Prints a break section as per the policy outlined in " { $link line-break } "." } ;
 154
 155 HELP: empty-block?
 156 { $values { "block" block } { "?" "a boolean" } }
 157 { $description "Tests if the block has no child sections." } ;
 158
 159 HELP: if-nonempty
 160 { $values { "block" block } { "quot" "a quotation with stack effect " { $snippet "( block -- )" } } }
 161 { $description "If the block has child sections, calls the quotation, otherwise does nothing." } ;
 162
 163 HELP: (<block)
 164 { $values { "block" block } }
 165 { $description "Begins constructing a nested block." } ;
 166
 167 HELP: <block
 168 { $description "Begins a plain block." } ;
 169
 170 HELP: <text>
 171 { $values { "string" string } { "style" hashtable } { "text" "a new text section" } }
 172 { $description "Creates a text section." } ;
 173
 174 HELP: text
 175 { $values { "string" string } }
 176 { $description "Adds a string to the current block." }
 177 $prettyprinting-note ;
 178
 179 HELP: styled-text
 180 { $values { "string" string } { "style" hashtable } }
 181 { $description "Adds a styled string to the current block." }
 182 $prettyprinting-note ;
 183
 184 HELP: inset
 185 { $class-description "A " { $link block } " section which indents every line when printed as a " { $link long-section } "." } ;
 186
 187 HELP: <inset
 188 { $values { "narrow?" "a boolean" } }
 189 { $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." }
 190 { $examples
 191     "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 } "."
 192 } ;
 193
 194 HELP: flow
 195 { $class-description "A " { $link block } " section printed on its own line if it can fit entirely on one line." } ;
 196
 197 HELP: <flow
 198 { $description "Begins a " { $link flow } " section. " } ;
 199
 200 HELP: colon
 201 { $class-description "A " { $link block } " section. When printed as a " { $link long-section } ", indents every line except the first." }
 202 { $notes "Colon sections are used to enclose word definitions printed by " { $link see } "." } ;
 203
 204 HELP: <colon
 205 { $description "Begins a " { $link colon } " section." } ;
 206
 207 HELP: block>
 208 { $description "Adds the current block to its containing block." }
 209 $prettyprinting-note ;
 210
 211 HELP: do-pprint
 212 { $values { "block" block } }
 213 { $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 } "." } ;