X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=perl.mli;h=64d7904eb633bcc410f796d19e289bca49931bb5;hb=95d760554441dac36fb77011c0c875490f873d68;hp=73270d2445c94f2175e9281e4a6f0500a91ca9ec;hpb=885e4318d7a5540f55c3c78c03222f6d9fb6a70f;p=perl4caml.git diff --git a/perl.mli b/perl.mli index 73270d2..64d7904 100644 --- a/perl.mli +++ b/perl.mli @@ -1,12 +1,23 @@ -(** Interface to Perl from OCaml. - * - * Copyright (C) 2003 Merjis Ltd. - * - * $Id: perl.mli,v 1.8 2003-10-16 13:41:06 rich Exp $ - *) +(** Interface to Perl from OCaml. *) +(* Copyright (C) 2003 Merjis Ltd. + + 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. + + 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. -type t -(** Perl interpreter (abstract type). *) + 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. + + $Id: perl.mli,v 1.16 2008-03-01 13:02:21 rich Exp $ + *) type sv (** Perl scalar value. *) @@ -14,75 +25,12 @@ type sv 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, @@ -90,9 +38,9 @@ val int_of_sv : sv -> int *) val sv_of_int : int -> sv (** Convert an [int] into a Perl [SV]. *) -val float_of_sv : sv -> int +val float_of_sv : sv -> float (** Convert a Perl [SV] into a float. *) -val sv_of_float : int -> sv +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. *) @@ -126,10 +74,10 @@ type sv_t = SVt_NULL | 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_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 @@ -138,23 +86,53 @@ val sv_type : sv -> sv_t 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_arg]. + * [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_arg]. + * [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_arg]. + * [Invalid_argument]. *) -*) val av_empty : unit -> av (** Create an empty [AV] (array). *) @@ -183,23 +161,71 @@ val av_clear : av -> unit 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. *) +(** 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]. + (** 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]