perl.mli

   1 (** Interface to Perl from OCaml.
   2   *
   3   * Copyright (C) 2003 Merjis Ltd.
   4   *
   5   * $Id: perl.mli,v 1.2 2003-10-12 10:52:00 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 external create : ?args:string array -> unit -> t
  18   = "perl4caml_create"
  19 (** Create a Perl interpreter.
  20   *
  21   * The optional [?args] parameter is the command line passed to the
  22   * interpreter, and controls things like whether warnings are enabled
  23   * ([-w]) and which file(s) are parsed. The first element in the
  24   * array is the executable name (you can just set this to [""]).
  25   *
  26   * Perl won't allow you to create multiple interpreters at the same time
  27   * unless Perl itself was compiled with [-Dusemultiplicity]. However you
  28   * can create, then destroy, then create another and so on.
  29   *)
  30
  31 external destroy : t -> unit
  32   = "perl4caml_destroy"
  33 (** Destroy a Perl interpreter, performing any necessary cleanup. *)
  34
  35 external set_context : t -> unit
  36   = "perl4caml_set_context"
  37 (** IF Perl was compiled with [-Dusemultiplicity] and IF you are using
  38   * multiple interpreters at the same time, then you must call this to
  39   * set the implied "current" interpreter.
  40   *
  41   * Most users will never need to call this function.
  42   *)
  43
  44 external int_of_sv : sv -> int = "perl4caml_int_of_sv"
  45 (** Convert a Perl [SV] into an integer. Note that OCaml [int]s aren't
  46   * large enough to store the full 32 (or 64) bits from a Perl integer,
  47   * so you may get a silent overflow.
  48   *)
  49 external sv_of_int : int -> sv = "perl4caml_sv_of_int"
  50 (** Convert an [int] into a Perl [SV]. *)
  51 external float_of_sv : sv -> int = "perl4caml_float_of_sv"
  52 (** Convert a Perl [SV] into a float. *)
  53 external sv_of_float : int -> sv = "perl4caml_sv_of_float"
  54 (** Convert a [float] into a Perl [SV]. *)
  55 external string_of_sv : sv -> string = "perl4caml_string_of_sv"
  56 (** Convert a Perl [SV] into a string. *)
  57 external sv_of_string : string -> sv = "perl4caml_sv_of_string"
  58 (** Convert a [string] into a Perl [SV]. *)
  59
  60 external get_sv : ?create:bool -> string -> sv = "perl4caml_get_sv"
  61 (** Return a scalar value by name. For example, if you have a symbol
  62   * called [$a] in Perl, then [get_sv "a"] will return its value.
  63   *
  64   * If the symbol does not exist, this throws [Not_found].
  65   *
  66   * If the optional [?create] argument is set to true and the symbol does
  67   * not exist, then Perl will create the symbol (with value [undef]) and
  68   * this function will return the [SV] for [undef].
  69   *)
  70
  71 external call : ?sv:sv -> ?fn:string -> sv list -> sv
  72   = "perl4caml_call"
  73 (** Call a Perl function in a scalar context, either by name (using the [?fn]
  74   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
  75   *
  76   * Returns the Perl [SV] containing the result value. (See {!int_of_sv} etc.).
  77   *
  78   * If the Perl code calls [die] then this will throw [Perl_failure].
  79   *)
  80
  81 external call_array : ?sv:sv -> ?fn:string -> sv list -> sv list
  82   = "perl4caml_call_array"
  83 (** Call a Perl function in an array context, either by name (using the [?fn]
  84   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
  85   *
  86   * Returns the list of results.
  87   *
  88   * If the Perl code calls [die] then this will throw [Perl_failure].
  89   *)
  90
  91 external call_void : ?sv:sv -> ?fn:string -> sv list -> unit
  92   = "perl4caml_call_void"
  93 (** Call a Perl function in a void context, either by name (using the [?fn]
  94   * parameter) or by calling a string/CODEREF (using the [?sv] parameter).
  95   *
  96   * Any results are discarded.
  97   *
  98   * If the Perl code calls [die] then this will throw [Perl_failure].
  99   *)
 100
 101 external eval : string -> sv
 102   = "perl4caml_eval"
 103 (** This is exactly like the Perl [eval] command. It evaluates a piece of
 104   * Perl code (in scalar context) and returns the result (a Perl [SV]).
 105   *)