1 (** Interface to Perl from OCaml.
3 * Copyright (C) 2003 Merjis Ltd.
5 * $Id: perl.mli,v 1.13 2005-01-28 23:09:32 rich Exp $
9 (** Perl scalar value. *)
12 (** Perl array value. *)
15 (** Perl hash value. *)
17 exception Perl_failure of string
18 (** [die] in Perl code is translated automatically into this exception. *)
20 val int_of_sv : sv -> int
21 (** Convert a Perl [SV] into an integer. Note that OCaml [int]s aren't
22 * large enough to store the full 32 (or 64) bits from a Perl integer,
23 * so you may get a silent overflow.
25 val sv_of_int : int -> sv
26 (** Convert an [int] into a Perl [SV]. *)
27 val float_of_sv : sv -> float
28 (** Convert a Perl [SV] into a float. *)
29 val sv_of_float : float -> sv
30 (** Convert a [float] into a Perl [SV]. *)
31 val string_of_sv : sv -> string
32 (** Convert a Perl [SV] into a string. *)
33 val sv_of_string : string -> sv
34 (** Convert a [string] into a Perl [SV]. *)
35 val bool_of_sv : sv -> bool
36 (** Convert an [SV] into a boolean. *)
37 val sv_of_bool : bool -> sv
38 (** Convert a boolean into an [SV]. *)
40 val sv_is_true : sv -> bool
41 (** Return [true] if the [SV] is "true" (in the Perl sense of truth). *)
42 val sv_is_undef : sv -> bool
43 (** Return [true] if the [SV] is undefined (is [undef]). *)
44 val sv_undef : unit -> sv
45 (** Returns [undef]. *)
46 val sv_true : unit -> sv
47 (** Returns an [SV] which is true. *)
48 val sv_false : unit -> sv
49 (** Returns an [SV] which is false. *)
50 val sv_yes : unit -> sv
51 (** Returns Perl's internal [PL_sv_yes]. (There are some unresolved issues
52 * with using this, so use {!Perl.sv_true} instead). *)
53 val sv_no : unit -> sv
54 (** Returns Perl's internal [PL_sv_no]. (There are some unresolved issues
55 * with using this, so use {!Perl.sv_false} instead). *)
57 (* Actually there are many more types defined than this ... *)
59 | SVt_IV (** Integer scalar. *)
60 | SVt_NV (** Floating point scalar. *)
61 | SVt_PV (** String scalar. *)
62 | SVt_RV (** Reference. *)
63 | SVt_PVAV (** Array. *)
64 | SVt_PVHV (** Hash. *)
65 | SVt_PVCV (** Code. *)
66 | SVt_PVGV (** Glob (possibly a file handle). *)
67 | SVt_PVMG (** Blessed or magical scalar. *)
68 val sv_type : sv -> sv_t
69 (** Return the type of data contained in an [SV]. Somewhat equivalent to
70 * calling Perl's [ref] function.
72 val string_of_sv_t : sv_t -> string
73 (** Return a printable string for an [sv_t] ([SV] type). *)
75 val address_of_sv : sv -> Nativeint.t
76 (** Returns the address of the SV. Useful for debugging since
77 * Perl also prints out addresses on internal errors.
79 val address_of_av : av -> Nativeint.t
80 (** Returns the address of the AV. Useful for debugging since
81 * Perl also prints out addresses on internal errors.
83 val address_of_hv : hv -> Nativeint.t
84 (** Returns the address of the HV. Useful for debugging since
85 * Perl also prints out addresses on internal errors.
88 val scalarref : sv -> sv
89 (** Given a scalar, this returns a reference to the scalar. Note that
90 * because references are [SV]s, this returns [sv].
92 val arrayref : av -> sv
93 (** Given an array, this returns a reference to the array. Note that
94 * because references are [SV]s, this returns [sv].
96 val hashref : hv -> sv
97 (** Given a hash, this returns a reference to the hash. Note that
98 * because references are [SV]s, this returns [sv].
102 (** The input is a reference to a scalar. This returns the underlying
103 * scalar [SV]. If the input is not a reference to a scalar, throws
104 * [Invalid_argument].
106 val deref_array : sv -> av
107 (** The input is a reference to an array. This returns the underlying
108 * array [AV]. If the input is not a reference to an array, throws
109 * [Invalid_argument].
111 val deref_hash : sv -> hv
112 (** The input is a reference to a hash. This returns the underlying
113 * hash [HV]. If the input is not a reference to a hash, throws
114 * [Invalid_argument].
117 val av_empty : unit -> av
118 (** Create an empty [AV] (array). *)
119 val av_of_sv_list : sv list -> av
120 (** Create an array from a list of [SVs]. *)
121 val av_push : av -> sv -> unit
122 (** Append the [SV] to the end of the array. Same as Perl
123 * [push \@av, $sv]. *)
124 val av_pop : av -> sv
125 (** Remove the [SV] at the end of the array and return it. Same as
126 * Perl [$sv = pop \@av]. *)
127 val av_shift : av -> sv
128 (** Remove the [SV] at the beginning of the array and return it. Same as
129 * Perl [$sv = shift \@av]. *)
130 val av_unshift : av -> sv -> unit
131 (** Prepend the [SV] to the start of the array. Same as Perl
132 * [unshift \@av, $sv]. *)
133 val av_length : av -> int
134 (** Return the length of the [AV]. *)
135 val av_set : av -> int -> sv -> unit
136 (** Replace the i'th element of the [AV] with [SV]. *)
137 val av_get : av -> int -> sv
138 (** Get the i'th element of the [AV]. *)
139 val av_clear : av -> unit
140 (** Remove all elements from the [AV]. Same as Perl [\@av = ()]. *)
141 val av_undef : av -> unit
142 (** Delete the [AV] (and all elements in it). Same as Perl [undef \@av]. *)
143 val av_extend : av -> int -> unit
144 (** Extend the [AV] so it contains at least [n+1] elements. Note that
145 * this apparently just changes the amount of allocated storage. The
146 * extra elements are not visible until you store something in them.
148 val av_map : (sv -> 'a) -> av -> 'a list
149 (** Map a function over the elements in the [AV], return a list of the
151 val list_of_av : av -> sv list
152 (** Convert an [AV] into a simple list of [SV]s. *)
153 val av_of_string_list : string list -> av
154 (** Build an [AV] from a list of strings. *)
156 val hv_empty : unit -> hv
157 (** Create an empty [HV] (hash). *)
158 val hv_set : hv -> string -> sv -> unit
159 (** Store the given [SV] in the named key in the hash. *)
160 val hv_get : hv -> string -> sv
161 (** Return the [SV] at the key in the hash. Throws [Not_found] if no key. *)
162 val hv_exists : hv -> string -> bool
163 (** Return true if the hash contains the given key. Same as Perl [exists]. *)
164 val hv_delete : hv -> string -> unit
165 (** Delete the given key from the hash. Same as Perl [delete]. *)
166 val hv_clear : hv -> unit
167 (** Remove all elements from the [HV]. Same as Perl [%av = ()]. *)
168 val hv_undef : hv -> unit
169 (** Delete the [HV] (and all elements in it). Same as Perl [undef %hv]. *)
171 val get_sv : ?create:bool -> string -> sv
172 (** Return a scalar value by name. For example, if you have a symbol
173 * called [$a] in Perl, then [get_sv "a"] will return its value.
175 * If the symbol does not exist, this throws [Not_found].
177 * If the optional [?create] argument is set to true and the symbol does
178 * not exist, then Perl will create the symbol (with value [undef]) and
179 * this function will return the [SV] for [undef].
181 val get_av : ?create:bool -> string -> av
182 (** Same as {!Perl.get_sv} except will return and/or create [\@a]. *)
183 val get_hv : ?create:bool -> string -> hv
184 (** Same as {!Perl.get_sv} except will return and/or create [%a]. *)
186 val call : ?sv:sv -> ?fn:string -> sv list -> sv
187 (** Call a Perl function in a scalar context, either by name (using the [?fn]
188 * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
190 * Returns the Perl [SV] containing the result value. (See
191 * {!Perl.int_of_sv} etc.).
193 * If the Perl code calls [die] then this will throw [Perl_failure].
196 val call_array : ?sv:sv -> ?fn:string -> sv list -> sv list
197 (** Call a Perl function in an array context, either by name (using the [?fn]
198 * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
200 * Returns the list of results.
202 * If the Perl code calls [die] then this will throw [Perl_failure].
205 val call_void : ?sv:sv -> ?fn:string -> sv list -> unit
206 (** Call a Perl function in a void context, either by name (using the [?fn]
207 * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
209 * Any results are discarded.
211 * If the Perl code calls [die] then this will throw [Perl_failure].
214 val eval : string -> sv
215 (** This is exactly like the Perl [eval] command. It evaluates a piece of
216 * Perl code (in scalar context) and returns the result (a Perl [SV]).
219 val call_method : sv -> string -> sv list -> sv
220 (** [call_method obj name [parameters]] calls the method [name] on the Perl
221 * object [obj] with the given parameters, in a scalar context. Thus this
222 * is equivalent to [$obj->name (parameters)].
224 * Returns the Perl [SV] containing the result value.
226 * If the method calls [die] then this will throw [Perl_failure].
229 val call_method_array : sv -> string -> sv list -> sv list
230 (** Like [call_method], but the method is called in an array context. *)
232 val call_method_void : sv -> string -> sv list -> unit
233 (** Like [call_method], but the method is called in a void context (results
236 val call_class_method : string -> string -> sv list -> sv
237 (** [call_class_method classname name [parameters]] calls the static method
238 * [name] in the Perl class [classname] with the given parameters, in a
239 * scalar context. Thus this is equivalent to [$classname->name (parameters)].
241 * Returns the Perl [SV] containing the result value.
243 * If the static method calls [die] then this will throw [Perl_failure].
246 val call_class_method_array : string -> string -> sv list -> sv list
247 (** Like [call_class_method], but the method is called in an array context. *)
249 val call_class_method_void : string -> string -> sv list -> unit
250 (** Like [call_class_method], but the method is called in a void context. *)