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 { $subsection stream-format }
  96 { $subsection make-span-stream }
  97 { $subsection make-block-stream }
  98 { $subsection make-cell-stream }
  99 { $subsection stream-write-table } ;
 100
 101 ARTICLE: "formatted-stdout" "Formatted output on the default stream"
 102 "The below words perform formatted output on " { $link output-stream } "."
 103 $nl
 104 "Formatted output:"
 105 { $subsection format }
 106 { $subsection with-style }
 107 { $subsection with-nesting }
 108 "Tabular output:"
 109 { $subsection tabular-output }
 110 { $subsection with-row }
 111 { $subsection with-cell }
 112 { $subsection write-cell } ;
 113
 114 HELP: href
 115 { $description "Character style. A URL string that the text links to." } ;
 116
 117 HELP: image
 118 { $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." } ;
 119
 120 ARTICLE: "character-styles" "Character styles"
 121 "Character styles for " { $link stream-format } " and " { $link with-style } ":"
 122 { $subsection foreground }
 123 { $subsection background }
 124 { $subsection font-name }
 125 { $subsection font-size }
 126 { $subsection font-style }
 127 "Special styles:"
 128 { $subsection href }
 129 { $subsection image }
 130 { $see-also "presentations" } ;
 131
 132 ARTICLE: "paragraph-styles" "Paragraph styles"
 133 "Paragraph styles for " { $link with-nesting } ":"
 134 { $subsection page-color }
 135 { $subsection border-color }
 136 { $subsection inset }
 137 { $subsection wrap-margin }
 138 { $subsection presented } ;
 139
 140 ARTICLE: "table-styles" "Table styles"
 141 "Table styles for " { $link tabular-output } ":"
 142 { $subsection table-gap }
 143 { $subsection table-border } ;
 144
 145 HELP: write-object
 146 { $values { "str" string } { "obj" "an object" } }
 147 { $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 } "." }
 148 $io-error ;
 149
 150 ARTICLE: "presentations" "Presentations"
 151 "A special style for " { $link format } " and " { $link with-nesting } ":"
 152 { $subsection presented }
 153 "The " { $link presented } " style can be used to emit clickable objects. A utility word for outputting this style:"
 154 { $subsection write-object } ;
 155
 156 ARTICLE: "styles" "Text styles"
 157 "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."
 158 $nl
 159 "Style hashtables are keyed by symbols from the " { $vocab-link "io.styles" } " vocabulary."
 160 { $subsection "character-styles" }
 161 { $subsection "paragraph-styles" }
 162 { $subsection "table-styles" }
 163 { $subsection "presentations" } ;
 164
 165 ARTICLE: "io.styles" "Formatted output"
 166 "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" } "."
 167 { $subsection "formatted-stream-protocol" }
 168 { $subsection "formatted-stdout" }
 169 { $subsection "styles" } ;
 170
 171 ABOUT: "io.styles"
 172
 173 HELP: plain
 174 { $description "A value for the " { $link font-style } " character style denoting plain text." } ;
 175
 176 HELP: bold
 177 { $description "A value for the " { $link font-style } " character style denoting boldface text." } ;
 178
 179 HELP: italic
 180 { $description "A value for the " { $link font-style } " character style denoting italicized text." } ;
 181
 182 HELP: bold-italic
 183 { $description "A value for the " { $link font-style } " character style denoting boldface italicized text." } ;
 184
 185 HELP: foreground
 186 { $description "Character style. An instance of " { $link color } ". See " { $link "colors" } "." }
 187 { $examples
 188     { $code
 189         "10 ["
 190             "    \"Hello world\\n\""
 191             "    swap 10 / 1 <gray> foreground associate format"
 192         "] each"
 193     }
 194 } ;
 195
 196 HELP: background
 197 { $description "Character style. An instance of " { $link color } ". See " { $link "colors" } "." }
 198 { $examples
 199     { $code
 200         "10 ["
 201             "    \"Hello world\\n\""
 202             "    swap 10 / 1 1 over - over 1 <rgba>"
 203             "    background associate format nl"
 204         "] each"
 205     }
 206 } ;
 207
 208 HELP: font-name
 209 { $description "Character style. Font family named by a string." }
 210 { $examples
 211     "This example outputs some different font sizes:"
 212     { $code "{ \"monospace\" \"serif\" \"sans-serif\" }\n[ dup font-name associate format nl ] each" }
 213 } ;
 214
 215 HELP: font-size
 216 { $description "Character style. Font size, an integer." }
 217 { $examples
 218     "This example outputs some different font sizes:"
 219     { $code "{ 12 18 24 72 }"
 220         "[ \"Bigger\" swap font-size associate format nl ] each"
 221     }
 222 }  ;
 223
 224 HELP: font-style
 225 { $description "Character style. Font style, one of " { $link plain } ", " { $link bold } ", " { $link italic } ", or " { $link bold-italic } "." }
 226 { $examples
 227     "This example outputs text in all three styles:"
 228     { $code "{ plain bold italic bold-italic }\n[ [ name>> ] keep font-style associate format nl ] each" }
 229 }  ;
 230
 231 HELP: presented
 232 { $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." } ;
 233
 234 HELP: page-color
 235 { $description "Paragraph style. An instance of " { $link color } ". See " { $link "colors" } "." }
 236 { $examples
 237     { $code "H{ { page-color T{ rgba f 1 0.8 0.5 1 } } }\n[ \"A background\" write ] with-nesting nl" }
 238 } ;
 239
 240 HELP: border-color
 241 { $description "Paragraph style. An instance of " { $link color } ". See " { $link "colors" } "." }
 242 { $examples
 243     { $code "H{ { border-color T{ rgba f 1 0 0 1 } } }\n[ \"A border\" write ] with-nesting nl" }
 244 } ;
 245
 246 HELP: inset
 247 { $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." }
 248 { $examples
 249     { $code "H{ { inset { 10 10 } } }\n[ \"Some inset text\" write ] with-nesting nl" }
 250 } ;
 251
 252 HELP: wrap-margin
 253 { $description "Paragraph style. Pixels between left margin and right margin where text is wrapped, an integer." } ;
 254
 255 { wrap-margin bl } related-words
 256
 257 HELP: table-gap
 258 { $description "Table style. Horizontal and vertical gap between table cells, denoted by a pair of integers." } ;
 259
 260 { table-gap table-border stream-write-table tabular-output } related-words
 261
 262 HELP: table-border
 263 { $description "Table style. An instance of " { $link color } ". See " { $link "colors" } "." } ;
 264
 265 HELP: input
 266 { $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> } "." }
 267 { $examples
 268     "This presentation class is used for the code examples you see in the online help:"
 269     { $code "\"2 3 + .\" dup <input> write-object nl" }
 270 } ;
 271
 272 HELP: <input>
 273 { $values { "string" string } { "input" input } }
 274 { $description "Creates a new " { $link input } "." } ;
 275
 276 HELP: standard-table-style
 277 { $values { "value" hashtable } }
 278 { $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 } "." } ;
 279
 280 ARTICLE: "io.streams.plain" "Plain writer streams"
 281 "Plain writer streams wrap an underlying stream and provide a default implementation of "
 282 { $link stream-nl } ", "
 283 { $link stream-format } ", "
 284 { $link make-span-stream } ", "
 285 { $link make-block-stream } " and "
 286 { $link make-cell-stream } "."
 287 { $subsection plain-writer } ;