]> matita.cs.unibo.it Git - helm.git/blob - helm/DEVEL/pxp/netstring/doc/README
...
[helm.git] / helm / DEVEL / pxp / netstring / doc / README
1 ******************************************************************************
2 README - Netstring, string processing functions for the net
3 ******************************************************************************
4
5
6 ==============================================================================
7 Abstract
8 ==============================================================================
9
10 Netstring is a collection of string processing functions that are useful in 
11 conjunction with Internet messages and protocols. In particular, it contains 
12 functions for the following purposes:
13
14 -  Parsing MIME messages
15    
16 -  Several encoding/decoding functions (Base 64, Quoted Printable, Q, 
17    URL-encoding)
18    
19 -  A new implementation of the CGI interface that allows users to upload files
20    
21 -  A simple HTML parser
22    
23 -  URL parsing, printing and processing
24    
25 -  Conversion between character sets
26    
27 ==============================================================================
28 Download
29 ==============================================================================
30
31 You can download Netstring as gzip'ed tarball [1]. 
32
33 ==============================================================================
34 Documentation
35 ==============================================================================
36
37 Sorry, there is no manual. The mli files describe each function in detail. 
38 Furthermore, the following additional information may be useful.
39
40 ------------------------------------------------------------------------------
41 New CGI implementation
42 ------------------------------------------------------------------------------
43
44 For a long time, the CGI implementation by Jean-Christophe Filliatre has been 
45 the only freely available module that implemented the CGI interface (it also 
46 based on code by Daniel de Rauglaudre). It worked well, but it did not support 
47 file uploads because this requires a parser for MIME messages.
48
49 The main goal of Netstring is to realize such uploads, and because of this it 
50 contains an almost complete parser for MIME messages.
51
52 The new CGI implementation provides the same functions than the old one, and 
53 some extensions. If you call Cgi.parse_args(), you get the CGI parameters as 
54 before, but as already explained this works also if the parameters are 
55 encaspulated as MIME message. In the HTML code, you can select the MIME format 
56 by using 
57
58 <form action="..." method="post" enctype="multipart/form-data">
59 ...
60 </form>
61
62
63 - this "enctype" attribute forces the browser to send the form parameters as 
64 multipart MIME message (Note: You can neither send the parameters of a 
65 conventional hyperlink as MIME message nor the form parameters if the "method" 
66 is "get"). In many browsers only this particular encoding enables the file 
67 upload elements, you cannot perform file uploads with other encodings. 
68
69 As MIME messages can transport MIME types, filename, and other additional 
70 properties, it is also possible to get these using the enhanced interface. 
71 After calling 
72
73 Cgi.parse_arguments config
74
75 you can get all available information about a certain parameter by invoking 
76
77 let param = Cgi.argument "name"
78
79 - where "param" has the type "argument". There are several accessor functions 
80 to extract the various aspects of arguments (name, filename, value by string, 
81 value by temporary file, MIME type, MIME header) from "argument" values. 
82
83 ------------------------------------------------------------------------------
84 Base64, and other encodings
85 ------------------------------------------------------------------------------
86
87 Netstring is also the successor of the Base64 package. It provides a Base64 
88 compatible interface, and an enhanced API. The latter is contained in the 
89 Netencoding module which also offers implementations of the "quoted printable", 
90 "Q", and "URL" encodings. Please see netencoding.mli for details.
91
92 ------------------------------------------------------------------------------
93 The MIME scanner functions
94 ------------------------------------------------------------------------------
95
96 In the Mimestring module you can find several functions scanning parts of MIME 
97 messages. These functions already cover most aspects of MIME messages: Scanning 
98 of headers, analysis of structured header entries, and scanning of multipart 
99 bodies. Of course, a full-featured MIME scanner would require some more 
100 functions, especially concrete parsers for frequent structures (mail addresses 
101 or date strings). 
102
103 Please see the file mimestring.mli for details.
104
105 ------------------------------------------------------------------------------
106 The HTML parser
107 ------------------------------------------------------------------------------
108
109 The HTML parser should be able to read every HTML file; whether it is correct 
110 or not. The parser tries to recover from parsing errors as much as possible. 
111
112 The parser returns the HTML term as conventional recursive value (i.e. no 
113 object-oriented design).
114
115 The parser depends a bit on knowledge about the HTML version; mainly because it 
116 needs to know the tags that are always empty. It may be necessary that you must 
117 adjust this configuration before the parser works well enough for your purpose. 
118
119 Please see the Nethtml module for details.
120
121 ------------------------------------------------------------------------------
122 The abstract data type URL
123 ------------------------------------------------------------------------------
124
125 The module Neturl contains support for URL parsing and processing. The 
126 implementation follows strictly the standards RFC 1738 and RFC 1808. URLs can 
127 be parsed, and several accessor functions allow the user to get components of 
128 parsed URLs, or to change components. Modifying URLs is safe; it is impossible 
129 to create a URL that does not have a valid string representation.
130
131 Both absolute and relative URLs are supported. It is possible to apply a 
132 relative URL to a base URL in order to get the corresponding absolute URL.
133
134 ------------------------------------------------------------------------------
135 Conversion between character sets and encodings
136 ------------------------------------------------------------------------------
137
138 The module Netconversion converts strings from one characters set to another. 
139 It is Unicode-based, and there are conversion tables for more than 50 
140 encodings.
141
142 ==============================================================================
143 Author, Copying
144 ==============================================================================
145
146 Netstring has been written by Gerd Stolpmann [2]. You may copy it as you like, 
147 you may use it even for commercial purposes as long as the license conditions 
148 are respected, see the file LICENSE coming with the distribution. It allows 
149 almost everything. 
150
151 ==============================================================================
152 History
153 ==============================================================================
154
155 -  Changed in 0.9.3: Fixed a bug in the "install" rule of the Makefile.
156    
157 -  Changed in 0.9.2: New format for the conversion tables which are now much 
158    smaller.
159    
160 -  Changed in 0.9.1: Updated the Makefile such that (native-code) compilation 
161    of netmappings.ml becomes possible. 
162    
163 -  Changed in 0.9: Extended Mimestring module: It can now process RFC-2047 
164    messages.
165    New Netconversion module which converts strings between character encodings.
166    
167 -  Changed in 0.8.1: Added the component url_accepts_8bits to 
168    Neturl.url_syntax. This helps processing URLs which intentionally contain 
169    bytes >= 0x80.
170    Fixed a bug: Every URL containing a 'j' was malformed!
171    
172 -  Changed in 0.8: Added the module Neturl which provides the abstract data 
173    types of URLs.
174    The whole package is now thread-safe.
175    Added printers for the various opaque data types.
176    Added labels to function arguments where appropriate. The following 
177    functions changed their signatures significantly: Cgi.mk_memory_arg, 
178    Cgi.mk_file_arg.
179    
180 -  Changed in 0.7: Added workarounds for frequent browser bugs. Some functions 
181    take now an additional argument specifying which workarounds are enabled.
182    
183 -  Changed in 0.6.1: Updated URLs in documentation.
184    
185 -  Changed in 0.6: The file upload has been re-implemented to support large 
186    files; the file is now read block by block and the blocks can be collected 
187    either in memory or in a temporary file.
188    Furthermore, the CGI API has been revised. There is now an opaque data type 
189    "argument" that hides all implementation details and that is extensible (if 
190    necessary, it is possible to add features without breaking the interface 
191    again).
192    The CGI argument parser can be configured; currently it is possible to limit 
193    the size of uploaded data, to control by which method arguments are 
194    processed, and to set up where temporary files are created.
195    The other parts of the package that have nothing to do with CGI remain 
196    unchanged. 
197    
198 -  Changed in 0.5.1: A mistake in the documentation has been corrected.
199    
200 -  Initial version 0.5: The Netstring package wants to be the successor of the 
201    Base64-0.2 and the Cgi-0.3 packages. The sum of both numbers is 0.5, and 
202    because of this, the first version number is 0.5. 
203    
204
205 --------------------------
206
207 [1]   see http://www.ocaml-programming.de/packages/netstring-0.9.2.tar.gz
208
209 [2]   see mailto:gerd@gerd-stolpmann.de
210
211
212