basis/io/styles/styles-docs.factor

   1 USING: help.markup help.syntax io.streams.plain io strings
   2 hashtables kernel quotations colors assocs ;
   3 IN: io.styles
   4
   5 HELP: stream-format
   6 { $values { "str" string } { "style" assoc } { "stream" "an output stream" } }
   7 { $contract "Writes formatted text to the stream. If the stream does buffering, output may not be performed immediately; use " { $link stream-flush } " to force output."
   8 $nl
   9 "The " { $snippet "style" } " assoc holds character style information. See " { $link "character-styles" } "." }
  10 { $notes "Most code only works on one stream at a time and should instead use " { $link format } "; see " { $link "stdio" } "." }
  11 $io-error ;
  12
  13 HELP: make-block-stream
  14 { $values { "style" assoc } { "stream" "an output stream" } { "stream'" "an output stream" } }
  15 { $contract "Creates an output stream which wraps " { $snippet "stream" } " and adds " { $snippet "style" } " on calls to " { $link stream-write } " and " { $link stream-format } "."
  16 $nl
  17 "Unlike " { $link make-span-stream } ", this creates a new paragraph block in the output."
  18 $nl
  19 "The " { $snippet "style" } " hashtable holds paragraph style information. See " { $link "paragraph-styles" } "." }
  20 { $notes "Most code only works on one stream at a time and should instead use " { $link with-nesting } "; see " { $link "stdio" } "." }
  21 $io-error ;
  22
  23 HELP: stream-write-table
  24 { $values { "table-cells" "a sequence of sequences of table cells" } { "style" assoc } { "stream" "an output stream" } }
  25 { $contract "Prints a table of cells produced by " { $link with-cell } "."
  26 $nl
  27 "The " { $snippet "style" } " hashtable holds table style information. See " { $link "table-styles" } "." }
  28 { $notes "Most code only works on one stream at a time and should instead use " { $link tabular-output } "; see " { $link "stdio" } "." }
  29 $io-error ;
  30
  31 HELP: make-cell-stream
  32 { $values { "style" assoc } { "stream" "an output stream" } { "stream'" object } }
  33 { $contract "Creates an output stream which writes to a table cell object." }
  34 { $notes "Most code only works on one stream at a time and should instead use " { $link with-cell } "; see " { $link "stdio" } "." }
  35 $io-error ;
  36
  37 HELP: make-span-stream
  38 { $values { "style" assoc } { "stream" "an output stream" } { "stream'" "an output stream" } }
  39 { $contract "Creates an output stream which wraps " { $snippet "stream" } " and adds " { $snippet "style" } " on calls to " { $link stream-write } " and " { $link stream-format } "."
  40 $nl
  41 "Unlike " { $link make-block-stream } ", the stream output is inline, and not nested in a paragraph block." }
  42 { $notes "Most code only works on one stream at a time and should instead use " { $link with-style } "; see " { $link "stdio" } "." }
  43 $io-error ;
  44
  45 HELP: format
  46 { $values { "str" string } { "style" assoc } }
  47 { $description "Writes formatted text to " { $link output-stream } ". If the stream does buffering, output may not be performed immediately; use " { $link flush } " to force output." }
  48 { $notes "Details are in the documentation for " { $link stream-format } "." }
  49 $io-error ;
  50
  51 HELP: with-nesting
  52 { $values { "style" assoc } { "quot" quotation } }
  53 { $description "Calls the quotation in a new dynamic scope with " { $link output-stream } " rebound to a nested paragraph stream, with formatting information applied." }
  54 { $notes "Details are in the documentation for " { $link make-block-stream } "." }
  55 $io-error ;
  56
  57 HELP: tabular-output
  58 { $values { "style" assoc } { "quot" quotation } }
  59 { $description "Calls a quotation which emits a series of equal-length table rows using " { $link with-row } ". The results are laid out in a tabular fashion on " { $link output-stream } "."
  60 $nl
  61 "The " { $snippet "style" } " hashtable holds table style information. See " { $link "table-styles" } "." }
  62 { $examples
  63     { $code
  64         "{ { 1 2 } { 3 4 } }"
  65         "H{ { table-gap { 10 10 } } } ["
  66         "    [ [ [ [ . ] with-cell ] each ] with-row ] each"
  67         "] tabular-output"
  68     }
  69 }
  70 $io-error ;
  71
  72 HELP: with-row
  73 { $values { "quot" quotation } }
  74 { $description "Calls a quotation which emits a series of table cells using " { $link with-cell } ". This word can only be called inside the quotation given to " { $link tabular-output } "." }
  75 $io-error ;
  76
  77 HELP: with-cell
  78 { $values { "quot" quotation } }
  79 { $description "Calls a quotation in a new scope with " { $link output-stream } " rebound. Output performed by the quotation is displayed in a table cell. This word can only be called inside the quotation given to " { $link with-row } "." }
  80 $io-error ;
  81
  82 HELP: write-cell
  83 { $values { "str" string } }
  84 { $description "Outputs a table cell containing a single string. This word can only be called inside the quotation given to " { $link with-row } "." }
  85 $io-error ;
  86
  87 HELP: with-style
  88 { $values { "style" assoc } { "quot" quotation } }
  89 { $description "Calls the quotation in a new dynamic scope where calls to " { $link write } ", " { $link format } " and other stream output words automatically inherit style settings from " { $snippet "style" } "." }
  90 { $notes "Details are in the documentation for " { $link make-span-stream } "." }
  91 $io-error ;
  92
  93 ARTICLE: "formatted-stream-protocol" "Formatted stream protocol"
  94 "The " { $vocab-link "io.styles" } " vocabulary defines a protocol for output streams that support rich text."
  95 { $subsections
  96     stream-format
  97     make-span-stream
  98     make-block-stream
  99     make-cell-stream
 100     stream-write-table
 101 } ;
 102
 103 ARTICLE: "formatted-stdout" "Formatted output on the default stream"
 104 "The below words perform formatted output on " { $link output-stream } "."
 105 $nl
 106 "Formatted output:"
 107 { $subsections
 108     format
 109     with-style
 110     with-nesting
 111 }
 112 "Tabular output:"
 113 { $subsections
 114     tabular-output
 115     with-row
 116     with-cell
 117     write-cell
 118 } ;
 119
 120 HELP: href
 121 { $description "Character style. A URL string that the text links to." } ;
 122
 123 HELP: image
 124 { $description "Character style. A pathname string for an image file to display in place of the printed text. If this style is specified, the printed text serves the same role as the " { $snippet "alt" } " attribute of an HTML " { $snippet "img" } " tag -- the text is only displayed if the output medium does not support images." } ;
 125
 126 ARTICLE: "character-styles" "Character styles"
 127 "Character styles for " { $link stream-format } " and " { $link with-style } ":"
 128 { $subsections
 129     foreground
 130     background
 131     font-name
 132     font-size
 133     font-style
 134 }
 135 "Special styles:"
 136 { $subsections
 137     href
 138     image
 139 }
 140 { $see-also "presentations" } ;
 141
 142 ARTICLE: "paragraph-styles" "Paragraph styles"
 143 "Paragraph styles for " { $link with-nesting } ":"
 144 { $subsections
 145     page-color
 146     border-color
 147     inset
 148     wrap-margin
 149     presented
 150 } ;
 151
 152 ARTICLE: "table-styles" "Table styles"
 153 "Table styles for " { $link tabular-output } ":"
 154 { $subsections
 155     table-gap
 156     table-border
 157 } ;
 158
 159 HELP: write-object
 160 { $values { "str" string } { "obj" "an object" } }
 161 { $description "Writes a string to " { $link output-stream } ", associating it with the object. If formatted output is supported, the string will become a clickable presentation of the object, otherwise this word behaves like a call to " { $link write } "." }
 162 $io-error ;
 163
 164 ARTICLE: "presentations" "Presentations"
 165 "A special style for " { $link format } " and " { $link with-nesting } ":"
 166 { $subsections presented }
 167 "The " { $link presented } " style can be used to emit clickable objects. A utility word for outputting this style:"
 168 { $subsections write-object } ;
 169
 170 ARTICLE: "styles" "Text styles"
 171 "The " { $link stream-format } ", " { $link with-style } ", " { $link with-nesting } " and " { $link tabular-output } " words take a hashtable of style attributes. Output stream implementations are free to ignore style information."
 172 $nl
 173 "Style hashtables are keyed by symbols from the " { $vocab-link "io.styles" } " vocabulary."
 174 { $subsections
 175     "character-styles"
 176     "paragraph-styles"
 177     "table-styles"
 178     "presentations"
 179 } ;
 180
 181 ARTICLE: "io.styles" "Formatted output"
 182 "The " { $vocab-link "io.styles" } " vocabulary defines a protocol for formatted output. This is used by the prettyprinter, help system, and various developer tools. Implementations include " { $vocab-link "ui.gadgets.panes" } ", " { $vocab-link "html.streams" } ", and " { $vocab-link "io.streams.plain" } "."
 183 { $subsections
 184     "formatted-stream-protocol"
 185     "formatted-stdout"
 186     "styles"
 187 } ;
 188
 189 ABOUT: "io.styles"
 190
 191 HELP: plain
 192 { $description "A value for the " { $link font-style } " character style denoting plain text." } ;
 193
 194 HELP: bold
 195 { $description "A value for the " { $link font-style } " character style denoting boldface text." } ;
 196
 197 HELP: italic
 198 { $description "A value for the " { $link font-style } " character style denoting italicized text." } ;
 199
 200 HELP: bold-italic
 201 { $description "A value for the " { $link font-style } " character style denoting boldface italicized text." } ;
 202
 203 HELP: foreground
 204 { $description "Character style. An instance of " { $link color } ". See " { $link "colors" } "." }
 205 { $examples
 206     { $code
 207         "10 ["
 208             "    \"Hello world\\n\""
 209             "    swap 10 / 1 <gray> foreground associate format"
 210         "] each"
 211     }
 212 } ;
 213
 214 HELP: background
 215 { $description "Character style. An instance of " { $link color } ". See " { $link "colors" } "." }
 216 { $examples
 217     { $code
 218         "10 ["
 219             "    \"Hello world\\n\""
 220             "    swap 10 / 1 1 over - over 1 <rgba>"
 221             "    background associate format nl"
 222         "] each"
 223     }
 224 } ;
 225
 226 HELP: font-name
 227 { $description "Character style. Font family named by a string." }
 228 { $examples
 229     "This example outputs some different font sizes:"
 230     { $code "{ \"monospace\" \"serif\" \"sans-serif\" }\n[ dup font-name associate format nl ] each" }
 231 } ;
 232
 233 HELP: font-size
 234 { $description "Character style. Font size, an integer." }
 235 { $examples
 236     "This example outputs some different font sizes:"
 237     { $code "{ 12 18 24 72 }"
 238         "[ \"Bigger\" swap font-size associate format nl ] each"
 239     }
 240 }  ;
 241
 242 HELP: font-style
 243 { $description "Character style. Font style, one of " { $link plain } ", " { $link bold } ", " { $link italic } ", or " { $link bold-italic } "." }
 244 { $examples
 245     "This example outputs text in all three styles:"
 246     { $code "{ plain bold italic bold-italic }\n[ [ name>> ] keep font-style associate format nl ] each" }
 247 }  ;
 248
 249 HELP: presented
 250 { $description "Character and paragraph style. An object associated with the text. In the Factor UI, this is shown as a clickable presentation of the object; left-clicking invokes a default command, and right-clicking shows a menu of commands." } ;
 251
 252 HELP: page-color
 253 { $description "Paragraph style. An instance of " { $link color } ". See " { $link "colors" } "." }
 254 { $examples
 255     { $code "H{ { page-color T{ rgba f 1 0.8 0.5 1 } } }\n[ \"A background\" write ] with-nesting nl" }
 256 } ;
 257
 258 HELP: border-color
 259 { $description "Paragraph style. An instance of " { $link color } ". See " { $link "colors" } "." }
 260 { $examples
 261     { $code "H{ { border-color T{ rgba f 1 0 0 1 } } }\n[ \"A border\" write ] with-nesting nl" }
 262 } ;
 263
 264 HELP: inset
 265 { $description "Paragraph style. A pair of integers representing the number of pixels that the content should be inset from the border. The first number is the horizontal inset, and the second is the vertical inset." }
 266 { $examples
 267     { $code "H{ { inset { 10 10 } } }\n[ \"Some inset text\" write ] with-nesting nl" }
 268 } ;
 269
 270 HELP: wrap-margin
 271 { $description "Paragraph style. Pixels between left margin and right margin where text is wrapped, an integer." } ;
 272
 273 { wrap-margin bl } related-words
 274
 275 HELP: table-gap
 276 { $description "Table style. Horizontal and vertical gap between table cells, denoted by a pair of integers." } ;
 277
 278 { table-gap table-border stream-write-table tabular-output } related-words
 279
 280 HELP: table-border
 281 { $description "Table style. An instance of " { $link color } ". See " { $link "colors" } "." } ;
 282
 283 HELP: input
 284 { $class-description "Class of input text presentations. Instances can be used passed to " { $link write-object } " to output a clickable piece of input. Input text presentations are created by calling " { $link <input> } "." }
 285 { $examples
 286     "This presentation class is used for the code examples you see in the online help:"
 287     { $code "\"2 3 + .\" dup <input> write-object nl" }
 288 } ;
 289
 290 HELP: <input>
 291 { $values { "string" string } { "input" input } }
 292 { $description "Creates a new " { $link input } "." } ;
 293
 294 HELP: standard-table-style
 295 { $values { "value" hashtable } }
 296 { $description "Outputs a table style where cells are separated by 5-pixel gaps and framed by a light gray border. This style can be passed to " { $link tabular-output } "." } ;
 297
 298 ARTICLE: "io.streams.plain" "Plain writer streams"
 299 "Plain writer streams wrap an underlying stream and provide a default implementation of "
 300 { $link stream-nl } ", "
 301 { $link stream-format } ", "
 302 { $link make-span-stream } ", "
 303 { $link make-block-stream } " and "
 304 { $link make-cell-stream } "."
 305 { $subsections plain-writer } ;