X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/8f45ff6cb9a269fc6f8f631908f93b4c8123419c..4aee39a18184ae8595936a03ad254c27d149a0eb:/man/url.3

diff --git a/man/url.3 b/man/url.3
deleted file mode 100644
index 4e8aa71..0000000
--- a/man/url.3
+++ /dev/null
@@ -1,148 +0,0 @@
-.\" -*-nroff-*-
-.de VS
-.sp 1
-.in +5n
-.ft B
-.nf
-..
-.de VE
-.ft R
-.in -5n
-.sp 1
-.fi
-..
-.TH url 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-url \- manipulation of form-urlencoded strings
-.\" @url_initenc
-.\" @url_enc
-.\" @url_initdec
-.\" @url_dec
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/url.h>"
-
-.BI "void url_initenc(url_ectx *" ctx );
-.BI "void url_enc(url_ectx *" ctx ", dstr *" d ,
-.BI "             const char *" name ", const char *" value );
-
-.BI "void url_initdec(url_dctx *" ctx ", const char *" p );
-.BI "int url_dec(url_dctx *" ctx ", dstr *" n ", dstr *" v );
-.fi
-.SH DESCRIPTION
-The functions in
-.B <mLib/url.h>
-read and write `form-urlencoded' data, as specified in RFC1866.  The
-encoding represents a sequence of name/value pairs where both the name
-and value are arbitrary binary strings (although the format is optimized
-for textual data).  An encoded string contains no nonprintable
-characters or whitespace.  This interface is capable of decoding any
-urlencoded string; however, it can currently only
-.I encode
-names and values which do not contain null bytes, because the encoding
-interface uses standard C strings.
-.PP
-Encoding a sequence of name/value pairs is achieved using the
-.B url_enc
-function.  It requires as input an
-.IR "encoding context" ,
-represented as an object of type
-.BR url_ectx .
-This must be initialized before use by passing it to the function
-.BR url_initenc .
-Each call to
-.B url_enc
-encodes one name/value pair, appending the encoded output to a dynamic
-string (see
-.BR dstr (3)
-for details).
-.PP
-You can set flags in the encoding context's
-.B f
-member:
-.TP
-.B URLF_STRICT
-Be strict about escaping non-alphanumeric characters.  Without this,
-potentially unsafe characters such as
-.RB ` / '
-and
-.RB ` ~ '
-will be left unescaped, which makes encoded filenames (for example) more
-readable.
-.TP
-.B URLF_LAX
-Be very lax about non-alphanumeric characters.  Everything except
-obviously-unsafe characters like
-.RB ` & '
-and
-.RB ` = '
-are left unescaped.
-.PP
-Decoding a sequence of name/value pairs is performed using the
-.B url_dec
-function.  It requires as input a
-.IR "decoding context" ,
-represented as an object of type
-.BR url_dctx .
-This must be initialized before use by passing it to the function
-.BR url_initdec ,
-along with the address of the urlencoded string to decode.  The string
-is not modified during decoding.  Each call to
-.B url_dec
-extracts a name/value pair.  The name and value are written to the
-dynamic strings
-.I n
-and
-.IR v ,
-so you probably want to reset them before each call.  If there are no
-more name/value pairs to read,
-.B url_dec
-returns zero; otherwise it returns a nonzero value.
-.SH EXAMPLE
-The example code below demonstrates converting between a symbol table
-and a urlencoded representation.  The code is untested.
-.VS
-#include <stdlib.h>
-#include <mLib/alloc.h>
-#include <mLib/dstr.h>
-#include <mLib/sym.h>
-#include <mLib/url.h>
-
-typedef struct {
-  sym_base _b;
-  char *v;
-} val;
-
-void decode(sym_table *t, const char *p)
-{
-  url_dctx c;
-  dstr n = DSTR_INIT, v = DSTR_INIT;
-
-  for (url_initdec(&c, p); url_dec(&c, &n, &v); ) {
-    unsigned f;
-    val *vv = sym_find(t, n.buf, -1, sizeof(*vv), &f);
-    if (f)
-      free(vv->v);
-    vv->v = xstrdup(v.buf);
-    DRESET(&n);
-    DRESET(&v);
-  }
-  dstr_destroy(&n);
-  dstr_destroy(&v);
-}
-
-void encode(sym_table *t, dstr *d)
-{
-  sym_iter i;
-  url_ectx c;
-  val *v;
-
-  url_initenc(&c);
-  for (sym_mkiter(&i, t); (v = sym_next(&i)) != 0; )
-    url_enc(&c, d, SYM_NAME(v), v->v);
-}
-.VE
-.SH "SEE ALSO"
-.BR mLib (3).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>.