Home

Table of Contents Processing Tab-Separated Values in jQuery Usage Headers Functions Details Compatibility Future work

Processing Tab-Separated Values in jQuery

Note: For now, at least, the primary home and most up-to-date documentation will be on the Google Code site. Please submit any bugs and comments there.

The jQuery.tsv plugin was inspired by Evan Plaice's jQuery.csv plugin. After adapting that in my project, I found I really needed a proper Tab Separated Values plugin.

Tab,Separated Values format is much simpler (and more limited) than Comma-Separated Values. In particular, there is no possibility of a tab being contained in a value, no quoting, etc.

It's not a very _good_ format, but it's a very _simple_ format and an extremely _common_ format.

The IANA description of the text/tab-separated-values media type appears here:

http://www.iana.org/assignments/media-types/text/tab-separated-values

This package comes with an extensive test suite, and the core TSV functionality is functionally complete.

Usage

Simply load jQuery-tsv after jQuery, and in your code, use it like this:

 
  var tsv = $.tsv.toArrays(data);
  var firstRow = tsv[0];
  

Headers

Unfortunately, while the standard description for the mime type says it should have a header row, in practice, often it will not. There's no way for the code to tell, so you will have to know or guess.

If you supply the `{ stripHeader: true `} header option, the first line will be removed as a header line. It can be retrieved using an index of [-1].

Functions

For details, see the API documentation.

Static Functions:

  * $.tsv.toArrays -- parse an entire TSV string as arrays of values
  * $.tsv.toArray -- parse one line of TSV = as a single array of values

  * $.tsv.toObjects -- parse an entire TSV string as objects
  * $.tsv.toObject -- parse one line of TSV as one object

  * $.tsv.arraysToObjects -- convert an entire array of row arrays to objects.
  * $.tsv.objectsToArrays -- convert an entire array of objects to an array of row arrays.
  * $.tsv.arrayToObject -- convert one row array to an object.
  * $.tsv.objectToArray -- convert one object to a row array.

  * $.tsv.fromArrays -- format an entire array of row arrays to tsv.
  * $.tsv.fromArray -- format a single row array to tsv.
  * $.tsv.fromObjects -- format an entire array of objects to tsv
  * $.tsv.fromObject -- format one object to one line of tsv

  * $.tsv.options -- default values for the various options.

Details

The package provides the following features.

  * Conversion from tsv text to Javascript arrays of array values
    * An array of line arrays, `e.g. `[["header1","header2"], ["val11", "val12"], ["val21", "val22"]]
    * Line-at-a-time, `["val1", "val2"]`
  * Conversion from tsv text to Javascript arrays of objects
    * e.g. `[ {header1: "val11", header2: "val12"}, {header1: "val21", header2: "val22"}]`
    * Column/attribute names can be taken from the tsv header row (if present), or supplied
    * An array of objects, or an object at a time.
  * Conversion from either format above to tsv text.
  * Parsers/formatters can be specified for the data values (so numbers and dates can be read/written as numbers and dates, for example).

Compatibility

Prior versions had alternate names for many of the functions. The older names are deprecated but still available. They will be removed in a future release, after 1.0.

Future work

  * Integrate this directly with jQuery's ajax facilities?
  * Some sort of merger or coordination of API with jQuery-csv?