Updated deps

[perl4caml.git] / perl.mli

diff --git a/perl.mli b/perl.mli
index 778de58..e16ada2 100644 (file)
--- a/perl.mli
+++ b/perl.mli
@@ -2,7 +2,7 @@
   *
   * Copyright (C) 2003 Merjis Ltd.
   *
-  * $Id: perl.mli,v 1.12 2004-03-03 12:39:20 rich Exp $
+  * $Id: perl.mli,v 1.15 2005-04-14 13:05:12 rich Exp $
   *)
 
 type sv
@@ -60,10 +60,10 @@ type sv_t    = SVt_NULL
             | 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_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
@@ -72,6 +72,25 @@ val sv_type : sv -> sv_t
 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 -> 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 -> 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 -> 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].
@@ -128,7 +147,10 @@ val av_clear : av -> unit
 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. *)
+(** 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. *)
@@ -151,16 +173,40 @@ 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]. *)
+
+(* The following are the low-level iteration interface to hashes,
+ * which you probably shouldn't use directly.  Use {!hv_keys},
+ * {!assoc_of_hv}, etc. instead.  See [perlguts(3)] if you really
+ * want to use this interface.
+ *)
+type he
+val hv_iterinit : hv -> 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].
+  (** 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]. *)