Documentation

Convert CSV to JSON

Delimited data can be parsed out of strings or files. Files that are parsed can be local or remote. Local files are opened with FileReader, and remote files are downloaded with XMLHttpRequest.

Parse string

Papa.parse(csvString[, config])

• csvString is a string of delimited text to be parsed.
• config is an optional config object.
• Returns a parse results object (if not streaming or using worker).

Parse local files

Papa.parse(file, config)

• file is a File object obtained from the DOM.
• config is a config object which contains a callback.
• Doesn't return anything. Results are provided asynchronously to a callback function.

Parse remote file

Papa.parse(url, {
	download: true,
	// rest of config ...
})

• url is the path or URL to the file to download.
• The second argument is a config object where download: true is set.
• Doesn't return anything. Results are provided asynchronously to a callback function.

Using jQuery to select files

$('input[type=file]').parse({
	config: {
		// base config to use for each file
	},
	before: function(file, inputElem)
	{
		// executed before parsing each file begins;
		// what you return here controls the flow
	},
	error: function(err, file, inputElem, reason)
	{
		// executed if an error occurs while loading the file,
		// or if before callback aborted for some reason
	},
	complete: function()
	{
		// executed after all files are complete
	}
});

• Select the file input elements with files you want to parse.
• before is an optional callback that lets you inspect each file before parsing begins. Return an object like:

  {
  	action: "abort",
  	reason: "Some reason",
  	config: // altered config...
  }

  to alter the flow of parsing. Actions can be "abort" to skip this and all other files in the queue, "skip" to skip just this file, or "continue" to carry on (equivalent to returning nothing). reason can be a reason for aborting. config can be a modified configuration for parsing just this file.
• The complete callback shown here is executed after all files are finished and does not receive any data. Use the complete callback in config for per-file results.

Convert JSON to CSV

Papa's unparse utility writes out correct delimited text strings given an array of arrays or an array of objects.

Unparse

Papa.unparse(data[, config])

• Returns the resulting delimited text as a string.
• data can be one of:
  • An array of arrays
  • An array of objects
  • An object explicitly defining fields and data
• config is an optional object with any of these properties:

  // defaults shown
  {
  	quotes: false,
  	quoteChar: '"',
  	escapeChar: '"',
  	delimiter: ",",
  	header: true,
  	newline: "\r\n"
  }

  Set quotes to true to always enclose each field in quotes, or an array of true/false values correlating to specific to columns to force-quote. The character used to quote can be customized using quoteChar. The character used to escape the quoteChar within a field can be customized using escapeChar. The delimiter can be any valid delimiting character. The newline character(s) may also be customized. Setting header to false will omit the header row.

Examples

// Two-line, comma-delimited file
var csv = Papa.unparse([
	["1-1", "1-2", "1-3"],
	["2-1", "2-2", "2-3"]
]);

// With implicit header row
// (keys of first object populate header row)
var csv = Papa.unparse([
	{
		"Column 1": "foo",
		"Column 2": "bar"
	},
	{
		"Column 1": "abc",
		"Column 2": "def"
	}
]);

// Specifying fields and data explicitly
var csv = Papa.unparse({
	fields: ["Column 1", "Column 2"],
	data: [
		["foo", "bar"],
		["abc", "def"]
	]
});

The Parse Config Object

The parse function may be passed a configuration object. It defines settings, behavior, and callbacks used during parsing. Any properties left unspecified will resort to their default values.

Default Config With All Options

Config Options

The Parse Result Object

A parse result always contains three objects: data, errors, and meta. Data and errors are arrays, and meta is an object. In the step callback, the data array will only contain one element.

Result Structure

{
	data:   // array of parsed data
	errors: // array of errors
	meta:   // object with extra info
}

• data is an array of rows. If header is false, rows are arrays; otherwise they are objects of data keyed by the field name.
• errors is an array of errors.
• meta contains extra information about the parse, such as delimiter used, the newline sequence, whether the process was aborted, etc. Properties in this object are not guaranteed to exist in all situations.

Data

// Example (header: false)
[
	["Column 1", "Column 2"],
	["foo", "bar"],
	["abc", "def"]
]

// Example (header: true)
[
	{
		"Column 1": "foo",
		"Column 2": "bar"
	},
	{
		"Column 1": "abc",
		"Column 2": "def"
	}
]

• If header row is enabled and more fields are found on a row of data than in the header row, an extra field will appear in that row called __parsed_extra. It contains an array of all data parsed from that row that extended beyond the header row.

Errors

// Error structure
{
	type: "",     // A generalization of the error
	code: "",     // Standardized error code
	message: "",  // Human-readable details
	row: 0,       // Row index of parsed data where error is
	
}

• The error type will be one of "Quotes", "Delimiter", or "FieldMismatch".
• The code may be "MissingQuotes", "UndetectableDelimiter", "TooFewFields", or "TooManyFields" (depending on the error type).
• Just because errors are generated does not necessarily mean that parsing failed. The worst error you can get is probably MissingQuotes.

Meta

{
	delimiter: // Delimiter used
	linebreak: // Line break sequence used
	aborted:   // Whether process was aborted
	fields:    // Array of field names
	truncated: // Whether preview consumed all input
}

• Not all meta properties will always be available. For instance, fields is only given when header row is enabled.

Extras

There's a few other things that Papa exposes to you that weren't explained above.

Read-Only

Configurable