3.12 Get parameters from HTML forms

The library library(http/http_parameters) provides two predicates to fetch HTTP request parameters as a type-checked list easily. The library transparently handles both GET and POST requests. It builds on top of the low-level request representation described in section 3.13.

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,[])

http_parameters(+Request, ?Parameters, +Options)

In addition to http_parameters/2, the following options are defined.

form_data(-Data)

Return the entire set of provided Name=Value pairs from the GET or POST request. All values are returned as atoms.

attribute_declarations(:Goal)

If a parameter specification lacks the parameter options, call call(Goal, +ParamName, -Options) to find the options. Intended to share declarations over many calls to http_parameters/3. Using this construct the above can be written as below.

reply(Request) :-
        http_parameters(Request,
                        [ title(Title),
                          name(Name),
                          age(Age)
                        ],
                        [ attribute_declarations(param)
                        ]),
        ...

param(title, [optional(true)]).
param(name,  [length >= 2 ]).
param(age,   [integer]).