Implement form interface

This new interface allows library users to parse
application/x-www-form-urlencoded data conveniently.

2 files changed, 124 insertions, 0 deletions

diff --git a/doc/man7/Makefile b/doc/man7/Makefile
index f9dc22c..bf588e6 100644
--- a/doc/man7/Makefile
+++ b/doc/man7/Makefile
@@ -5,6 +5,7 @@ datarootdir = $(prefix)/share
 mandir = $(datarootdir)/man
 man7dir = $(mandir)/man7
 OBJECTS = \
+	$(DESTDIR)$(man7dir)/libweb_form.7 \
 	$(DESTDIR)$(man7dir)/libweb_handler.7 \
 	$(DESTDIR)$(man7dir)/libweb_html.7 \
 	$(DESTDIR)$(man7dir)/libweb_http.7
diff --git a/doc/man7/libweb_form.7 b/doc/man7/libweb_form.7
new file mode 100644
index 0000000..8b21810
--- /dev/null
+++ b/doc/man7/libweb_form.7
@@ -0,0 +1,123 @@
+.TH LIBWEB_FORM 7 2025-10-02 0.5.0 "libweb Library Reference"
+
+.SH NAME
+libweb_form \- libweb www-form decoding
+
+.SH SYNOPSIS
+.LP
+.nf
+#include <libweb/form.h>
+.fi
+
+.SH DESCRIPTION
+This component allows library users to decode payloads with
+.IR "Content-Type application/x-www-form-urlencoded" .
+Contents are stored into an opaque abstraction, namely
+.IR "struct form" ,
+and can be retrieved with the functions described below.
+
+.IR libweb_form (7)
+provides the following functions:
+
+.IP \(bu 2
+.IR form_alloc (3):
+Parses a human-readable string of
+.IR application/x-www-form-urlencoded -encoded
+data and, if valid, allocates a
+.I struct form
+instance that can be used to interact with other functions from this section.
+
+.IP \(bu 2
+.IR form_value (3):
+Returns a value for a given key from a
+.I struct form
+instance previously allocated by
+.IR form_alloc (3).
+
+.IP \(bu 2
+.IR form_foreach (3):
+Executes a user-defined function for each key inside a
+.I struct form
+instance previously allocated by
+.IR form_alloc (3).
+
+.IP \(bu 2
+.IR form_free (3):
+Deallocates a
+.I struct form
+instance and all the data associated to it.
+
+.SH EXAMPLE
+
+The following source code shows how to parse
+.IR application/x-www-form-urlencoded -encoded
+data using the interface described by this section:
+
+.PP
+.in +4n
+.EX
+#include <libweb/form.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+static int print(const char *const key, const char *const value,
+    void *const user)
+{
+    unsigned *const cnt = user;
+
+    printf("key=%s, value=%s, cnt=%u\en", key, value, ++(*cnt));
+    return 0;
+}
+
+int main(int argc, char *argv[])
+{
+    int ret = EXIT_FAILURE;
+    const char *payload;
+    struct form *f = NULL;
+    unsigned cnt = 0;
+    int n;
+
+    if (argc != 2)
+    {
+        fprintf(stderr, "Usage: %s <payload>\en", *argv);
+        goto end;
+    }
+    else if ((n = form_alloc(payload = argv[1], &f)) < 0)
+    {
+        fprintf(stderr, "%s: form_alloc failed\en", __func__);
+        goto end;
+    }
+    else if (n)
+    {
+        fprintf(stderr, "%s: invalid user input: %s\en", __func__, payload);
+        goto end;
+    }
+    else if (form_foreach(f, print, &cnt))
+    {
+        fprintf(stderr, "%s: form_foreach failed\en", __func__);
+        goto end;
+    }
+
+    ret = EXIT_SUCCESS;
+
+end:
+    form_free(f);
+    return ret;
+}
+.EE
+.in
+.PP
+
+.SH SEE ALSO
+.BR form_alloc (3),
+.BR form_value (3),
+.BR form_foreach (3),
+.BR form_free (3).
+
+.SH COPYRIGHT
+Copyright (C) 2023-2025 libweb contributors
+.P
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.