@@@ much mess, mostly manpages

[mLib] / codec / url.3.in

.\" -*-nroff-*-
.\"
.\" Manual for form-urlencoding
.\"
.\" (c) 1999, 2001, 2005--2007, 2009, 2023, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH url 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @url_initenc
.\" @url_enc
.\" @url_initdec
.\" @url_dec
.
.\"--------------------------------------------------------------------------
.SH NAME
url \- manipulation of form-urlencoded strings
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/url.h>"
.PP
.ta 2n
.B "typedef struct {"
.B "	unsigned f;"
.B "	..."
.B "} url_ectx;"
.PP
.B "typedef struct {"
.B "	unsigned f;"
.B "	..."
.B "} url_dctx;"
.PP
.B "#define URLF_STRICT ..."
.B "#define URLF_LAX ..."
.B "#define URLF_SEMI ..."
.PP
.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 );
.PP
.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
.ta 2n +2n
#include <stdlib.h>
#include <mLib/alloc.h>
#include <mLib/dstr.h>
#include <mLib/sym.h>
#include <mLib/url.h>
.VP
typedef struct {
	sym_base _b;
	char *v;
} val;
.VP
void decode(sym_table *t, const char *p)
{
	url_dctx c;
	dstr n = DSTR_INIT, v = DSTR_INIT;
	val *vv;
	unsigned f;
.VP
	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);
}
.VP
void encode(sym_table *t, dstr *d)
{
	sym_iter i;
	url_ectx c;
	val *v;
.VP
	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>.
.
.\"----- That's all, folks --------------------------------------------------