Updated deps.

[perl4caml.git] / perl.mli

diff --git a/perl.mli b/perl.mli
index b589323..7473d29 100644 (file)
--- a/perl.mli
+++ b/perl.mli
@@ -2,7 +2,7 @@
   *
   * Copyright (C) 2003 Merjis Ltd.
   *
-  * $Id: perl.mli,v 1.1 2003-10-11 18:25:52 rich Exp $
+  * $Id: perl.mli,v 1.3 2003-10-12 11:56:26 rich Exp $
   *)
 
 type t
@@ -11,7 +11,7 @@ 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
@@ -56,29 +56,56 @@ external string_of_sv : sv -> string = "perl4caml_string_of_sv"
 (** Convert a Perl [SV] into a string. *)
 external sv_of_string : string -> sv = "perl4caml_sv_of_string"
 (** Convert a [string] into a Perl [SV]. *)
+external sv_is_true : sv -> bool = "perl4caml_sv_is_true"
+(** Return [true] if the [SV] is "true" (in the Perl sense of truth). *)
+external sv_is_undef : sv -> bool = "perl4caml_sv_is_undef"
+(** Return [true] if the [SV] is undefined (is [undef]). *)
+val sv_undef : sv
+(** Returns [undef]. *)
+val sv_true : sv
+(** Returns an [SV] which is true. *)
+val sv_false : sv
+(** Returns an [SV] which is false. *)
 
-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 : ?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 : string -> sv list -> sv list
+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).
   *
-  * 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.
+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
@@ -86,4 +113,42 @@ 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]).
   *)
-*)
+
+external call_method : sv -> string -> sv list -> sv
+  = "perl4caml_call_method"
+(** [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].
+  *)
+
+external call_method_array : sv -> string -> sv list -> sv list
+  = "perl4caml_call_method_array"
+(** Like [call_method], but the method is called in an array context. *)
+
+external call_method_void : sv -> string -> sv list -> unit
+  = "perl4caml_call_method_void"
+(** Like [call_method], but the method is called in a void context (results
+  * are discarded). *)
+
+external call_class_method : string -> string -> sv list -> sv
+  = "perl4caml_call_class_method"
+(** [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].
+  *)
+
+external call_class_method_array : string -> string -> sv list -> sv list
+  = "perl4caml_call_class_method_array"
+(** Like [call_class_method], but the method is called in an array context. *)
+
+external call_class_method_void : string -> string -> sv list -> unit
+  = "perl4caml_call_class_method_void"
+(** Like [call_class_method], but the method is called in a void context. *)