core/io/encodings/encodings-docs.factor

   1 USING: help.markup help.syntax io quotations math sequences strings ;
   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 end is reached." }
  22 $low-level-note ;
  23
  24 HELP: decode-until
  25 { $values
  26   { "seps" sequence }
  27   { "stream" "an input stream" }
  28   { "encoding" "an encoding descriptor" }
  29   { "string/f" { $maybe string } }
  30   { "sep/f" { $maybe "encountered separator" } }
  31 }
  32 { $description "Decodes characters from the stream until one of the separators are encountered." } ;
  33
  34 HELP: encode-char
  35 { $values { "char" "a character" }
  36     { "stream" "an underlying output stream" }
  37     { "encoding" "an encoding descriptor" } }
  38 { $contract "Writes the code point to the underlying stream in the given encoding." }
  39 $low-level-note ;
  40
  41 { encode-char decode-char } related-words
  42
  43 HELP: decode-input
  44 { $values
  45     { "encoding" "an encoding descriptor" }
  46 }
  47 { $description "Changes the encoding of the current input stream stored in the " { $link input-stream } " variable." } ;
  48
  49 HELP: encode-output
  50 { $values
  51     { "encoding" "an encoding descriptor" }
  52 }
  53 { $description "Changes the encoding of the current output stream stored in the " { $link output-stream } " variable." } ;
  54
  55 HELP: re-decode
  56 { $values
  57     { "stream" "a stream" } { "encoding" "an encoding descriptor" }
  58     { "newstream" "a new stream" }
  59 }
  60 { $description "Creates a new decoding stream with the supplied encoding descriptor from an existing stream by calling the " { $link <decoder> } " word." } ;
  61
  62 HELP: re-encode
  63 { $values
  64     { "stream" "a stream" } { "encoding" "an encoding descriptor" }
  65     { "newstream" "a new stream" }
  66 }
  67 { $description "Creates a new encoding stream with the supplied encoding descriptor from an existing stream by calling the " { $link <encoder> } " word." } ;
  68
  69 { re-decode re-encode } related-words
  70
  71 HELP: with-decoded-input
  72 { $values
  73     { "encoding" "an encoding descriptor" } { "quot" quotation }
  74 }
  75 { $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." } ;
  76
  77 HELP: with-encoded-output
  78 { $values
  79     { "encoding" "an encoding descriptor" } { "quot" quotation }
  80 }
  81 { $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." } ;
  82
  83 HELP: replacement-char
  84 { $values
  85     { "value" integer }
  86 }
  87 { $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." } ;
  88
  89 ARTICLE: "encodings-descriptors" "Encoding descriptors"
  90 "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:"
  91 { $subsections
  92     "io.encodings.binary"
  93     "io.encodings.utf8"
  94 }
  95 { $vocab-subsections
  96     { "UTF-16 encoding" "io.encodings.utf16" }
  97     { "UTF-32 encoding" "io.encodings.utf32" }
  98     { "Strict encodings" "io.encodings.strict" }
  99     { "8-bit encodings" "io.encodings.8-bit" }
 100     { "ASCII encoding" "io.encodings.ascii" }
 101 }
 102 { $see-also "encodings-introduction" } ;
 103
 104 ARTICLE: "encodings-protocol" "Encoding protocol"
 105 "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."
 106 { $subsections
 107     <encoder>
 108     <decoder>
 109 }
 110 "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:"
 111 { $subsections
 112     decode-char
 113     encode-char
 114 }
 115 { $see-also "encodings-introduction" } ;
 116
 117 ARTICLE: "encodings-constructors" "Manually constructing an encoded stream"
 118 "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."
 119 { $subsections
 120     <encoder>
 121     <decoder>
 122 } ;
 123
 124 ARTICLE: "io.encodings" "I/O encodings"
 125 "The " { $vocab-link "io.encodings" } " vocabulary provides utilities for encoding and decoding bytes that represent text. Encodings can be used in the following situations:"
 126 { $list
 127   "With binary input streams, to convert bytes to characters"
 128   "With binary output streams, to convert characters to bytes"
 129   "With byte arrays, to convert bytes to characters"
 130   "With strings, to convert characters to bytes"
 131 }
 132 { $subsections
 133     "encodings-descriptors"
 134     "encodings-constructors"
 135     "io.encodings.string"
 136 }
 137 "New types of encodings can be defined:"
 138 { $subsections "encodings-protocol" }
 139 "Setting encodings on the current streams:"
 140 { $subsections
 141     encode-output
 142     decode-input
 143 }
 144 "Setting encodings on streams:"
 145 { $subsections
 146     re-encode
 147     re-decode
 148 }
 149 "Combinators to change the encoding:"
 150 { $subsections
 151     with-encoded-output
 152     with-decoded-input
 153 }
 154 { $see-also "encodings-introduction" } ;
 155
 156 ABOUT: "io.encodings"