X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=perl.mli;h=64d7904eb633bcc410f796d19e289bca49931bb5;hb=36b9a44ab49471646b7a3548d1e2d28c015063ad;hp=7473d29445c3c6bb926450ee907d5367ca4645de;hpb=dafc0bde0b51d76c41b2d646af3699730e31dfbb;p=perl4caml.git diff --git a/perl.mli b/perl.mli index 7473d29..64d7904 100644 --- a/perl.mli +++ b/perl.mli @@ -1,95 +1,243 @@ -(** Interface to Perl from OCaml. - * - * Copyright (C) 2003 Merjis Ltd. - * - * $Id: perl.mli,v 1.3 2003-10-12 11:56:26 rich Exp $ - *) +(** Interface to Perl from OCaml. *) +(* Copyright (C) 2003 Merjis Ltd. -type t -(** Perl interpreter (abstract type). *) + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. -type sv -(** Perl scalar value. *) + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. -exception Perl_failure of string -(** [die] in Perl code is translated automatically into this exception. *) + You should have received a copy of the GNU General Public License + along with this library; see the file COPYING. If not, write to + the Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. -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. + $Id: perl.mli,v 1.16 2008-03-01 13:02:21 rich Exp $ *) -external destroy : t -> unit - = "perl4caml_destroy" -(** Destroy a Perl interpreter, performing any necessary cleanup. *) +type sv +(** Perl scalar value. *) + +type av +(** Perl array value. *) -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. - *) +type hv +(** Perl hash value. *) + +exception Perl_failure of string +(** [die] in Perl code is translated automatically into this exception. *) -external int_of_sv : sv -> int = "perl4caml_int_of_sv" +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. *) -external sv_of_int : int -> sv = "perl4caml_sv_of_int" +val sv_of_int : int -> sv (** Convert an [int] into a Perl [SV]. *) -external float_of_sv : sv -> int = "perl4caml_float_of_sv" +val float_of_sv : sv -> float (** Convert a Perl [SV] into a float. *) -external sv_of_float : int -> sv = "perl4caml_sv_of_float" +val sv_of_float : float -> sv (** Convert a [float] into a Perl [SV]. *) -external string_of_sv : sv -> string = "perl4caml_string_of_sv" +val string_of_sv : sv -> string (** Convert a Perl [SV] into a string. *) -external sv_of_string : string -> sv = "perl4caml_sv_of_string" +val sv_of_string : string -> sv (** Convert a [string] into a Perl [SV]. *) -external sv_is_true : sv -> bool = "perl4caml_sv_is_true" +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). *) -external sv_is_undef : sv -> bool = "perl4caml_sv_is_undef" +val sv_is_undef : sv -> bool (** Return [true] if the [SV] is undefined (is [undef]). *) -val sv_undef : sv +val sv_undef : unit -> sv (** Returns [undef]. *) -val sv_true : sv +val sv_true : unit -> sv (** Returns an [SV] which is true. *) -val sv_false : sv +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). *) -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]. +(* 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. *) + | SVt_PVHV (** Hash. *) + | SVt_PVCV (** Code. *) + | SVt_PVGV (** Glob (possibly a file handle). *) + | 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 reftype : sv -> sv_t +(** The parameter [sv] must be a reference. This convenience function + * works out what it is a reference to, either a scalar, array, hash, + * code or glob. If the parameter is not a reference, or is a reference + * to an unknown type, then this will throw [Invalid_argument]. *) + +val address_of_sv : sv -> Nativeint.t +(** Returns the address of the SV. Useful for debugging since + * Perl also prints out addresses on internal errors. + *) +val address_of_av : av -> Nativeint.t +(** Returns the address of the AV. Useful for debugging since + * Perl also prints out addresses on internal errors. + *) +val address_of_hv : hv -> Nativeint.t +(** Returns the address of the HV. Useful for debugging since + * Perl also prints out addresses on internal errors. + *) + +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_argument]. + *) +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_argument]. + *) +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_argument]. + *) + +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. Note that + * this apparently just changes the amount of allocated storage. The + * extra elements are not visible until you store something in them. + *) +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 hv_of_assoc : (string * sv) list -> hv +(** Create an [HV] directly from an assoc list. Perl hashes cannot + * support multiple values attached to the same key, so if you try + * to provide an assoc list with multiple identical keys, the results + * will be undefined. + *) +val assoc_of_hv : hv -> (string * sv) list +(** Take an [HV] and return an assoc list. *) +val hv_keys : hv -> string list +(** Return all the keys of an [HV]. *) +val hv_values : hv -> sv list +(** Return all the values of an [HV]. *) + +(* The following are the low-level iteration interface to hashes, + * which you probably shouldn't use directly. Use {!hv_keys}, + * {!assoc_of_hv}, etc. instead. See [perlguts(3)] if you really + * want to use this interface. + *) +type he +val hv_iterinit : hv -> Int32.t +val hv_iternext : hv -> he +val hv_iterkey : he -> string +val hv_iterval : hv -> he -> sv +val hv_iternextsv : hv -> string * sv + +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]. *) -external call : ?sv:sv -> ?fn:string -> sv list -> sv - = "perl4caml_call" +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 {!int_of_sv} etc.). + * 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]. *) -external call_array : ?sv:sv -> ?fn:string -> sv list -> sv list - = "perl4caml_call_array" +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). * @@ -98,8 +246,7 @@ external call_array : ?sv:sv -> ?fn:string -> sv list -> sv list * 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" +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). * @@ -108,14 +255,12 @@ external call_void : ?sv:sv -> ?fn:string -> sv list -> unit * If the Perl code calls [die] then this will throw [Perl_failure]. *) -external eval : string -> sv - = "perl4caml_eval" +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]). *) -external call_method : sv -> string -> sv list -> sv - = "perl4caml_call_method" +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)]. @@ -125,17 +270,14 @@ external call_method : sv -> string -> sv list -> sv * 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" +val call_method_array : sv -> string -> sv list -> sv list (** 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" +val call_method_void : sv -> string -> sv list -> unit (** 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" +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)]. @@ -145,10 +287,8 @@ external call_class_method : string -> string -> sv list -> sv * 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" +val call_class_method_array : string -> string -> sv list -> sv list (** 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" +val call_class_method_void : string -> string -> sv list -> unit (** Like [call_class_method], but the method is called in a void context. *)