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         "USING: io.styles prettyprint sequences ;"
  65         "{ { 1 2 } { 3 4 } }"
  66         "H{ { table-gap { 10 10 } } } ["
  67         "    [ [ [ [ . ] with-cell ] each ] with-row ] each"
  68         "] tabular-output"
  69     }
  70 }
  71 $io-error ;
  72
  73 HELP: with-row
  74 { $values { "quot" quotation } }
  75 { $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 } "." }
  76 $io-error ;
  77
  78 HELP: with-cell
  79 { $values { "quot" quotation } }
  80 { $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 } "." }
  81 $io-error ;
  82
  83 HELP: write-cell
  84 { $values { "str" string } }
  85 { $description "Outputs a table cell containing a single string. This word can only be called inside the quotation given to " { $link with-row } "." }
  86 $io-error ;
  87
  88 HELP: with-style
  89 { $values { "style" assoc } { "quot" quotation } }
  90 { $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" } "." }
  91 { $notes "Details are in the documentation for " { $link make-span-stream } "." }
  92 $io-error ;
  93
  94 ARTICLE: "formatted-stream-protocol" "Formatted stream protocol"
  95 "The " { $vocab-link "io.styles" } " vocabulary defines a protocol for output streams that support rich text."
  96 { $subsections
  97     stream-format
  98     make-span-stream
  99     make-block-stream
 100     make-cell-stream
 101     stream-write-table
 102 } ;
 103
 104 ARTICLE: "formatted-stdout" "Formatted output on the default stream"
 105 "The below words perform formatted output on " { $link output-stream } "."
 106 $nl
 107 "Formatted output:"
 108 { $subsections
 109     format
 110     with-style
 111     with-nesting
 112 }
 113 "Tabular output:"
 114 { $subsections
 115     tabular-output
 116     with-row
 117     with-cell
 118     write-cell
 119 } ;
 120
 121 HELP: href
 122 { $description "Character style. A URL string that the text links to." } ;
 123
 124 HELP: image-style
 125 { $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." } ;
 126
 127 ARTICLE: "character-styles" "Character styles"
 128 "Character styles for " { $link stream-format } " and " { $link with-style } ":"
 129 { $subsections
 130     foreground
 131     background
 132     font-name
 133     font-size
 134     font-style
 135 }
 136 "Special styles:"
 137 { $subsections
 138     href
 139     image-style
 140 }
 141 { $see-also "presentations" } ;
 142
 143 ARTICLE: "paragraph-styles" "Paragraph styles"
 144 "Paragraph styles for " { $link with-nesting } ":"
 145 { $subsections
 146     page-color
 147     border-color
 148     inset
 149     wrap-margin
 150     presented
 151 } ;
 152
 153 ARTICLE: "table-styles" "Table styles"
 154 "Table styles for " { $link tabular-output } ":"
 155 { $subsections
 156     table-gap
 157     table-border
 158 } ;
 159
 160 HELP: write-object
 161 { $values { "str" string } { "obj" object } }
 162 { $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 } "." }
 163 $io-error ;
 164
 165 ARTICLE: "presentations" "Presentations"
 166 "A special style for " { $link format } " and " { $link with-nesting } ":"
 167 { $subsections presented }
 168 "The " { $link presented } " style can be used to emit clickable objects. A utility word for outputting this style:"
 169 { $subsections write-object } ;
 170
 171 ARTICLE: "styles" "Text styles"
 172 "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."
 173 $nl
 174 "Style hashtables are keyed by symbols from the " { $vocab-link "io.styles" } " vocabulary."
 175 { $subsections
 176     "character-styles"
 177     "paragraph-styles"
 178     "table-styles"
 179     "presentations"
 180 } ;
 181
 182 ARTICLE: "io.styles" "Formatted output"
 183 "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" } "."
 184 { $subsections
 185     "formatted-stream-protocol"
 186     "formatted-stdout"
 187     "styles"
 188 } ;
 189
 190 ABOUT: "io.styles"
 191
 192 HELP: plain
 193 { $description "A value for the " { $link font-style } " character style denoting plain text." } ;
 194
 195 HELP: bold
 196 { $description "A value for the " { $link font-style } " character style denoting boldface text." } ;
 197
 198 HELP: italic
 199 { $description "A value for the " { $link font-style } " character style denoting italicized text." } ;
 200
 201 HELP: bold-italic
 202 { $description "A value for the " { $link font-style } " character style denoting boldface italicized text." } ;
 203
 204 HELP: foreground
 205 { $description "Character style. An instance of " { $link color } ". See " { $link "colors" } "." }
 206 { $examples
 207     { $code
 208         "USING: colors.gray io.styles hashtables sequences kernel math ;"
 209         "10 <iota> ["
 210         "    \"Hello world\\n\""
 211         "    swap 10 / 1 <gray> foreground associate format"
 212         "] each"
 213     }
 214 } ;
 215
 216 HELP: background
 217 { $description "Character style. An instance of " { $link color } ". See " { $link "colors" } "." }
 218 { $examples
 219     { $code
 220         "USING: colors hashtables io io.styles kernel math sequences ;"
 221         "10 <iota> ["
 222         "    \"Hello world\\n\""
 223         "    swap 10 / 1 over - over 1 <rgba>"
 224         "    background associate format"
 225         "] each"
 226     }
 227 } ;
 228
 229 HELP: font-name
 230 { $description "Character style. Font family named by a string." }
 231 { $examples
 232     "This example outputs some different font sizes:"
 233     { $code
 234         "USING: hashtables io io.styles kernel sequences ;"
 235         "{ \"monospace\" \"serif\" \"sans-serif\" }"
 236         "[ dup font-name associate format nl ] each"
 237     }
 238 } ;
 239
 240 HELP: font-size
 241 { $description "Character style. Font size, an integer." }
 242 { $examples
 243     "This example outputs some different font sizes:"
 244     { $code
 245         "USING: hashtables io io.styles kernel sequences ;"
 246         "{ 12 18 24 72 }"
 247         "[ \"Bigger\" swap font-size associate format nl ] each"
 248     }
 249 }  ;
 250
 251 HELP: font-style
 252 { $description "Character style. Font style, one of " { $link plain } ", " { $link bold } ", " { $link italic } ", or " { $link bold-italic } "." }
 253 { $examples
 254     "This example outputs text in all three styles:"
 255     { $code
 256         "USING: accessors hashtables io io.styles kernel sequences ;"
 257         "{ plain bold italic bold-italic }"
 258         "[ [ name>> ] keep font-style associate format nl ] each"
 259     }
 260 }  ;
 261
 262 HELP: presented
 263 { $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." } ;
 264
 265 HELP: page-color
 266 { $description "Paragraph style. An instance of " { $link color } ". See " { $link "colors" } "." }
 267 { $examples
 268     { $code
 269         "USING: colors io io.styles ;"
 270         "H{ { page-color T{ rgba f 1 0.8 0.5 1 } } }"
 271         "[ \"A background\" write ] with-nesting nl"
 272     }
 273 } ;
 274
 275 HELP: border-color
 276 { $description "Paragraph style. An instance of " { $link color } ". See " { $link "colors" } "." }
 277 { $examples
 278     { $code
 279         "USING: colors io io.styles ;"
 280         "H{ { border-color T{ rgba f 1 0 0 1 } } }"
 281         "[ \"A border\" write ] with-nesting nl"
 282     }
 283 } ;
 284
 285 HELP: inset
 286 { $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." }
 287 { $examples
 288     { $code
 289         "USING: io io.styles ;"
 290         "H{ { inset { 10 10 } } }"
 291         "[ \"Some inset text\" write ] with-nesting nl"
 292     }
 293 } ;
 294
 295 HELP: wrap-margin
 296 { $description "Paragraph style. Pixels between left margin and right margin where text is wrapped, an integer." } ;
 297
 298 { wrap-margin bl } related-words
 299
 300 HELP: table-gap
 301 { $description "Table style. Horizontal and vertical gap between table cells, denoted by a pair of integers." } ;
 302
 303 { table-gap table-border stream-write-table tabular-output } related-words
 304
 305 HELP: table-border
 306 { $description "Table style. An instance of " { $link color } ". See " { $link "colors" } "." } ;
 307
 308 HELP: input
 309 { $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> } "." }
 310 { $examples
 311     "This presentation class is used for the code examples you see in the online help:"
 312     { $code
 313         "USING: io io.styles kernel ;"
 314         "\"2 3 + .\" dup <input> write-object nl"
 315     }
 316 } ;
 317
 318 HELP: <input>
 319 { $values { "string" string } { "input" input } }
 320 { $description "Creates a new " { $link input } "." } ;
 321
 322 HELP: standard-table-style
 323 { $values { "value" hashtable } }
 324 { $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 } "." } ;
 325
 326 ARTICLE: "io.streams.plain" "Plain writer streams"
 327 "Plain writer streams wrap an underlying stream and provide a default implementation of "
 328 { $link stream-nl } ", "
 329 { $link stream-format } ", "
 330 { $link make-span-stream } ", "
 331 { $link make-block-stream } " and "
 332 { $link make-cell-stream } "."
 333 { $subsections plain-writer } ;