http_parameters.pl -- Extract parameters (GET and POST) from HTTP requests

Most code doesn't need to use this directly; instead use library(http/http_server), which combines this library with the typical HTTP libraries that most servers need.

This module is used to extract the value of GET or POST parameters from an HTTP request. The typical usage is e.g.,

:- http_handler('/register_user', register_user, []).

register_user(Request) :-
    http_parameters(Request,
                    [ name(Name, []),
                      sex(Sex, [oneof([male,female])]),
                      birth_year(BY, [between(1850,10000)])
                    ]),
    register_user(Name, Sex, BY),
    html_reply_page(title('New user added'),
                    ...).

See also

- http_dispatch.pl dispatches requests to predicates.

 http_parameters(+Request, ?Parms) is det

 http_parameters(+Request, ?Parms, :Options) is det

Get HTTP GET or POST form-data, applying type validation, default values, etc. Provided options are:

attribute_declarations(:Goal)

Causes the declarations for an attributed named A to be fetched using call(Goal, A, Declarations).

form_data(-Data)

Return the data read from the GET por POST request as a list Name = Value. All data, including name/value pairs used for Parms, is unified with Data.

The attribute_declarations hook allows sharing the declaration of attribute-properties between many http_parameters/3 calls. In this form, the requested attribute takes only one argument and the options are acquired by calling the hook. For example:

    ...,
    http_parameters(Request,
                    [ sex(Sex)
                    ],
                    [ attribute_declarations(http_param)
                    ]),
    ...

http_param(sex, [ oneof(male, female),
                  description('Sex of the person')
                ]).

bug

- If both request parameters (?name=value&...) and a POST are present the parameters are extracted from the request parameters. Still, as it is valid to have request parameters in a POST request this predicate should not process POST requests. We will keep the current behaviour as the it is not common for a request to have both request parameters and a POST data of the type application/x-www-form-urlencoded.

In the unlikely event this poses a problem the request may be specified as [method(get)|Request].

 http_convert_parameters(+Data, ?Params) is det

 http_convert_parameters(+Data, ?Params, :AttrDecl) is det

Implements the parameter translation of http_parameters/2 or http_parameters/3. I.e., http_parameters/2 for a POST request can be implemented as:

http_parameters(Request, Params) :-
    http_read_data(Request, Data, []),
    http_convert_parameters(Data, Params).

 http_convert_parameter(+Options, +FieldName, +ValueIn, -ValueOut) is det

Conversion of an HTTP form value. First tries the multifile hook http:convert_parameter/3 and next the built-in checks.

Arguments:

Option	- List as provided with the parameter
FieldName	- Name of the HTTP field (for better message)
ValueIn	- Atom value as received from HTTP layer
ValueOut	- Possibly converted final value

Errors

- type_error(Type, Value)

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 http_parameters(Arg1, Arg2, Arg3)

 http_convert_parameters(Arg1, Arg2, Arg3)