(** csv.mli - comma separated values parser
  *
  * $Id: csv.mli,v 1.2 2004-12-06 17:40:50 rich Exp $
  *)

type t = string list list
(** Representation of CSV files. *)

exception Bad_CSV_file of string
(** Badly formed CSV files throw this exception: *)

val lines : t -> int
(** Work out the number of lines in a CSV file. *)

val columns : t -> int
(** Work out the (maximum) number of columns in a CSV file. Note that each
  * line may be a different length, so this finds the one with the most
  * columns.
  *)

val load_in : in_channel -> t
(** Load a CSV file.
  * @param chan Input file stream
  *)

val load : string -> t
(** Load a CSV file.
  * @param filename CSV filename.
  *)

val load_rows : (string list -> unit) -> in_channel -> unit
(** For very large CSV files which cannot be processed in memory at once,
  * this function is appropriate. It parses the input one row at a time and
  * calls your function once for each row.
  *
  * Note that if you CSV file contains cells which have embedded
  * line feeds, then it is non-trivial to parse these lines and
  * pass them correctly to [load_rows].
  *
  * @param f Callout function.
  * @param chan Input file stream.
  *)

val trim : ?top:bool -> ?left:bool -> ?right:bool -> ?bottom:bool -> t -> t
(** This takes a CSV file and trims empty cells.
  *
  * All four of the option arguments ([~top], [~left], [~right], [~bottom])
  * default to [true].
  *
  * The exact behaviour is:
  *
  * [~right]: If true, remove any empty cells at the right hand end of
  * any row.  The number of columns in the resulting CSV structure will
  * not necessarily be the same for each row.
  *
  * [~top]: If true, remove any empty rows (no cells, or containing just empty
  * cells) from the top of the CSV structure.
  *
  * [~bottom]: If true, remove any empty rows from the bottom of the
  * CSV structure.
  *
  * [~left]: If true, remove any empty columns from the left of the
  * CSV structure.  Note that [~left] and [~right] are quite different:
  * [~left] considers the whole CSV structure, whereas [~right] considers
  * each row in isolation.
  *)

val print : t -> unit
(** Print string list list - same as [save_out stdout] *)

val save_out : out_channel -> t -> unit
(** Save string list list to a channel. *)

val save : string -> t -> unit
(** Save string list list to a file. *)