perl.mli

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