*
* Copyright (C) 2003 Merjis Ltd.
*
- * $Id: perl.mli,v 1.7 2003-10-16 08:54:56 rich Exp $
+ * $Id: perl.mli,v 1.10 2003-10-26 11:22:38 rich Exp $
*)
type t
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 sv_of_int : int -> sv
(** Convert an [int] into a Perl [SV]. *)
-val float_of_sv : sv -> int
+val float_of_sv : sv -> float
(** Convert a Perl [SV] into a float. *)
-val sv_of_float : int -> sv
+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. *)
(** 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 {!sv_true} instead). *)
+ * 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 {!sv_false} instead). *)
+ * with using this, so use {!Perl.sv_false} instead). *)
(* Actually there are many more types defined than this ... *)
type sv_t = SVt_NULL
val string_of_sv_t : sv_t -> string
(** Return a printable string for an [sv_t] ([SV] type). *)
+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
* array [AV]. If the input is not a reference to an array, throws
* [Invalid_arg].
*)
-(*
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_arg].
*)
-*)
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]. *)
+(** 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]. *)
+ * 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]. *)
+ * 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]. *)
+ * [unshift \@av, $sv]. *)
val av_length : av -> int
(** Return the length of the [AV]. *)
val av_set : av -> int -> sv -> unit
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 = ()]. *)
+(** 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]. *)
+(** 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. *)
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 get_sv : ?create:bool -> string -> sv
(** Return a scalar value by name. For example, if you have a symbol
* this function will return the [SV] for [undef].
*)
val get_av : ?create:bool -> string -> av
-(** Same as {!get_sv} except will return and/or create [@a]. *)
+(** 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 {!int_of_sv} etc.).
+ * 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].
*)