Convert the documentation to Asciidoc

A few small revisions were made, and Erlang.mk has been updated.

1 files changed, 0 insertions, 715 deletions

diff --git a/doc/src/manual/cowboy_req.ezdoc b/doc/src/manual/cowboy_req.ezdoc
deleted file mode 100644
index 9b73886..0000000
--- a/doc/src/manual/cowboy_req.ezdoc
+++ /dev/null
@@ -1,715 +0,0 @@
-::: cowboy_req
-
-The `cowboy_req` module provides functions to access, manipulate
-and respond to requests.
-
-The functions in this module follow patterns for their return types,
-based on the kind of function.
-
-* access: `Value`
-* action: `ok | {Result, Req} | {Result, Value, Req}`
-* modification: `Req`
-* question: `boolean()`
-
-Whenever `Req` is returned, you must use this returned value and
-ignore any previous you may have had. This value contains various
-values which are necessary for Cowboy to keep track of the request
-and response states.
-
-All functions which perform an action should only be called once.
-This includes reading the request body or replying. Cowboy will
-throw an error on the second call when it detects suspicious behavior.
-
-It is highly discouraged to pass the Req object to another process.
-Doing so and calling `cowboy_req` functions from it leads to
-undefined behavior.
-
-:: Types
-
-: body_opts() = [{continue, boolean()}
-	| {length, non_neg_integer()}
-	| {read_length, non_neg_integer()}
-	| {read_timeout, timeout()}
-	| {transfer_decode, transfer_decode_fun(), any()}
-	| {content_decode, content_decode_fun()}]
-
-Request body reading options.
-
-: cookie_opts() = [{max_age, non_neg_integer()}
-	| {domain, binary()} | {path, binary()}
-	| {secure, boolean()} | {http_only, boolean()}]
-
-Cookie options.
-
-: req() - opaque to the user
-
-The Req object.
-
-All functions in this module receive a `Req` as argument,
-and most of them return a new object labelled `Req2` in
-the function descriptions below.
-
-:: Request related exports
-
-: binding(Name, Req) -> binding(Name, Req, undefined)
-: binding(Name, Req, Default) -> Value
-
-Types:
-
-* Name = atom()
-* Default = any()
-* Value = any() | Default
-
-Return the value for the given binding.
-
-By default the value is a binary, however constraints may change
-the type of this value (for example automatically converting
-numbers to integer).
-
-: bindings(Req) -> [{Name, Value}]
-
-Types:
-
-* Name = atom()
-* Value = any()
-
-Return all bindings.
-
-By default the value is a binary, however constraints may change
-the type of this value (for example automatically converting
-numbers to integer).
-
-: header(Name, Req) -> header(Name, Req, undefined)
-: header(Name, Req, Default) -> Value
-
-Types:
-
-* Name = binary()
-* Default = any()
-* Value = binary() | Default
-
-Return the value for the given header.
-
-While header names are case insensitive, this function expects
-the name to be a lowercase binary.
-
-: headers(Req) -> Headers
-
-Types:
-
-* Headers = cowboy:http_headers()
-
-Return all headers.
-
-: host(Req) -> Host
-
-Types:
-
-* Host = binary()
-
-Return the requested host.
-
-: host_info(Req) -> HostInfo
-
-Types:
-
-* HostInfo = cowboy_router:tokens() | undefined
-
-Return the extra tokens from matching against `...` during routing.
-
-: host_url(Req) -> HostURL
-
-Types:
-
-* HostURL = binary() | undefined
-
-Return the requested URL excluding the path component.
-
-This function will always return `undefined` until the
-`cowboy_router` middleware has been executed.
-
-: match_cookies(Fields, Req) -> Map
-
-Types:
-
-* Fields = cowboy:fields()
-* Map = map()
-
-Match cookies against the given fields.
-
-Cowboy will only return the cookie values specified in the
-fields list, and ignore all others. Fields can be either
-the name of the cookie requested; the name along with a
-list of constraints; or the name, a list of constraints
-and a default value in case the cookie is missing.
-
-This function will crash if the cookie is missing and no
-default value is provided. This function will also crash
-if a constraint fails.
-
-The name of the cookie must be provided as an atom. The
-key of the returned map will be that atom. The value may
-be converted through the use of constraints, making this
-function able to extract, validate and convert values all
-in one step.
-
-: match_qs(Fields, Req) -> Map
-
-Types:
-
-* Fields = cowboy:fields()
-* Map = map()
-
-Match the query string against the given fields.
-
-Cowboy will only return the query string values specified
-in the fields list, and ignore all others. Fields can be
-either the key requested; the key along with a list of
-constraints; or the key, a list of constraints and a
-default value in case the key is missing.
-
-This function will crash if the key is missing and no
-default value is provided. This function will also crash
-if a constraint fails.
-
-The key must be provided as an atom. The key of the
-returned map will be that atom. The value may be converted
-through the use of constraints, making this function able
-to extract, validate and convert values all in one step.
-
-: meta(Name, Req) -> meta(Name, Req, undefined)
-: meta(Name, Req, Default) -> Value
-
-Types:
-
-* Name = atom()
-* Default = any()
-* Value = any()
-
-Return metadata about the request.
-
-: method(Req) -> Method
-
-Types:
-
-* Method = binary()
-
-Return the method.
-
-Methods are case sensitive. Standard methods are always uppercase.
-
-: parse_cookies(Req) -> [{Name, Value}]
-
-Types:
-
-* Name = binary()
-* Value = binary()
-
-Parse and return all cookies.
-
-Cookie names are case sensitive.
-
-: parse_header(Name, Req) -> see below
-: parse_header(Name, Req, Default) -> ParsedValue | Default
-
-Types:
-
-* Name = binary()
-* Default = any()
-* ParsedValue - see below
-
-Parse the given header.
-
-While header names are case insensitive, this function expects
-the name to be a lowercase binary.
-
-The `parse_header/2` function will call `parser_header/3` with a
-different default value depending on the header being parsed. The
-following table summarizes the default values used.
-
-||	Header name			Default value
-|
-|	content-length		`0`
-|	cookie				`[]`
-|	transfer-encoding	`[<<"identity">>]`
-|	Any other header	`undefined`
-
-The parsed value differs depending on the header being parsed. The
-following table summarizes the different types returned.
-
-||	Header name				Type
-|
-|	accept					`[{{Type, SubType, Params}, Quality, AcceptExt}]`
-|	accept-charset			`[{Charset, Quality}]`
-|	accept-encoding			`[{Encoding, Quality}]`
-|	accept-language			`[{LanguageTag, Quality}]`
-|	authorization			`{AuthType, Credentials}`
-|	content-length			`non_neg_integer()`
-|	content-type			`{Type, SubType, ContentTypeParams}`
-|	cookie					`[{binary(), binary()}]`
-|	expect					`[Expect | {Expect, ExpectValue, Params}]`
-|	if-match				`'*' | [{weak | strong, OpaqueTag}]`
-|	if-modified-since		`calendar:datetime()`
-|	if-none-match			`'*' | [{weak | strong, OpaqueTag}]`
-|	if-unmodified-since		`calendar:datetime()`
-|	range					`{Unit, [Range]}`
-|	sec-websocket-protocol	`[binary()]`
-|	transfer-encoding		`[binary()]`
-|	upgrade					`[binary()]`
-|	x-forwarded-for			`[binary()]`
-
-Types for the above table:
-
-* Type = SubType = Charset = Encoding = LanguageTag = binary()
-* AuthType = Expect = OpaqueTag = Unit = binary()
-* Params = ContentTypeParams = [{binary(), binary()}]
-* Quality = 0..1000
-* AcceptExt = [{binary(), binary()} | binary()]
-* Credentials - see below
-* Range = {non_neg_integer(), non_neg_integer() | infinity} | neg_integer()
-
-The cookie names and values, the values of the sec-websocket-protocol
-and x-forwarded-for headers, the values in `AcceptExt` and `Params`,
-the authorization `Credentials`, the `ExpectValue` and `OpaqueTag`
-are case sensitive. All values in `ContentTypeParams` are case sensitive
-except the value of the charset parameter, which is case insensitive.
-All other values are case insensitive and will be returned as lowercase.
-
-The headers accept, accept-encoding and cookie headers can return
-an empty list. Some other headers are expected to have a value if provided
-and may crash if the value is missing.
-
-The authorization header parsing code currently only supports basic
-HTTP authentication. The `Credentials` type is thus `{Username, Password}`
-with `Username` and `Password` being `binary()`.
-
-The range header value `Range` can take three forms:
-
-* `{From, To}`: from `From` to `To` units
-* `{From, infinity}`: everything after `From` units
-* `-Final`: the final `Final` units
-
-An `undefined` tuple will be returned if Cowboy doesn't know how
-to parse the requested header.
-
-: parse_qs(Req) -> [{Name, Value}]
-
-Types:
-
-* Name = binary()
-* Value = binary() | true
-
-Return the request's query string as a list of tuples.
-
-The atom `true` is returned for keys which have no value.
-Keys with no value are different from keys with an empty
-value in that they do not have a `=` indicating the presence
-of a value.
-
-: path(Req) -> Path
-
-Types:
-
-* Path = binary()
-
-Return the requested path.
-
-: path_info(Req) -> PathInfo
-
-Types:
-
-* PathInfo = cowboy_router:tokens() | undefined
-
-Return the extra tokens from matching against `...` during routing.
-
-: peer(Req) -> Peer
-
-Types:
-
-* Peer = {inet:ip_address(), inet:port_number()}
-
-Return the client's IP address and port number.
-
-: port(Req) -> Port
-
-Types:
-
-* Port = inet:port_number()
-
-Return the request's port.
-
-The port returned by this function is obtained by parsing
-the host header. It may be different than the actual port
-the client used to connect to the Cowboy server.
-
-: qs(Req) -> QueryString
-
-Types:
-
-* QueryString = binary()
-
-Return the request's query string.
-
-: set_meta(Name, Value, Req) -> Req2
-
-Types:
-
-* Name = atom()
-* Value = any()
-
-Set metadata about the request.
-
-An existing value will be overwritten.
-
-: url(Req) -> URL
-
-Types:
-
-* URL = binary() | undefined
-
-Return the requested URL.
-
-This function will always return `undefined` until the
-`cowboy_router` middleware has been executed.
-
-: version(Req) -> Version
-
-Types:
-
-* Version = cowboy:http_version()
-
-Return the HTTP version used for this request.
-
-:: Request body related exports
-
-: body(Req) -> body(Req, [])
-: body(Req, Opts) -> {ok, Data, Req2} | {more, Data, Req2}
-
-Types:
-
-* Opts = [body_opt()]
-* Data = binary()
-* Reason = atom()
-
-Read the request body.
-
-This function will read a chunk of the request body. If there is
-more data to be read after this function call, then a `more` tuple
-is returned. Otherwise an `ok` tuple is returned.
-
-Cowboy will automatically send a `100 Continue` reply if
-required. If this behavior is not desirable, it can be disabled
-by setting the `continue` option to `false`.
-
-Cowboy will by default attempt to read up to 8MB of the body,
-but in chunks of 1MB. It will use a timeout of 15s per chunk.
-All these values can be changed using the `length`, `read_length`
-and `read_timeout` options respectively. Note that the size
-of the data may not be the same as requested as the decoding
-functions may grow or shrink it, and Cowboy makes not attempt
-at returning an exact amount.
-
-Cowboy will properly handle chunked transfer-encoding by
-default. If any other transfer-encoding or content-encoding
-has been used for the request, custom decoding functions
-can be used. The `content_decode` and `transfer_decode`
-options allow setting the decode functions manually.
-
-After the body has been streamed fully, Cowboy will remove
-the transfer-encoding header from the Req object, and add
-the content-length header if it wasn't already there.
-
-This function can only be called once. Cowboy will not cache
-the result of this call.
-
-: body_length(Req) -> Length
-
-Types:
-
-* Length = non_neg_integer() | undefined
-
-Return the length of the request body.
-
-The length will only be returned if the request does not
-use any transfer-encoding and if the content-length header
-is present.
-
-: body_qs(Req) -> body_qs(Req,
-	[{length, 64000}, {read_length, 64000}, {read_timeout, 5000}])
-: body_qs(Req, Opts) -> {ok, [{Name, Value}], Req2} | {badlength, Req2}
-
-Types:
-
-* Opts = [body_opt()]
-* Name = binary()
-* Value = binary() | true
-* Reason = chunked | badlength | atom()
-
-Return the request body as a list of tuples.
-
-This function will parse the body assuming the content-type
-application/x-www-form-urlencoded, commonly used for the
-query string.
-
-This function calls `body/2` for reading the body, with the
-same options it received. By default it will attempt to read
-a body of 64KB in one chunk, with a timeout of 5s. If the
-body is larger then a `badlength` tuple is returned.
-
-This function can only be called once. Cowboy will not cache
-the result of this call.
-
-: has_body(Req) -> boolean()
-
-Return whether the request has a body.
-
-: part(Req) -> part(Req,
-	[{length, 64000}, {read_length, 64000}, {read_timeout, 5000}])
-: part(Req, Opts) -> {ok, Headers, Req2} | {done, Req2}
-
-Types:
-
-* Opts = [body_opt()]
-* Headers = cow_multipart:headers()
-
-Read the headers for the next part of the multipart message.
-
-Cowboy will skip any data remaining until the beginning of
-the next part. This includes the preamble to the multipart
-message but also the body of a previous part if it hasn't
-been read. Both are skipped automatically when calling this
-function.
-
-The headers returned are MIME headers, NOT HTTP headers.
-They can be parsed using the functions from the `cow_multipart`
-module. In addition, the `cow_multipart:form_data/1` function
-can be used to quickly figure out `multipart/form-data` messages.
-It takes the list of headers and returns whether this part is
-a simple form field or a file being uploaded.
-
-Note that once a part has been read, or skipped, it cannot
-be read again.
-
-This function calls `body/2` for reading the body, with the
-same options it received. By default it will only read chunks
-of 64KB with a timeout of 5s. This is tailored for reading
-part headers, not for skipping the previous part's body.
-You might want to consider skipping large parts manually.
-
-: part_body(Req) -> part_body(Req, [])
-: part_body(Req, Opts) -> {ok, Data, Req2} | {more, Data, Req2}
-
-Types:
-
-* Opts = [body_opt()]
-* Data = binary()
-
-Read the body of the current part of the multipart message.
-
-This function calls `body/2` for reading the body, with the
-same options it received. It uses the same defaults.
-
-If there are more data to be read from the socket for this
-part, the function will return what it could read inside a
-`more` tuple. Otherwise, it will return an `ok` tuple.
-
-Calling this function again after receiving a `more` tuple
-will return another chunk of body. The last chunk will be
-returned inside an `ok` tuple.
-
-Note that once the body has been read, fully or partially,
-it cannot be read again.
-
-:: Response related exports
-
-: chunk(Data, Req) -> ok
-
-Types:
-
-* Data = iodata()
-* Reason = atom()
-
-Send a chunk of data.
-
-This function should be called as many times as needed
-to send data chunks after calling `chunked_reply/{2,3}`.
-
-When the method is HEAD, no data will actually be sent.
-
-If the request uses HTTP/1.0, the data is sent directly
-without wrapping it in an HTTP/1.1 chunk, providing
-compatibility with older clients.
-
-: chunked_reply(StatusCode, Req) -> chunked_reply(StatusCode, [], Req)
-: chunked_reply(StatusCode, Headers, Req) -> Req2
-
-Types:
-
-* StatusCode = cowboy:http_status()
-* Headers = cowboy:http_headers()
-
-Send a response using chunked transfer-encoding.
-
-This function effectively sends the response status line
-and headers to the client.
-
-This function will not send any body set previously. After
-this call the handler must use the `chunk/2` function
-repeatedly to send the body in as many chunks as needed.
-
-If the request uses HTTP/1.0, the data is sent directly
-without wrapping it in an HTTP/1.1 chunk, providing
-compatibility with older clients.
-
-This function can only be called once, with the exception
-of overriding the response in the `onresponse` hook.
-
-: continue(Req) -> ok
-
-Types:
-
-* Reason = atom()
-
-Send a 100 Continue intermediate reply.
-
-This reply is required before the client starts sending the
-body when the request contains the `expect` header with the
-`100-continue` value.
-
-Cowboy will send this automatically when required. However
-you may want to do it manually by disabling this behavior
-with the `continue` body option and then calling this
-function.
-
-: delete_resp_header(Name, Req) -> Req2
-
-Types:
-
-* Name = binary()
-
-Delete the given response header.
-
-While header names are case insensitive, this function expects
-the name to be a lowercase binary.
-
-: has_resp_body(Req) -> boolean()
-
-Return whether a response body has been set.
-
-This function will return false if a response body has
-been set with a length of 0.
-
-: has_resp_header(Name, Req) -> boolean()
-
-Types:
-
-* Name = binary()
-
-Return whether the given response header has been set.
-
-While header names are case insensitive, this function expects
-the name to be a lowercase binary.
-
-: reply(StatusCode, Req) -> reply(StatusCode, [], Req)
-: reply(StatusCode, Headers, Req) - see below
-: reply(StatusCode, Headers, Body, Req) -> Req2
-
-Types:
-
-* StatusCode = cowboy:http_status()
-* Headers = cowboy:http_headers()
-* Body = iodata()
-
-Send a response.
-
-This function effectively sends the response status line,
-headers and body to the client, in a single send function
-call.
-
-The `reply/2` and `reply/3` functions will send the body
-set previously, if any. The `reply/4` function overrides
-any body set previously and sends `Body` instead.
-
-If a body function was set, and `reply/2` or `reply/3` was
-used, it will be called before returning.
-
-No more data can be sent to the client after this function
-returns.
-
-This function can only be called once, with the exception
-of overriding the response in the `onresponse` hook.
-
-: set_resp_body(Body, Req) -> Req2
-
-Types:
-
-* Body = iodata()
-
-Set a response body.
-
-This body will not be sent if `chunked_reply/{2,3}` or
-`reply/4` is used, as they override it.
-
-: set_resp_body_fun(Fun, Req) -> Req2
-: set_resp_body_fun(Length, Fun, Req) -> Req2
-
-Types:
-
-* Fun = fun((Socket, Transport) -> ok)
-* Socket = inet:socket()
-* Transport = module()
-* Length = non_neg_integer()
-
-Set a fun for sending the response body.
-
-If a `Length` is provided, it will be sent in the
-content-length header in the response. It is recommended
-to set the length if it can be known in advance. Otherwise,
-the transfer-encoding header will be set to identity.
-
-This function will only be called if the response is sent
-using the `reply/2` or `reply/3` function.
-
-The fun will receive the Ranch `Socket` and `Transport` as
-arguments. Only send and sendfile operations are supported.
-
-: set_resp_body_fun(chunked, Fun, Req) -> Req2
-
-Types:
-
-* Fun = fun((ChunkFun) -> ok)
-* ChunkFun = fun((iodata()) -> ok)
-
-Set a fun for sending the response body using chunked transfer-encoding.
-
-This function will only be called if the response is sent
-using the `reply/2` or `reply/3` function.
-
-The fun will receive another fun as argument. This fun is to
-be used to send chunks in a similar way to the `chunk/2` function,
-except the fun only takes one argument, the data to be sent in
-the chunk.
-
-: set_resp_cookie(Name, Value, Opts, Req) -> Req2
-
-Types:
-
-* Name = iodata()
-* Value = iodata()
-* Opts = cookie_opts()
-
-Set a cookie in the response.
-
-Cookie names are case sensitive.
-
-: set_resp_header(Name, Value, Req) -> Req2
-
-Types:
-
-* Name = binary()
-* Value = iodata()
-
-Set a response header.
-
-You should use `set_resp_cookie/4` instead of this function
-to set cookies.