(* File: sexp.mli

    Copyright (C) 2005-

      Jane Street Holding, LLC
      Author: Markus Mottl
      email: mmottl@janestcapital.com
      WWW: http://www.janestcapital.com/ocaml

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with this library; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*)

(** Sexp: Module for handling S-expressions (I/O, etc.) *)

open Format
open Lexing

(** Type of S-expressions *)
type t = Type.t = Atom of string | List of t list


(** {6 Defaults} *)

val default_indent : int ref
(** [default_indent] reference to default indentation level for
    human-readable conversions.  Initialisation value: 2. *)


(** {6 Scan functions} *)

val scan_sexp : ?buf : Buffer.t -> lexbuf -> t
(** [scan_sexp ?buf lexbuf] scans an S-expression from lex buffer
    [lexbuf] using the optional string buffer [buf] for storing
    intermediate strings. *)

val scan_sexps : ?buf : Buffer.t -> lexbuf -> t list
(** [scan_sexps ?buf lexbuf] reads a list of S-expressions from lex buffer
    [lexbuf] using the optional string buffer [buf] for storing
    intermediate strings. *)

val load_sexp : string -> t
(** [load_sexp file] reads an S-expression from file [file]. *)

val load_sexps : string -> t list
(** [load_sexps file] reads a list of S-expressions from file [file]. *)

val scan_iter_sexps : ?buf : Buffer.t -> f : (t -> unit) -> lexbuf -> unit
(** [scan_iter_sexps ?buf ~f lexbuf] iterates over all S-expressions
    scanned from lex buffer [lexbuf] using function [f], and the optional
    string buffer [buf] for storing intermediate strings. *)

val scan_fold_sexps :
  ?buf : Buffer.t -> f : (t -> 'a -> 'a) -> init : 'a -> lexbuf -> 'a
(** [scan_fold_sexps ?buf ~f ~init lexbuf] folds over all S-expressions
    scanned from lex buffer [lexbuf] using function [f], initial state
    [init], and the optional string buffer [buf] for storing intermediate
    strings. *)

val scan_cnv_sexps : ?buf : Buffer.t -> f : (t -> 'a) -> lexbuf -> 'a list
(** [scan_cnv_sexps ?buf ~f lexbuf] maps all S-expressions scanned
    from lex buffer [lexbuf] to some list using function [f], and the
    optional string buffer [buf] for storing intermediate strings. *)


(** {6 Output of S-expressions to I/O-channels} *)

val output_hum : out_channel -> t -> unit
(** [output_hum oc sexp] outputs S-expression [sexp] to output channel
    [oc] in human readable form. *)

val output_hum_indent : int -> out_channel -> t -> unit
(** [output_hum_indent indent oc sexp] outputs S-expression [sexp]
    to output channel [oc] in human readable form using indentation level
    [indent].
*)

val output_mach : out_channel -> t -> unit
(** [output_mach oc sexp] outputs S-expression [sexp] to output channel
    [oc] in machine readable (i.e. most compact) form. *)

val output : out_channel -> t -> unit
(** [output oc sexp] same as [output_mach]. *)


(** {6 Output of S-expressions to formatters} *)

val pp_hum : formatter -> t -> unit
(** [pp_hum ppf sexp] outputs S-expression [sexp] to formatter [ppf]
    in human readable form. *)

val pp_hum_indent : int -> formatter -> t -> unit
(** [pp_hum_indent n ppf sexp] outputs S-expression [sexp] to formatter
    [ppf] in human readable form and indentation level [n]. *)

val pp_mach : formatter -> t -> unit
(** [pp_mach ppf sexp] outputs S-expression [sexp] to formatter [ppf]
    in machine readable (i.e. most compact) form. *)

val pp : formatter -> t -> unit
(** [pp ppf sexp] same as [pp_mach]. *)


(** {6 String conversions} *)

val of_string : string -> t
(** [of_string str] converts string [str] to an S-expression. *)

val to_string_hum : ?indent : int -> t -> string
(** [to_string_hum ?indent sexp] converts S-expression [sexp] to a
    string in human readable form with indentation level [indent].

    @param indent default = [!default_indent]
*)

val to_string_mach : t -> string
(** [to_string_mach sexp] converts S-expression [sexp] to a string in
    machine readable (i.e. most compact) form. *)

val to_string : t -> string
(** [to_string sexp] same as [to_string_mach]. *)


(** {6 Buffer conversions} *)

val to_buffer_hum : ?buf : Buffer.t -> ?indent : int -> t -> Buffer.t
(** [to_buffer_hum ?indent ?buf sexp] outputs the S-expression [sexp]
    converted to a string in human readable form to buffer [buf].
    @return [buf].

    @param buf default = [Buffer.create 4096]
    @param indent default = [!default_indent]
*)

val to_buffer_mach : ?buf : Buffer.t -> t -> Buffer.t
(** [to_buffer_mach ?buf sexp] outputs the S-expression [sexp]
    converted to a string in machine readable (i.e. most compact) form
    to buffer [buf].  @return [buf].

    @param buf default = [Buffer.create 4096]
*)

val to_buffer : ?buf : Buffer.t -> t -> Buffer.t
(** [to_buffer sexp] same as [to_buffer_mach]. *)


(** {6 Utilities for automated type conversions} *)

val unit : t
(** [unit] the unit-value as expressed by an S-expression. *)

external sexp_of_t : t -> t = "%identity"
(** [sexp_of_t sexp] maps S-expressions which are part of a type with
    automated S-expression conversion to themselves. *)

external t_of_sexp : t -> t = "%identity"
(** [t_of_sexp sexp] maps S-expressions which are part of a type with
    automated S-expression conversion to themselves. *)