basis/prettyprint/prettyprint-docs.factor

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