1 package org.djutils.data.csv;
2
3 import java.io.FileReader;
4 import java.io.FileWriter;
5 import java.io.IOException;
6 import java.io.Reader;
7 import java.io.Writer;
8
9 import org.djutils.data.Table;
10 import org.djutils.data.serialization.TextSerializationException;
11 import org.djutils.io.CompressedFileWriter;
12
13 import de.siegmar.fastcsv.writer.LineDelimiter;
14
15 /**
16 * TsvData takes care of reading and writing of table data in Tab-Separated-Value format. The class can be used, e.g., as
17 * follows:
18 *
19 * <pre>
20 * Table dataTable = new ListTable("data", "dataTable", columns);
21 * Writer writer = new FileWriter("c:/data/data.tsv");
22 * Writer metaWriter = new FileWriter("c:/data/data.meta.tsv");
23 * TsvData.writeData(writer, metaWriter, dataTable);
24 * </pre>
25 * <p>
26 * Copyright (c) 2020-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
27 * BSD-style license. See <a href="https://djutils.org/docs/current/djutils/licenses.html">DJUTILS License</a>.
28 * </p>
29 * @author <a href="https://github.com/averbraeck">Alexander Verbraeck</a>
30 * @author <a href="https://tudelft.nl/staff/p.knoppers-1">Peter Knoppers</a>
31 * @author <a href="https://dittlab.tudelft.nl">Wouter Schakel</a>
32 */
33 public final class TsvData
34 {
35 /**
36 * Utility class, no public constructor.
37 */
38 private TsvData()
39 {
40 // utility class
41 }
42
43 /**
44 * Write the data from the data table in TSV format. The writer writes the data, whereas the metaWriter writes the metadata.
45 * The metadata consists of a TSV file with three columns: the id, the description, and the class. The first row after the
46 * header contains the id, description, and class of the data table itself. The second and further rows contain information
47 * about the columns of the data table.
48 * @param writer Writer; the writer that writes the data, e.g. to a file
49 * @param metaWriter Writer; the writer for the metadata
50 * @param dataTable Table; the data table to write
51 * @throws IOException on I/O error when writing the data
52 * @throws TextSerializationException on unknown data type for serialization
53 */
54 public static void writeData(final Writer writer, final Writer metaWriter, final Table dataTable)
55 throws IOException, TextSerializationException
56 {
57 CsvData.writeData(writer, metaWriter, dataTable, '\t', '\u0000', LineDelimiter.CRLF);
58 }
59
60 /**
61 * Write the data from the data table in TSV format.
62 * @param filename String; the file name to write the data to
63 * @param metaFilename String; the file name to write the metadata to
64 * @param dataTable Table; the data table to write
65 * @throws IOException on I/O error when writing the data
66 * @throws TextSerializationException on unknown data type for serialization
67 */
68 public static void writeData(final String filename, final String metaFilename, final Table dataTable)
69 throws IOException, TextSerializationException
70 {
71 try (FileWriter fw = new FileWriter(filename); FileWriter mfw = new FileWriter(metaFilename);)
72 {
73 writeData(fw, mfw, dataTable);
74 }
75 }
76
77 /**
78 * Write the data from the data table in TSV format. The data file and meta data file are zipped. The metadata consists of a
79 * TSV file with three columns: the id, the description, and the class. The first row after the header contains the id,
80 * description, and class of the data table itself. The second and further rows contain information about the columns of the
81 * data table.
82 * @param writer Writer; the writer that writes the data, e.g. to a file
83 * @param tsvName String; name of the TSV file within the zip file
84 * @param metaName String; name of the meta data file within the zip file
85 * @param table Table; the data table to write
86 * @throws IOException on I/O error when writing the data
87 * @throws TextSerializationException on unknown data type for serialization
88 */
89 public static void writeZippedData(final CompressedFileWriter writer, final String tsvName, final String metaName,
90 final Table table) throws IOException, TextSerializationException
91 {
92 CsvData.writeZippedData(writer, tsvName, metaName, table, '\t', '\u0000', LineDelimiter.CRLF);
93 }
94
95 /**
96 * Read the data from the TSV-file into the data table. Use the metadata to reconstruct the data table.
97 * @param reader Reader; the reader that can read the data, e.g. from a file
98 * @param metaReader Reader; the writer for the metadata
99 * @return dataTable the data table reconstructed from the meta data and filled with the data
100 * @throws IOException on I/O error when reading the data
101 * @throws TextSerializationException on unknown data type for serialization
102 */
103 public static Table readData(final Reader reader, final Reader metaReader) throws IOException, TextSerializationException
104 {
105 return CsvData.readData(reader, metaReader, '\t', '\u0000');
106 }
107
108 /**
109 * Read the data from the TSV-file into the data table. Use the metadata to reconstruct the data table.
110 * @param filename String; the file name to read the data from
111 * @param metaFilename String; the file name to read the metadata from
112 * @return dataTable the data table reconstructed from the meta data and filled with the data
113 * @throws IOException on I/O error when reading the data
114 * @throws TextSerializationException on unknown data type for serialization
115 */
116 public static Table readData(final String filename, final String metaFilename)
117 throws IOException, TextSerializationException
118 {
119 try (FileReader fr = new FileReader(filename); FileReader mfr = new FileReader(metaFilename);)
120 {
121 return readData(fr, mfr);
122 }
123 }
124
125 /**
126 * Read the data from a TSV-file inside a zip file. The metadata file should be in the same zipfile. Use the metadata to
127 * reconstruct the data table.
128 * @param fileName String; file name of the zip file
129 * @param tsvName String; name of the TSV-file, without path
130 * @param metaName String; name of the metadata file, without path
131 * @return Table the data table reconstructed from the meta data and filled with the data
132 * @throws IOException when the CSV data was not formatted right
133 * @throws TextSerializationException on unknown data type for serialization
134 */
135 public static Table readZippedData(final String fileName, final String tsvName, final String metaName)
136 throws IOException, TextSerializationException
137 {
138 return CsvData.readZippedData(fileName, tsvName, metaName, '\t', '\u0000');
139 }
140
141 }