csv.mli

   1 (** csv.mli - comma separated values parser
   2   *
   3   * $Id: csv.mli,v 1.5 2005-05-24 13:52:50 rich Exp $
   4   *)
   5
   6 type t = string list list
   7 (** Representation of CSV files. *)
   8
   9 exception Bad_CSV_file of string
  10 (** Badly formed CSV files throw this exception. *)
  11
  12 val lines : t -> int
  13 (** Work out the number of lines in a CSV file. *)
  14
  15 val columns : t -> int
  16 (** Work out the (maximum) number of columns in a CSV file. Note that each
  17   * line may be a different length, so this finds the one with the most
  18   * columns.
  19   *)
  20
  21 val load_in : ?separator:char -> in_channel -> t
  22 (** Load a CSV file.
  23   * @param chan Input file stream
  24   *)
  25
  26 val load : ?separator:char -> string -> t
  27 (** Load a CSV file.
  28   * @param filename CSV filename.
  29   *)
  30
  31 val load_rows : ?separator:char -> (string list -> unit) -> in_channel -> unit
  32 (** For very large CSV files which cannot be processed in memory at once,
  33   * this function is appropriate. It parses the input one row at a time and
  34   * calls your function once for each row.
  35   *
  36   * Note that if you CSV file contains cells which have embedded
  37   * line feeds, then it is non-trivial to parse these lines and
  38   * pass them correctly to [load_rows].
  39   *
  40   * @param f Callout function.
  41   * @param chan Input file stream.
  42   *)
  43
  44 val trim : ?top:bool -> ?left:bool -> ?right:bool -> ?bottom:bool -> t -> t
  45 (** This takes a CSV file and trims empty cells.
  46   *
  47   * All four of the option arguments ([~top], [~left], [~right], [~bottom])
  48   * default to [true].
  49   *
  50   * The exact behaviour is:
  51   *
  52   * [~right]: If true, remove any empty cells at the right hand end of
  53   * any row.  The number of columns in the resulting CSV structure will
  54   * not necessarily be the same for each row.
  55   *
  56   * [~top]: If true, remove any empty rows (no cells, or containing just empty
  57   * cells) from the top of the CSV structure.
  58   *
  59   * [~bottom]: If true, remove any empty rows from the bottom of the
  60   * CSV structure.
  61   *
  62   * [~left]: If true, remove any empty columns from the left of the
  63   * CSV structure.  Note that [~left] and [~right] are quite different:
  64   * [~left] considers the whole CSV structure, whereas [~right] considers
  65   * each row in isolation.
  66   *)
  67
  68 val square : t -> t
  69 (** Make the CSV data "square" (actually rectangular).  This pads out
  70   * each row with empty cells so that all rows are the same length as
  71   * the longest row.  After this operation, every row will have length
  72   * {!columns}.
  73   *)
  74
  75 val associate : string list -> t -> (string * string) list list
  76 (** [associate header data] takes a block of data and converts each
  77   * row in turn into an assoc list which maps column header to data cell.
  78   *
  79   * Typically a spreadsheet will have the format:
  80   * {v
  81   *   header1   header2   header3
  82   *   data11    data12    data13
  83   *   data21    data22    data23
  84   *     ...
  85   * v}
  86   *
  87   * This function arranges the data into a more usable form which is
  88   * robust against changes in column ordering.  The output of the
  89   * function is:
  90   * {v
  91   *   [ ["header1", "data11"; "header2", "data12"; "header3", "data13"];
  92   *     ["header1", "data21"; "header2", "data22"; "header3", "data23"];
  93   *     etc. ]
  94   * v}
  95   *
  96   * Each row is turned into an assoc list (see {!List.assoc}).
  97   *
  98   * If a row is too short, it is padded with empty cells ([""]).  If
  99   * a row is too long, it is truncated.
 100   *
 101   * You would typically call this function as:
 102   *
 103   * {v
 104   * let header, data = match csv with h :: d -> h, d | [] -> assert false;;
 105   * let data = Csv.associate header data;;
 106   * v}
 107   *
 108   * The header strings are shared, so the actual space in memory consumed
 109   * by the spreadsheet is not much larger.
 110   *)
 111
 112 val print : ?separator:char -> t -> unit
 113 (** Print string list list - same as [save_out stdout] *)
 114
 115 val save_out : ?separator:char -> out_channel -> t -> unit
 116 (** Save string list list to a channel. *)
 117
 118 val save : ?separator:char -> string -> t -> unit
 119 (** Save string list list to a file. *)
 120
 121 val print_readable : t -> unit
 122 (** Print the CSV data to [stdout] in a human-readable format.  Not much
 123   * is guaranteed about how the CSV is printed, except that it will be
 124   * easier to follow than a "raw" output done with {!print}.  This is
 125   * a one-way operation.  There is no easy way to parse the output of
 126   * this command back into CSV data.
 127   *)
 128 val save_out_readable : out_channel -> t -> unit
 129 (** As for {!print_readable}, allowing the output to be sent to a channel. *)