Debian -2 release.
[perl4caml.git] / perl.mli
1 (** Interface to Perl from OCaml.
2   *
3   * Copyright (C) 2003 Merjis Ltd.
4   *
5   * $Id: perl.mli,v 1.10 2003-10-26 11:22:38 rich Exp $
6   *)
7
8 type t
9 (** Perl interpreter (abstract type). *)
10
11 type sv
12 (** Perl scalar value. *)
13
14 type av
15 (** Perl array value. *)
16
17 type hv
18 (** Perl hash value. *)
19
20 exception Perl_failure of string
21 (** [die] in Perl code is translated automatically into this exception. *)
22
23 val current_interpreter : unit -> t
24 (** The [Perl] module has a notion of the "current" interpreter. Throws
25   * [Not_found] if there is no current interpreter.
26   *
27   * When a program starts up, if it has been linked with [perl_init.cmo]
28   * (which is should be), an interpreter is created for you. Normally
29   * this should be all you need to know about interpreters, unless you
30   * want to be really good and call
31   * [Perl.destroy (Perl.current_interpreter ())] at the end of your
32   * program to do proper cleanup.
33   *
34   * You can also, under certain circumstances, create other interpreters,
35   * although this is experiemental and definitely not recommended.
36   *
37   * If Perl was compiled with [-Dusemultiplicity] then you can create
38   * mutliple interpreters at the same time and switch between them by
39   * calling {!Perl.set_context}.
40   *
41   * Otherwise you may destroy the current interpreter and create another
42   * one (provided that at no time you have two "live" interpreters),
43   * by calling {!Perl.destroy} followed by {!Perl.create}.
44 *)
45
46 val destroy : t -> unit
47 (** Destroy the Perl interpreter, performing any necessary cleanup.
48   *
49   * You should call [Perl.destroy (Perl.current_interpreter ())]  at
50   * the end of your program, otherwise Perl won't properly clean up
51   * (running [END] blocks, destroying objects and the like).
52   *
53   * Note that a Perl interpreter is created for you by default when you
54   * use perl4caml.
55   *
56   * The current interpreter can be found by calling
57   * {!Perl.current_interpreter}.
58   *)
59
60 val create : ?args:string array -> unit -> t
61 (** Create a new Perl interpreter. (Note that a Perl interpreter is created
62   * for you by default so you don't need to call this).
63   *
64   * The optional [?args] parameter is the command line passed to the
65   * interpreter, and controls things like whether warnings are enabled
66   * ([-w]) and which file(s) are parsed. The first element in the
67   * array is the executable name (you can just set this to [""]).
68   *
69   * Perl won't allow you to create multiple interpreters at the same time
70   * unless Perl itself was compiled with [-Dusemultiplicity]. However you
71   * can create, then destroy, then create another and so on.
72   *
73   * The newly created interpreter is set as the "current interpreter".
74   *)
75
76 val set_context : t -> unit
77 (** IF Perl was compiled with [-Dusemultiplicity] and IF you are using
78   * multiple interpreters at the same time, then you must call this to
79   * set the implied "current" interpreter.
80   *
81   * Most users will never need to call this function.
82   *)
83
84 val int_of_sv : sv -> int
85 (** Convert a Perl [SV] into an integer. Note that OCaml [int]s aren't
86   * large enough to store the full 32 (or 64) bits from a Perl integer,
87   * so you may get a silent overflow.
88   *)
89 val sv_of_int : int -> sv
90 (** Convert an [int] into a Perl [SV]. *)
91 val float_of_sv : sv -> float
92 (** Convert a Perl [SV] into a float. *)
93 val sv_of_float : float -> sv
94 (** Convert a [float] into a Perl [SV]. *)
95 val string_of_sv : sv -> string
96 (** Convert a Perl [SV] into a string. *)
97 val sv_of_string : string -> sv
98 (** Convert a [string] into a Perl [SV]. *)
99 val bool_of_sv : sv -> bool
100 (** Convert an [SV] into a boolean. *)
101 val sv_of_bool : bool -> sv
102 (** Convert a boolean into an [SV]. *)
103
104 val sv_is_true : sv -> bool
105 (** Return [true] if the [SV] is "true" (in the Perl sense of truth). *)
106 val sv_is_undef : sv -> bool
107 (** Return [true] if the [SV] is undefined (is [undef]). *)
108 val sv_undef : unit -> sv
109 (** Returns [undef]. *)
110 val sv_true : unit -> sv
111 (** Returns an [SV] which is true. *)
112 val sv_false : unit -> sv
113 (** Returns an [SV] which is false. *)
114 val sv_yes : unit -> sv
115 (** Returns Perl's internal [PL_sv_yes]. (There are some unresolved issues
116   * with using this, so use {!Perl.sv_true} instead). *)
117 val sv_no : unit -> sv
118 (** Returns Perl's internal [PL_sv_no]. (There are some unresolved issues
119   * with using this, so use {!Perl.sv_false} instead). *)
120
121 (* Actually there are many more types defined than this ... *)
122 type sv_t    = SVt_NULL
123              | SVt_IV        (** Integer scalar.  *)
124              | SVt_NV        (** Floating point scalar. *)
125              | SVt_PV        (** String scalar. *)
126              | SVt_RV        (** Reference. *)
127              | SVt_PVAV      (** Array ref. *)
128              | SVt_PVHV      (** Hash ref. *)
129              | SVt_PVCV      (** Code ref. *)
130              | SVt_PVGV      (** Glob. *)
131              | SVt_PVMG      (** Blessed or magical scalar. *)
132 val sv_type : sv -> sv_t
133 (** Return the type of data contained in an [SV]. Somewhat equivalent to
134   * calling Perl's [ref] function.
135   *)
136 val string_of_sv_t : sv_t -> string
137 (** Return a printable string for an [sv_t] ([SV] type). *)
138
139 val scalarref : sv -> sv
140 (** Given a scalar, this returns a reference to the scalar. Note that
141   * because references are [SV]s, this returns [sv].
142   *)
143 val arrayref : av -> sv
144 (** Given an array, this returns a reference to the array. Note that
145   * because references are [SV]s, this returns [sv].
146   *)
147 val hashref : hv -> sv
148 (** Given a hash, this returns a reference to the hash. Note that
149   * because references are [SV]s, this returns [sv].
150   *)
151
152 val deref : sv -> sv
153 (** The input is a reference to a scalar. This returns the underlying
154   * scalar [SV]. If the input is not a reference to a scalar, throws
155   * [Invalid_arg].
156   *)
157 val deref_array : sv -> av
158 (** The input is a reference to an array. This returns the underlying
159   * array [AV]. If the input is not a reference to an array, throws
160   * [Invalid_arg].
161   *)
162 val deref_hash : sv -> hv
163 (** The input is a reference to a hash. This returns the underlying
164   * hash [HV]. If the input is not a reference to a hash, throws
165   * [Invalid_arg].
166   *)
167
168 val av_empty : unit -> av
169 (** Create an empty [AV] (array). *)
170 val av_of_sv_list : sv list -> av
171 (** Create an array from a list of [SVs]. *)
172 val av_push : av -> sv -> unit
173 (** Append the [SV] to the end of the array. Same as Perl
174   * [push \@av, $sv]. *)
175 val av_pop : av -> sv
176 (** Remove the [SV] at the end of the array and return it. Same as
177   * Perl [$sv = pop \@av]. *)
178 val av_shift : av -> sv
179 (** Remove the [SV] at the beginning of the array and return it. Same as
180   * Perl [$sv = shift \@av]. *)
181 val av_unshift : av -> sv -> unit
182 (** Prepend the [SV] to the start of the array. Same as Perl
183   * [unshift \@av, $sv]. *)
184 val av_length : av -> int
185 (** Return the length of the [AV]. *)
186 val av_set : av -> int -> sv -> unit
187 (** Replace the i'th element of the [AV] with [SV]. *)
188 val av_get : av -> int -> sv
189 (** Get the i'th element of the [AV]. *)
190 val av_clear : av -> unit
191 (** Remove all elements from the [AV]. Same as Perl [\@av = ()]. *)
192 val av_undef : av -> unit
193 (** Delete the [AV] (and all elements in it). Same as Perl [undef \@av]. *)
194 val av_extend : av -> int -> unit
195 (** Extend the [AV] so it contains at least [n+1] elements. *)
196 val av_map : (sv -> 'a) -> av -> 'a list
197 (** Map a function over the elements in the [AV], return a list of the
198   * results. *)
199 val list_of_av : av -> sv list
200 (** Convert an [AV] into a simple list of [SV]s. *)
201 val av_of_string_list : string list -> av
202 (** Build an [AV] from a list of strings. *)
203
204 val hv_empty : unit -> hv
205 (** Create an empty [HV] (hash). *)
206 val hv_set : hv -> string -> sv -> unit
207 (** Store the given [SV] in the named key in the hash. *)
208 val hv_get : hv -> string -> sv
209 (** Return the [SV] at the key in the hash. Throws [Not_found] if no key. *)
210 val hv_exists : hv -> string -> bool
211 (** Return true if the hash contains the given key. Same as Perl [exists]. *)
212 val hv_delete : hv -> string -> unit
213 (** Delete the given key from the hash. Same as Perl [delete]. *)
214 val hv_clear : hv -> unit
215 (** Remove all elements from the [HV]. Same as Perl [%av = ()]. *)
216 val hv_undef : hv -> unit
217 (** Delete the [HV] (and all elements in it). Same as Perl [undef %hv]. *)
218
219 val get_sv : ?create:bool -> string -> sv
220 (** Return a scalar value by name. For example, if you have a symbol
221   * called [$a] in Perl, then [get_sv "a"] will return its value.
222   *
223   * If the symbol does not exist, this throws [Not_found].
224   *
225   * If the optional [?create] argument is set to true and the symbol does
226   * not exist, then Perl will create the symbol (with value [undef]) and
227   * this function will return the [SV] for [undef].
228   *)
229 val get_av : ?create:bool -> string -> av
230 (** Same as {!Perl.get_sv} except will return and/or create [\@a]. *)
231 val get_hv : ?create:bool -> string -> hv
232 (** Same as {!Perl.get_sv} except will return and/or create [%a]. *)
233
234 val call : ?sv:sv -> ?fn:string -> sv list -> sv
235 (** Call a Perl function in a scalar context, either by name (using the [?fn]
236   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
237   *
238   * Returns the Perl [SV] containing the result value. (See
239   * {!Perl.int_of_sv} etc.).
240   *
241   * If the Perl code calls [die] then this will throw [Perl_failure].
242   *)
243
244 val call_array : ?sv:sv -> ?fn:string -> sv list -> sv list
245 (** Call a Perl function in an array context, either by name (using the [?fn]
246   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
247   *
248   * Returns the list of results.
249   *
250   * If the Perl code calls [die] then this will throw [Perl_failure].
251   *)
252
253 val call_void : ?sv:sv -> ?fn:string -> sv list -> unit
254 (** Call a Perl function in a void context, either by name (using the [?fn]
255   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
256   *
257   * Any results are discarded.
258   *
259   * If the Perl code calls [die] then this will throw [Perl_failure].
260   *)
261
262 val eval : string -> sv
263 (** This is exactly like the Perl [eval] command. It evaluates a piece of
264   * Perl code (in scalar context) and returns the result (a Perl [SV]).
265   *)
266
267 val call_method : sv -> string -> sv list -> sv
268 (** [call_method obj name [parameters]] calls the method [name] on the Perl
269   * object [obj] with the given parameters, in a scalar context. Thus this
270   * is equivalent to [$obj->name (parameters)].
271   *
272   * Returns the Perl [SV] containing the result value.
273   *
274   * If the method calls [die] then this will throw [Perl_failure].
275   *)
276
277 val call_method_array : sv -> string -> sv list -> sv list
278 (** Like [call_method], but the method is called in an array context. *)
279
280 val call_method_void : sv -> string -> sv list -> unit
281 (** Like [call_method], but the method is called in a void context (results
282   * are discarded). *)
283
284 val call_class_method : string -> string -> sv list -> sv
285 (** [call_class_method classname name [parameters]] calls the static method
286   * [name] in the Perl class [classname] with the given parameters, in a
287   * scalar context. Thus this is equivalent to [$classname->name (parameters)].
288   *
289   * Returns the Perl [SV] containing the result value.
290   *
291   * If the static method calls [die] then this will throw [Perl_failure].
292   *)
293
294 val call_class_method_array : string -> string -> sv list -> sv list
295 (** Like [call_class_method], but the method is called in an array context. *)
296
297 val call_class_method_void : string -> string -> sv list -> unit
298 (** Like [call_class_method], but the method is called in a void context. *)