*
* 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
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