|
|
@@ -0,0 +1,63 @@
|
|
|
+Text.CSV is a CSV (Comma Separated Values) file parser. CSV files are a popular format for exchanging data between
|
|
|
+applications, as they are simple, flexible, and can be easily generated or consumed by various software programs.
|
|
|
+
|
|
|
+We will explore the CSV file format in depth, and learn how to use the Text.CSV to load and manipulate CSV files in
|
|
|
+BlitzMax applications.
|
|
|
+
|
|
|
+## CSV File Format
|
|
|
+
|
|
|
+CSV files are plain text files that store tabular data, making them suitable for representing spreadsheet-like
|
|
|
+structures. Each row in a CSV file corresponds to a single line of text, and columns within a row are separated by
|
|
|
+a delimiter, which is typically a comma (`,`) or a tab (`\t`). CSV files can store various types of data, such as
|
|
|
+numbers, text, and dates, and they can accommodate both simple and complex data structures.
|
|
|
+
|
|
|
+There are several reasons why one might choose to use the CSV file format over other formats:
|
|
|
+
|
|
|
+1. **Simplicity** : CSV files are easy to create and understand, as they have a straightforward structure and use plain
|
|
|
+text encoding.
|
|
|
+2. **Portability** : CSV files can be read and written by a wide variety of software applications, including
|
|
|
+spreadsheet programs, databases, and data analysis tools.
|
|
|
+3. **Size** : Because CSV files are plain text, they can be compressed efficiently, reducing storage and
|
|
|
+transmission costs.
|
|
|
+4. **Human Readable** : Unlike binary formats, CSV files can be opened and examined with a simple text editor,
|
|
|
+making it easier to identify and troubleshoot issues.
|
|
|
+
|
|
|
+To create a valid CSV file that can be loaded into Text.CSV, you should follow these basic rules:
|
|
|
+
|
|
|
+1. **Consistent Delimiters** : Use the same delimiter character (e.g., a comma or a tab) to separate columns
|
|
|
+throughout the entire file. Mixing delimiters within the same file can lead to parsing errors.
|
|
|
+2. **Quoting** : If a field value contains the delimiter character, newlines, or double quotes, enclose the value
|
|
|
+in double quotes. For example, `"John Doe", 25, "123 Main St, Apt 4B"` has the address field quoted because it contains
|
|
|
+a comma. To represent a double quote within a quoted field, use two double quotes together, like `""`. For example,
|
|
|
+`"He said, ""Hello"""`
|
|
|
+3. **Header Row** : It's a good practice to include a header row at the beginning of the file that lists the column
|
|
|
+names. This makes it easier to understand the structure and content of the file.
|
|
|
+4. **Consistent Rows** : Ensure that each row has the same number of columns. This helps prevent parsing errors and
|
|
|
+ensures that the data can be processed correctly.
|
|
|
+5. **UTF-8 Encoding** : Save the file using UTF-8 encoding to ensure that it can be read correctly by the parser.
|
|
|
+
|
|
|
+## Parsing CSV Files
|
|
|
+
|
|
|
+You'll need to create an instance of the #TCsvParser type, and then use its various methods to interact with the
|
|
|
+CSV data. The parser accepts input streams in UTF-8 format.
|
|
|
+
|
|
|
+Here is a basic example of how to use the module:
|
|
|
+
|
|
|
+```blitzmax
|
|
|
+SuperStrict
|
|
|
+
|
|
|
+Framework BRL.StandardIO
|
|
|
+Import Text.CSV
|
|
|
+
|
|
|
+Local options:TCsvOptions = New TCsvOptions
|
|
|
+options.delimiter = ","
|
|
|
+
|
|
|
+Local parser:TCsvParser = TCsvParser.Parse("path/to/your/csvfile.csv", options)
|
|
|
+
|
|
|
+While parser.NextRow() = ECsvStatus.row
|
|
|
+ Local row:TCsvRow = parser.GetRow()
|
|
|
+ Print row.GetValue("column_name")
|
|
|
+Wend
|
|
|
+
|
|
|
+parser.Free()
|
|
|
+```
|
Brucey