basis/prettyprint/prettyprint-docs.factor

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