http_parameters/2

Availability::- use_module(library(http/http_parameters)).

http_parameters(+Request, ?Parameters)

The predicate is passes the Request as provided to the handler goal by http_wrapper/5 as well as a partially instantiated lists describing the requested parameters and their types. Each parameter specification in Parameters is a term of the format Name(-Value, +Options) . Options is a list of option terms describing the type, default, etc. If no options are specified the parameter must be present and its value is returned in Value as an atom.

If a parameter is missing the exception error(existence_error(http_parameter, Name), _) is thrown which. If the argument cannot be converted to the requested type, a error(existence_error(Type, Value), _) is raised, where the error context indicates the HTTP parameter. If not caught, the server translates both errors into a 400 Bad request HTTP message.

Options fall into three categories: those that handle presence of the parameter, those that guide conversion and restrict types and those that support automatic generation of documentation. First, the presence-options:

default(Default): If the named parameter is missing, Value is unified to Default.
optional(true): If the named parameter is missing, Value is left unbound and no error is generated.
list(Type): The same parameter may not appear or appear multiple times. If this option is present, default and optional are ignored and the value is returned as a list. Type checking options are processed on each value.
zero_or_more: Deprecated. Use list(Type).

The type and conversion options are given below. The type-language can be extended by providing clauses for the multifile hook http:convert_parameter/3.

;(Type1, Type2): Succeed if either Type1 or Type2 applies. It allows for checks such as (nonneg;oneof([infinite])) to specify an integer or a symbolic value.
oneof(List): Succeeds if the value is member of the given list.
length > N: Succeeds if value is an atom of more than N characters.
length >= N: Succeeds if value is an atom of more than or equal to N characters.
length < N: Succeeds if value is an atom of less than N characters.
length =< N: Succeeds if value is an atom of length less than or equal to N characters.
atom: No-op. Allowed for consistency.
string: Convert value to a string.
between(+Low, +High): Convert value to a number and if either Low or High is a float, force value to be a float. Then check that the value is in the given range, which includes the boundaries.
boolean: Translate =true=, =yes=, =on= and’1’into =true=; =false=, =no=, =off= and’0’into =false= and raises an error otherwise.
float: Convert value to a float. Integers are transformed into float. Throws a type-error otherwise.
integer: Convert value to an integer. Throws a type-error otherwise.
nonneg: Convert value to a non-negative integer. Throws a type-error of the value cannot be converted to an integer and a domain-error otherwise.
number: Convert value to a number. Throws a type-error otherwise.

The last set of options is to support automatic generation of HTTP API documentation from the sources.^{4This
facility is under development in ClioPatria; see http_help.pl}.

description(+Atom): Description of the parameter in plain text.
group(+Parameters, +Options): Define a logical group of parameters. Parameters are processed as normal. Options may include a description of the group. Groups can be nested.

Below is an example

reply(Request) :-
        http_parameters(Request,
                        [ title(Title, [ optional(true) ]),
                          name(Name,   [ length >= 2 ]),
                          age(Age,     [ between(0, 150) ])
                        ]),
        ...

Same as http_parameters(Request, Parameters,[])