basis/prettyprint/prettyprint-docs.factor

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