From c528d9b0f7698b5b901cbc8841a96fb4bd38aba9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Fri, 2 Dec 2016 16:50:31 +0100
Subject: Add the man pages for body reading functions

[ci skip]
---
 .../cowboy_req.read_urlencoded_body.asciidoc       | 94 ++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc

(limited to 'doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc')

diff --git a/doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc b/doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc
new file mode 100644
index 0000000..f8a72ab
--- /dev/null
+++ b/doc/src/manual/cowboy_req.read_urlencoded_body.asciidoc
@@ -0,0 +1,94 @@
+= cowboy_req:read_urlencoded_body(3)
+
+== Name
+
+cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body
+
+== Description
+
+[source,erlang]
+----
+read_urlencoded_body(Req :: cowboy_req:req())
+    -> read_urlencoded_body(Req, #{})
+
+read_urlencoded_body(Req :: cowboy_req:req(), Opts)
+    -> {ok, Body, Req}
+
+Opts :: cowboy_req:read_body_opts()
+Body :: [{Key :: binary(), Value :: binary() | true}]
+----
+
+Read and parse a urlencoded request body.
+
+This function reads the request body and parses it as
+`application/x-www-form-urlencoded`. It returns a list
+of key/values.
+
+The urlencoded media type is used by Web browsers when
+submitting HTML forms using the POST method.
+
+Cowboy needs to read the full body before parsing. By default
+it will read bodies of size up to 64KB. It is possible to
+provide options to read larger bodies if required.
+
+Cowboy will automatically handle protocol details including
+the expect header, chunked transfer-encoding and others.
+
+Once the body has been read, Cowboy sets the content-length
+header if it was not previously provided.
+
+This function can only be called once. Calling it again will
+result in undefined behavior.
+
+== Arguments
+
+Req::
+
+The Req object.
+
+Opts::
+
+A map of body reading options. Please refer to
+link:man:cowboy_req:read_body(3)[cowboy_req:read_body(3)]
+for details about each option.
++
+This function defaults the `length` to 64KB and the `period`
+to 5 seconds.
+
+== Return value
+
+An `ok` tuple is returned containing a list of key/values found
+in the body.
+
+The Req object returned in the tuple must be used for that point
+onward. It contains a more up to date representation of the request.
+For example it may have an added content-length header once the
+body has been read.
+
+== Changelog
+
+* *2.0*: Function introduced. Replaces `body_qs/1,2`.
+
+== Examples
+
+.Read a urlencoded body
+[source,erlang]
+----
+{ok, Body, Req} = cowboy_req:read_urlencoded_body(Req0),
+{_, Lang} = lists:keyfind(<<"lang">>, 1, Body).
+----
+
+.Allow large urlencoded bodies
+[source,erlang]
+----
+{ok, Body, Req} = cowboy_req:read_urlencoded_body(Req0, #{length => 1000000}).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:has_body(3)[cowboy_req:has_body(3)],
+link:man:cowboy_req:body_length(3)[cowboy_req:body_length(3)],
+link:man:cowboy_req:read_body(3)[cowboy_req:read_body(3)],
+link:man:cowboy_req:read_part(3)[cowboy_req:read_part(3)],
+link:man:cowboy_req:read_part_body(3)[cowboy_req:read_part_body(3)]
-- 
cgit v1.2.3