*
* Copyright (C) 2003 Merjis Ltd.
*
- * $Id: perl.mli,v 1.1 2003-10-11 18:25:52 rich Exp $
+ * $Id: perl.mli,v 1.2 2003-10-12 10:52:00 rich Exp $
*)
type t
type sv
(** Perl scalar value. *)
-exception PerlFailure of string
+exception Perl_failure of string
(** [die] in Perl code is translated automatically into this exception. *)
external create : ?args:string array -> unit -> t
external sv_of_string : string -> sv = "perl4caml_sv_of_string"
(** Convert a [string] into a Perl [SV]. *)
-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.).
+external get_sv : ?create:bool -> string -> sv = "perl4caml_get_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 Perl code calls [die] then this will throw [PerlFailure].
+ * 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].
*)
-(*
-external call_array : string -> sv list -> sv list
+external call : ?sv:sv -> ?fn:string -> sv list -> sv
+ = "perl4caml_call"
+(** 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.).
+ *
+ * If the Perl code calls [die] then this will throw [Perl_failure].
+ *)
+
+external call_array : ?sv:sv -> ?fn: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.
+(** 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).
+ *
+ * Returns the list of results.
*
- * 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 : string -> sv list -> unit
- = "perl4caml_call"
-(** Call a named Perl function in a void context, discarding any results.
+external call_void : ?sv:sv -> ?fn:string -> sv list -> unit
+ = "perl4caml_call_void"
+(** 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
(** 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]).
*)
-*)