3.12 Get parameters from HTML forms
All Application Manual Name SummaryHelp

  • Documentation
    • Reference manual
    • Packages
      • SWI-Prolog HTTP support
        • The HTTP server libraries
          • Get parameters from HTML forms
            • http_parameters/2
            • http_parameters/3
Availability::- use_module(library(http/http_parameters)).
Sourcehttp_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,[])