core/io/encodings/encodings-docs.factor

   1 USING: help.markup help.syntax io quotations math ;
   2 IN: io.encodings
   3
   4 HELP: <encoder>
   5 { $values { "stream" "an output stream" }
   6     { "encoding" "an encoding descriptor" }
   7     { "newstream" "an encoded output stream" } }
   8 { $description "Wraps the given stream in a new stream using the given encoding for all output. The encoding descriptor can either be a class or an instance of something conforming to the " { $link "encodings-protocol" } "." }
   9 $low-level-note ;
  10
  11 HELP: <decoder>
  12 { $values { "stream" "an input stream" }
  13     { "encoding" "an encoding descriptor" }
  14     { "newstream" "an encoded output stream" } }
  15 { $description "Wraps the given stream in a new stream using the given encoding for all input. The encoding descriptor can either be a class or an instance of something conforming to the " { $link "encodings-protocol" } "." }
  16 $low-level-note ;
  17
  18 HELP: decode-char
  19 { $values { "stream" "an underlying input stream" }
  20     { "encoding" "An encoding descriptor tuple" } { "char/f" "a code point or " { $link f } } }
  21 { $contract "Reads a single code point from the underlying stream, interpreting it by the encoding. Returns " { $link f } " if the stream is reached." }
  22 $low-level-note ;
  23
  24 HELP: encode-char
  25 { $values { "char" "a character" }
  26     { "stream" "an underlying output stream" }
  27     { "encoding" "an encoding descriptor" } }
  28 { $contract "Writes the code point to the underlying stream in the given encoding." }
  29 $low-level-note ;
  30
  31 { encode-char decode-char } related-words
  32
  33 HELP: decode-input
  34 { $values
  35      { "encoding" "an encoding descriptor" }
  36 }
  37 { $description "Changes the encoding of the current input stream stored in the " { $link input-stream } " variable." } ;
  38
  39 HELP: encode-output
  40 { $values
  41      { "encoding" "an encoding descriptor" }
  42 }
  43 { $description "Changes the encoding of the current output stream stored in the " { $link output-stream } " variable." } ;
  44
  45 HELP: re-decode
  46 { $values
  47      { "stream" "a stream" } { "encoding" "an encoding descriptor" }
  48      { "newstream" "a new stream" }
  49 }
  50 { $description "Creates a new decoding stream with the supplied encoding descriptor from an existing stream by calling the " { $link <decoder> } " word." } ;
  51
  52 HELP: re-encode
  53 { $values
  54      { "stream" "a stream" } { "encoding" "an encoding descriptor" }
  55      { "newstream" "a new stream" }
  56 }
  57 { $description "Creates a new encoding stream with the supplied encoding descriptor from an existing stream by calling the " { $link <encoder> } " word." } ;
  58
  59 { re-decode re-encode } related-words
  60
  61 HELP: with-decoded-input
  62 { $values
  63      { "encoding" "an encoding descriptor" } { "quot" quotation }
  64 }
  65 { $description "Creates a new decoding stream with the given encoding descriptor and calls the quotation with this stream set to the " { $link input-stream } " variable. The original decoder stream is restored after the quotation returns and the stream is kept open for future input operations." } ;
  66
  67 HELP: with-encoded-output
  68 { $values
  69      { "encoding" "an encoding descriptor" } { "quot" quotation }
  70 }
  71 { $description "Creates a new encoder with the given encoding descriptor and calls the quotation using this encoder. The original encoder object is restored after the quotation returns and the stream is kept open for future output operations." } ;
  72
  73 HELP: replacement-char
  74 { $values
  75     { "value" integer }
  76 }
  77 { $description "A code point that replaces input that could not be decoded. The presence of this character in the decoded data usually signifies an error." } ;
  78
  79 ARTICLE: "encodings-descriptors" "Encoding descriptors"
  80 "An encoding descriptor is something which can be used with binary input or output streams to encode or decode bytes stored in a certain representation. It must conform to the " { $link "encodings-protocol" } ". Encodings which you can use are defined in the following vocabularies:"
  81 { $subsection "io.encodings.binary" }
  82 { $subsection "io.encodings.utf8" }
  83 { $vocab-subsection "UTF-16 encoding" "io.encodings.utf16" }
  84 { $vocab-subsection "UTF-32 encoding" "io.encodings.utf32" }
  85 { $vocab-subsection "Strict encodings" "io.encodings.strict" }
  86 "Legacy encodings:"
  87 { $vocab-subsection "8-bit encodings" "io.encodings.8-bit" }
  88 { $vocab-subsection "ASCII encoding" "io.encodings.ascii" }
  89 { $see-also "encodings-introduction" } ;
  90
  91 ARTICLE: "encodings-protocol" "Encoding protocol"
  92 "There are two parts to implementing a new encoding. First, methods for creating an encoded or decoded stream must be provided. These have defaults, however, which wrap a stream in an encoder or decoder wrapper with the given encoding descriptor."
  93 { $subsection <encoder> }
  94 { $subsection <decoder> }
  95 "If an encoding might be contained in the code slot of an encoder or decoder tuple, then the following methods must be implemented to read or write one code point from a stream:"
  96 { $subsection decode-char }
  97 { $subsection encode-char }
  98 { $see-also "encodings-introduction" } ;
  99
 100 ARTICLE: "encodings-constructors" "Manually constructing an encoded stream"
 101 "The following words can be used to construct encoded streams. Note that they are usually not used directly, but rather by the stream constructors themselves. Most stream constructors take an encoding descriptor as a parameter and call these constructors internally."
 102 { $subsection <encoder> }
 103 { $subsection <decoder> } ;
 104
 105 ARTICLE: "io.encodings" "I/O encodings"
 106 "The " { $vocab-link "io.encodings" } " vocabulary provides utilities for encoding and decoding bytes that represent text. Encodings can be used in the following situations:"
 107 { $list
 108   "With binary input streams, to convert bytes to characters"
 109   "With binary output streams, to convert characters to bytes"
 110   "With byte arrays, to convert bytes to characters"
 111   "With strings, to convert characters to bytes"
 112 }
 113 { $subsection "encodings-descriptors" }
 114 { $subsection "encodings-constructors" }
 115 { $subsection "io.encodings.string" }
 116 "New types of encodings can be defined:"
 117 { $subsection "encodings-protocol" }
 118 "Setting encodings on the current streams:"
 119 { $subsection encode-output }
 120 { $subsection decode-input }
 121 "Setting encodings on streams:"
 122 { $subsection re-encode }
 123 { $subsection re-decode }
 124 "Combinators to change the encoding:"
 125 { $subsection with-encoded-output }
 126 { $subsection with-decoded-input }
 127 { $see-also "encodings-introduction" } ;
 128
 129 ABOUT: "io.encodings"