*
* Copyright (C) 2003 Merjis Ltd.
*
- * $Id: perl.mli,v 1.1 2003-10-11 18:25:52 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 PerlFailure of string
-(** [die] in Perl code is translated automatically into this exception. *)
-
-external create : ?args:string array -> unit -> t
- = "perl4caml_create"
-(** Create a Perl interpreter.
- *
- * 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.
- *)
+type av
+(** Perl array value. *)
-external destroy : t -> unit
- = "perl4caml_destroy"
-(** Destroy a Perl interpreter, performing any necessary cleanup. *)
+type hv
+(** Perl hash value. *)
-external set_context : t -> unit
- = "perl4caml_set_context"
-(** 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.
- *)
+exception Perl_failure of string
+(** [die] in Perl code is translated automatically into this exception. *)
-external int_of_sv : sv -> int = "perl4caml_int_of_sv"
+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,
* so you may get a silent overflow.
*)
-external sv_of_int : int -> sv = "perl4caml_sv_of_int"
+val sv_of_int : int -> sv
(** Convert an [int] into a Perl [SV]. *)
-external float_of_sv : sv -> int = "perl4caml_float_of_sv"
+val float_of_sv : sv -> float
(** Convert a Perl [SV] into a float. *)
-external sv_of_float : int -> sv = "perl4caml_sv_of_float"
+val sv_of_float : float -> sv
(** Convert a [float] into a Perl [SV]. *)
-external string_of_sv : sv -> string = "perl4caml_string_of_sv"
+val string_of_sv : sv -> string
(** Convert a Perl [SV] into a string. *)
-external sv_of_string : string -> sv = "perl4caml_sv_of_string"
+val sv_of_string : string -> sv
(** 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]. *)
+
+val sv_is_true : sv -> bool
+(** Return [true] if the [SV] is "true" (in the Perl sense of truth). *)
+val sv_is_undef : sv -> bool
+(** Return [true] if the [SV] is undefined (is [undef]). *)
+val sv_undef : unit -> sv
+(** Returns [undef]. *)
+val sv_true : unit -> sv
+(** Returns an [SV] which is true. *)
+val sv_false : unit -> sv
+(** 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 {!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 {!Perl.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. *)
+ | 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
+ * calling Perl's [ref] function.
+ *)
+val string_of_sv_t : sv_t -> string
+(** Return a printable string for an [sv_t] ([SV] type). *)
-external call_scalar : string -> sv list -> sv
- = "perl4caml_call_scalar"
-(** Call a named Perl function in a scalar context. Returns the Perl [SV]
- * containing the result value. (See {!int_of_sv} etc.).
+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_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_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_argument].
+ *)
+
+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]. *)
+val av_pop : av -> sv
+(** Remove the [SV] at the end of the array and return it. Same as
+ * 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]. *)
+val av_unshift : av -> sv -> unit
+(** Prepend the [SV] to the start of the array. Same as Perl
+ * [unshift \@av, $sv]. *)
+val av_length : av -> int
+(** Return the length of the [AV]. *)
+val av_set : av -> int -> sv -> unit
+(** Replace the i'th element of the [AV] with [SV]. *)
+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 = ()]. *)
+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. 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. *)
+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 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].
+ *)
+val get_av : ?create:bool -> string -> av
+(** 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
+ * {!Perl.int_of_sv} etc.).
*
- * If the Perl code calls [die] then this will throw [PerlFailure].
+ * If the Perl code calls [die] then this will throw [Perl_failure].
*)
-(*
-external call_array : string -> sv list -> sv list
- = "perl4caml_call_array"
-(** Call a named Perl function in an array context. Returns the array as
- * a list of Perl [SV]s.
+val call_array : ?sv:sv -> ?fn:string -> sv list -> sv list
+(** Call a Perl function in an array context, either by name (using the [?fn]
+ * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
*
- * If the Perl code calls [die] then this will throw [PerlFailure].
+ * Returns the list of results.
+ *
+ * If the Perl code calls [die] then this will throw [Perl_failure].
*)
-external call : string -> sv list -> unit
- = "perl4caml_call"
-(** Call a named Perl function in a void context, discarding any results.
+val call_void : ?sv:sv -> ?fn:string -> sv list -> unit
+(** Call a Perl function in a void context, either by name (using the [?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 [PerlFailure].
+ * If the Perl code calls [die] then this will throw [Perl_failure].
*)
-external eval : string -> sv
- = "perl4caml_eval"
+val eval : string -> sv
(** This is exactly like the Perl [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
+(** Like [call_method], but the method is called in an array context. *)
+
+val call_method_void : sv -> string -> sv list -> unit
+(** Like [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
+(** Like [call_class_method], but the method is called in an array context. *)
+
+val call_class_method_void : string -> string -> sv list -> unit
+(** Like [call_class_method], but the method is called in a void context. *)
git.annexia.org / perl4caml.git / blobdiff