perl.mli

   1 (** Interface to Perl from OCaml.
   2   *
   3   * Copyright (C) 2003 Merjis Ltd.
   4   *
   5   * $Id: perl.mli,v 1.12 2004-03-03 12:39:20 rich Exp $
   6   *)
   7
   8 type sv
   9 (** Perl scalar value. *)
  10
  11 type av
  12 (** Perl array value. *)
  13
  14 type hv
  15 (** Perl hash value. *)
  16
  17 exception Perl_failure of string
  18 (** [die] in Perl code is translated automatically into this exception. *)
  19
  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.
  24   *)
  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]. *)
  39
  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). *)
  56
  57 (* Actually there are many more types defined than this ... *)
  58 type sv_t    = SVt_NULL
  59              | SVt_IV        (** Integer scalar.  *)
  60              | SVt_NV        (** Floating point scalar. *)
  61              | SVt_PV        (** String scalar. *)
  62              | SVt_RV        (** Reference. *)
  63              | SVt_PVAV      (** Array ref. *)
  64              | SVt_PVHV      (** Hash ref. *)
  65              | SVt_PVCV      (** Code ref. *)
  66              | SVt_PVGV      (** Glob. *)
  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.
  71   *)
  72 val string_of_sv_t : sv_t -> string
  73 (** Return a printable string for an [sv_t] ([SV] type). *)
  74
  75 val scalarref : sv -> sv
  76 (** Given a scalar, this returns a reference to the scalar. Note that
  77   * because references are [SV]s, this returns [sv].
  78   *)
  79 val arrayref : av -> sv
  80 (** Given an array, this returns a reference to the array. Note that
  81   * because references are [SV]s, this returns [sv].
  82   *)
  83 val hashref : hv -> sv
  84 (** Given a hash, this returns a reference to the hash. Note that
  85   * because references are [SV]s, this returns [sv].
  86   *)
  87
  88 val deref : sv -> sv
  89 (** The input is a reference to a scalar. This returns the underlying
  90   * scalar [SV]. If the input is not a reference to a scalar, throws
  91   * [Invalid_argument].
  92   *)
  93 val deref_array : sv -> av
  94 (** The input is a reference to an array. This returns the underlying
  95   * array [AV]. If the input is not a reference to an array, throws
  96   * [Invalid_argument].
  97   *)
  98 val deref_hash : sv -> hv
  99 (** The input is a reference to a hash. This returns the underlying
 100   * hash [HV]. If the input is not a reference to a hash, throws
 101   * [Invalid_argument].
 102   *)
 103
 104 val av_empty : unit -> av
 105 (** Create an empty [AV] (array). *)
 106 val av_of_sv_list : sv list -> av
 107 (** Create an array from a list of [SVs]. *)
 108 val av_push : av -> sv -> unit
 109 (** Append the [SV] to the end of the array. Same as Perl
 110   * [push \@av, $sv]. *)
 111 val av_pop : av -> sv
 112 (** Remove the [SV] at the end of the array and return it. Same as
 113   * Perl [$sv = pop \@av]. *)
 114 val av_shift : av -> sv
 115 (** Remove the [SV] at the beginning of the array and return it. Same as
 116   * Perl [$sv = shift \@av]. *)
 117 val av_unshift : av -> sv -> unit
 118 (** Prepend the [SV] to the start of the array. Same as Perl
 119   * [unshift \@av, $sv]. *)
 120 val av_length : av -> int
 121 (** Return the length of the [AV]. *)
 122 val av_set : av -> int -> sv -> unit
 123 (** Replace the i'th element of the [AV] with [SV]. *)
 124 val av_get : av -> int -> sv
 125 (** Get the i'th element of the [AV]. *)
 126 val av_clear : av -> unit
 127 (** Remove all elements from the [AV]. Same as Perl [\@av = ()]. *)
 128 val av_undef : av -> unit
 129 (** Delete the [AV] (and all elements in it). Same as Perl [undef \@av]. *)
 130 val av_extend : av -> int -> unit
 131 (** Extend the [AV] so it contains at least [n+1] elements. *)
 132 val av_map : (sv -> 'a) -> av -> 'a list
 133 (** Map a function over the elements in the [AV], return a list of the
 134   * results. *)
 135 val list_of_av : av -> sv list
 136 (** Convert an [AV] into a simple list of [SV]s. *)
 137 val av_of_string_list : string list -> av
 138 (** Build an [AV] from a list of strings. *)
 139
 140 val hv_empty : unit -> hv
 141 (** Create an empty [HV] (hash). *)
 142 val hv_set : hv -> string -> sv -> unit
 143 (** Store the given [SV] in the named key in the hash. *)
 144 val hv_get : hv -> string -> sv
 145 (** Return the [SV] at the key in the hash. Throws [Not_found] if no key. *)
 146 val hv_exists : hv -> string -> bool
 147 (** Return true if the hash contains the given key. Same as Perl [exists]. *)
 148 val hv_delete : hv -> string -> unit
 149 (** Delete the given key from the hash. Same as Perl [delete]. *)
 150 val hv_clear : hv -> unit
 151 (** Remove all elements from the [HV]. Same as Perl [%av = ()]. *)
 152 val hv_undef : hv -> unit
 153 (** Delete the [HV] (and all elements in it). Same as Perl [undef %hv]. *)
 154
 155 val get_sv : ?create:bool -> string -> sv
 156 (** Return a scalar value by name. For example, if you have a symbol
 157   * called [$a] in Perl, then [get_sv "a"] will return its value.
 158   *
 159   * If the symbol does not exist, this throws [Not_found].
 160   *
 161   * If the optional [?create] argument is set to true and the symbol does
 162   * not exist, then Perl will create the symbol (with value [undef]) and
 163   * this function will return the [SV] for [undef].
 164   *)
 165 val get_av : ?create:bool -> string -> av
 166 (** Same as {!Perl.get_sv} except will return and/or create [\@a]. *)
 167 val get_hv : ?create:bool -> string -> hv
 168 (** Same as {!Perl.get_sv} except will return and/or create [%a]. *)
 169
 170 val call : ?sv:sv -> ?fn:string -> sv list -> sv
 171 (** Call a Perl function in a scalar context, either by name (using the [?fn]
 172   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
 173   *
 174   * Returns the Perl [SV] containing the result value. (See
 175   * {!Perl.int_of_sv} etc.).
 176   *
 177   * If the Perl code calls [die] then this will throw [Perl_failure].
 178   *)
 179
 180 val call_array : ?sv:sv -> ?fn:string -> sv list -> sv list
 181 (** Call a Perl function in an array context, either by name (using the [?fn]
 182   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
 183   *
 184   * Returns the list of results.
 185   *
 186   * If the Perl code calls [die] then this will throw [Perl_failure].
 187   *)
 188
 189 val call_void : ?sv:sv -> ?fn:string -> sv list -> unit
 190 (** Call a Perl function in a void context, either by name (using the [?fn]
 191   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
 192   *
 193   * Any results are discarded.
 194   *
 195   * If the Perl code calls [die] then this will throw [Perl_failure].
 196   *)
 197
 198 val eval : string -> sv
 199 (** This is exactly like the Perl [eval] command. It evaluates a piece of
 200   * Perl code (in scalar context) and returns the result (a Perl [SV]).
 201   *)
 202
 203 val call_method : sv -> string -> sv list -> sv
 204 (** [call_method obj name [parameters]] calls the method [name] on the Perl
 205   * object [obj] with the given parameters, in a scalar context. Thus this
 206   * is equivalent to [$obj->name (parameters)].
 207   *
 208   * Returns the Perl [SV] containing the result value.
 209   *
 210   * If the method calls [die] then this will throw [Perl_failure].
 211   *)
 212
 213 val call_method_array : sv -> string -> sv list -> sv list
 214 (** Like [call_method], but the method is called in an array context. *)
 215
 216 val call_method_void : sv -> string -> sv list -> unit
 217 (** Like [call_method], but the method is called in a void context (results
 218   * are discarded). *)
 219
 220 val call_class_method : string -> string -> sv list -> sv
 221 (** [call_class_method classname name [parameters]] calls the static method
 222   * [name] in the Perl class [classname] with the given parameters, in a
 223   * scalar context. Thus this is equivalent to [$classname->name (parameters)].
 224   *
 225   * Returns the Perl [SV] containing the result value.
 226   *
 227   * If the static method calls [die] then this will throw [Perl_failure].
 228   *)
 229
 230 val call_class_method_array : string -> string -> sv list -> sv list
 231 (** Like [call_class_method], but the method is called in an array context. *)
 232
 233 val call_class_method_void : string -> string -> sv list -> unit
 234 (** Like [call_class_method], but the method is called in a void context. *)