perl.mli

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