]> matita.cs.unibo.it Git - helm.git/blob - helm/DEVEL/pxp/netstring/netencoding.mli
minidom.c : fixed memory leak
[helm.git] / 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  *)