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

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

type sv
(** Perl scalar value. *)

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

external create : ?args:string array -> unit -> t
  = "perl4caml_create"
(** Create a Perl interpreter.
  *
  * 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.
  *)

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

external int_of_sv : sv -> int = "perl4caml_int_of_sv"
(** 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.
  *)
external sv_of_int : int -> sv = "perl4caml_sv_of_int"
(** Convert an [int] into a Perl [SV]. *)
external float_of_sv : sv -> int = "perl4caml_float_of_sv"
(** Convert a Perl [SV] into a float. *)
external sv_of_float : int -> sv = "perl4caml_sv_of_float"
(** Convert a [float] into a Perl [SV]. *)
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 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 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 : ?sv:sv -> ?fn:string -> sv list -> sv list
  = "perl4caml_call_array"
(** 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].
  *)

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

external eval : string -> sv
  = "perl4caml_eval"
(** 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. *)