perl.mli

   1 (** Interface to Perl from OCaml.
   2   *
   3   * Copyright (C) 2003 Merjis Ltd.
   4   *
   5   * $Id: perl.mli,v 1.4 2003-10-12 17:33:14 rich Exp $
   6   *)
   7
   8 type t
   9 (** Perl interpreter (abstract type). *)
  10
  11 type sv
  12 (** Perl scalar value. *)
  13
  14 exception Perl_failure of string
  15 (** [die] in Perl code is translated automatically into this exception. *)
  16
  17 val init : unit -> unit
  18 (** Don't call this. Instead link your program with [perl_init.cmo] or
  19   * [perl_init.cmx] which calls this for you.
  20   *)
  21
  22 external destroy : unit -> unit
  23   = "perl4caml_destroy"
  24 (** Destroy the current Perl interpreter, performing any necessary cleanup.
  25   * You should call this at the end of your program, otherwise Perl won't
  26   * properly clean up.
  27   *
  28   * Note that a Perl interpreter is created for you by default when you
  29   * use perl4caml.
  30   *)
  31
  32 external create : ?args:string array -> unit -> t
  33   = "perl4caml_create"
  34 (** Create a new Perl interpreter. (Note that a Perl interpreter is created
  35   * for you by default so you don't need to call this).
  36   *
  37   * The optional [?args] parameter is the command line passed to the
  38   * interpreter, and controls things like whether warnings are enabled
  39   * ([-w]) and which file(s) are parsed. The first element in the
  40   * array is the executable name (you can just set this to [""]).
  41   *
  42   * Perl won't allow you to create multiple interpreters at the same time
  43   * unless Perl itself was compiled with [-Dusemultiplicity]. However you
  44   * can create, then destroy, then create another and so on.
  45   *
  46   * The newly created interpreter is set as the "current interpreter".
  47   *)
  48
  49 external set_context : t -> unit
  50   = "perl4caml_set_context"
  51 (** IF Perl was compiled with [-Dusemultiplicity] and IF you are using
  52   * multiple interpreters at the same time, then you must call this to
  53   * set the implied "current" interpreter.
  54   *
  55   * Most users will never need to call this function.
  56   *)
  57
  58 external int_of_sv : sv -> int = "perl4caml_int_of_sv"
  59 (** Convert a Perl [SV] into an integer. Note that OCaml [int]s aren't
  60   * large enough to store the full 32 (or 64) bits from a Perl integer,
  61   * so you may get a silent overflow.
  62   *)
  63 external sv_of_int : int -> sv = "perl4caml_sv_of_int"
  64 (** Convert an [int] into a Perl [SV]. *)
  65 external float_of_sv : sv -> int = "perl4caml_float_of_sv"
  66 (** Convert a Perl [SV] into a float. *)
  67 external sv_of_float : int -> sv = "perl4caml_sv_of_float"
  68 (** Convert a [float] into a Perl [SV]. *)
  69 external string_of_sv : sv -> string = "perl4caml_string_of_sv"
  70 (** Convert a Perl [SV] into a string. *)
  71 external sv_of_string : string -> sv = "perl4caml_sv_of_string"
  72 (** Convert a [string] into a Perl [SV]. *)
  73 val bool_of_sv : sv -> bool
  74 (** Convert an [SV] into a boolean. *)
  75 val sv_of_bool : bool -> sv
  76 (** Convert a boolean into an [SV]. *)
  77
  78 external sv_is_true : sv -> bool = "perl4caml_sv_is_true"
  79 (** Return [true] if the [SV] is "true" (in the Perl sense of truth). *)
  80 external sv_is_undef : sv -> bool = "perl4caml_sv_is_undef"
  81 (** Return [true] if the [SV] is undefined (is [undef]). *)
  82 external sv_undef : unit -> sv = "perl4caml_sv_undef"
  83 (** Returns [undef]. *)
  84 val sv_true : unit -> sv
  85 (** Returns an [SV] which is true. *)
  86 val sv_false : unit -> sv
  87 (** Returns an [SV] which is false. *)
  88 external sv_yes : unit -> sv = "perl4caml_sv_yes"
  89 (** Returns Perl's internal [PL_sv_yes]. (There are some unresolved issues
  90   * with using this, so use {!sv_true} instead). *)
  91 external sv_no : unit -> sv = "perl4caml_sv_no"
  92 (** Returns Perl's internal [PL_sv_no]. (There are some unresolved issues
  93   * with using this, so use {!sv_false} instead). *)
  94
  95 (* Actually there are many more types defined than this ... *)
  96 type sv_t    = SVt_NULL
  97              | SVt_IV        (** Integer scalar.  *)
  98              | SVt_NV        (** Floating point scalar. *)
  99              | SVt_PV        (** String scalar. *)
 100              | SVt_RV        (** Reference. *)
 101              | SVt_PVAV      (** Array ref. *)
 102              | SVt_PVHV      (** Hash ref. *)
 103              | SVt_PVCV      (** Code ref. *)
 104              | SVt_PVGV      (** Glob. *)
 105              | SVt_PVMG      (** Blessed or magical scalar. *)
 106 external sv_type : sv -> sv_t = "perl4caml_sv_type"
 107 (** Return the type of data contained in an [SV]. Somewhat equivalent to
 108   * calling Perl's [ref] function.
 109   *)
 110
 111 external deref : sv -> sv = "perl4caml_deref"
 112 (** The input is a reference to a scalar. This returns the underlying
 113   * scalar [SV]. If the input is not a reference to a scalar, throws
 114   * [Invalid_arg].
 115   *)
 116 (*
 117 external deref_array : sv -> av = "perl4caml_deref_array"
 118 (** The input is a reference to an array. This returns the underlying
 119   * array [AV]. If the input is not a reference to an array, throws
 120   * [Invalid_arg].
 121   *)
 122 external deref_hash : sv -> hv = "perl4caml_deref_hash"
 123 (** The input is a reference to a hash. This returns the underlying
 124   * hash [HV]. If the input is not a reference to a hash, throws
 125   * [Invalid_arg].
 126   *)
 127 *)
 128
 129 external get_sv : ?create:bool -> string -> sv = "perl4caml_get_sv"
 130 (** Return a scalar value by name. For example, if you have a symbol
 131   * called [$a] in Perl, then [get_sv "a"] will return its value.
 132   *
 133   * If the symbol does not exist, this throws [Not_found].
 134   *
 135   * If the optional [?create] argument is set to true and the symbol does
 136   * not exist, then Perl will create the symbol (with value [undef]) and
 137   * this function will return the [SV] for [undef].
 138   *)
 139
 140 external call : ?sv:sv -> ?fn:string -> sv list -> sv
 141   = "perl4caml_call"
 142 (** Call a Perl function in a scalar context, either by name (using the [?fn]
 143   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
 144   *
 145   * Returns the Perl [SV] containing the result value. (See {!int_of_sv} etc.).
 146   *
 147   * If the Perl code calls [die] then this will throw [Perl_failure].
 148   *)
 149
 150 external call_array : ?sv:sv -> ?fn:string -> sv list -> sv list
 151   = "perl4caml_call_array"
 152 (** Call a Perl function in an array context, either by name (using the [?fn]
 153   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
 154   *
 155   * Returns the list of results.
 156   *
 157   * If the Perl code calls [die] then this will throw [Perl_failure].
 158   *)
 159
 160 external call_void : ?sv:sv -> ?fn:string -> sv list -> unit
 161   = "perl4caml_call_void"
 162 (** Call a Perl function in a void context, either by name (using the [?fn]
 163   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
 164   *
 165   * Any results are discarded.
 166   *
 167   * If the Perl code calls [die] then this will throw [Perl_failure].
 168   *)
 169
 170 external eval : string -> sv
 171   = "perl4caml_eval"
 172 (** This is exactly like the Perl [eval] command. It evaluates a piece of
 173   * Perl code (in scalar context) and returns the result (a Perl [SV]).
 174   *)
 175
 176 external call_method : sv -> string -> sv list -> sv
 177   = "perl4caml_call_method"
 178 (** [call_method obj name [parameters]] calls the method [name] on the Perl
 179   * object [obj] with the given parameters, in a scalar context. Thus this
 180   * is equivalent to [$obj->name (parameters)].
 181   *
 182   * Returns the Perl [SV] containing the result value.
 183   *
 184   * If the method calls [die] then this will throw [Perl_failure].
 185   *)
 186
 187 external call_method_array : sv -> string -> sv list -> sv list
 188   = "perl4caml_call_method_array"
 189 (** Like [call_method], but the method is called in an array context. *)
 190
 191 external call_method_void : sv -> string -> sv list -> unit
 192   = "perl4caml_call_method_void"
 193 (** Like [call_method], but the method is called in a void context (results
 194   * are discarded). *)
 195
 196 external call_class_method : string -> string -> sv list -> sv
 197   = "perl4caml_call_class_method"
 198 (** [call_class_method classname name [parameters]] calls the static method
 199   * [name] in the Perl class [classname] with the given parameters, in a
 200   * scalar context. Thus this is equivalent to [$classname->name (parameters)].
 201   *
 202   * Returns the Perl [SV] containing the result value.
 203   *
 204   * If the static method calls [die] then this will throw [Perl_failure].
 205   *)
 206
 207 external call_class_method_array : string -> string -> sv list -> sv list
 208   = "perl4caml_call_class_method_array"
 209 (** Like [call_class_method], but the method is called in an array context. *)
 210
 211 external call_class_method_void : string -> string -> sv list -> unit
 212   = "perl4caml_call_class_method_void"
 213 (** Like [call_class_method], but the method is called in a void context. *)