(** Interface to Perl from OCaml.
  *
  * Copyright (C) 2003 Merjis Ltd.
  *
  * $Id: perl.mli,v 1.10 2003-10-26 11:22:38 rich Exp $
  *)

type t
(** Perl interpreter (abstract type). *)

type sv
(** Perl scalar value. *)

type av
(** Perl array value. *)

type hv
(** Perl hash value. *)

exception Perl_failure of string
(** [die] in Perl code is translated automatically into this exception. *)

val current_interpreter : unit -> t
(** 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}.
*)

val destroy : t -> unit
(** 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}.
  *)

val create : ?args:string array -> unit -> t
(** 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
  * ([-w]) and which file(s) are parsed. The first element in the
  * array is the executable name (you can just set this to [""]).
  *
  * 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".
  *)

val set_context : t -> unit
(** IF Perl was compiled with [-Dusemultiplicity] and IF you are using
  * multiple interpreters at the same time, then you must call this to
  * set the implied "current" interpreter.
  *
  * Most users will never need to call this function.
  *)

val int_of_sv : sv -> int
(** Convert a Perl [SV] into an integer. Note that OCaml [int]s aren't
  * large enough to store the full 32 (or 64) bits from a Perl integer,
  * so you may get a silent overflow.
  *)
val sv_of_int : int -> sv
(** Convert an [int] into a Perl [SV]. *)
val float_of_sv : sv -> float
(** Convert a Perl [SV] into a float. *)
val sv_of_float : float -> sv
(** Convert a [float] into a Perl [SV]. *)
val string_of_sv : sv -> string
(** Convert a Perl [SV] into a string. *)
val sv_of_string : string -> sv
(** 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]. *)

val sv_is_true : sv -> bool
(** Return [true] if the [SV] is "true" (in the Perl sense of truth). *)
val sv_is_undef : sv -> bool
(** Return [true] if the [SV] is undefined (is [undef]). *)
val sv_undef : unit -> sv
(** Returns [undef]. *)
val sv_true : unit -> sv
(** Returns an [SV] which is true. *)
val sv_false : unit -> sv
(** Returns an [SV] which is false. *)
val sv_yes : unit -> sv
(** Returns Perl's internal [PL_sv_yes]. (There are some unresolved issues
  * with using this, so use {!Perl.sv_true} instead). *)
val sv_no : unit -> sv
(** Returns Perl's internal [PL_sv_no]. (There are some unresolved issues
  * with using this, so use {!Perl.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. *)
val sv_type : sv -> sv_t
(** Return the type of data contained in an [SV]. Somewhat equivalent to
  * calling Perl's [ref] function.
  *)
val string_of_sv_t : sv_t -> string
(** Return a printable string for an [sv_t] ([SV] type). *)

val scalarref : sv -> sv
(** Given a scalar, this returns a reference to the scalar. Note that
  * because references are [SV]s, this returns [sv].
  *)
val arrayref : av -> sv
(** Given an array, this returns a reference to the array. Note that
  * because references are [SV]s, this returns [sv].
  *)
val hashref : hv -> sv
(** Given a hash, this returns a reference to the hash. Note that
  * because references are [SV]s, this returns [sv].
  *)

val deref : sv -> sv
(** 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].
  *)
val deref_array : sv -> av
(** 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].
  *)
val deref_hash : sv -> hv
(** 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].
  *)

val av_empty : unit -> av
(** Create an empty [AV] (array). *)
val av_of_sv_list : sv list -> av
(** Create an array from a list of [SVs]. *)
val av_push : av -> sv -> unit
(** Append the [SV] to the end of the array. Same as Perl
  * [push \@av, $sv]. *)
val av_pop : av -> sv
(** Remove the [SV] at the end of the array and return it. Same as
  * Perl [$sv = pop \@av]. *)
val av_shift : av -> sv
(** Remove the [SV] at the beginning of the array and return it. Same as
  * Perl [$sv = shift \@av]. *)
val av_unshift : av -> sv -> unit
(** Prepend the [SV] to the start of the array. Same as Perl
  * [unshift \@av, $sv]. *)
val av_length : av -> int
(** Return the length of the [AV]. *)
val av_set : av -> int -> sv -> unit
(** Replace the i'th element of the [AV] with [SV]. *)
val av_get : av -> int -> sv
(** Get the i'th element of the [AV]. *)
val av_clear : av -> unit
(** Remove all elements from the [AV]. Same as Perl [\@av = ()]. *)
val av_undef : av -> unit
(** Delete the [AV] (and all elements in it). Same as Perl [undef \@av]. *)
val av_extend : av -> int -> unit
(** Extend the [AV] so it contains at least [n+1] elements. *)
val av_map : (sv -> 'a) -> av -> 'a list
(** Map a function over the elements in the [AV], return a list of the
  * results. *)
val list_of_av : av -> sv list
(** Convert an [AV] into a simple list of [SV]s. *)
val av_of_string_list : string list -> av
(** Build an [AV] from a list of strings. *)

val hv_empty : unit -> hv
(** Create an empty [HV] (hash). *)
val hv_set : hv -> string -> sv -> unit
(** Store the given [SV] in the named key in the hash. *)
val hv_get : hv -> string -> sv
(** Return the [SV] at the key in the hash. Throws [Not_found] if no key. *)
val hv_exists : hv -> string -> bool
(** Return true if the hash contains the given key. Same as Perl [exists]. *)
val hv_delete : hv -> string -> unit
(** Delete the given key from the hash. Same as Perl [delete]. *)
val hv_clear : hv -> unit
(** Remove all elements from the [HV]. Same as Perl [%av = ()]. *)
val hv_undef : hv -> unit
(** Delete the [HV] (and all elements in it). Same as Perl [undef %hv]. *)

val get_sv : ?create:bool -> string -> 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 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].
  *)
val get_av : ?create:bool -> string -> av
(** Same as {!Perl.get_sv} except will return and/or create [\@a]. *)
val get_hv : ?create:bool -> string -> hv
(** Same as {!Perl.get_sv} except will return and/or create [%a]. *)

val call : ?sv:sv -> ?fn:string -> sv list -> sv
(** 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
  * {!Perl.int_of_sv} etc.).
  *
  * If the Perl code calls [die] then this will throw [Perl_failure].
  *)

val call_array : ?sv:sv -> ?fn:string -> sv list -> sv list
(** 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 [Perl_failure].
  *)

val call_void : ?sv:sv -> ?fn:string -> sv list -> unit
(** 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 [Perl_failure].
  *)

val 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]).
  *)

val call_method : sv -> string -> sv list -> sv
(** [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].
  *)

val call_method_array : sv -> string -> sv list -> sv list
(** Like [call_method], but the method is called in an array context. *)

val call_method_void : sv -> string -> sv list -> unit
(** Like [call_method], but the method is called in a void context (results
  * are discarded). *)

val call_class_method : string -> string -> sv list -> sv
(** [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].
  *)

val call_class_method_array : string -> string -> sv list -> sv list
(** Like [call_class_method], but the method is called in an array context. *)

val call_class_method_void : string -> string -> sv list -> unit
(** Like [call_class_method], but the method is called in a void context. *)