X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=perl.mli;h=778de580a7d0165fc80b1c945e6041f6a0bb4995;hb=9197d217f9a7993ad3fb5e21a1de2fe3820d5d52;hp=7bf89c3540ece27d4813aa53268e2ca705dde0bc;hpb=9e543055271a1ec799d56f507ab048c78d3d7a88;p=perl4caml.git diff --git a/perl.mli b/perl.mli index 7bf89c3..778de58 100644 --- a/perl.mli +++ b/perl.mli @@ -2,103 +2,57 @@ * * Copyright (C) 2003 Merjis Ltd. * - * $Id: perl.mli,v 1.5 2003-10-14 16:05:21 rich Exp $ + * $Id: perl.mli,v 1.12 2004-03-03 12:39:20 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" +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]. *) 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" +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]). *) -external sv_undef : unit -> sv = "perl4caml_sv_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. *) -external sv_yes : unit -> sv = "perl4caml_sv_yes" +val sv_yes : unit -> sv (** 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" + * 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 {!sv_false} instead). *) + * with using this, so use {!Perl.sv_false} instead). *) (* Actually there are many more types defined than this ... *) type sv_t = SVt_NULL @@ -111,63 +65,94 @@ type sv_t = SVt_NULL | SVt_PVCV (** Code ref. *) | SVt_PVGV (** Glob. *) | SVt_PVMG (** Blessed or magical scalar. *) -external sv_type : sv -> sv_t = "perl4caml_sv_type" +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). *) -external deref : sv -> sv = "perl4caml_deref" +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]. *) -external deref_array : sv -> av = "perl4caml_deref_array" +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]. *) -(* -external deref_hash : sv -> hv = "perl4caml_deref_hash" +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]. *) -*) -external av_empty : unit -> av = "perl4caml_av_empty" +val av_empty : unit -> av (** Create an empty [AV] (array). *) -external av_of_sv_list : sv list -> av = "perl4caml_av_of_sv_list" +val av_of_sv_list : sv list -> av (** 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" +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]. *) -external av_shift : av -> sv = "perl4caml_av_shift" + * 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]. *) -external av_unshift : av -> sv -> unit = "perl4caml_av_unshift" + * 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]. *) -external av_length : av -> int = "perl4caml_av_length" + * [unshift \@av, $sv]. *) +val av_length : av -> int (** Return the length of the [AV]. *) -external av_set : av -> int -> sv -> unit = "perl4caml_av_set" +val av_set : av -> int -> sv -> unit (** Replace the i'th element of the [AV] with [SV]. *) -external av_get : av -> int -> sv = "perl4caml_av_get" +val av_get : av -> int -> sv (** 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" +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. *) - -external get_sv : ?create:bool -> string -> sv = "perl4caml_get_sv" +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. * @@ -177,21 +162,22 @@ external get_sv : ?create:bool -> string -> sv = "perl4caml_get_sv" * 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]. *) +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). * @@ -200,8 +186,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). * @@ -210,14 +195,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)]. @@ -227,17 +210,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)]. @@ -247,10 +227,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. *)