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)
Re-exported predicates
The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.
- 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).