-USING: hashtables hashtables-internals help kernel namespaces
-queues ;
+USING: hashtables hashtables-internals help io-internals kernel
+namespaces queues ;
GLOSSARY: "collection" "an object whose primary purpose is to aggregate other objects; examples include sequences, queues and hashtables" ;
ARTICLE: "collections" "Collections"
+"Classical data structures:"
{ $subsection "sequences" }
{ $subsection "queues" }
{ $subsection "hashtables" }
-{ $subsection "namespaces" } ;
+"An abstraction on hashtables:"
+{ $subsection "namespaces" }
+"A low-level facility:"
+{ $subsection "buffers" } ;
ARTICLE: "queues" "Queues"
"A simple last-in-first-out queue data structure."
"A pair of words push and pop namespaces on the namestack."
{ $subsection >n }
{ $subsection n> } ;
+
+ARTICLE: "buffers" "Locked I/O buffers"
+"I/O buffers are a circular ring structure, a fixed-size queue of characters. Their key feature is that they are backed by manually allocated storage that does not get moved by the garbage collector. They are typically used for asynchronous I/O in conjunction with the C library interface in Factor's implementation."
+$terpri
+"Buffer words are in the " { $snippet "io-internals" } " vocabulary."
+{ $subsection buffer }
+{ $subsection <buffer> }
+"Buffers must be manually deallocated:"
+{ $subsection buffer-free }
+"Buffer operations:"
+{ $subsection buffer-reset }
+{ $subsection buffer-length }
+{ $subsection buffer-empty? }
+{ $subsection buffer-capacity }
+"Reading from the buffer:"
+{ $subsection buffer-peek }
+{ $subsection buffer-pop }
+{ $subsection buffer> }
+{ $subsection buffer>> }
+{ $subsection buffer-contents }
+"Writing to the buffer:"
+{ $subsection buffer-extend }
+{ $subsection ch>buffer }
+{ $subsection >buffer } ;
{ $subsection "presentation-intro" }
{ $subsection "tutorial" }
{ $subsection "quickref" }
-"More detailed reference documentation:"
+"Detailed reference documentation:"
{ $subsection "syntax" }
{ $subsection "dataflow" }
{ $subsection "words" }
{ $subsection "math" }
{ $subsection "collections" }
{ $subsection "streams" }
-{ $subsection "parser" } ;
+{ $subsection "parser" }
+{ $subsection "prettyprint" }
+;
ARTICLE: "presentation-intro" "The presentation-based UI"
"Factor provides a " { $emphasis "presentation-based" } " user interface. A " { $emphasis "presentation" } " is a graphical representation of a live object. You can see presentations everywhere; help links, words, and code examples are all presentations."
--- /dev/null
+USING: help io prettyprint ;
+
+GLOSSARY: "prettyprinter" "a set of words for printing objects in readable form" ;
+
+ARTICLE: "prettyprint" "The prettyprinter"
+"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."
+$terpri
+"Prettyprinter words are found in the " { $snippet "prettyprint" } " vocabulary."
+$terpri
+"The key words to print an object to the " { $link stdio } " stream; the first two emit a trailing newline, the second two do not:"
+{ $subsection . }
+{ $subsection short. }
+{ $subsection pprint }
+{ $subsection pprint-short }
+"The string representation of an object can be requested:"
+{ $subsection unparse }
+{ $subsection unparse-short }
+"The prettyprinter is flexible and extensible."
+{ $subsection "prettyprint-limitations" }
+{ $subsection "prettyprint-variables" }
+{ $subsection "prettyprint-extension" }
+;
+
+ARTICLE: "prettyprint-limitations" "Prettyprinter limitations"
+"The prettyprinter has some limitations; namely, the following objects may not print in a readable form:"
+{ $list
+ { "When printing words, no " { $link POSTPONE: USE: } " declarations are output, hence the result may not be immediately readable without prefixing appropriate declarations." }
+ "Shared structure is not reflected in the printed output; if the output is parsed back in, fresh objects are created for all literal denotations."
+ { "Circular structure is not printed in a readable way. Circular references print as " { $snippet "#" } "." }
+ "Floating point numbers might not equal themselves after being printed and read, since a decimal representation of a float is inexact."
+}
+"On a final note, the " { $link short. } ", " { $link pprint-short } " and " { $link unparse-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." ;
+
+ARTICLE: "prettyprint-variables" "Prettyprint control variables"
+"The following variables affect the " { $link . } " and " { $link pprint } " words if set in the current dynamic scope:"
+{ $subsection tab-size }
+{ $subsection margin }
+{ $subsection nesting-limit }
+{ $subsection length-limit }
+{ $subsection line-limit }
+{ $subsection string-limit }
+"Note that the " { $link short. } " and " { $link pprint-short } " variables override some of these variables."
+{
+ $warning "Treat the global variables as essentially being constants. Only ever rebind them in a nested scope."
+ $terpri
+ "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."
+} ;
+
+ARTICLE: "prettyprint-extension" "Extending the prettyprinter"
+"It is possible to define literal syntax for a new class using the " { $link "parser" } ", and then define a corresponding prettyprint method for the class which reproduces the literal syntax."
+$terpri
+"The prettyprinter maintains some internal state while prettyprinting. First, the object graph is traversed and a tree of " { $emphasis "sections" } " is produced. A section is either a text node or a " { $emphasis "block" } " which itself consists of sections."
+$terpri
+"Once the output is divided into sections, the tree is traversed and intelligent decisions are made about indentation and line breaks. If a block does not fit on the remainder of the current line, a newline is output before and after the block, and additional indentation is used when printing the block."
+$terpri
+"The following generic word is called to output a prettyprinting section for an object:"
+{ $subsection pprint* }
+"Two types of leaf sections:"
+{ $subsection text }
+{ $subsection newline }
+"Nesting and denesting is done using three words. There are two words to denest a block; they vary in indentation policy:"
+{ $subsection <block }
+{ $subsection block> }
+{ $subsection block; }
+"Recall that since " { $link text } " sections take style hashtables as input, any type of formatted text can be output, including presentations. See " { $link "styles" } " to explore the possibility." ;
"/doc/handbook/math.facts"
"/doc/handbook/objects.facts"
"/doc/handbook/parser.facts"
+ "/doc/handbook/prettyprinter.facts"
"/doc/handbook/sequences.facts"
"/doc/handbook/streams.facts"
"/doc/handbook/syntax.facts"
-USING: help prettyprint words ;
+USING: help kernel prettyprint words ;
IN: help
: $prettyprinting-note
- {
+ drop {
"This word should only be called from inside the "
{ $link with-pprint } " combinator."
} $notes ;
HELP: unparse "( obj -- str )"
{ $values { "obj" "an object" } { "str" "Factor source string" } }
-{ $description "Outputs a prettyprinted string representation of an object." } ;
+{ $description "Outputs a prettyprinted string representation of an object. Output is influenced by many variables; see " { $link "prettyprint-variables" } "." } ;
HELP: pprint-short "( obj -- )"
{ $values { "obj" "an object" } }
-{ $description "Prettyprints an object to the default stream. This word rebinds printer control variables to enforce ``shorter'' output." } ;
+{ $description "Prettyprints an object to the default stream. This word rebinds printer control variables to enforce ``shorter'' output. See " { $link "prettyprint-variables" } "." } ;
HELP: short. "( obj -- )"
{ $values { "obj" "an object" } }
HELP: unparse-short "( obj -- str )"
{ $values { "obj" "an object" } { "str" "Factor source string" } }
-{ $description "Outputs a prettyprinted string representation of an object. This word rebinds printer control variables to enforce ``shorter'' output." } ;
+{ $description "Outputs a prettyprinted string representation of an object. This word rebinds printer control variables to enforce ``shorter'' output. See " { $link "prettyprint-variables" } "." } ;
HELP: .b "( n -- )"
{ $values { "n" "an integer" } }
projects / factor.git / commitdiff