basis/prettyprint/prettyprint-docs.factor

   1 USING: prettyprint.backend prettyprint.config prettyprint.custom
   2 prettyprint.sections prettyprint.private help.markup help.syntax
   3 io kernel words definitions quotations strings generic classes ;
   4 IN: prettyprint
   5
   6 ARTICLE: "prettyprint-numbers" "Prettyprinting numbers"
   7 "The " { $link . } " word prints numbers in decimal. A set of words in the " { $vocab-link "prettyprint" } " vocabulary is provided to print integers using another base."
   8 { $subsection .b }
   9 { $subsection .o }
  10 { $subsection .h } ;
  11
  12 ARTICLE: "prettyprint-stacks" "Prettyprinting stacks"
  13 "Prettyprinting the current data, retain, call stacks:"
  14 { $subsection .s }
  15 { $subsection .r }
  16 { $subsection .c }
  17 "Prettyprinting any stack:"
  18 { $subsection stack. }
  19 "Prettyprinting any call stack:"
  20 { $subsection callstack. }
  21 "Note that calls to " { $link .s } " can also be included inside words as a debugging aid, however a more convenient way to achieve this is to use the annotation facility. See " { $link "tools.annotations" } "." ;
  22
  23 ARTICLE: "prettyprint-variables" "Prettyprint control variables"
  24 "The following variables affect the " { $link . } " and " { $link pprint } " words if set in the current dynamic scope:"
  25 { $subsection tab-size }
  26 { $subsection margin }
  27 { $subsection nesting-limit }
  28 { $subsection length-limit }
  29 { $subsection line-limit }
  30 { $subsection string-limit? }
  31 { $subsection boa-tuples? }
  32 "Note that the " { $link short. } " and " { $link pprint-short } " variables override some of these variables."
  33 {
  34     $warning "Treat the global variables as essentially being constants. Only ever rebind them in a nested scope."
  35     $nl
  36     "Some of the globals are safe to change, like the tab size and wrap margin. However setting limits globally could break code which uses the prettyprinter as a serialization mechanism."
  37 } ;
  38
  39 ARTICLE: "prettyprint-limitations" "Prettyprinter limitations"
  40 "When using the prettyprinter as a serialization mechanism, keep the following points in mind:"
  41 { $list
  42     { "When printing words, " { $link POSTPONE: USING: } " declarations are only output if the " { $link pprint-use } " or " { $link unparse-use } "  words are used." }
  43     { "Long output will be truncated if certain " { $link "prettyprint-variables" } " are set." }
  44     "Shared structure is not reflected in the printed output; if the output is parsed back in, fresh objects are created for all literal denotations."
  45     { "Circular structure is not printed in a readable way. For example, try this:"
  46         { $code "{ f } dup dup set-first ." }
  47     }
  48     "Floating point numbers might not equal themselves after being printed and read, since a decimal representation of a float is inexact."
  49 }
  50 "On a final note, the " { $link short. } " and " { $link pprint-short } " words restrict the length and nesting of printed sequences, their output will very likely not be valid syntax. They are only intended for interactive use." ;
  51
  52 ARTICLE: "prettyprint-section-protocol" "Prettyprinter section protocol"
  53 "Prettyprinter sections must subclass " { $link section } ", and they must also obey a protocol."
  54 $nl
  55 "Layout queries:"
  56 { $subsection section-fits? }
  57 { $subsection indent-section? }
  58 { $subsection unindent-first-line? }
  59 { $subsection newline-after? }
  60 { $subsection short-section? }
  61 "Printing sections:"
  62 { $subsection short-section }
  63 { $subsection long-section }
  64 "Utilities to use when implementing sections:"
  65 { $subsection new-section }
  66 { $subsection new-block }
  67 { $subsection add-section } ;
  68
  69 ARTICLE: "prettyprint-sections" "Prettyprinter sections"
  70 "The prettyprinter's formatting engine can be used directly:"
  71 { $subsection with-pprint }
  72 "Code in a " { $link with-pprint } " block or a method on " { $link pprint* } " can build up a tree of " { $emphasis "sections" } ". A section is either a text node or a " { $emphasis "block" } " which itself consists of sections."
  73 $nl
  74 "Once the output sections have been generated, the tree of sections is traversed and intelligent decisions are made about indentation and line breaks. Finally, text is output."
  75 { $subsection section }
  76 "Adding leaf sections:"
  77 { $subsection line-break }
  78 { $subsection text }
  79 { $subsection styled-text }
  80 "Nesting and denesting sections:"
  81 { $subsection <object }
  82 { $subsection <block }
  83 { $subsection <inset }
  84 { $subsection <flow }
  85 { $subsection <colon }
  86 { $subsection block> }
  87 "New types of sections can be defined."
  88 { $subsection "prettyprint-section-protocol" } ;
  89
  90 ARTICLE: "prettyprint-literal" "Literal prettyprinting protocol"
  91 "Most custom data types have a literal syntax which resembles a sequence. An easy way to define such a syntax is to add a method to the " { $link pprint* } " generic word which calls " { $link pprint-object } ", and then to provide methods on two other generic words:"
  92 { $subsection pprint-delims }
  93 { $subsection >pprint-sequence }
  94 "For example, consider the following data type, together with a parsing word for creating literals:"
  95 { $code
  96     "TUPLE: rect w h ;"
  97     ""
  98     ": RECT["
  99     "    scan-word"
 100     "    scan-word \\ * assert="
 101     "    scan-word"
 102     "    scan-word \\ ] assert="
 103     "    <rect> parsed ; parsing"
 104 }
 105 "An example literal might be:"
 106 { $code "RECT[ 100 * 200 ]" }
 107 "Without further effort, the literal does not print in the same way:"
 108 { $unchecked-example "RECT[ 100 * 200 ] ." "T{ rect f 100 200 }" }
 109 "However, we can define three methods easily enough:"
 110 { $code
 111     "M: rect pprint-delims drop \\ RECT[ \\ ] ;"
 112     "M: rect >pprint-sequence dup rect-w \\ * rot rect-h 3array ;"
 113     "M: rect pprint* pprint-object ;"
 114 }
 115 "Now, it will be printed in a custom way:"
 116 { $unchecked-example "RECT[ 100 * 200 ] ." "RECT[ 100 * 200 ]" } ;
 117
 118 ARTICLE: "prettyprint-literal-more" "Prettyprinting more complex literals"
 119 "If the " { $link "prettyprint-literal" } " is insufficient, a method can be defined to control prettyprinting directly:"
 120 { $subsection pprint* }
 121 "Some utilities which can be called from methods on " { $link pprint* } ":"
 122 { $subsection pprint-object }
 123 { $subsection pprint-word }
 124 { $subsection pprint-elements }
 125 { $subsection pprint-string }
 126 { $subsection pprint-prefix }
 127 "Custom methods defined on " { $link pprint* } " do not perform I/O directly, instead they call prettyprinter words to construct " { $emphasis "sections" } " of output. See " { $link "prettyprint-sections" } "." ;
 128
 129 ARTICLE: "prettyprint-extension" "Extending the prettyprinter"
 130 "One can define literal syntax for a new class using the " { $link "parser" } " together with corresponding prettyprinting methods which print instances of the class using this syntax."
 131 { $subsection "prettyprint-literal" }
 132 { $subsection "prettyprint-literal-more" }
 133 "The prettyprinter actually exposes a general source code output engine and is not limited to printing object structure."
 134 { $subsection "prettyprint-sections" } ;
 135
 136 ARTICLE: "prettyprint" "The prettyprinter"
 137 "One of Factor's key features is the ability to print almost any object as a valid source literal expression. This greatly aids debugging and provides the building blocks for light-weight object serialization facilities."
 138 $nl
 139 "Prettyprinter words are found in the " { $vocab-link "prettyprint" } " vocabulary."
 140 $nl
 141 "The key words to print an object to " { $link output-stream } "; the first two emit a trailing newline, the second two do not:"
 142 { $subsection . }
 143 { $subsection short. }
 144 { $subsection pprint }
 145 { $subsection pprint-short }
 146 { $subsection pprint-use }
 147 "The string representation of an object can be requested:"
 148 { $subsection unparse }
 149 { $subsection unparse-use }
 150 "Utility for tabular output:"
 151 { $subsection pprint-cell }
 152 "Printing a definition (see " { $link "definitions" } "):"
 153 { $subsection see }
 154 "Printing the methods defined on a generic word or class (see " { $link "objects" } "):"
 155 { $subsection see-methods }
 156 "More prettyprinter usage:"
 157 { $subsection "prettyprint-numbers" }
 158 { $subsection "prettyprint-stacks" }
 159 "Prettyprinter customization:"
 160 { $subsection "prettyprint-variables" }
 161 { $subsection "prettyprint-extension" }
 162 { $subsection "prettyprint-limitations" }
 163 { $see-also "number-strings" } ;
 164
 165 ABOUT: "prettyprint"
 166
 167 HELP: with-pprint
 168 { $values { "obj" object } { "quot" quotation } }
 169 { $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 " { $link output-stream } "." } ;
 170
 171 HELP: pprint
 172 { $values { "obj" object } }
 173 { $description "Prettyprints an object to " { $link output-stream } ". Output is influenced by many variables; see " { $link "prettyprint-variables" } "." }
 174 { $warning
 175     "Unparsing a large object can take a long time and consume a lot of memory. If you need to print large objects, use " { $link pprint-short } " or set some " { $link "prettyprint-variables" } " to limit output size."
 176 } ;
 177
 178 { pprint pprint* with-pprint } related-words
 179
 180 HELP: .
 181 { $values { "obj" object } }
 182 { $description "Prettyprints an object to " { $link output-stream } " with a trailing line break. Output is influenced by many variables; see " { $link "prettyprint-variables" } "." }
 183 { $warning
 184     "Printing a large object can take a long time and consume a lot of memory. If you need to print large objects, use " { $link short. } " or set some " { $link "prettyprint-variables" } " to limit output size."
 185 } ;
 186
 187 HELP: unparse
 188 { $values { "obj" object } { "str" "Factor source string" } }
 189 { $description "Outputs a prettyprinted string representation of an object. Output is influenced by many variables; see " { $link "prettyprint-variables" } "." }
 190 { $warning
 191     "Unparsing a large object can take a long time and consume a lot of memory. If you need to unparse large objects, use " { $link unparse-short } " or set some " { $link "prettyprint-variables" } " to limit output size."
 192 } ;
 193
 194 HELP: pprint-short
 195 { $values { "obj" object } }
 196 { $description "Prettyprints an object to " { $link output-stream } ". This word rebinds printer control variables to enforce “shorter” output. See " { $link "prettyprint-variables" } "." } ;
 197
 198 HELP: short.
 199 { $values { "obj" object } }
 200 { $description "Prettyprints an object to " { $link output-stream } " with a trailing line break. This word rebinds printer control variables to enforce “shorter” output." } ;
 201
 202 HELP: .b
 203 { $values { "n" "an integer" } }
 204 { $description "Outputs an integer in binary." } ;
 205
 206 HELP: .o
 207 { $values { "n" "an integer" } }
 208 { $description "Outputs an integer in octal." } ;
 209
 210 HELP: .h
 211 { $values { "n" "an integer" } }
 212 { $description "Outputs an integer in hexadecimal." } ;
 213
 214 HELP: stack.
 215 { $values { "seq" "a sequence" } }
 216 { $description "Prints a the elements of the sequence, one per line." }
 217 { $notes "This word is used in the implementation of " { $link .s } " and " { $link .r } "." } ;
 218
 219 HELP: callstack.
 220 { $values { "callstack" callstack } }
 221 { $description "Displays a sequence output by " { $link callstack } " in a nice way, by highlighting the current execution point in every call frame with " { $link -> } "." } ;
 222
 223 HELP: .c
 224 { $description "Displays the contents of the call stack, with the top of the stack printed first." } ;
 225
 226 HELP: .r
 227 { $description "Displays the contents of the retain stack, with the top of the stack printed first." } ;
 228
 229 HELP: .s
 230 { $description "Displays the contents of the data stack, with the top of the stack printed first." } ;
 231
 232 HELP: in.
 233 { $values { "vocab" "a vocabulary specifier" } }
 234 { $description "Prettyprints a " { $snippet "IN:" } " declaration." }
 235 $prettyprinting-note ;
 236
 237 HELP: synopsis
 238 { $values { "defspec" "a definition specifier" } { "str" string } }
 239 { $contract "Prettyprints the prologue of a definition." } ;
 240
 241 HELP: synopsis*
 242 { $values { "defspec" "a definition specifier" } }
 243 { $contract "Adds sections to the current block corresponding to a the prologue of a definition, in source code-like form." }
 244 { $notes "This word should only be called from inside the " { $link with-pprint } " combinator. Client code should call " { $link synopsis } " instead." } ;
 245
 246 HELP: comment.
 247 { $values { "string" "a string" } }
 248 { $description "Prettyprints some text with the comment style." }
 249 $prettyprinting-note ;
 250
 251 HELP: see
 252 { $values { "defspec" "a definition specifier" } }
 253 { $contract "Prettyprints a definition." } ;
 254
 255 HELP: see-methods
 256 { $values { "word" "a " { $link generic } " or a " { $link class } } }
 257 { $contract "Prettyprints the methods defined on a generic word or class." } ;
 258
 259 HELP: definer
 260 { $values { "defspec" "a definition specifier" } { "start" word } { "end" "a word or " { $link f } } }
 261 { $contract "Outputs the parsing words which delimit the definition." }
 262 { $examples
 263     { $example "USING: definitions prettyprint ;"
 264                "IN: scratchpad"
 265                ": foo ; \\ foo definer . ."
 266                ";\nPOSTPONE: :"
 267     }
 268     { $example "USING: definitions prettyprint ;"
 269                "IN: scratchpad"
 270                "SYMBOL: foo \\ foo definer . ."
 271                "f\nPOSTPONE: SYMBOL:"
 272     }
 273 }
 274 { $notes "This word is used in the implementation of " { $link see } "." } ;
 275
 276 HELP: definition
 277 { $values { "defspec" "a definition specifier" } { "seq" "a sequence" } }
 278 { $contract "Outputs the body of a definition." }
 279 { $examples
 280     { $example "USING: definitions math prettyprint ;" "\\ sq definition ." "[ dup * ]" }
 281 }
 282 { $notes "This word is used in the implementation of " { $link see } "." } ;