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

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].

 posted_form(+Request, -Data) is det[private]

True when Data is list of Name=Value pairs representing the posted data.

 fill_parameters(+ParamDecls, +FormData, +DeclGoal)[private]

Fill values from the parameter list

 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)

 check_type3(+Type, +ValueIn, -ValueOut) is semidet[private]

HTTP parameter type-check for types that need converting.

 check_type2(+Type, +ValueIn) is semidet[private]

HTTP parameter type-check for types that need no conversion.

 truth(+In, -Boolean) is semidet[private]

Translate some commonly used textual representations for true and false into their canonical representation.

 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).