1 (** Interface to Perl from OCaml.
3 * Copyright (C) 2003 Merjis Ltd.
5 * $Id: perl.mli,v 1.6 2003-10-15 16:51:12 rich Exp $
9 (** Perl interpreter (abstract type). *)
12 (** Perl scalar value. *)
15 (** Perl array value. *)
19 (** Perl hash value. *)
22 exception Perl_failure of string
23 (** [die] in Perl code is translated automatically into this exception. *)
25 external current_interpreter : unit -> t
26 = "perl4caml_current_interpreter"
27 (** The [Perl] module has a notion of the "current" interpreter. Throws
28 * [Not_found] if there is no current interpreter.
30 * When a program starts up, if it has been linked with [perl_init.cmo]
31 * (which is should be), an interpreter is created for you. Normally
32 * this should be all you need to know about interpreters, unless you
33 * want to be really good and call
34 * [Perl.destroy (Perl.current_interpreter ())] at the end of your
35 * program to do proper cleanup.
37 * You can also, under certain circumstances, create other interpreters,
38 * although this is experiemental and definitely not recommended.
40 * If Perl was compiled with [-Dusemultiplicity] then you can create
41 * mutliple interpreters at the same time and switch between them by
42 * calling {!Perl.set_context}.
44 * Otherwise you may destroy the current interpreter and create another
45 * one (provided that at no time you have two "live" interpreters),
46 * by calling {!Perl.destroy} followed by {!Perl.create}.
49 external destroy : t -> unit
51 (** Destroy the Perl interpreter, performing any necessary cleanup.
53 * You should call [Perl.destroy (Perl.current_interpreter ())] at
54 * the end of your program, otherwise Perl won't properly clean up
55 * (running [END] blocks, destroying objects and the like).
57 * Note that a Perl interpreter is created for you by default when you
60 * The current interpreter can be found by calling
61 * {!Perl.current_interpreter}.
64 external create : ?args:string array -> unit -> t
66 (** Create a new Perl interpreter. (Note that a Perl interpreter is created
67 * for you by default so you don't need to call this).
69 * The optional [?args] parameter is the command line passed to the
70 * interpreter, and controls things like whether warnings are enabled
71 * ([-w]) and which file(s) are parsed. The first element in the
72 * array is the executable name (you can just set this to [""]).
74 * Perl won't allow you to create multiple interpreters at the same time
75 * unless Perl itself was compiled with [-Dusemultiplicity]. However you
76 * can create, then destroy, then create another and so on.
78 * The newly created interpreter is set as the "current interpreter".
81 external set_context : t -> unit
82 = "perl4caml_set_context"
83 (** IF Perl was compiled with [-Dusemultiplicity] and IF you are using
84 * multiple interpreters at the same time, then you must call this to
85 * set the implied "current" interpreter.
87 * Most users will never need to call this function.
90 external int_of_sv : sv -> int = "perl4caml_int_of_sv"
91 (** Convert a Perl [SV] into an integer. Note that OCaml [int]s aren't
92 * large enough to store the full 32 (or 64) bits from a Perl integer,
93 * so you may get a silent overflow.
95 external sv_of_int : int -> sv = "perl4caml_sv_of_int"
96 (** Convert an [int] into a Perl [SV]. *)
97 external float_of_sv : sv -> int = "perl4caml_float_of_sv"
98 (** Convert a Perl [SV] into a float. *)
99 external sv_of_float : int -> sv = "perl4caml_sv_of_float"
100 (** Convert a [float] into a Perl [SV]. *)
101 external string_of_sv : sv -> string = "perl4caml_string_of_sv"
102 (** Convert a Perl [SV] into a string. *)
103 external sv_of_string : string -> sv = "perl4caml_sv_of_string"
104 (** Convert a [string] into a Perl [SV]. *)
105 val bool_of_sv : sv -> bool
106 (** Convert an [SV] into a boolean. *)
107 val sv_of_bool : bool -> sv
108 (** Convert a boolean into an [SV]. *)
110 external sv_is_true : sv -> bool = "perl4caml_sv_is_true"
111 (** Return [true] if the [SV] is "true" (in the Perl sense of truth). *)
112 external sv_is_undef : sv -> bool = "perl4caml_sv_is_undef"
113 (** Return [true] if the [SV] is undefined (is [undef]). *)
114 external sv_undef : unit -> sv = "perl4caml_sv_undef"
115 (** Returns [undef]. *)
116 val sv_true : unit -> sv
117 (** Returns an [SV] which is true. *)
118 val sv_false : unit -> sv
119 (** Returns an [SV] which is false. *)
120 external sv_yes : unit -> sv = "perl4caml_sv_yes"
121 (** Returns Perl's internal [PL_sv_yes]. (There are some unresolved issues
122 * with using this, so use {!sv_true} instead). *)
123 external sv_no : unit -> sv = "perl4caml_sv_no"
124 (** Returns Perl's internal [PL_sv_no]. (There are some unresolved issues
125 * with using this, so use {!sv_false} instead). *)
127 (* Actually there are many more types defined than this ... *)
129 | SVt_IV (** Integer scalar. *)
130 | SVt_NV (** Floating point scalar. *)
131 | SVt_PV (** String scalar. *)
132 | SVt_RV (** Reference. *)
133 | SVt_PVAV (** Array ref. *)
134 | SVt_PVHV (** Hash ref. *)
135 | SVt_PVCV (** Code ref. *)
136 | SVt_PVGV (** Glob. *)
137 | SVt_PVMG (** Blessed or magical scalar. *)
138 external sv_type : sv -> sv_t = "perl4caml_sv_type"
139 (** Return the type of data contained in an [SV]. Somewhat equivalent to
140 * calling Perl's [ref] function.
142 val string_of_sv_t : sv_t -> string
143 (** Return a printable string for an [sv_t] ([SV] type). *)
145 external deref : sv -> sv = "perl4caml_deref"
146 (** The input is a reference to a scalar. This returns the underlying
147 * scalar [SV]. If the input is not a reference to a scalar, throws
150 external deref_array : sv -> av = "perl4caml_deref_array"
151 (** The input is a reference to an array. This returns the underlying
152 * array [AV]. If the input is not a reference to an array, throws
156 external deref_hash : sv -> hv = "perl4caml_deref_hash"
157 (** The input is a reference to a hash. This returns the underlying
158 * hash [HV]. If the input is not a reference to a hash, throws
163 external av_empty : unit -> av = "perl4caml_av_empty"
164 (** Create an empty [AV] (array). *)
165 external av_of_sv_list : sv list -> av = "perl4caml_av_of_sv_list"
166 (** Create an array from a list of [SVs]. *)
167 external av_push : av -> sv -> unit = "perl4caml_av_push"
168 (** Append the [SV] to the end of the array. Same as Perl [push @av, $sv]. *)
169 external av_pop : av -> sv = "perl4caml_av_pop"
170 (** Remove the [SV] at the end of the array and return it. Same as
171 * Perl [$sv = pop @av]. *)
172 external av_shift : av -> sv = "perl4caml_av_shift"
173 (** Remove the [SV] at the beginning of the array and return it. Same as
174 * Perl [$sv = shift @av]. *)
175 external av_unshift : av -> sv -> unit = "perl4caml_av_unshift"
176 (** Prepend the [SV] to the start of the array. Same as Perl
177 * [unshift @av, $sv]. *)
178 external av_length : av -> int = "perl4caml_av_length"
179 (** Return the length of the [AV]. *)
180 external av_set : av -> int -> sv -> unit = "perl4caml_av_set"
181 (** Replace the i'th element of the [AV] with [SV]. *)
182 external av_get : av -> int -> sv = "perl4caml_av_get"
183 (** Get the i'th element of the [AV]. *)
184 external av_clear : av -> unit = "perl4caml_av_clear"
185 (** Remove all elements from the [AV]. Same as Perl [@av = ()]. *)
186 external av_undef : av -> unit = "perl4caml_av_undef"
187 (** Delete the [AV] (and all elements in it). Same as Perl [undef @av]. *)
188 external av_extend : av -> int -> unit = "perl4caml_av_extend"
189 (** Extend the [AV] so it contains at least [n+1] elements. *)
190 val av_map : (sv -> 'a) -> av -> 'a list
191 (** Map a function over the elements in the [AV], return a list of the
194 external get_sv : ?create:bool -> string -> sv = "perl4caml_get_sv"
195 (** Return a scalar value by name. For example, if you have a symbol
196 * called [$a] in Perl, then [get_sv "a"] will return its value.
198 * If the symbol does not exist, this throws [Not_found].
200 * If the optional [?create] argument is set to true and the symbol does
201 * not exist, then Perl will create the symbol (with value [undef]) and
202 * this function will return the [SV] for [undef].
204 external get_av : ?create:bool -> string -> av = "perl4caml_get_av"
205 (** Same as {!get_sv} except will return and/or create [@a]. *)
207 external call : ?sv:sv -> ?fn:string -> sv list -> sv
209 (** Call a Perl function in a scalar context, either by name (using the [?fn]
210 * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
212 * Returns the Perl [SV] containing the result value. (See {!int_of_sv} etc.).
214 * If the Perl code calls [die] then this will throw [Perl_failure].
217 external call_array : ?sv:sv -> ?fn:string -> sv list -> sv list
218 = "perl4caml_call_array"
219 (** Call a Perl function in an array context, either by name (using the [?fn]
220 * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
222 * Returns the list of results.
224 * If the Perl code calls [die] then this will throw [Perl_failure].
227 external call_void : ?sv:sv -> ?fn:string -> sv list -> unit
228 = "perl4caml_call_void"
229 (** Call a Perl function in a void context, either by name (using the [?fn]
230 * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
232 * Any results are discarded.
234 * If the Perl code calls [die] then this will throw [Perl_failure].
237 external eval : string -> sv
239 (** This is exactly like the Perl [eval] command. It evaluates a piece of
240 * Perl code (in scalar context) and returns the result (a Perl [SV]).
243 external call_method : sv -> string -> sv list -> sv
244 = "perl4caml_call_method"
245 (** [call_method obj name [parameters]] calls the method [name] on the Perl
246 * object [obj] with the given parameters, in a scalar context. Thus this
247 * is equivalent to [$obj->name (parameters)].
249 * Returns the Perl [SV] containing the result value.
251 * If the method calls [die] then this will throw [Perl_failure].
254 external call_method_array : sv -> string -> sv list -> sv list
255 = "perl4caml_call_method_array"
256 (** Like [call_method], but the method is called in an array context. *)
258 external call_method_void : sv -> string -> sv list -> unit
259 = "perl4caml_call_method_void"
260 (** Like [call_method], but the method is called in a void context (results
263 external call_class_method : string -> string -> sv list -> sv
264 = "perl4caml_call_class_method"
265 (** [call_class_method classname name [parameters]] calls the static method
266 * [name] in the Perl class [classname] with the given parameters, in a
267 * scalar context. Thus this is equivalent to [$classname->name (parameters)].
269 * Returns the Perl [SV] containing the result value.
271 * If the static method calls [die] then this will throw [Perl_failure].
274 external call_class_method_array : string -> string -> sv list -> sv list
275 = "perl4caml_call_class_method_array"
276 (** Like [call_class_method], but the method is called in an array context. *)
278 external call_class_method_void : string -> string -> sv list -> unit
279 = "perl4caml_call_class_method_void"
280 (** Like [call_class_method], but the method is called in a void context. *)