module Eliom_parameters: sig
.. end
This module defines the values used to declare the type of service
parameters.
Here are some examples of how to specify the types and names of
service parameters:
unit
for a service without parameter.
(int "myvalue")
for a service that takes one parameter,
of type int
, called "myvalue"
.
(The service handler function takes a parameter of type int
).
(int "myvalue" ** string "mystring")
for a service that takes
two parameters, one of type int
called "myvalue"
,
and one of type string
called "mystring"
.
(The service handler function takes a parameter of type (int * string)
).
(opt (int "myvalue"))
for a service that takes an optional parameter
of type int
called "myvalue"
.
(The handler function takes a parameter of type int option
).
(set int "myvalue")
for a service that takes any number of integer
parameters, all called "myvalue"
.
(The handler function takes a parameter of type int list
).
list "l" (int "myvalue" ** string "mystring")
for a service
taking a list of pairs.
(The handler takes a parameter of type (int * string) list
).
Note: We could make even more static checking in parameter's types (for example
to forbid any
in suffixes), but it would make the types of parameters and
services more complicated. We believe that these errors should be easy
to find during implementation.
Types used by the module
type ('a, +'b, +'c)
params_type
Type for parameters of a web page.
'typ
is the type of the parameter (taken by the service handler)
'suff
is a polymorphic variant type telling the type of parameter
(suffix or not ...)
'name
is the type of the parameter name (usually using Eliom_parameters.param_name
)
type 'a
param_name
Type for names of page parameters (given to the functions
to construct forms, for example in
Eliom_predefmod.XHTMLFORMSSIG.get_form
).
The names of parameters are not just strings to enforce using
forms widgets with the right parameter type.
The parameter of that type is often a subtype of the polymorphic variant
type
[ `Set of 'a | `One of 'a | `Opt of 'a ]
, where
`Set of 'a
means: any number of 'a
`One of 'a
means: exactly one 'a
`Opt of 'a
means: zero or one 'a
type 'a
setoneradio = [ `One of 'a | `Radio of 'a | `Set of 'a ]
This type is used by some form widgets like
Eliom_predefmod.XHTMLFORMSSIG.int_input
that may be used against services
expecting one parameter of that name,
or services expecting an optional parameter of that name,
or services expecting any number of parameters of that name.
type 'a
oneradio = [ `One of 'a | `Radio of 'a ]
type 'a
setone = [ `One of 'a | `Set of 'a ]
This type is used by some form widgets like
Eliom_predefmod.XHTMLFORMSSIG.int_button
that may be used against services
expecting one parameter of that name,
or services expecting any number of parameters of that name.
type ('a, 'b)
binsum =
| |
Inj1 of 'a |
| |
Inj2 of 'b |
type 'a
listnames = {
|
it : 'b 'c. ('a -> 'b -> 'c list) -> 'b list -> 'c list -> 'c list ; |
}
Type of the iterator used to construct forms from lists
Basic types of pages parameters
val int : string ->
(int, [ `WithoutSuffix ], [ `One of int ] param_name)
params_type
int s
tells that the service takes an integer as parameter, labeled s
.
val int32 : string ->
(int32, [ `WithoutSuffix ], [ `One of int32 ] param_name)
params_type
int32 s
tells that the service takes a 32 bits integer as parameter, labeled s
.
val int64 : string ->
(int64, [ `WithoutSuffix ], [ `One of int64 ] param_name)
params_type
int64 s
tells that the service takes a 64 bits integer as parameter, labeled s
.
val float : string ->
(float, [ `WithoutSuffix ], [ `One of float ] param_name)
params_type
float s
tells that the service takes a floating point number as parameter, labeled s
.
val string : string ->
(string, [ `WithoutSuffix ], [ `One of string ] param_name)
params_type
string s
tells that the service takes a string as parameter, labeled s
.
val bool : string ->
(bool, [ `WithoutSuffix ], [ `One of bool ] param_name)
params_type
bool s
tells that the service takes a boolean as parameter, labeled s
.
(to use for example with boolean checkboxes)
val file : string ->
(Ocsigen_extensions.file_info, [ `WithoutSuffix ],
[ `One of Ocsigen_extensions.file_info ] param_name)
params_type
file s
tells that the service takes a file as parameter, labeled s
.
val unit : (unit, [ `WithoutSuffix ], unit) params_type
used for services that don't have any parameters
val user_type : (string -> 'a) ->
('a -> string) ->
string ->
('a, [ `WithoutSuffix ], [ `One of 'a ] param_name)
params_type
Allows to use whatever type you want for a parameter of the service.
user_type t_of_string string_of_t s
tells that the service take a parameter, labeled s
, and that the server will have to use t_of_string
and string_of_t
to make the conversion from and to string.
type
coordinates = {
|
abscissa : int ; |
|
ordinate : int ; |
}
coordinates
is for the data sent by an <input type="image" ...>
.
val coordinates : string ->
(coordinates, [ `WithoutSuffix ],
[ `One of coordinates ] param_name)
params_type
string s
tells that the service takes as parameters the coordinates
of the point where the user were clicked on an image.
val string_coordinates : string ->
(string * coordinates, [ `WithoutSuffix ],
[ `One of string * coordinates ]
param_name)
params_type
It is possible to send a value together with the coordinates
(<input type="image" value="..." ...>
) (Here a string)
val int_coordinates : string ->
(int * coordinates, [ `WithoutSuffix ],
[ `One of int * coordinates ] param_name)
params_type
Same for an integer value
val int32_coordinates : string ->
(int32 * coordinates, [ `WithoutSuffix ],
[ `One of int32 * coordinates ] param_name)
params_type
Same for a 32 bits integer value
val int64_coordinates : string ->
(int64 * coordinates, [ `WithoutSuffix ],
[ `One of int64 * coordinates ] param_name)
params_type
Same for a 64 integer value
val float_coordinates : string ->
(float * coordinates, [ `WithoutSuffix ],
[ `One of float * coordinates ] param_name)
params_type
Same for a float value
val user_type_coordinates : (string -> 'a) ->
('a -> string) ->
string ->
('a * coordinates, [ `WithoutSuffix ],
[ `One of 'a * coordinates ] param_name)
params_type
Same for a value of your own type
Composing types of pages parameters
val (**) : ('a, [ `WithoutSuffix ], 'b) params_type ->
('c, [< `Endsuffix | `WithoutSuffix ] as 'd, 'e) params_type ->
('a * 'c, 'd, 'b * 'e) params_type
This is a combinator to allow the service to take several parameters
(see examples above)
Warning: it is a binary operator.
Pages cannot take tuples but only pairs.
val prod : ('a, [ `WithoutSuffix ], 'b) params_type ->
('c, [< `Endsuffix | `WithoutSuffix ] as 'd, 'e) params_type ->
('a * 'c, 'd, 'b * 'e) params_type
Same as **
above
val sum : ('a, [ `WithoutSuffix ], 'b) params_type ->
('a, [ `WithoutSuffix ], 'b) params_type ->
(('a, 'a) binsum, [ `WithoutSuffix ], 'b * 'b)
params_type
This is a combinator to allow the service to take either a parameter
or another one
Warning: it is a binary operator.
val opt : ('a, [ `WithoutSuffix ], 'b) params_type ->
('a option, [ `WithoutSuffix ], 'b) params_type
Use this if you want one or some parameters to be optional
val radio : (string ->
('a, [ `WithoutSuffix ], [ `One of 'b ] param_name)
params_type) ->
string ->
('a option, [ `WithoutSuffix ], [ `Radio of 'b ] param_name)
params_type
Use this if you want to use this parameter with a radio button.
It is equivalent to opt
but works only for one single parameter.
val any : ((string * string) list, [ `WithoutSuffix ], unit)
params_type
Use this if you want to take any parameters.
The service will answer to all the request,
and get all parameters as an association list of strings.
val set : (string ->
('a, [ `WithoutSuffix ], [ `One of 'b ] param_name)
params_type) ->
string ->
('a list, [ `WithoutSuffix ], [ `Set of 'b ] param_name)
params_type
Use this if you want your service to take several parameters
with the same name. The service handler will receive a list of values.
To create the form, just use the same name several times.
For example set int "i"
will match the parameter string
i=4&i=22&i=111
and send to the service handler a list containing
the three integers 4, 22 and 111. The order is unspecified.
val list : string ->
('a, [ `WithoutSuffix ], 'b) params_type ->
('a list, [ `WithoutSuffix ], 'b listnames)
params_type
The service takes a list of parameters.
The first parameter of this function is the name of the list.
The service handler will receive a list of values.
To create the form, an iterator of type
Eliom_parameters.listnames
is given to
generate the name for each value.
val regexp : Netstring_pcre.regexp ->
string ->
string ->
(string, [ `WithoutSuffix ], [ `One of string ] param_name)
params_type
regexp r d s
tells that the service takes a string
that matches the regular expression r
as parameter,
labeled s
, and that will be rewritten in d.
The syntax of regexp is PCRE's one (uses Netstring_pcre
, from OCamlnet).
For example: regexp (Netstring_pcre.regexp "\[(.* )\]") "($1)" "myparam"
will match the parameter myparam=[hello]
and send the string "(hello)"
to
the service handler.
val suffix : ('a, [< `Endsuffix | `WithoutSuffix ], 'b) params_type ->
('a, [ `WithSuffix ], 'b) params_type
Tells that the parameter of the service handler is
the suffix of the URL of the current service.
e.g. suffix (int "i" ** string "s")
will match an URL ending by 380/yo
.
and send (380, "yo")
to the service handler.
val all_suffix : string ->
(string list, [ `Endsuffix ],
[ `One of string list ] param_name)
params_type
Takes all the suffix, as long as possible, as a (slash separated)
string list
val all_suffix_string : string ->
(string, [ `Endsuffix ], [ `One of string ] param_name)
params_type
Takes all the suffix, as long as possible, as a string
val all_suffix_user : (string -> 'a) ->
('a -> string) ->
string ->
('a, [ `Endsuffix ], [ `One of 'a ] param_name)
params_type
Takes all the suffix, as long as possible,
with a type specified by the user.
val all_suffix_regexp : Netstring_pcre.regexp ->
string ->
string ->
(string, [ `Endsuffix ], [ `One of string ] param_name)
params_type
all_suffix_regexp r d s
takes all the suffix, as long as possible,
matching the regular expression r
, name s
, and rewrite it in d
.
val suffix_prod : ('a, [< `Endsuffix | `WithoutSuffix ], 'b) params_type ->
('c, [ `WithoutSuffix ], 'd) params_type ->
('a * 'c, [ `WithSuffix ], 'b * 'd) params_type
Tells that the function that will generate the service takes
a pair whose first element is the suffix of the URL of the current service,
and the second element corresponds to other (regular) parameters.
e.g.: suffix_prod (int "suff" ** all_suffix "endsuff") (int "i")
will match an URL ending by 777/go/go/go?i=320
and send the value
((777, ["go";"go";"go"]), 320)
to the service handler.