module Perl:sig
..end
Interface to Perl from OCaml.
type
sv
Perl scalar value.
type
av
Perl array value.
type
hv
Perl hash value.
exception Perl_failure of string
die
in Perl code is translated automatically into this exception.
val int_of_sv : sv -> int
Convert a Perl SV
into an integer. Note that OCaml int
s aren't
large enough to store the full 32 (or 64) bits from a Perl integer,
so you may get a silent overflow.
val sv_of_int : int -> sv
Convert an int
into a Perl SV
.
val float_of_sv : sv -> float
Convert a Perl SV
into a float.
val sv_of_float : float -> sv
Convert a float
into a Perl SV
.
val string_of_sv : sv -> string
Convert a Perl SV
into a string.
val sv_of_string : string -> sv
Convert a string
into a Perl SV
.
val bool_of_sv : sv -> bool
Convert an SV
into a boolean.
val sv_of_bool : bool -> sv
Convert a boolean into an SV
.
val sv_is_true : sv -> bool
Return true
if the SV
is "true" (in the Perl sense of truth).
val sv_is_undef : sv -> bool
Return true
if the SV
is undefined (is undef
).
val sv_undef : unit -> sv
Returns undef
.
val sv_true : unit -> sv
Returns an SV
which is true.
val sv_false : unit -> sv
Returns an SV
which is false.
val sv_yes : unit -> sv
Returns Perl's internal PL_sv_yes
. (There are some unresolved issues
with using this, so use Perl.sv_true
instead).
val sv_no : unit -> sv
Returns Perl's internal PL_sv_no
. (There are some unresolved issues
with using this, so use Perl.sv_false
instead).
type
sv_t =
| |
SVt_NULL |
|||
| |
SVt_IV |
(* | Integer scalar. | *) |
| |
SVt_NV |
(* | Floating point scalar. | *) |
| |
SVt_PV |
(* | String scalar. | *) |
| |
SVt_RV |
(* | Reference. | *) |
| |
SVt_PVAV |
(* | Array. | *) |
| |
SVt_PVHV |
(* | Hash. | *) |
| |
SVt_PVCV |
(* | Code. | *) |
| |
SVt_PVGV |
(* | Glob (possibly a file handle). | *) |
| |
SVt_PVMG |
(* | Blessed or magical scalar. | *) |
val sv_type : sv -> sv_t
Return the type of data contained in an SV
. Somewhat equivalent to
calling Perl's ref
function.
val string_of_sv_t : sv_t -> string
Return a printable string for an sv_t
(SV
type).
val reftype : sv -> sv_t
The parameter sv
must be a reference. This convenience function
works out what it is a reference to, either a scalar, array, hash,
code or glob. If the parameter is not a reference, or is a reference
to an unknown type, then this will throw Invalid_argument
.
val address_of_sv : sv -> Stdlib.Nativeint.t
Returns the address of the SV. Useful for debugging since Perl also prints out addresses on internal errors.
val address_of_av : av -> Stdlib.Nativeint.t
Returns the address of the AV. Useful for debugging since Perl also prints out addresses on internal errors.
val address_of_hv : hv -> Stdlib.Nativeint.t
Returns the address of the HV. Useful for debugging since Perl also prints out addresses on internal errors.
val scalarref : sv -> sv
Given a scalar, this returns a reference to the scalar. Note that
because references are SV
s, this returns sv
.
val arrayref : av -> sv
Given an array, this returns a reference to the array. Note that
because references are SV
s, this returns sv
.
val hashref : hv -> sv
Given a hash, this returns a reference to the hash. Note that
because references are SV
s, this returns sv
.
val deref : sv -> sv
The input is a reference to a scalar. This returns the underlying
scalar SV
. If the input is not a reference to a scalar, throws
Invalid_argument
.
val deref_array : sv -> av
The input is a reference to an array. This returns the underlying
array AV
. If the input is not a reference to an array, throws
Invalid_argument
.
val deref_hash : sv -> hv
The input is a reference to a hash. This returns the underlying
hash HV
. If the input is not a reference to a hash, throws
Invalid_argument
.
val av_empty : unit -> av
Create an empty AV
(array).
val av_of_sv_list : sv list -> av
Create an array from a list of SVs
.
val av_push : av -> sv -> unit
Append the SV
to the end of the array. Same as Perl
push @av, $sv
.
val av_pop : av -> sv
Remove the SV
at the end of the array and return it. Same as
Perl $sv = pop @av
.
val av_shift : av -> sv
Remove the SV
at the beginning of the array and return it. Same as
Perl $sv = shift @av
.
val av_unshift : av -> sv -> unit
Prepend the SV
to the start of the array. Same as Perl
unshift @av, $sv
.
val av_length : av -> int
Return the length of the AV
.
val av_set : av -> int -> sv -> unit
Replace the i'th element of the AV
with SV
.
val av_get : av -> int -> sv
Get the i'th element of the AV
.
val av_clear : av -> unit
Remove all elements from the AV
. Same as Perl @av = ()
.
val av_undef : av -> unit
Delete the AV
(and all elements in it). Same as Perl undef @av
.
val av_extend : av -> int -> unit
Extend the AV
so it contains at least n+1
elements. Note that
this apparently just changes the amount of allocated storage. The
extra elements are not visible until you store something in them.
val av_map : (sv -> 'a) -> av -> 'a list
Map a function over the elements in the AV
, return a list of the
results.
val list_of_av : av -> sv list
Convert an AV
into a simple list of SV
s.
val av_of_string_list : string list -> av
Build an AV
from a list of strings.
val hv_empty : unit -> hv
Create an empty HV
(hash).
val hv_set : hv -> string -> sv -> unit
Store the given SV
in the named key in the hash.
val hv_get : hv -> string -> sv
Return the SV
at the key in the hash. Throws Not_found
if no key.
val hv_exists : hv -> string -> bool
Return true if the hash contains the given key. Same as Perl exists
.
val hv_delete : hv -> string -> unit
Delete the given key from the hash. Same as Perl delete
.
val hv_clear : hv -> unit
Remove all elements from the HV
. Same as Perl %av = ()
.
val hv_undef : hv -> unit
Delete the HV
(and all elements in it). Same as Perl undef %hv
.
val hv_of_assoc : (string * sv) list -> hv
Create an HV
directly from an assoc list. Perl hashes cannot
support multiple values attached to the same key, so if you try
to provide an assoc list with multiple identical keys, the results
will be undefined.
val assoc_of_hv : hv -> (string * sv) list
Take an HV
and return an assoc list.
val hv_keys : hv -> string list
Return all the keys of an HV
.
val hv_values : hv -> sv list
Return all the values of an HV
.
type
he
val hv_iterinit : hv -> Stdlib.Int32.t
val hv_iternext : hv -> he
val hv_iterkey : he -> string
val hv_iterval : hv -> he -> sv
val hv_iternextsv : hv -> string * sv
val get_sv : ?create:bool -> string -> sv
Return a scalar value by name. For example, if you have a symbol
called $a
in Perl, then get_sv "a"
will return its value.
If the symbol does not exist, this throws Not_found
.
If the optional ?create
argument is set to true and the symbol does
not exist, then Perl will create the symbol (with value undef
) and
this function will return the SV
for undef
.
val get_av : ?create:bool -> string -> av
Same as Perl.get_sv
except will return and/or create @a
.
val get_hv : ?create:bool -> string -> hv
Same as Perl.get_sv
except will return and/or create %a
.
val call : ?sv:sv -> ?fn:string -> sv list -> sv
Call a Perl function in a scalar context, either by name (using the ?fn
parameter) or by calling a string/CODEREF (using the ?sv
parameter).
Returns the Perl SV
containing the result value. (See
Perl.int_of_sv
etc.).
If the Perl code calls die
then this will throw Perl_failure
.
val call_array : ?sv:sv -> ?fn:string -> sv list -> sv list
Call a Perl function in an array context, either by name (using the ?fn
parameter) or by calling a string/CODEREF (using the ?sv
parameter).
Returns the list of results.
If the Perl code calls die
then this will throw Perl_failure
.
val call_void : ?sv:sv -> ?fn:string -> sv list -> unit
Call a Perl function in a void context, either by name (using the ?fn
parameter) or by calling a string/CODEREF (using the ?sv
parameter).
Any results are discarded.
If the Perl code calls die
then this will throw Perl_failure
.
val eval : string -> sv
This is exactly like the Perl eval
command. It evaluates a piece of
Perl code (in scalar context) and returns the result (a Perl SV
).
val call_method : sv -> string -> sv list -> sv
call_method obj name [parameters]
calls the method name
on the Perl
object obj
with the given parameters, in a scalar context. Thus this
is equivalent to $obj->name (parameters)
.
Returns the Perl SV
containing the result value.
If the method calls die
then this will throw Perl_failure
.
val call_method_array : sv -> string -> sv list -> sv list
Like call_method
, but the method is called in an array context.
val call_method_void : sv -> string -> sv list -> unit
Like call_method
, but the method is called in a void context (results
are discarded).
val call_class_method : string -> string -> sv list -> sv
call_class_method classname name [parameters]
calls the static method
name
in the Perl class classname
with the given parameters, in a
scalar context. Thus this is equivalent to $classname->name (parameters)
.
Returns the Perl SV
containing the result value.
If the static method calls die
then this will throw Perl_failure
.
val call_class_method_array : string -> string -> sv list -> sv list
Like call_class_method
, but the method is called in an array context.
val call_class_method_void : string -> string -> sv list -> unit
Like call_class_method
, but the method is called in a void context.