*
* Copyright (C) 2003 Merjis Ltd.
*
- * $Id: perl.mli,v 1.3 2003-10-12 11:56:26 rich Exp $
+ * $Id: perl.mli,v 1.5 2003-10-14 16:05:21 rich Exp $
*)
type t
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 init : unit -> unit
+(** Don't call this. Instead link your program with [perl_init.cmo] or
+ * [perl_init.cmx] which calls this for you.
+ *)
+
+external destroy : unit -> unit
+ = "perl4caml_destroy"
+(** Destroy the current Perl interpreter, performing any necessary cleanup.
+ * You should call this at the end of your program, otherwise Perl won't
+ * properly clean up.
+ *
+ * Note that a Perl interpreter is created for you by default when you
+ * use perl4caml.
+ *)
+
external create : ?args:string array -> unit -> t
= "perl4caml_create"
-(** Create a Perl interpreter.
+(** Create a new Perl interpreter. (Note that a Perl interpreter is created
+ * for you by default so you don't need to call this).
*
* The optional [?args] parameter is the command line passed to the
* interpreter, and controls things like whether warnings are enabled
* 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".
*)
-external destroy : t -> unit
- = "perl4caml_destroy"
-(** Destroy a Perl interpreter, performing any necessary cleanup. *)
-
external set_context : t -> unit
= "perl4caml_set_context"
(** IF Perl was compiled with [-Dusemultiplicity] and IF you are using
(** Convert a Perl [SV] into a string. *)
external sv_of_string : string -> sv = "perl4caml_sv_of_string"
(** 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]. *)
+
external sv_is_true : sv -> bool = "perl4caml_sv_is_true"
(** Return [true] if the [SV] is "true" (in the Perl sense of truth). *)
external sv_is_undef : sv -> bool = "perl4caml_sv_is_undef"
(** Return [true] if the [SV] is undefined (is [undef]). *)
-val sv_undef : sv
+external sv_undef : unit -> sv = "perl4caml_sv_undef"
(** Returns [undef]. *)
-val sv_true : sv
+val sv_true : unit -> sv
(** Returns an [SV] which is true. *)
-val sv_false : sv
+val sv_false : unit -> sv
(** Returns an [SV] which is false. *)
+external sv_yes : unit -> sv = "perl4caml_sv_yes"
+(** Returns Perl's internal [PL_sv_yes]. (There are some unresolved issues
+ * with using this, so use {!sv_true} instead). *)
+external sv_no : unit -> sv = "perl4caml_sv_no"
+(** Returns Perl's internal [PL_sv_no]. (There are some unresolved issues
+ * with using this, so use {!sv_false} instead). *)
+
+(* Actually there are many more types defined than this ... *)
+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. *)
+external sv_type : sv -> sv_t = "perl4caml_sv_type"
+(** 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). *)
+
+external deref : sv -> sv = "perl4caml_deref"
+(** 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_arg].
+ *)
+external deref_array : sv -> av = "perl4caml_deref_array"
+(** 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_arg].
+ *)
+(*
+external deref_hash : sv -> hv = "perl4caml_deref_hash"
+(** 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_arg].
+ *)
+*)
+
+external av_empty : unit -> av = "perl4caml_av_empty"
+(** Create an empty [AV] (array). *)
+external av_of_sv_list : sv list -> av = "perl4caml_av_of_sv_list"
+(** Create an array from a list of [SVs]. *)
+external av_push : av -> sv -> unit = "perl4caml_av_push"
+(** Append the [SV] to the end of the array. Same as Perl [push @av, $sv]. *)
+external av_pop : av -> sv = "perl4caml_av_pop"
+(** Remove the [SV] at the end of the array and return it. Same as
+ * Perl [$sv = pop @av]. *)
+external av_shift : av -> sv = "perl4caml_av_shift"
+(** Remove the [SV] at the beginning of the array and return it. Same as
+ * Perl [$sv = shift @av]. *)
+external av_unshift : av -> sv -> unit = "perl4caml_av_unshift"
+(** Prepend the [SV] to the start of the array. Same as Perl
+ * [unshift @av, $sv]. *)
+external av_length : av -> int = "perl4caml_av_length"
+(** Return the length of the [AV]. *)
+external av_set : av -> int -> sv -> unit = "perl4caml_av_set"
+(** Replace the i'th element of the [AV] with [SV]. *)
+external av_get : av -> int -> sv = "perl4caml_av_get"
+(** Get the i'th element of the [AV]. *)
+external av_clear : av -> unit = "perl4caml_av_clear"
+(** Remove all elements from the [AV]. Same as Perl [@av = ()]. *)
+external av_undef : av -> unit = "perl4caml_av_undef"
+(** Delete the [AV] (and all elements in it). Same as Perl [undef @av]. *)
+external av_extend : av -> int -> unit = "perl4caml_av_extend"
+(** Extend the [AV] so it contains at least [n+1] elements. *)
+val av_map : (sv -> 'a) -> av -> 'a list
+(** Map a function over the elements in the [AV], return a list of the
+ * results. *)
external get_sv : ?create:bool -> string -> sv = "perl4caml_get_sv"
(** Return a scalar value by name. For example, if you have a symbol
* not exist, then Perl will create the symbol (with value [undef]) and
* this function will return the [SV] for [undef].
*)
+external get_av : ?create:bool -> string -> av = "perl4caml_get_av"
+(** Same as {!get_sv} except will return and/or create [@a]. *)
external call : ?sv:sv -> ?fn:string -> sv list -> sv
= "perl4caml_call"