.TH "Eliom_parameter" 3o 2014-07-10 OCamldoc ""
.SH NAME
Eliom_parameter \- Ad-hoc runtime type representation for service parameters.
.SH Module
Module Eliom_parameter
.SH Documentation
.sp
Module
.BI "Eliom_parameter"
:
.B sig end
.sp
Ad\-hoc runtime type representation for service parameters\&.
.sp
Please read Eliom\&'s manual before this page
to learn how to use
\&.
.sp
.sp
.sp
.sp
.sp
.I type
.B ('a, +'b, +'c)
.I params_type
.sp
Abstract type for service parameters\&. See for example the
parameter
.B ~get_param
of
.B Eliom_service\&.Http\&.service
\&.
.sp
.sp
\-
.B \&'a
is the type for the OCaml type of the
parameter as expected by the service handler\&.
.sp
\-
.B \&'b
is a phantom type, subtype of
.B Eliom_parameter\&.suff
, stating the kind
of the parameter: suffix or not\&.
.sp
\-
.B \&'c
is the type of the parameter name, usually an instance of
.B Eliom_parameter\&.param_name
, as used by forms construction
functions (e\&. g\&. the last parameter of
.B Eliom_content\&.Html5\&.D\&.get_form
), and specialized form widget (see
for example the section
.B Eliom_content\&.Html5\&.D\&.form_widgets
of
.B Eliom_content\&.HTML5\&.D
)\&. )
.sp
.sp
.I type suff
=
.B [ `Endsuffix | `WithSuffix | `WithoutSuffix ]
.sp
This type is used as a phantom type in
.B Eliom_parameter\&.params_type
to describe
whether a parameter is encoded in the path of the URI as a suffix
parameter\&.
.sp
.sp
.PP
.B ===
.B Typed parameter\&'s name
.B ===
.PP
.I type
.B 'a
.I param_name
.sp
Abstract type for parameters\&' name\&. The
.B \&'a
type parameter is a phantom type, usually a
subtype of
.B Eliom_parameter\&.setoneradio
, used to denotes the parameter\&'s arity\&.
.sp
.sp
.I type no_param_name
.sp
Empty type used to denotes it is not possible to use the parameter
in a form\&. See for example
.B Eliom_parameter\&.raw_post_data
\&.
.sp
.sp
.I type
.B 'a
.I setoneradio
=
.B [ `One of 'a | `Radio of 'a | `Set of 'a ]
.sp
A parameter arity could either be:
.sp
\-
.B `Set of \&'a
means: any number of
.B \&'a
\&.
.sp
\-
.B `One of \&'a
means: exactly one
.B \&'a
\&.
.sp
\-
.B `Radio of \&'a
means: zero or one
.B \&'a
\&.
.sp
.sp
.I type
.B 'a
.I oneradio
=
.B [ `One of 'a | `Radio of 'a ]
.sp
Restriction of
.B Eliom_parameter\&.setoneradio
unary and optional parameters\&.
.sp
.sp
.I type
.B 'a
.I setone
=
.B [ `One of 'a | `Set of 'a ]
.sp
Restriction of
.B Eliom_parameter\&.setoneradio
unary and set parameters\&.
.sp
.sp
.PP
.B ===
.B Types helpers
.B ===
.PP
.I type
.B ('a, 'b)
.I binsum
=
| Inj1
.B of
.B 'a
| Inj2
.B of
.B 'b
.sp
Helpers type used for parameters of type binary sum, see
.B Eliom_parameter\&.sum
\&.
.sp
.sp
.I type
.B 'an
.I listnames
= {
it :
.B 'el 'a. ('an -> 'el -> 'a -> 'a) -> 'el list -> 'a -> 'a
;
}
.sp
Helpers type used to construct forms from lists, see
.B Eliom_parameter\&.list
\&.
.sp
.sp
.PP
.B ===
.B Basic types of pages parameters
.B ===
.PP
.I val int
:
.B string ->
.B (int, [ `WithoutSuffix ], [ `One of int ] param_name)
.B params_type
.sp
Specifying parameter as
.B int s
tells that the service takes an integer as parameter, labeled
.B s
\&.
.sp
.sp
.I val int32
:
.B string ->
.B (int32, [ `WithoutSuffix ], [ `One of int32 ] param_name)
.B params_type
.sp
Specifying parameter as
.B int32 s
tells that the service takes a 32 bits integer as parameter, labeled
.B s
\&.
.sp
.sp
.I val int64
:
.B string ->
.B (int64, [ `WithoutSuffix ], [ `One of int64 ] param_name)
.B params_type
.sp
Specifying parameter as
.B int64 s
tells that the service takes a 64 bits integer as parameter, labeled
.B s
\&.
.sp
.sp
.I val float
:
.B string ->
.B (float, [ `WithoutSuffix ], [ `One of float ] param_name)
.B params_type
.sp
Specifying parameter as
.B float s
tells that the service takes a floating point number as parameter, labeled
.B s
\&.
.sp
.sp
.I val string
:
.B string ->
.B (string, [ `WithoutSuffix ], [ `One of string ] param_name)
.B params_type
.sp
Specifying parameter as
.B string s
tells that the service takes a string as parameter, labeled
.B s
\&.
.sp
.sp
.I val bool
:
.B string ->
.B (bool, [ `WithoutSuffix ], [ `One of bool ] param_name)
.B params_type
.sp
Specifying parameter as
.B bool s
tells that the service takes a boolean as parameter, labeled
.B s
\&.
(to use for example with boolean checkboxes)
.sp
.sp
.I val file
:
.B string ->
.B (Eliom_lib.file_info, [ `WithoutSuffix ],
.B [ `One of Eliom_lib.file_info ] param_name)
.B params_type
.sp
Specifying parameter as
.B file s
tells that the service takes a file as parameter, labeled
.B s
\&.
.sp
.sp
.I val unit
:
.B (unit, [ `WithoutSuffix ], unit) params_type
.sp
Specifying parameter as
.B unit
is used for services that don\&'t have any parameters
.sp
.sp
.I val user_type
:
.B of_string:(string -> 'a) ->
.B to_string:('a -> string) ->
.B string ->
.B ('a, [ `WithoutSuffix ], [ `One of 'a ] param_name)
.B params_type
.sp
Specifying parameter as
.B user_type ~of_string ~to_string s
tells that the
service take a parameter, labeled
.B s
, and that the server will
have to use
.B of_string
and
.B to_string
to make the conversion
between the OCaml representation of the parameter and it\&'s
external representation as a string\&. It allows one to use whatever
type you want for a parameter of the service\&.
.sp
.sp
.I val type_checker
:
.B ('a -> unit) ->
.B ('a, 'b, 'c) params_type ->
.B ('a, 'b, 'c) params_type
.sp
Specifying parameter as
.B type_checker check t
is equivalent as
.B t
but the check function is called after decoding the
parameters, allowing you to make more checks on the parameters before
the service handler is called\&. Raise an exception if the parameter
is not correct, and the error handler will be called instead of the
service handler\&.
.sp
.sp
.I type coordinates
= {
abscissa :
.B int
;
ordinate :
.B int
;
}
.sp
The type
.B coordinates
represent the data sent by an
.B
\&.
.sp
.sp
.I val coordinates
:
.B string ->
.B (coordinates, [ `WithoutSuffix ],
.B [ `One of coordinates ] param_name)
.B params_type
.sp
Specifying parameter as
.B coordinates s
tells that the service takes as
parameters the coordinates of a point in an
.B
\&.
.sp
.sp
.I val string_coordinates
:
.B string ->
.B (string * coordinates, [ `WithoutSuffix ],
.B [ `One of string * coordinates ] param_name)
.B params_type
.sp
Specifying parameter as
.B string_coordinates s
tells that the service takes
as parameters the coordinates of a point and the associated
.B string
value in an
.B
\&.
.sp
.sp
.I val int_coordinates
:
.B string ->
.B (int * coordinates, [ `WithoutSuffix ],
.B [ `One of int * coordinates ] param_name)
.B params_type
.sp
Same as
.B string_coordinates
but for an integer value
.sp
.sp
.I val int32_coordinates
:
.B string ->
.B (int32 * coordinates, [ `WithoutSuffix ],
.B [ `One of int32 * coordinates ] param_name)
.B params_type
.sp
Same as
.B string_coordinates
but for a 32 bits integer value
.sp
.sp
.I val int64_coordinates
:
.B string ->
.B (int64 * coordinates, [ `WithoutSuffix ],
.B [ `One of int64 * coordinates ] param_name)
.B params_type
.sp
Same as
.B string_coordinates
but for a 64 integer value
.sp
.sp
.I val float_coordinates
:
.B string ->
.B (float * coordinates, [ `WithoutSuffix ],
.B [ `One of float * coordinates ] param_name)
.B params_type
.sp
Same as
.B string_coordinates
but for a float value
.sp
.sp
.I val user_type_coordinates
:
.B of_string:(string -> 'a) ->
.B to_string:('a -> string) ->
.B string ->
.B ('a * coordinates, [ `WithoutSuffix ],
.B [ `One of 'a * coordinates ] param_name)
.B params_type
.sp
Same as
.B string_coordinates
but for a value of your own type\&. See
.B Eliom_parameter\&.user_type
for a description of the
.B of_string
and
.B to_string
parameters\&.
.sp
.sp
.PP
.B ===
.B Composing types of pages parameters
.B ===
.PP
.I val ( ** )
:
.B ('a, [ `WithoutSuffix ], 'b) params_type ->
.B ('c, [< `Endsuffix | `WithoutSuffix ] as 'e, 'd) params_type ->
.B ('a * 'c, 'e, 'b * 'd) params_type
.sp
The combinator
.B p1 ** p2
allows one to define service that take a
pair of parameter\&. The associated service handler should expect a
pair
.B (p1, p2)
as parameter\&.
.sp
.sp
.I val prod
:
.B ('a, [ `WithoutSuffix ], 'b) params_type ->
.B ('c, [< `Endsuffix | `WithoutSuffix ] as 'e, 'd) params_type ->
.B ('a * 'c, 'e, 'b * 'd) params_type
.sp
Same as
.B Eliom_parameter\&.( ** )
\&.
.sp
.sp
.I val sum
:
.B ('a, [ `WithoutSuffix ], 'b) params_type ->
.B ('c, [ `WithoutSuffix ], 'd) params_type ->
.B (('a, 'c) binsum, [ `WithoutSuffix ], 'b * 'd)
.B params_type
.sp
The combinator
.B sum p1 p2
allows one to define service that expect
either the parameter
.B p1
or the parameter
.B p2
\&.
.sp
.sp
.I val opt
:
.B ('a, [ `WithoutSuffix ], 'b) params_type ->
.B ('a option, [ `WithoutSuffix ], 'b) params_type
.sp
The combinator
.B opt p
allow to define an optional parameter\&.
.sp
.sp
.I val neopt
:
.B ('a, [ `WithoutSuffix ], 'b) params_type ->
.B ('a option, [ `WithoutSuffix ], 'b) params_type
.sp
The combinator
.B neopt p
allow to define an optional parameter assumed to be None if empty\&.
.sp
.sp
.I val radio
:
.B (string ->
.B ('a, [ `WithoutSuffix ], [ `One of 'b ] param_name)
.B params_type) ->
.B string ->
.B ('a option, [ `WithoutSuffix ], [ `Radio of 'b ] param_name)
.B params_type
.sp
Specifying parameter as
.B radio f s
tells that the service takes an optional
argument labeled
.B s
and of type
.B f s
\&. Use
.B radio
instead of
.B Eliom_parameter\&.opt
if you want to use this parameter with a radio button\&.
.sp
.sp
.I val any
:
.B ((string * string) list, [ `WithoutSuffix ], unit)
.B params_type
.sp
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\&.
.sp
.sp
.I val set
:
.B (string ->
.B ('a, [ `WithoutSuffix ], [ `One of 'b ] param_name)
.B params_type) ->
.B string ->
.B ('a list, [ `WithoutSuffix ], [ `Set of 'b ] param_name)
.B params_type
.sp
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
.B set int "i"
will match the parameter string
.B 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\&.
.sp
.sp
.I val list
:
.B string ->
.B ('a, [ `WithoutSuffix ], 'b) params_type ->
.B ('a list, [ `WithoutSuffix ], 'b listnames)
.B params_type
.sp
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
.B Eliom_parameter\&.listnames
is given to
generate the name for each value\&.
.sp
.sp
.I val regexp
:
.B Netstring_pcre.regexp ->
.B string ->
.B to_string:(string -> string) ->
.B string ->
.B (string, [ `WithoutSuffix ], [ `One of string ] param_name)
.B params_type
.sp
.B regexp r d s
tells that the service takes a string
that matches the regular expression
.B r
as parameter,
labeled
.B s
, and that will be rewritten in d\&.
The syntax of regexp is PCRE\&'s one (uses
.B Netstring_pcre
, from OCamlnet)\&.
For example:
.B regexp (Netstring_pcre\&.regexp "\(rs[(\&.* )\(rs]") "($1)" "myparam"
will match the parameter
.B myparam=[hello]
and send the string
.B "(hello)"
to
the service handler\&.
.sp
.sp
.I val guard
:
.B (string -> ('a, 'b, 'c) params_type) ->
.B string -> ('a -> bool) -> ('a, 'b, 'c) params_type
.sp
.B guard construct name pred
returns the same parameter
as
.B construct name
but with ensuring that each value must satisfy
.B pred
\&.
For instance:
.B int "age" ((>=) 0)
.sp
.sp
.I val suffix
:
.B ?redirect_if_not_suffix:bool ->
.B ('s, [< `Endsuffix | `WithoutSuffix ], 'sn) params_type ->
.B ('s, [ `WithSuffix ], 'sn) params_type
.sp
Tells that the parameter of the service handler is
the suffix of the URL of the current service\&.
e\&.g\&.
.B suffix (int "i" ** string "s")
will match an URL ending by
.B 380/yo
\&.
and send
.B (380, "yo")
to the service handler\&.
.sp
For each service with suffix, there is also a service with regular
parameters (without suffix) that will be used if you create a form
towards a service with suffix\&.
If
.B redirect_if_not_suffix
is
.B true
(default),
this service without suffix will be redirected to the suffix version\&.
.sp
.sp
.I val all_suffix
:
.B string ->
.B (string list, [ `Endsuffix ],
.B [ `One of string list ] param_name)
.B params_type
.sp
Takes all the suffix, as long as possible, as a (slash separated)
string list
.sp
.sp
.I val all_suffix_string
:
.B string ->
.B (string, [ `Endsuffix ], [ `One of string ] param_name)
.B params_type
.sp
Takes all the suffix, as long as possible, as a string
.sp
.sp
.I val all_suffix_user
:
.B of_string:(string -> 'a) ->
.B to_string:('a -> string) ->
.B string ->
.B ('a, [ `Endsuffix ], [ `One of 'a ] param_name)
.B params_type
.sp
Takes all the suffix, as long as possible,
with a type specified by the user\&.
.sp
.sp
.I val all_suffix_regexp
:
.B Netstring_pcre.regexp ->
.B string ->
.B to_string:(string -> string) ->
.B string ->
.B (string, [ `Endsuffix ], [ `One of string ] param_name)
.B params_type
.sp
.B all_suffix_regexp r d s
takes all the suffix, as long as possible,
matching the regular expression
.B r
, name
.B s
, and rewrite it in
.B d
\&.
.sp
.sp
.I val suffix_prod
:
.B ?redirect_if_not_suffix:bool ->
.B ('s, [< `Endsuffix | `WithoutSuffix ], 'sn) params_type ->
.B ('a, [ `WithoutSuffix ], 'an) params_type ->
.B ('s * 'a, [ `WithSuffix ], 'sn * 'an) params_type
.sp
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\&.:
.B suffix_prod (int "suff" ** all_suffix "endsuff") (int "i")
will match an URL ending by
.B 777/go/go/go?i=320
and send the value
.B ((777, ["go";"go";"go"]), 320)
to the service handler\&.
.sp
.sp
.I val suffix_const
:
.B string ->
.B (unit, [ `WithoutSuffix ], [ `One of unit ] param_name)
.B params_type
.sp
.B suffix_const v
is used only inside suffixes (do nothing for
regular parameters)\&.
It tells that the service takes a constant parameter
inside the suffix, whose value must be
.B v
\&.
It is used for putting constant directory names inside
suffix parameters (and thus make suffix parameters not be only suffixes
but anywhere you want in the path, e\&.g\&.
.B /param1/const/param2
)\&.
.sp
.sp
.I type
.B 'a
.I ocaml
.sp
marshaled OCaml values of type \&'a
.sp
.sp
.I val ocaml
:
.B string ->
.B 'a Deriving_Json.t ->
.B ('a, [ `WithoutSuffix ],
.B [ `One of 'a ocaml ] param_name)
.B params_type
.sp
.B ocaml s
tells that the service is expecting some caml (client side)
program to send some value of type \&'a, marshaled\&.
As usual
.B s
is the name of the parameter\&.
.sp
.sp
.I type raw_post_data
=
.B ((string * string) * (string * string) list) option *
.B string Ocsigen_stream.t option
.sp
When the content type is neither URLencoded form data or multipart data,
it is possible to get it as a stream of strings\&.
The first element of the pair is the content\-type\&.
This kind of parameter cannot be combined with other ones,
and it is not possible to create a form towards a service taking
this kind of parameter\&.
.sp
.sp
.I val raw_post_data
:
.B (raw_post_data, [ `WithoutSuffix ],
.B no_param_name)
.B params_type
.sp
.sp
.I type
.B ('a, +'tipo, +'names)
.I non_localized_params
.sp
.B Non localized parameters
.sp
.sp
.I val make_non_localized_parameters
:
.B prefix:string ->
.B name:string ->
.B ?persistent:bool ->
.B ('a, [ `WithoutSuffix ], 'b) params_type ->
.B ('a, [ `WithoutSuffix ], 'b) non_localized_params
.sp
create a new specification for non localized parameters\&.
You must give a name to this set of parameters\&.
Warning: the names must be unique for the whole application\&.
That\&'s why the name is composed by a prefix (the name of your project) and
another string (the name of your non localized parameters)\&.
.sp
Will fail with exception
.B Failure _
if the name contains a dot\&.
If
.B ?persistent
is
.B true
, the non localized parameter
may remain if you call another service, if this service
allows this (default
.B false
)\&.
.sp
.sp
.I val get_non_localized_get_parameters
:
.B ('a, [ `WithoutSuffix ], 'b) non_localized_params ->
.B 'a option
.sp
.B get_non_localized_get_parameters ~sp p
decodes and
returns non localized GET parameters specified by
.B p
if present\&.
.sp
.sp
.I val get_non_localized_post_parameters
:
.B ('a, [ `WithoutSuffix ], 'b) non_localized_params ->
.B 'a option
.sp
.B get_non_localized_post_parameters ~sp p
decodes and
returns non localized POST parameters specified by
.B p
if present\&.
.sp
.sp
.I type nl_params_set
.sp
Use this type to give non localized parameters to a link or a form
.sp
.sp
.I val empty_nl_params_set
:
.B nl_params_set
.sp
.sp
.I val add_nl_parameter
:
.B nl_params_set ->
.B ('a, [< `WithSuffix | `WithoutSuffix ], 'b)
.B non_localized_params -> 'a -> nl_params_set
.sp
.sp
.I val get_nl_params_names
:
.B ('b, [< `WithSuffix | `WithoutSuffix ], 'a)
.B non_localized_params -> 'a
.sp
.sp
.I val get_to_and_from
:
.B ('a, 'b, 'c) params_type -> (string -> 'a) * ('a -> string)
.sp
Given a parameter type, get the two functions
that converts from and to strings\&. You should
only use this function on
.sp
\-options ;
.sp
\-basic types : int, int32, int64, float, string
.sp
\-marshal
.sp
\-unit
.sp
\-string
.sp
\-bool
.sp
.sp