(** Interface to Perl from OCaml. * * Copyright (C) 2003 Merjis Ltd. * * $Id: perl.mli,v 1.5 2003-10-14 16:05:21 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 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 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". *) 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]. *) 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]). *) external sv_undef : unit -> sv = "perl4caml_sv_undef" (** Returns [undef]. *) val sv_true : unit -> sv (** Returns an [SV] which is true. *) 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. *) val string_of_sv_t : sv_t -> string (** Return a printable string for an [sv_t] ([SV] type). *) 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 av_empty : unit -> av = "perl4caml_av_empty" (** Create an empty [AV] (array). *) external av_of_sv_list : sv list -> av = "perl4caml_av_of_sv_list" (** Create an array from a list of [SVs]. *) external av_push : av -> sv -> unit = "perl4caml_av_push" (** Append the [SV] to the end of the array. Same as Perl [push @av, $sv]. *) external av_pop : av -> sv = "perl4caml_av_pop" (** Remove the [SV] at the end of the array and return it. Same as * Perl [$sv = pop @av]. *) external av_shift : av -> sv = "perl4caml_av_shift" (** Remove the [SV] at the beginning of the array and return it. Same as * Perl [$sv = shift @av]. *) external av_unshift : av -> sv -> unit = "perl4caml_av_unshift" (** Prepend the [SV] to the start of the array. Same as Perl * [unshift @av, $sv]. *) external av_length : av -> int = "perl4caml_av_length" (** Return the length of the [AV]. *) external av_set : av -> int -> sv -> unit = "perl4caml_av_set" (** Replace the i'th element of the [AV] with [SV]. *) external av_get : av -> int -> sv = "perl4caml_av_get" (** Get the i'th element of the [AV]. *) external av_clear : av -> unit = "perl4caml_av_clear" (** Remove all elements from the [AV]. Same as Perl [@av = ()]. *) external av_undef : av -> unit = "perl4caml_av_undef" (** Delete the [AV] (and all elements in it). Same as Perl [undef @av]. *) external av_extend : av -> int -> unit = "perl4caml_av_extend" (** 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. *) 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 get_av : ?create:bool -> string -> av = "perl4caml_get_av" (** Same as {!get_sv} except will return and/or create [@a]. *) 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. *)