X-Git-Url: https://git.distorted.org.uk/~mdw/mLib/blobdiff_plain/18c831dcd0ae4d660c70ccac69d27ed2a97851be..adec5584e13c63662fda18915280ec026063b29d:/codec/url.3

diff --git a/codec/url.3 b/codec/url.3
index 4e8aa71..9e8e880 100644
--- a/codec/url.3
+++ b/codec/url.3
@@ -22,9 +22,25 @@ url \- manipulation of form-urlencoded strings
 .nf
 .B "#include <mLib/url.h>"
 
+.ta 2n
+.B "typedef struct {"
+.B "	unsigned f;"
+.B "	..."
+.B "} url_ectx;"
+
+.B "typedef struct {"
+.B "	unsigned f;"
+.B "	..."
+.B "} url_dctx;"
+
+.B "#define URLF_STRICT ..."
+.B "#define URLF_LAX ..."
+.B "#define URLF_SEMI ..."
+
 .BI "void url_initenc(url_ectx *" ctx );
+.ta \w'\fBvoid url_enc('u
 .BI "void url_enc(url_ectx *" ctx ", dstr *" d ,
-.BI "             const char *" name ", const char *" value );
+.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 );
@@ -77,6 +93,12 @@ obviously-unsafe characters like
 and
 .RB ` = '
 are left unescaped.
+.TP
+.B URLF_SEMI
+Use a semicolon
+.RB ` ; '
+to separate name/value pairs, rather than the ampersand
+.RB ` & '.
 .PP
 Decoding a sequence of name/value pairs is performed using the
 .B url_dec
@@ -98,10 +120,31 @@ 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.
+.PP
+You can set flags in the encoding context's
+.B f
+member:
+.TP
+.B URLF_SEMI
+Allow a semicolon
+.RB ` ; '
+to separate name/value pairs,
+.I in addition to
+the ampersand
+.RB ` & '.
+Without this flag, the semicolon is considered an `ordinary' character
+which can appear unescaped as part of names and values.  (Note the
+difference from the same flag's meaning when encoding.  When encoding,
+it
+.I forces
+the use of the semicolon, and when decoding, it
+.I permits
+its use.)
 .SH EXAMPLE
 The example code below demonstrates converting between a symbol table
 and a urlencoded representation.  The code is untested.
 .VS
+.ta 2n +2n
 #include <stdlib.h>
 #include <mLib/alloc.h>
 #include <mLib/dstr.h>
@@ -109,37 +152,36 @@ and a urlencoded representation.  The code is untested.
 #include <mLib/url.h>
 
 typedef struct {
-  sym_base _b;
-  char *v;
+	sym_base _b;
+	char *v;
 } val;
 
 void decode(sym_table *t, const char *p)
 {
-  url_dctx c;
-  dstr n = DSTR_INIT, v = DSTR_INIT;
+	url_dctx c;
+	dstr n = DSTR_INIT, v = DSTR_INIT;
+	val *vv;
+	unsigned f;
 
-  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);
+	for (url_initdec(&c, p); url_dec(&c, &n, &v); ) {
+		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;
+	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);
+	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"