module Perl: sig end
Copyright (C) 2003 Merjis Ltd.
$Id: perl.mli,v 1.10 2003/10/26 11:22:38 rich Exp $
type
t
type
sv
type
av
type
hv
exception Perl_failure of string
die
in Perl code is translated automatically into this exception.val current_interpreter : unit -> t
Perl
module has a notion of the "current" interpreter. Throws
Not_found
if there is no current interpreter.
When a program starts up, if it has been linked with perl_init.cmo
(which is should be), an interpreter is created for you. Normally
this should be all you need to know about interpreters, unless you
want to be really good and call
Perl.destroy (Perl.current_interpreter ())
at the end of your
program to do proper cleanup.
You can also, under certain circumstances, create other interpreters, although this is experiemental and definitely not recommended.
If Perl was compiled with -Dusemultiplicity
then you can create
mutliple interpreters at the same time and switch between them by
calling Perl.set_context
.
Otherwise you may destroy the current interpreter and create another
one (provided that at no time you have two "live" interpreters),
by calling Perl.destroy
followed by Perl.create
.
val destroy : t -> unit
You should call Perl.destroy (Perl.current_interpreter ())
at
the end of your program, otherwise Perl won't properly clean up
(running END
blocks, destroying objects and the like).
Note that a Perl interpreter is created for you by default when you use perl4caml.
The current interpreter can be found by calling
Perl.current_interpreter
.
val create : ?args:string array -> unit -> t
The optional ?args
parameter is the command line passed to the
interpreter, and controls things like whether warnings are enabled
(-w
) and which file(s) are parsed. The first element in the
array is the executable name (you can just set this to ""
).
Perl won't allow you to create multiple interpreters at the same time
unless Perl itself was compiled with -Dusemultiplicity
. However you
can create, then destroy, then create another and so on.
The newly created interpreter is set as the "current interpreter".
val set_context : t -> unit
-Dusemultiplicity
and IF you are using
multiple interpreters at the same time, then you must call this to
set the implied "current" interpreter.
Most users will never need to call this function.
val int_of_sv : sv -> int
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
int
into a Perl SV
.val float_of_sv : sv -> float
SV
into a float.val sv_of_float : float -> sv
float
into a Perl SV
.val string_of_sv : sv -> string
SV
into a string.val sv_of_string : string -> sv
string
into a Perl SV
.val bool_of_sv : sv -> bool
SV
into a boolean.val sv_of_bool : bool -> sv
SV
.val sv_is_true : sv -> bool
true
if the SV
is "true" (in the Perl sense of truth).val sv_is_undef : sv -> bool
true
if the SV
is undefined (is undef
).val sv_undef : unit -> sv
undef
.val sv_true : unit -> sv
SV
which is true.val sv_false : unit -> sv
SV
which is false.val sv_yes : unit -> sv
PL_sv_yes
. (There are some unresolved issues
with using this, so use Perl.sv_true
instead).val sv_no : unit -> sv
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 ref. | *) |
| |
SVt_PVHV |
(* | Hash ref. | *) |
| |
SVt_PVCV |
(* | Code ref. | *) |
| |
SVt_PVGV |
(* | Glob. | *) |
| |
SVt_PVMG |
(* | Blessed or magical scalar. | *) |
val sv_type : sv -> sv_t
SV
. Somewhat equivalent to
calling Perl's ref
function.val string_of_sv_t : sv_t -> string
sv_t
(SV
type).val scalarref : sv -> sv
SV
s, this returns sv
.val arrayref : av -> sv
SV
s, this returns sv
.val hashref : hv -> sv
SV
s, this returns sv
.val deref : sv -> sv
SV
. If the input is not a reference to a scalar, throws
Invalid_arg
.val deref_array : sv -> av
AV
. If the input is not a reference to an array, throws
Invalid_arg
.val deref_hash : sv -> hv
HV
. If the input is not a reference to a hash, throws
Invalid_arg
.val av_empty : unit -> av
AV
(array).val av_of_sv_list : sv list -> av
SVs
.val av_push : av -> sv -> unit
SV
to the end of the array. Same as Perl
push @av, $sv
.val av_pop : av -> sv
SV
at the end of the array and return it. Same as
Perl $sv = pop @av
.val av_shift : av -> sv
SV
at the beginning of the array and return it. Same as
Perl $sv = shift @av
.val av_unshift : av -> sv -> unit
SV
to the start of the array. Same as Perl
unshift @av, $sv
.val av_length : av -> int
AV
.val av_set : av -> int -> sv -> unit
AV
with SV
.val av_get : av -> int -> sv
AV
.val av_clear : av -> unit
AV
. Same as Perl @av = ()
.val av_undef : av -> unit
AV
(and all elements in it). Same as Perl undef @av
.val av_extend : av -> int -> unit
AV
so it contains at least n+1
elements.val av_map : (sv -> 'a) -> av -> 'a list
AV
, return a list of the
results.val list_of_av : av -> sv list
AV
into a simple list of SV
s.val av_of_string_list : string list -> av
AV
from a list of strings.val hv_empty : unit -> hv
HV
(hash).val hv_set : hv -> string -> sv -> unit
SV
in the named key in the hash.val hv_get : hv -> string -> sv
SV
at the key in the hash. Throws Not_found
if no key.val hv_exists : hv -> string -> bool
exists
.val hv_delete : hv -> string -> unit
delete
.val hv_clear : hv -> unit
HV
. Same as Perl %av = ()
.val hv_undef : hv -> unit
HV
(and all elements in it). Same as Perl undef %hv
.val get_sv : ?create:bool -> string -> sv
$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
val get_hv : ?create:bool -> string -> hv
val call : ?sv:sv -> ?fn:string -> sv list -> sv
?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
?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
?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
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
call_method
, but the method is called in an array context.val call_method_void : sv -> string -> sv list -> unit
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
call_class_method
, but the method is called in an array context.val call_class_method_void : string -> string -> sv list -> unit
call_class_method
, but the method is called in a void context.