Wrappers now automatically 'use' modules.

[perl4caml.git] / perl.mli

diff --git a/perl.mli b/perl.mli
index 7bf89c3..6be7f38 100644 (file)
--- a/perl.mli
+++ b/perl.mli
@@ -2,7 +2,7 @@
   *
   * Copyright (C) 2003 Merjis Ltd.
   *
-  * $Id: perl.mli,v 1.5 2003-10-14 16:05:21 rich Exp $
+  * $Id: perl.mli,v 1.6 2003-10-15 16:51:12 rich Exp $
   *)
 
 type t
@@ -22,19 +22,43 @@ type hv
 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 current_interpreter : unit -> t
+  = "perl4caml_current_interpreter"
+(** 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}.
+*)
 
-external destroy : unit -> unit
+external destroy : t -> 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.
+(** 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}.
   *)
 
 external create : ?args:string array -> unit -> t