Merge pull request #15 from ws-garcia/TSV-files-support

TSV files support

Author: ws-garcia

README.md

@@ -6,10 +6,16 @@
 
 VBA CSV interface is a class module developed to accomplish the data exchange task between VBA arrays and CSV files at high speed. Projects from [@sdkn104](https://github.com/sdkn104/VBA-CSV) and [@Senipah](https://github.com/Senipah/VBA-Better-Array), both on Github, were used for comparative performance purposes.
 
-The parser is compatible with those CSV files compliant with the RFC-4180 specs, but add some useful features like: 
-* In-line comments (with a user-defined character). See [Papa Parse](https://www.papaparse.com/) project.
-* Skip blanks lines and empty ones.
-* User-defined escape character (option not available in _Power Query for Excel 2019_ and with some inconsistences when use the _From Text(Legacy)_ wizard)[[1]](#1).
+## Advantages
+* Writes and reads files at high speed.
+* Supports those CSV's that follows the RFC-4180 specs.
+* Supports [Tab Separated Values(TSV)](https://www.iana.org/assignments/media-types/text/tab-separated-values) files. Gracefully handles line-breaks inside TSV fields enclosed in double-quotes.
+* Auto exclude any quote mark when data is imported.
+* Allows an user-defined escape token (option not available in _Power Query for Excel 2019_ and with some inconsistences when user launch the _From Text(Legacy)_ wizard)[[1]](#1).
+* Supports One-dimensional arrays, Two-dimensional arrays and [jagged arrays](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/arrays/jagged-arrays).
+* User has the option to import only certain range of records from given file.
+* Supports in-line comments (with a user-defined character). See [Papa Parse](https://www.papaparse.com/) project.
+* Supports blanks lines and empty ones.
 
 <a id="1">[1]</a> 
 Power Query, and its legacy counterpart, was not able to handle fields’ embedded line breaks when the CSV's "Text qualifier" is a Single Quote or the Apostrophe char.

docs/api/enumerations/escapetokens.md

@@ -0,0 +1,40 @@
+---
+title: EscapeTokens
+parent: Enumerations
+grand_parent: API
+nav_order: 1
+---
+
+# EscapeTokens Enum
+{: .fs-9 }
+
+Provides a list of constants for use to configure the char used as escape one.
+{: .fs-6 .fw-300 }
+
+---
+
+## Parts
+
+|**_Constant_**|**_Member name_**|
+|:----------|:----------|
+|0|*NullChar*|
+|1|*Apostrophe*|
+|2|*DoubleQuotes*|
+
+---
+
+## Syntax
+
+*variable* = `EscapeTokens`.*Constant*
+
+>📝**Note**
+>{: .text-grey-lt-000 .bg-green-000 }
+>The `EscapeTokens.NullChar` value is used with the`QuotationMode.All` setting to indicates the CSV/TSV file does not use any escape char in its whole length. This values combination conduces the file to be parse/write assuming the `FieldsDelimiter` property is enough for the import/export operations.
+>
+>In the case the `FieldsDelimiter` property is not enough for successfully done the import/export operations, the `EscapeTokens.DoubleQuotes` value would be used for parse/write an CSV/TSV having fields to be escaped with double quote and the `EscapeTokens.Apostrophe` values for parse/write a file having fields to be escaped with the apostrophe, using the `QuotationMode.Critical` mode.
+{: .text-grey-dk-300 .bg-grey-lt-000 }
+
+See also
+: [EscapeToken Property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/escapetoken.html), [QuotationMode Enumeration](https://ws-garcia.github.io/VBA-CSV-interface/api/enumerations/quotationmode.html), [FieldsDelimiter Property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/fieldsdelimiter.html).
+
+[Back to Enumerations overview](https://ws-garcia.github.io/VBA-CSV-interface/api/enumerations/)

docs/api/enumerations/escapetype.md

@@ -8,7 +8,7 @@ nav_order: 2
 # QuotationMode Enum
 {: .fs-9 }
 
-Provides a list of constants to configure the CSV parsing/writing operation behavior.
+Provides a list of constants to configure the CSV/TSV parsing/writing operation behavior.
 {: .fs-6 .fw-300 }
 
 ---
@@ -28,10 +28,10 @@ Provides a list of constants to configure the CSV parsing/writing operation beha
 
 >📝**Note**
 >{: .text-grey-lt-000 .bg-green-000 }
->The `QuotationMode.Critical` value, default one, is used to indicates the CSV file must use escape char only in fields having special char. The `QuotationMode.All` value most be used for those CSV files in wich all its fields will be escaped with the escape char given with the `EscapeChar` property.
+>The `QuotationMode.Critical` value, default one, is used to indicates the file must use escape char only in fields having special char. The `QuotationMode.All` value most be used for those files in wich all its fields will be escaped with the escape char given with the `EscapeToken` property.
 {: .text-grey-dk-300 .bg-grey-lt-000 }
 
 See also
-: [EscapeChar Property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/escapechar.html).
+: [EscapeToken Property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/escapetoken.html).
 
 [Back to Enumerations overview](https://ws-garcia.github.io/VBA-CSV-interface/api/enumerations/)

docs/api/enumerations/quotationmode.md

@@ -39,11 +39,11 @@ See also
 
 The `DumpToArray` method makes a copy of all the data stored in the current instance. The data is returned in the *OutPutArray* parameter for avoid additional data copies in the internals.
 
-The dumped data will be successively erased from memory, in other words, the current instance will doesn't hold the read CSV data any more. In the same way, the `DumpToArray` method doesn’t perform any modifications to the *OutPutArray* array for subsequent calls not preceded by one `ImportFromCSV` or `ImportFromCSVstring` method call.
+The dumped data will be successively erased from memory, in other words, the current instance will doesn't hold the read CSV/TSV data any more. In the same way, the `DumpToArray` method doesn’t perform any modifications to the *OutPutArray* array for subsequent calls not preceded by one `ImportFromCSV` or `ImportFromCSVstring` method call.
 
 >⚠️**Caution**
 >{: .text-grey-lt-000 .bg-green-000 }
->The data is always returned in a Two-dimensional array, even when the imported CSV file only contain a field per record.
+>The data is always returned in a Two-dimensional array, even when the imported file only contain a field per record.
 {: .text-grey-dk-300 .bg-yellow-000 }
 
 [Back to Methods overview](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/)

docs/api/methods/dumptoarray.md

@@ -42,7 +42,7 @@ See also
 
 The `DumpToJaggedArray` method makes a copy of all the data stored in the current instance. The data is returned in the *OutPutArray* parameter for avoid additional data copies in the internals.
 
-The dumped data will be successively erased from memory, in other words, the current instance will doesn't hold the read CSV data any more. In the same way, the `DumpToJaggedArray` method doesn’t perform any modifications to the *OutPutArray* array for subsequent calls not preceded by one `ImportFromCSV` or `ImportFromCSVstring` method call.
+The dumped data will be successively erased from memory, in other words, the current instance will doesn't hold the read CSV/TSV data any more. In the same way, the `DumpToJaggedArray` method doesn’t perform any modifications to the *OutPutArray* array for subsequent calls not preceded by one `ImportFromCSV` or `ImportFromCSVstring` method call.
 
 >📝**Note**
 >{: .text-grey-lt-000 .bg-green-000 }

docs/api/methods/dumptojaggedarray.md

@@ -60,5 +60,5 @@ See also
 
 When the *WBookName* parameter is omitted the data is dumped into the Workbook that holds the CSV interface's *VBAProject*. Omitting the *SheetName* parameter adds a new Worksheet to the desired Workbook. Also, if the *RngName* parameter is omitted the data will dumped starting on the "A1" named cell in the desired Worksheet.
 
-The dumped data will be successively erased from memory, in other words, the current instance will doesn't hold the read CSV data any more. In the same way, the `DumpToSheet` method doesn’t perform any action for subsequent calls not preceded by one `ImportFromCSV` or `ImportFromCSVstring` method call.
+The dumped data will be successively erased from memory, in other words, the current instance will doesn't hold the read CSV/TSV data any more. In the same way, the `DumpToSheet` method doesn’t perform any action for subsequent calls not preceded by one `ImportFromCSV` or `ImportFromCSVstring` method call.
 [Back to Methods overview](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/)

docs/api/methods/dumptosheet.md

@@ -8,7 +8,7 @@ nav_order: 5
 # ExportToCSV
 {: .fs-9 }
 
-Exports an array's content to a CSV file.
+Exports an array's content to a CSV/TSV file.
 {: .fs-6 .fw-300 }
 
 ---
@@ -44,16 +44,16 @@ _None_
 
 >📝**Note**
 >{: .text-grey-lt-000 .bg-green-000 }
->Before invoke the `ExportToCSV` method, the user must to open a connection to the CSV file. Passing a variable that isn't an array will cause an error and the operation aborts. 
+>Before invoke the `ExportToCSV` method, the user must to open a connection to the file. Passing a variable that isn't an array will cause an error and the operation aborts. 
 {: .text-grey-dk-300 .bg-grey-lt-000 }
 
 See also
-: [OpenConnection method](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/openconnection.html), [FieldsDelimiter property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/fieldsdelimiter.html), [RecordsDelimiter property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/recordsdelimiter.html), [EscapeChar property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/escapechar.html).
+: [OpenConnection method](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/openconnection.html), [FieldsDelimiter property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/fieldsdelimiter.html), [RecordsDelimiter property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/recordsdelimiter.html), [EscapeToken property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/escapetoken.html).
 
 ---
 
 ## Behavior
 
-The `FieldsDelimiter`, `RecordsDelimiter` and `EscapeChar` properties sets the method's behavior to the needs.
+The `FieldsDelimiter`, `RecordsDelimiter` and `EscapeToken` properties sets the method's behavior to the needs.
 
 [Back to Methods overview](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/)

docs/api/methods/exporttocsv.md

@@ -8,7 +8,7 @@ nav_order: 6
 # GetDataFromCSV
 {: .fs-9 }
 
-Dumps a CSV file content to a string variable
+Dumps a CSV/TSV file content to a string variable
 {: .fs-6 .fw-300 }
 
 ---
@@ -27,7 +27,7 @@ The required *csvPathAndFilename* argument is an identifier specifying a `String
 
 >📝**Note**
 >{: .text-grey-lt-000 .bg-green-000 }
->The *csvPathAndFilename* parameter must be the full path to the target CSV file, this means, the parameter holds the folder path, the file name and the ".csv" extension.
+>The *csvPathAndFilename* parameter must be the full path to the target file, this means, the parameter holds the folder path, the file name and the extension.
 {: .text-grey-dk-300 .bg-grey-lt-000 }
 
 ## Behavior

docs/api/methods/getdatafromcsv.md

@@ -8,7 +8,7 @@ nav_order: 7
 # ImportFromCSV
 {: .fs-9 }
 
-Imports a CSV file's content to the current instance.
+Imports a CSV/TSV file's content to the current instance.
 {: .fs-6 .fw-300 }
 
 ---
@@ -44,22 +44,22 @@ _None_
 
 >📝**Note**
 >{: .text-grey-lt-000 .bg-green-000 }
->If the *HeadersOmission* parameter is set to `True`, the CSV file headers, first record, will be ignored by the parser only when the `StartingRecord` property is set to 1. 
+>If the *HeadersOmission* parameter is set to `True`, the file headers, first record, will be ignored by the parser only when the `StartingRecord` property is set to 1. 
 >The *PassControlToOS* parameter allows user to pass control to the operating system. Control is returned after the operating system has finished processing the events in its queue.
 {: .text-grey-dk-300 .bg-grey-lt-000 }
 
 See also
-: [OpenConnection method](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/openconnection.html), [FieldsDelimiter property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/fieldsdelimiter.html), [RecordsDelimiter property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/recordsdelimiter.html), [EscapeChar property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/escapechar.html), [StartingRecord property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/startingrecord.html), [EndingRecord property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/endingrecord.html), [CommentLineIndicator property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/commentlineindicator.html).
+: [OpenConnection method](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/openconnection.html), [FieldsDelimiter property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/fieldsdelimiter.html), [RecordsDelimiter property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/recordsdelimiter.html), [EscapeToken property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/escapetoken.html), [StartingRecord property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/startingrecord.html), [EndingRecord property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/endingrecord.html), [CommentsToken property](https://ws-garcia.github.io/VBA-CSV-interface/api/properties/commentstoken.html).
 
 ---
 
 ## Behavior
 
-User can set `CommentLineIndicator` property for those CSV files having a combination of empties lines, blanks lines or commented ones for parse the file ONLY when the parser is working on `QuotationMode.Critical` mode. In that mode, the cited lines are simply skipped, leaving no empty values between records separated by this kind of lines. In other words, if the CSV file holds a record and then some special lines (blank, empty or commented) and then another record, the second record will be saved contiguous to the first record ignoring the lines between both.
+User can set `CommentsToken` property for those files having a combination of empties lines, blanks lines or commented ones for parse the file ONLY when the parser is working on `QuotationMode.Critical` mode. In that mode, the cited lines are simply skipped, leaving no empty values between records separated by this kind of lines. In other words, if the file holds a record and then some special lines (blank, empty or commented) and then another record, the second record will be saved contiguous to the first record ignoring the lines between both.
 
 >⚠️**Caution**
 >{: .text-grey-lt-000 .bg-green-000 }
->Before invoke the `ImportFromCSV` method, the user must to open a connection to the CSV file. If the CSV file has no data, this is the file is an empty one, the `ImportFromCSV` method returns an empty array, that is, an array bounded from 0 to -1 and holding no elements and no data.
+>Before invoke the `ImportFromCSV` method, the user must to open a connection to the file. If the target file has no data (the file is an empty one) the `ImportFromCSV` method returns an empty array, that is, an array bounded from 0 to -1 and holding no elements and no data.
 {: .text-grey-dk-300 .bg-yellow-000 }
 
 [Back to Methods overview](https://ws-garcia.github.io/VBA-CSV-interface/api/methods/)