Implement form interface

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

1 files changed, 39 insertions, 0 deletions

diff --git a/examples/form/README.md b/examples/form/README.md
new file mode 100644
index 0000000..6be1969
--- /dev/null
+++ b/examples/form/README.md
@@ -0,0 +1,39 @@
+# HTML forms example
+
+This example shows how to parse `application/x-www-form-urlencoded`-encoded
+data using `libweb`s `form` API, using untrusted user input.
+
+## How to build
+
+If using `make(1)`, just run `make` from this directory.
+
+If using CMake, examples are built by default when configuring the project
+from [the top-level `CMakeLists.txt`](../../CMakeLists.txt).
+
+## How to run
+
+Run the executable with a `application/x-www-form-urlencoded`-encoded given
+as its only argument.
+
+For example:
+
+```sh
+$ ./form 'username=admin&password=mypassword'
+```
+
+Shall return:
+
+```
+key=username, value=admin, cnt=1
+key=password, value=mypassword, cnt=2
+```
+
+An invalid string shall be reported to `stderr`:
+
+```sh
+$ ./form 'username=admin&thisisawrongvalue'
+```
+
+```
+main: invalid user input: username=admin&thisisawrongvalue
+```