X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=perl.mli;fp=perl.mli;h=2c60907e6318afc580b66bd32a0874889c8a26b5;hb=1c369c3ba6b71d4524dfacd0ba3554e8a524ed57;hp=7473d29445c3c6bb926450ee907d5367ca4645de;hpb=ca5c0933addc2b872316df28789f7de81281c3fe;p=perl4caml.git

diff --git a/perl.mli b/perl.mli
index 7473d29..2c60907 100644
--- a/perl.mli
+++ b/perl.mli
@@ -2,7 +2,7 @@
   *
   * Copyright (C) 2003 Merjis Ltd.
   *
-  * $Id: perl.mli,v 1.3 2003-10-12 11:56:26 rich Exp $
+  * $Id: perl.mli,v 1.4 2003-10-12 17:33:14 rich Exp $
   *)
 
 type t
@@ -14,9 +14,25 @@ type sv
 exception Perl_failure of string
 (** [die] in Perl code is translated automatically into this exception. *)
 
+val init : unit -> unit
+(** Don't call this. Instead link your program with [perl_init.cmo] or
+  * [perl_init.cmx] which calls this for you.
+  *)
+
+external destroy : unit -> unit
+  = "perl4caml_destroy"
+(** Destroy the current Perl interpreter, performing any necessary cleanup.
+  * You should call this at the end of your program, otherwise Perl won't
+  * properly clean up.
+  *
+  * Note that a Perl interpreter is created for you by default when you
+  * use perl4caml.
+  *)
+
 external create : ?args:string array -> unit -> t
   = "perl4caml_create"
-(** Create a Perl interpreter.
+(** 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
@@ -26,12 +42,10 @@ external create : ?args:string array -> unit -> t
   * 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".
   *)
 
-external destroy : t -> unit
-  = "perl4caml_destroy"
-(** Destroy a Perl interpreter, performing any necessary cleanup. *)
-
 external set_context : t -> unit
   = "perl4caml_set_context"
 (** IF Perl was compiled with [-Dusemultiplicity] and IF you are using
@@ -56,16 +70,61 @@ 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]. *)
+val bool_of_sv : sv -> bool
+(** Convert an [SV] into a boolean. *)
+val sv_of_bool : bool -> sv
+(** Convert a boolean into an [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
+external sv_undef : unit -> sv = "perl4caml_sv_undef"
 (** Returns [undef]. *)
-val sv_true : sv
+val sv_true : unit -> sv
 (** Returns an [SV] which is true. *)
-val sv_false : sv
+val sv_false : unit -> sv
 (** Returns an [SV] which is false. *)
+external sv_yes : unit -> sv = "perl4caml_sv_yes"
+(** Returns Perl's internal [PL_sv_yes]. (There are some unresolved issues
+  * with using this, so use {!sv_true} instead). *)
+external sv_no : unit -> sv = "perl4caml_sv_no"
+(** Returns Perl's internal [PL_sv_no]. (There are some unresolved issues
+  * with using this, so use {!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 ref. *)
+	     | SVt_PVHV	     (** Hash ref. *)
+	     | SVt_PVCV      (** Code ref. *)
+	     | SVt_PVGV	     (** Glob. *)
+	     | SVt_PVMG	     (** Blessed or magical scalar. *)
+external sv_type : sv -> sv_t = "perl4caml_sv_type"
+(** Return the type of data contained in an [SV]. Somewhat equivalent to
+  * calling Perl's [ref] function.
+  *)
+
+external deref : sv -> sv = "perl4caml_deref"
+(** 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].
+  *)
+(*
+external deref_array : sv -> av = "perl4caml_deref_array"
+(** 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].
+  *)
+external deref_hash : sv -> hv = "perl4caml_deref_hash"
+(** 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].
+  *)
+*)
 
 external get_sv : ?create:bool -> string -> sv = "perl4caml_get_sv"
 (** Return a scalar value by name. For example, if you have a symbol