*
* Copyright (C) 2003 Merjis Ltd.
*
- * $Id: perl.mli,v 1.9 2003-10-18 12:36:09 rich Exp $
+ * $Id: perl.mli,v 1.15 2005-04-14 13:05:12 rich Exp $
*)
-type t
-(** Perl interpreter (abstract type). *)
-
type sv
(** Perl scalar value. *)
exception Perl_failure of string
(** [die] in Perl code is translated automatically into this exception. *)
-val current_interpreter : unit -> t
-(** The [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
-(** Destroy the Perl interpreter, performing any necessary cleanup.
- *
- * 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
-(** 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
- * ([-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
-(** IF Perl was compiled with [-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
(** 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,
*)
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. *)
| 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
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].
+ *)
+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_arg].
+ * [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_arg].
+ * [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_arg].
+ * [Invalid_argument].
*)
val av_empty : unit -> 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. *)
+(** 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. *)
(** 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]. *)
git.annexia.org / perl4caml.git / blobdiff