codec/url.3: Add missing documentation for the `URLF_SEMI' flag.

[mLib] / codec / url.3

.\" -*-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.
.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
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.
.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
#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>.