README

This is a small PHP library for working with the tab-separated values format (TSV) without any dependencies.

Installation

Install the library via Composer:

composer require maximal/tsv

Usage

require_once __DIR__ . '/vendor/autoload.php';

use Maximal\Tsv\Tsv;

// Get TSV text for the given two-dimensional data table
$tsvString = Tsv::getTsv($dataTable);
// Every cell value in `Tsv::getTsv()` call will be cast to string using `(string)$value`.
// Make sure all values are castable, e.g. all the classes have `__toString()` methods.

// Get two-dimensional data table for the given TSV text
$table = Tsv::getTable($tsvString);

Value escaping

This library uses the most common special characters escaping:

Escape Sequence	Character
`\t`	tab
`\r`	carriage return
`\n`	line feed
`\\`	backslash

This works two-way: TSV → array → TSV conversion gives the initial TSV text.

Transitive Equivalence

Let’s review an example of chained table → TSV → table → TSV conversion:

// Initial two-dimensional data table
$dataTable = [[/* ... */], [/* ... */], /* ... */];
// $dataTable is `array<array<mixed>>`

// TSV text from the initial data
$tsv = Tsv::getTsv($dataTable);
// $tsv is `string`

// Data table taken back from resulting TSV text
$tableFromTsv = Tsv::getTable($tsv);
// $tableFromTsv is `list<list<string>>`

// TSV text again
$tsvFromTable = Tsv::getTsv($dataTable);
// $tsvFromTable is `string`

// `$tsv === $tsvFromTable` equality is guaranteed
// `$dataTable === $tsvFromTable` equality is NOT guaranteed

Here, $tsv text is guaranteed to be equal to $tsvFromTable: both are strings and similarly formatted.

However, $dataTable is not guaranteed to be equal to $tableFromTsv because the initial array can have various keys and different value types (array<array<mixed>>) while the resulting array is strictly a collection of list of strings (list<list<string>>).

Coding Style

PER-3T / PSR-12T (PHP’s standard PER-3 / PSR-12 with SmartTabs instead of spaces).

maximal / tsv

Maintainers

Details