1 (** csv.mli - comma separated values parser
3 * $Id: csv.mli,v 1.8 2006-02-23 15:24:25 rich Exp $
6 type t = string list list
7 (** Representation of CSV files. *)
9 exception Bad_CSV_file of string
10 (** Badly formed CSV files throw this exception. *)
13 (** Work out the number of lines in a CSV file. *)
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
21 val load_in : ?separator:char -> in_channel -> t
23 * @param chan Input file stream
26 val load : ?separator:char -> string -> t
28 * @param filename CSV filename.
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.
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].
40 * @param f Callout function.
41 * @param chan Input file stream.
44 val trim : ?top:bool -> ?left:bool -> ?right:bool -> ?bottom:bool -> t -> t
45 (** This takes a CSV file and trims empty cells.
47 * All four of the option arguments ([~top], [~left], [~right], [~bottom])
50 * The exact behaviour is:
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.
56 * [~top]: If true, remove any empty rows (no cells, or containing just empty
57 * cells) from the top of the CSV structure.
59 * [~bottom]: If true, remove any empty rows from the bottom of the
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.
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
75 val is_square : t -> bool
76 (** Return true iff the CSV is "square" (actually rectangular). This
77 * means that each row has the same number of cells.
80 val set_columns : int -> t -> t
81 (** [set_columns cols csv] makes the CSV data square by forcing the width
82 * to the given number of [cols]. Any short rows are padded with blank
83 * cells. Any long rows are truncated.
86 val set_rows : int -> t -> t
87 (** [set_rows rows csv] makes the CSV data have exactly [rows] rows
88 * by adding empty rows or truncating rows as necessary.
90 * Note that [set_rows] does not make the CSV square. If you want it
91 * to be square, call either {!Csv.square} or {!Csv.set_columns} after.
94 val set_size : int -> int -> t -> t
95 (** [set_size rows cols csv] makes the CSV data square by forcing the
96 * size to [rows * cols], adding blank cells or truncating as necessary.
97 * It is the same as calling [set_columns cols (set_rows rows csv)]
100 val sub : int -> int -> int -> int -> t -> t
101 (** [sub r c rows cols csv] returns a subset of [csv]. The subset is
102 * defined as having top left corner at row [r], column [c] (counting
103 * from [0]) and being [rows] deep and [cols] wide.
105 * The returned CSV will be square.
108 val compare : t -> t -> int
109 (** Compare two CSV files for equality, ignoring blank cells at the end
110 * of a row, and empty rows appended to one or the other. This is
111 * "semantic" equality - roughly speaking, the two CSV files would
112 * look the same if opened in a spreadsheet program.
115 val to_array : t -> string array array
116 val of_array : string array array -> t
117 (** Convenience functions to convert to and from a matrix representation.
118 * [to_array] will produce a ragged matrix (not all rows will have the
119 * same length) unless you call {!Csv.square} first.
122 val associate : string list -> t -> (string * string) list list
123 (** [associate header data] takes a block of data and converts each
124 * row in turn into an assoc list which maps column header to data cell.
126 * Typically a spreadsheet will have the format:
128 * header1 header2 header3
129 * data11 data12 data13
130 * data21 data22 data23
134 * This function arranges the data into a more usable form which is
135 * robust against changes in column ordering. The output of the
138 * [ ["header1", "data11"; "header2", "data12"; "header3", "data13"];
139 * ["header1", "data21"; "header2", "data22"; "header3", "data23"];
143 * Each row is turned into an assoc list (see [List.assoc]).
145 * If a row is too short, it is padded with empty cells ([""]). If
146 * a row is too long, it is truncated.
148 * You would typically call this function as:
151 * let header, data = match csv with h :: d -> h, d | [] -> assert false;;
152 * let data = Csv.associate header data;;
155 * The header strings are shared, so the actual space in memory consumed
156 * by the spreadsheet is not much larger.
159 val print : ?separator:char -> t -> unit
160 (** Print string list list - same as [save_out stdout] *)
162 val save_out : ?separator:char -> out_channel -> t -> unit
163 (** Save string list list to a channel. *)
165 val save : ?separator:char -> string -> t -> unit
166 (** Save string list list to a file. *)
168 val print_readable : t -> unit
169 (** Print the CSV data to [stdout] in a human-readable format. Not much
170 * is guaranteed about how the CSV is printed, except that it will be
171 * easier to follow than a "raw" output done with {!Csv.print}. This is
172 * a one-way operation. There is no easy way to parse the output of
173 * this command back into CSV data.
175 val save_out_readable : out_channel -> t -> unit
176 (** As for {!Csv.print_readable}, allowing the output to be sent to a channel.