helm/DEVEL/pxp/netstring/netencoding.mli

   1 (* $Id$
   2  * ----------------------------------------------------------------------
   3  *
   4  *)
   5
   6 (**********************************************************************)
   7 (* Several encodings important for the net                            *)
   8 (**********************************************************************)
   9
  10
  11 (**********************************************************************)
  12 (* Base 64 encoding                                                   *)
  13 (**********************************************************************)
  14
  15 (* See RFC 2045 for a description of Base 64 encoding. *)
  16
  17 (* THREAD-SAFETY:
  18  * All Base64 functions are reentrant and thus thread-safe.
  19  *)
  20
  21 module Base64 : sig
  22
  23   val encode : ?pos:int -> ?len:int -> ?linelength:int -> ?crlf:bool ->
  24                string -> string
  25       (* Compute the "base 64" encoding of the given string argument.
  26        * Note that the result is a string that only contains the characters
  27        * a-z, A-Z, 0-9, +, /, =, and optionally spaces, CR and LF characters.
  28        *
  29        * If pos and/or len are passed, only the substring starting at
  30        * pos (default: 0) with length len (default: rest of the string)
  31        * is encoded.
  32        *
  33        * The result is divided up into lines not longer than 'linelength'
  34        * (without counting the line separator); default: do not divide lines.
  35        * If 'linelength' is smaller than 4, no line division is performed.
  36        * If 'linelength' is not divisible by 4, the produced lines are a
  37        * bit shorter than 'linelength'.
  38        *
  39        * If 'crlf' (default: false) the lines are ended by CRLF; otherwise
  40        * they are only ended by LF.
  41        * (You need the crlf option to produce correct MIME messages.)
  42        *
  43        *)
  44
  45   val url_encode : ?pos:int -> ?len:int -> ?linelength:int -> ?crlf:bool ->
  46                    string -> string
  47       (* Same as 'encode' but use slightly different characters that can be
  48        * part of URLs without additional encodings.
  49        * The encoded string consists only of the characters a-z, A-Z, 0-9,
  50        * -, /, .
  51        * 'url_encode' does NOT implement the Base 64 encoding as described
  52        * in the standard!
  53        *)
  54
  55   val encode_substring : string -> pos:int -> len:int -> linelength:int ->
  56                          crlf:bool -> string
  57       (* *** DEPRECATED FUNCTION *** Use 'encode' instead! ***
  58        *
  59        * encode_substring s pos len linelen crlf:
  60        * Encodes the substring at position 'pos' in 's' with length 'len'.
  61        * The result is divided up into lines not longer than 'linelen' (without
  62        * counting the line separator).
  63        * If 'linelen' is smaller than 4, no line division is performed.
  64        * If 'linelen' is not divisible by 4, the produced lines are a
  65        * bit shorter than 'linelen'.
  66        * If 'crlf' the lines are ended by CRLF; otherwise they are only
  67        * ended by LF.
  68        * (You need the crlf option to produce correct MIME messages.)
  69        *)
  70
  71   val decode : ?pos:int -> ?len:int -> ?url_variant:bool ->
  72                ?accept_spaces:bool -> string -> string
  73       (* Decodes the given string argument.
  74        *
  75        * If pos and/or len are passed, only the substring starting at
  76        * pos (default: 0) with length len (default: rest of the string)
  77        * is decoded.
  78        *
  79        * If url_variant (default: true) is set, the functions also
  80        * accepts the characters '-' and '.' as produced by 'url_encode'.
  81        *
  82        * If accept_spaces (default: false) is set, the function ignores
  83        * white space contained in the string to decode (otherwise the
  84        * function fails if it finds white space).
  85        *)
  86
  87   val decode_ignore_spaces : string -> string
  88       (* *** DEPRECATED FUNCTION *** Use 'decode' instead! ***
  89        *
  90        * Decodes the string, too, but it is allowed that the string contains
  91        * whitespace characters.
  92        * This function is slower than 'decode'.
  93        *)
  94
  95   val decode_substring : string -> pos:int -> len:int -> url_variant:bool ->
  96                          accept_spaces:bool -> string
  97       (* *** DEPRECATED FUNCTION *** Use 'decode' instead! ***
  98        *
  99        * decode_substring s pos len url spaces:
 100        * Decodes the substring of 's' beginning at 'pos' with length 'len'.
 101        * If 'url', strings created by 'url_encode' are accepted, too.
 102        * If 'spaces', whitespace characters are allowed in the string.
 103        *)
 104 end
 105
 106 (**********************************************************************)
 107 (* Quoted printable encoding                                          *)
 108 (**********************************************************************)
 109
 110 (* See RFC 2045.
 111  * This implementation assumes that the encoded string has a text MIME
 112  * type. Because of this, the characters CR and LF are never protected
 113  * by hex tokens; they are copied literally to the output string.
 114  *)
 115
 116 (* THREAD-SAFETY:
 117  * All QuotedPrintable functions are reentrant and thus thread-safe.
 118  *)
 119
 120 module QuotedPrintable :
 121   sig
 122     val encode : ?pos:int -> ?len:int -> string -> string
 123         (* Encodes the string and returns it.
 124          * Note line breaks:
 125          *   No additional soft line breaks are added. The characters CR
 126          *   and LF are not represented as =0D resp. =0A. (But other control
 127          *   characters ARE encoded.)
 128          * Note unsafe characters:
 129          *   As recommended by RFC 2045, the characters !\"#$@[]^`{|}~
 130          *   are additionally represented as hex tokens.        -- "
 131          *
 132          * If pos and/or len are passed, only the substring starting at
 133          * pos (default: 0) with length len (default: rest of the string)
 134          * is encoded.
 135          *)
 136
 137     val encode_substring : string -> pos:int -> len:int -> string
 138         (* *** DEPRECATED FUNCTION *** Use 'encode' instead! ***
 139          * encode_substring s pos len:
 140          * Encodes the substring of 's' beginning at 'pos' with length 'len'.
 141          *)
 142
 143     val decode : ?pos:int -> ?len:int -> string -> string
 144         (* Decodes the string and returns it.
 145          * Most format errors cause an Invalid_argument exception.
 146          * Note that soft line breaks can be properly decoded although
 147          * 'encode' will never produce them.
 148          *
 149          * If pos and/or len are passed, only the substring starting at
 150          * pos (default: 0) with length len (default: rest of the string)
 151          * is decoded.
 152          *)
 153
 154     val decode_substring : string -> pos:int -> len:int -> string
 155         (* *** DEPRECATED FUNCTION *** Use 'decode' instead! ***
 156          * decode_substring s pos len:
 157          * Decodes the substring of 's' beginning at 'pos' with length 'len'.
 158          *)
 159
 160   end
 161
 162 (**********************************************************************)
 163 (* Q encoding                                                         *)
 164 (**********************************************************************)
 165
 166 (* See RFC 2047.
 167  * The functions behave similar to those of QuotedPrintable.
 168  *)
 169
 170 (* THREAD-SAFETY:
 171  * All Q functions are reentrant and thus thread-safe.
 172  *)
 173
 174 module Q :
 175   sig
 176     val encode : ?pos:int -> ?len:int -> string -> string
 177         (* Note:
 178          * All characters except alphanumeric characters are protected by
 179          * hex tokens.
 180          * In particular, spaces are represented as "=20", not as "_".
 181          *)
 182
 183     val decode : ?pos:int -> ?len:int -> string -> string
 184
 185     val encode_substring : string -> pos:int -> len:int -> string
 186         (* *** DEPRECATED FUNCTION *** Use 'encode' instead! *** *)
 187
 188     val decode_substring : string -> pos:int -> len:int -> string
 189         (* *** DEPRECATED FUNCTION *** Use 'decode' instead! *** *)
 190   end
 191
 192 (**********************************************************************)
 193 (* B encoding                                                         *)
 194 (**********************************************************************)
 195
 196 (* The B encoding of RFC 2047 is the same as Base64. *)
 197
 198
 199 (**********************************************************************)
 200 (* URL-encoding                                                       *)
 201 (**********************************************************************)
 202
 203 (* Encoding/Decoding within URLs:
 204  *
 205  * The following two functions perform the '%'-substitution for
 206  * characters that may otherwise be interpreted as metacharacters.
 207  *
 208  * According to: RFC 1738, RFC 1630
 209  *)
 210
 211 (* THREAD-SAFETY:
 212  * The Url functions are thread-safe.
 213  *)
 214
 215 module Url :
 216   sig
 217     val decode : string -> string
 218     val encode : string -> string
 219   end
 220
 221
 222 (**********************************************************************)
 223 (* HTMLization                                                        *)
 224 (**********************************************************************)
 225
 226 (* Encodes characters that need protection by converting them to
 227  * entity references. E.g. "<" is converted to "&lt;".
 228  * As the entities may be named, there is a dependency on the character
 229  * set. Currently, there are only functions for the Latin 1 alphabet.
 230  *)
 231
 232 (* THREAD-SAFETY:
 233  * The Html functions are thread-safe.
 234  *)
 235
 236 module Html :
 237   sig
 238     val encode_from_latin1 : string -> string
 239         (* Encodes the characters 0-8, 11-12, 14-31, '<', '>', '"', '&',
 240          * 127-255. If the characters have a name, a named entity is
 241          * preferred over a numeric entity.
 242          *)
 243     val decode_to_latin1   : string -> string
 244         (* Decodes the string. Unknown named entities are left as they
 245          * are (i.e. decode_to_latin1 "&nonsense;" = "&nonsense;").
 246          * The same applies to numeric entities greater than 255.
 247          *)
 248   end
 249
 250
 251 (* ======================================================================
 252  * History:
 253  *
 254  * $Log$
 255  * Revision 1.1  2000/11/17 09:57:27  lpadovan
 256  * Initial revision
 257  *
 258  * Revision 1.4  2000/06/25 22:34:43  gerd
 259  *      Added labels to arguments.
 260  *
 261  * Revision 1.3  2000/06/25 21:15:48  gerd
 262  *      Checked thread-safety.
 263  *
 264  * Revision 1.2  2000/03/03 01:08:29  gerd
 265  *      Added Netencoding.Html functions.
 266  *
 267  * Revision 1.1  2000/03/02 01:14:48  gerd
 268  *      Initial revision.
 269  *
 270  *
 271  *)