basis/io/styles/styles-docs.factor

   1 USING: help.markup help.syntax io.streams.plain io strings
   2 hashtables kernel quotations ;
   3 IN: io.styles
   4
   5 HELP: stream-format
   6 { $values { "str" string } { "style" "a hashtable" } { "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" } " hashtable 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" "a hashtable" } { "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" "a hashtable" } { "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" hashtable } { "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" "a hashtable" } { "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" "a hashtable" } }
  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" "a hashtable" } { "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" "a hashtable" } { "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" "a hashtable" } { "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 ARTICLE: "character-styles" "Character styles"
 115 "Character styles for " { $link stream-format } " and " { $link with-style } ":"
 116 { $subsection foreground }
 117 { $subsection background }
 118 { $subsection font }
 119 { $subsection font-size }
 120 { $subsection font-style }
 121 { $subsection presented } ;
 122
 123 ARTICLE: "paragraph-styles" "Paragraph styles"
 124 "Paragraph styles for " { $link with-nesting } ":"
 125 { $subsection page-color }
 126 { $subsection border-color }
 127 { $subsection border-width }
 128 { $subsection wrap-margin }
 129 { $subsection presented } ;
 130
 131 ARTICLE: "table-styles" "Table styles"
 132 "Table styles for " { $link tabular-output } ":"
 133 { $subsection table-gap }
 134 { $subsection table-border } ;
 135
 136 HELP: write-object
 137 { $values { "str" string } { "obj" "an object" } }
 138 { $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 } "." }
 139 $io-error ;
 140
 141 ARTICLE: "presentations" "Presentations"
 142 "The " { $link presented } " style can be used to emit clickable objects. A utility word for outputting this style:"
 143 { $subsection write-object } ;
 144
 145 ARTICLE: "styles" "Styled text"
 146 "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."
 147 $nl
 148 "Style hashtables are keyed by symbols from the " { $vocab-link "io.styles" } " vocabulary."
 149 { $subsection "character-styles" }
 150 { $subsection "paragraph-styles" }
 151 { $subsection "table-styles" }
 152 { $subsection "presentations" } ;
 153
 154 ARTICLE: "io.styles" "Formatted output"
 155 "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" } "."
 156 { $subsection "formatted-stream-protocol" }
 157 { $subsection "formatted-stdout" }
 158 { $subsection "styles" } ;
 159
 160 ABOUT: "io.styles"
 161
 162 HELP: plain
 163 { $description "A value for the " { $link font-style } " character style denoting plain text." } ;
 164
 165 HELP: bold
 166 { $description "A value for the " { $link font-style } " character style denoting boldface text." } ;
 167
 168 HELP: italic
 169 { $description "A value for the " { $link font-style } " character style denoting italicized text." } ;
 170
 171 HELP: bold-italic
 172 { $description "A value for the " { $link font-style } " character style denoting boldface italicized text." } ;
 173
 174 HELP: foreground
 175 { $description "Character style. Text color, denoted by a sequence of four numbers between 0 and 1 (red, green, blue and alpha)." }
 176 { $examples
 177     { $code
 178         "10 ["
 179             "    \"Hello world\" swap"
 180             "    { 0.1 0.1 0.2 1 } n*v { 1 1 1 1 } vmin"
 181             "    foreground associate format nl"
 182         "] each"
 183     }
 184 } ;
 185
 186 HELP: background
 187 { $description "Character style. Background color, denoted by a sequence of four numbers between 0 and 1 (red, green, blue and alpha)." }
 188 { $examples
 189     { $code
 190         "10 ["
 191             "    \"Hello world\" swap"
 192             "    { 0.1 0.4 0.1 } n*v { 1 1 1 } vmin { 1 } append"
 193             "    background associate format nl"
 194         "] each"
 195     }
 196 } ;
 197
 198 HELP: font
 199 { $description "Character style. Font family named by a string." }
 200 { $examples
 201     "This example outputs some different font sizes:"
 202     { $code "{ \"monospace\" \"serif\" \"sans-serif\" }\n[ dup font associate format nl ] each" }
 203 } ;
 204
 205 HELP: font-size
 206 { $description "Character style. Font size, an integer." }
 207 { $examples
 208     "This example outputs some different font sizes:"
 209     { $code "{ 12 18 24 72 }"
 210         "[ \"Bigger\" swap font-size associate format nl ] each"
 211     }
 212 }  ;
 213
 214 HELP: font-style
 215 { $description "Character style. Font style, one of " { $link plain } ", " { $link bold } ", " { $link italic } ", or " { $link bold-italic } "." }
 216 { $examples
 217     "This example outputs text in all three styles:"
 218     { $code "{ plain bold italic bold-italic }\n[ [ name>> ] keep font-style associate format nl ] each" }
 219 }  ;
 220
 221 HELP: presented
 222 { $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." } ;
 223
 224 HELP: presented-path
 225 { $description "Character and paragraph style. An editable object associated with the text. In the Factor UI, this is shown as a clickable presentation of the object path together with an expander button which displays an object editor; left-clicking invokes a default command, and right-clicking shows a menu of commands." } ;
 226
 227 HELP: presented-printer
 228 { $description "Character and paragraph style. A quotation with stack effect " { $snippet "( obj -- )" } " which is applied to the value at the " { $link presented-path } " if the presentation needs to be re-displayed after the object has been edited." } ;
 229
 230 HELP: page-color
 231 { $description "Paragraph style. Background color of the paragraph block, denoted by a sequence of four numbers between 0 and 1 (red, green, blue and alpha)." }
 232 { $examples
 233     { $code "H{ { page-color { 1 0.8 0.5 1 } } }\n[ \"A background\" write ] with-nesting nl" }
 234 } ;
 235
 236 HELP: border-color
 237 { $description "Paragraph style. Border color of the paragraph block, denoted by a sequence of four numbers between 0 and 1 (red, green, blue and alpha)." }
 238 { $examples
 239     { $code "H{ { border-color { 1 0 0 1 } } }\n[ \"A border\" write ] with-nesting nl" }
 240 } ;
 241
 242 HELP: border-width
 243 { $description "Paragraph style. Pixels between edge of text and border color, an integer." }
 244 { $examples
 245     { $code "H{ { border-width 10 } }\n[ \"Some inset text\" write ] with-nesting nl" }
 246 } ;
 247
 248 HELP: wrap-margin
 249 { $description "Paragraph style. Pixels between left margin and right margin where text is wrapped, an integer." } ;
 250
 251 { wrap-margin bl } related-words
 252
 253 HELP: table-gap
 254 { $description "Table style. Horizontal and vertical gap between table cells, denoted by a pair of integers." } ;
 255
 256 { table-gap table-border stream-write-table tabular-output } related-words
 257
 258 HELP: table-border
 259 { $description "Table style. Color of the border drawn between cells, denoted by a sequence of four numbers between 0 and 1 (red, green, blue and alpha)." } ;
 260
 261 HELP: input
 262 { $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> } "." }
 263 { $examples
 264     "This presentation class is used for the code examples you see in the online help:"
 265     { $code "\"2 3 + .\" dup <input> write-object nl" }
 266 } ;
 267
 268 HELP: <input>
 269 { $values { "string" string } { "input" input } }
 270 { $description "Creates a new " { $link input } "." } ;
 271
 272 HELP: standard-table-style
 273 { $values { "style" hashtable } }
 274 { $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 } "." } ;
 275
 276 ARTICLE: "io.streams.plain" "Plain writer streams"
 277 "Plain writer streams wrap an underlying stream and provide a default implementation of "
 278 { $link stream-nl } ", "
 279 { $link stream-format } ", "
 280 { $link make-span-stream } ", "
 281 { $link make-block-stream } " and "
 282 { $link make-cell-stream } "."
 283 { $subsection plain-writer } ;