Add a slew of manual pages.

[mLib] / man / url.3

diff --git a/man/url.3 b/man/url.3
new file mode 100644 (file)
index 0000000..f343962
--- /dev/null
+++ b/man/url.3
@@ -0,0 +1,121 @@
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.in +5n
+.ft B
+.nf
+..
+.de VE
+.ft R
+.in -5n
+.sp 1
+.fi
+..
+.TH url 3mLib "20 June 1999" mLib
+.SH NAME
+url \- manipulation of form-urlencoded strings
+.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 (3mLib)
+for details).
+.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 AUTHOR
+Mark Wooding, <mdw@nsict.org>.