perl.mli

   1 (** Interface to Perl from OCaml. *)
   2 (*  Copyright (C) 2003 Merjis Ltd.
   3
   4     This library is free software; you can redistribute it and/or
   5     modify it under the terms of the GNU Library General Public
   6     License as published by the Free Software Foundation; either
   7     version 2 of the License, or (at your option) any later version.
   8
   9     This library is distributed in the hope that it will be useful,
  10     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12     Library General Public License for more details.
  13
  14     You should have received a copy of the GNU General Public License
  15     along with this library; see the file COPYING.  If not, write to
  16     the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17     Boston, MA 02111-1307, USA.
  18
  19     $Id: perl.mli,v 1.16 2008-03-01 13:02:21 rich Exp $
  20   *)
  21
  22 type sv
  23 (** Perl scalar value. *)
  24
  25 type av
  26 (** Perl array value. *)
  27
  28 type hv
  29 (** Perl hash value. *)
  30
  31 exception Perl_failure of string
  32 (** [die] in Perl code is translated automatically into this exception. *)
  33
  34 val int_of_sv : sv -> int
  35 (** Convert a Perl [SV] into an integer. Note that OCaml [int]s aren't
  36   * large enough to store the full 32 (or 64) bits from a Perl integer,
  37   * so you may get a silent overflow.
  38   *)
  39 val sv_of_int : int -> sv
  40 (** Convert an [int] into a Perl [SV]. *)
  41 val float_of_sv : sv -> float
  42 (** Convert a Perl [SV] into a float. *)
  43 val sv_of_float : float -> sv
  44 (** Convert a [float] into a Perl [SV]. *)
  45 val string_of_sv : sv -> string
  46 (** Convert a Perl [SV] into a string. *)
  47 val sv_of_string : string -> sv
  48 (** Convert a [string] into a Perl [SV]. *)
  49 val bool_of_sv : sv -> bool
  50 (** Convert an [SV] into a boolean. *)
  51 val sv_of_bool : bool -> sv
  52 (** Convert a boolean into an [SV]. *)
  53
  54 val sv_is_true : sv -> bool
  55 (** Return [true] if the [SV] is "true" (in the Perl sense of truth). *)
  56 val sv_is_undef : sv -> bool
  57 (** Return [true] if the [SV] is undefined (is [undef]). *)
  58 val sv_undef : unit -> sv
  59 (** Returns [undef]. *)
  60 val sv_true : unit -> sv
  61 (** Returns an [SV] which is true. *)
  62 val sv_false : unit -> sv
  63 (** Returns an [SV] which is false. *)
  64 val sv_yes : unit -> sv
  65 (** Returns Perl's internal [PL_sv_yes]. (There are some unresolved issues
  66   * with using this, so use {!Perl.sv_true} instead). *)
  67 val sv_no : unit -> sv
  68 (** Returns Perl's internal [PL_sv_no]. (There are some unresolved issues
  69   * with using this, so use {!Perl.sv_false} instead). *)
  70
  71 (* Actually there are many more types defined than this ... *)
  72 type sv_t    = SVt_NULL
  73              | SVt_IV        (** Integer scalar.  *)
  74              | SVt_NV        (** Floating point scalar. *)
  75              | SVt_PV        (** String scalar. *)
  76              | SVt_RV        (** Reference. *)
  77              | SVt_PVAV      (** Array. *)
  78              | SVt_PVHV      (** Hash. *)
  79              | SVt_PVCV      (** Code. *)
  80              | SVt_PVGV      (** Glob (possibly a file handle). *)
  81              | SVt_PVMG      (** Blessed or magical scalar. *)
  82 val sv_type : sv -> sv_t
  83 (** Return the type of data contained in an [SV]. Somewhat equivalent to
  84   * calling Perl's [ref] function.
  85   *)
  86 val string_of_sv_t : sv_t -> string
  87 (** Return a printable string for an [sv_t] ([SV] type). *)
  88
  89 val reftype : sv -> sv_t
  90 (** The parameter [sv] must be a reference.  This convenience function
  91  * works out what it is a reference to, either a scalar, array, hash,
  92  * code or glob.  If the parameter is not a reference, or is a reference
  93  * to an unknown type, then this will throw [Invalid_argument].  *)
  94
  95 val address_of_sv : sv -> Nativeint.t
  96 (** Returns the address of the SV.  Useful for debugging since
  97   * Perl also prints out addresses on internal errors.
  98   *)
  99 val address_of_av : av -> Nativeint.t
 100 (** Returns the address of the AV.  Useful for debugging since
 101   * Perl also prints out addresses on internal errors.
 102   *)
 103 val address_of_hv : hv -> Nativeint.t
 104 (** Returns the address of the HV.  Useful for debugging since
 105   * Perl also prints out addresses on internal errors.
 106   *)
 107
 108 val scalarref : sv -> sv
 109 (** Given a scalar, this returns a reference to the scalar. Note that
 110   * because references are [SV]s, this returns [sv].
 111   *)
 112 val arrayref : av -> sv
 113 (** Given an array, this returns a reference to the array. Note that
 114   * because references are [SV]s, this returns [sv].
 115   *)
 116 val hashref : hv -> sv
 117 (** Given a hash, this returns a reference to the hash. Note that
 118   * because references are [SV]s, this returns [sv].
 119   *)
 120
 121 val deref : sv -> sv
 122 (** The input is a reference to a scalar. This returns the underlying
 123   * scalar [SV]. If the input is not a reference to a scalar, throws
 124   * [Invalid_argument].
 125   *)
 126 val deref_array : sv -> av
 127 (** The input is a reference to an array. This returns the underlying
 128   * array [AV]. If the input is not a reference to an array, throws
 129   * [Invalid_argument].
 130   *)
 131 val deref_hash : sv -> hv
 132 (** The input is a reference to a hash. This returns the underlying
 133   * hash [HV]. If the input is not a reference to a hash, throws
 134   * [Invalid_argument].
 135   *)
 136
 137 val av_empty : unit -> av
 138 (** Create an empty [AV] (array). *)
 139 val av_of_sv_list : sv list -> av
 140 (** Create an array from a list of [SVs]. *)
 141 val av_push : av -> sv -> unit
 142 (** Append the [SV] to the end of the array. Same as Perl
 143   * [push \@av, $sv]. *)
 144 val av_pop : av -> sv
 145 (** Remove the [SV] at the end of the array and return it. Same as
 146   * Perl [$sv = pop \@av]. *)
 147 val av_shift : av -> sv
 148 (** Remove the [SV] at the beginning of the array and return it. Same as
 149   * Perl [$sv = shift \@av]. *)
 150 val av_unshift : av -> sv -> unit
 151 (** Prepend the [SV] to the start of the array. Same as Perl
 152   * [unshift \@av, $sv]. *)
 153 val av_length : av -> int
 154 (** Return the length of the [AV]. *)
 155 val av_set : av -> int -> sv -> unit
 156 (** Replace the i'th element of the [AV] with [SV]. *)
 157 val av_get : av -> int -> sv
 158 (** Get the i'th element of the [AV]. *)
 159 val av_clear : av -> unit
 160 (** Remove all elements from the [AV]. Same as Perl [\@av = ()]. *)
 161 val av_undef : av -> unit
 162 (** Delete the [AV] (and all elements in it). Same as Perl [undef \@av]. *)
 163 val av_extend : av -> int -> unit
 164 (** Extend the [AV] so it contains at least [n+1] elements.  Note that
 165   * this apparently just changes the amount of allocated storage.  The
 166   * extra elements are not visible until you store something in them.
 167   *)
 168 val av_map : (sv -> 'a) -> av -> 'a list
 169 (** Map a function over the elements in the [AV], return a list of the
 170   * results. *)
 171 val list_of_av : av -> sv list
 172 (** Convert an [AV] into a simple list of [SV]s. *)
 173 val av_of_string_list : string list -> av
 174 (** Build an [AV] from a list of strings. *)
 175
 176 val hv_empty : unit -> hv
 177 (** Create an empty [HV] (hash). *)
 178 val hv_set : hv -> string -> sv -> unit
 179 (** Store the given [SV] in the named key in the hash. *)
 180 val hv_get : hv -> string -> sv
 181 (** Return the [SV] at the key in the hash. Throws [Not_found] if no key. *)
 182 val hv_exists : hv -> string -> bool
 183 (** Return true if the hash contains the given key. Same as Perl [exists]. *)
 184 val hv_delete : hv -> string -> unit
 185 (** Delete the given key from the hash. Same as Perl [delete]. *)
 186 val hv_clear : hv -> unit
 187 (** Remove all elements from the [HV]. Same as Perl [%av = ()]. *)
 188 val hv_undef : hv -> unit
 189 (** Delete the [HV] (and all elements in it). Same as Perl [undef %hv]. *)
 190 val hv_of_assoc : (string * sv) list -> hv
 191 (** Create an [HV] directly from an assoc list.  Perl hashes cannot
 192   * support multiple values attached to the same key, so if you try
 193   * to provide an assoc list with multiple identical keys, the results
 194   * will be undefined.
 195   *)
 196 val assoc_of_hv : hv -> (string * sv) list
 197 (** Take an [HV] and return an assoc list. *)
 198 val hv_keys : hv -> string list
 199 (** Return all the keys of an [HV]. *)
 200 val hv_values : hv -> sv list
 201 (** Return all the values of an [HV]. *)
 202
 203 (* The following are the low-level iteration interface to hashes,
 204  * which you probably shouldn't use directly.  Use {!hv_keys},
 205  * {!assoc_of_hv}, etc. instead.  See [perlguts(3)] if you really
 206  * want to use this interface.
 207  *)
 208 type he
 209 val hv_iterinit : hv -> Int32.t
 210 val hv_iternext : hv -> he
 211 val hv_iterkey : he -> string
 212 val hv_iterval : hv -> he -> sv
 213 val hv_iternextsv : hv -> string * sv
 214
 215 val get_sv : ?create:bool -> string -> sv
 216   (** Return a scalar value by name. For example, if you have a symbol
 217     * called [$a] in Perl, then [get_sv "a"] will return its value.
 218     *
 219     * If the symbol does not exist, this throws [Not_found].
 220     *
 221     * If the optional [?create] argument is set to true and the symbol does
 222     * not exist, then Perl will create the symbol (with value [undef]) and
 223     * this function will return the [SV] for [undef].
 224   *)
 225 val get_av : ?create:bool -> string -> av
 226 (** Same as {!Perl.get_sv} except will return and/or create [\@a]. *)
 227 val get_hv : ?create:bool -> string -> hv
 228 (** Same as {!Perl.get_sv} except will return and/or create [%a]. *)
 229
 230 val call : ?sv:sv -> ?fn:string -> sv list -> sv
 231 (** Call a Perl function in a scalar context, either by name (using the [?fn]
 232   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
 233   *
 234   * Returns the Perl [SV] containing the result value. (See
 235   * {!Perl.int_of_sv} etc.).
 236   *
 237   * If the Perl code calls [die] then this will throw [Perl_failure].
 238   *)
 239
 240 val call_array : ?sv:sv -> ?fn:string -> sv list -> sv list
 241 (** Call a Perl function in an array context, either by name (using the [?fn]
 242   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
 243   *
 244   * Returns the list of results.
 245   *
 246   * If the Perl code calls [die] then this will throw [Perl_failure].
 247   *)
 248
 249 val call_void : ?sv:sv -> ?fn:string -> sv list -> unit
 250 (** Call a Perl function in a void context, either by name (using the [?fn]
 251   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
 252   *
 253   * Any results are discarded.
 254   *
 255   * If the Perl code calls [die] then this will throw [Perl_failure].
 256   *)
 257
 258 val eval : string -> sv
 259 (** This is exactly like the Perl [eval] command. It evaluates a piece of
 260   * Perl code (in scalar context) and returns the result (a Perl [SV]).
 261   *)
 262
 263 val call_method : sv -> string -> sv list -> sv
 264 (** [call_method obj name [parameters]] calls the method [name] on the Perl
 265   * object [obj] with the given parameters, in a scalar context. Thus this
 266   * is equivalent to [$obj->name (parameters)].
 267   *
 268   * Returns the Perl [SV] containing the result value.
 269   *
 270   * If the method calls [die] then this will throw [Perl_failure].
 271   *)
 272
 273 val call_method_array : sv -> string -> sv list -> sv list
 274 (** Like [call_method], but the method is called in an array context. *)
 275
 276 val call_method_void : sv -> string -> sv list -> unit
 277 (** Like [call_method], but the method is called in a void context (results
 278   * are discarded). *)
 279
 280 val call_class_method : string -> string -> sv list -> sv
 281 (** [call_class_method classname name [parameters]] calls the static method
 282   * [name] in the Perl class [classname] with the given parameters, in a
 283   * scalar context. Thus this is equivalent to [$classname->name (parameters)].
 284   *
 285   * Returns the Perl [SV] containing the result value.
 286   *
 287   * If the static method calls [die] then this will throw [Perl_failure].
 288   *)
 289
 290 val call_class_method_array : string -> string -> sv list -> sv list
 291 (** Like [call_class_method], but the method is called in an array context. *)
 292
 293 val call_class_method_void : string -> string -> sv list -> unit
 294 (** Like [call_class_method], but the method is called in a void context. *)