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