agnes API

agnes is a mature javascript library for converting between json and csv.

Include agnes in your page like this.

<script type="text/javascript" src="agnes.js"></script>

If you're very clever then you might use a loader or something.

Get agnes here:

free source code!

She hasn't been minified: I leave that as an exercise for the reader.

Her unit tests are here, and a demonstration of her prowess is here. Her API is described below.

The girl herself is comprised of the following functions, which are documented (with executable examples) below.

jargon

agnes expects you to know these terms:

• json - javascript object notation.
• csv - comma separated values, but really refers to text separated by any form of delimiter.
• row - a row of data is sometimes called a line or a record.
• field - a field of data is sometimes called a cell or a column.
• row delimiter - the character (or string) that separates two rows in csv. This is typically a linefeed or a carriage return plus line feed.
• field delimiter - the character (or string) that separates two fields in csv.
• qualifier - if a field contains literal delimiters, the field must be 'qualified', i.e. surrounded by qualifiers (i'm doing air quotes here). The qualifier is typically a double-quote. If you need to represent the qualifier character literally it is doubled (i.e. repeated) inside a qualified field.

function: csvToJson

agnes.csvToJson(csvString, rowDelim, fieldDelim)

Parameters: csvString, [rowDelim,] [fieldDelim,] [qualifier]

Converts a piece of separated text into an array of Json objects. Assumes the first row of the csv is the name of the properties to create (i.e. assumes the csv includes a row of column headers).

Standard escaping rules are applied:

• Qualified fields can contain literal separators.
• A doubled qualifier in a qualified field is treated as a single literal qualifier. (Try saying that quickly with your jowls full of boiled sweets)
• Unqualified leading and trailing spaces are trimmed.
• Unqualified empty fields are treated as nulls.

The first parameter, csvString, is the separated text you wish to translate into Json.

The last three parameters (rowDelimiter, fieldDelimiter and qualifier) are optional. If you don't provide them, agnes is crafty when she works out what you want.

If no rowDelimiter is provided she will use whatever the current browser uses as a line separator. She performs a little feature detection to make sure she gets it right. You can use agnes's rowDelimiter() function to see what delimiter she will use by default on a given browser.

If you don't provide a field delimiter, agnes assumes you want a comma. You do want a comma don't you?

And for a qualifying character, agnes assumes you want a double-quote.

examples:

var csvData, jsonData;
csvData = "Name,Age\nJack,12\nJohn,5";
jsonData = agnes.csvToJson(csvData);
alert(JSON.stringify(jsonData,null,' '));

Or, if you're using custom delimiters, just specify them (row delimiter, then column delimiter)

var myCSV = "Name|Age;Jack|12;John|5;";
var myJSON = agnes.csvToJson(myCSV, ";", "|");
alert(JSON.stringify(myJSON,null,' '));

function: jsonToCsv

agnes.jsonToCsv(objects, rowDelim, fieldDelim, qualifier)

Parameters: objects, [rowDelim,] [fieldDelim,] [qualifier]

Converts a json object (or array of json objects) into a separated string. You can optionally provide the row delimiter, field delimiter and qualifying character. If you omit these parameters, sensible defaults are assumed.

The first parameter can be a single Json object, as in the first example, or an array of Json objects, as in the second example. agnes understands.

examples:

alert(agnes.jsonToCsv({ "name" : "Mary" }));

agnes is not concerned with case sensitivity.

var jsonData, csvData;
jsonData = [{ "name" : "Mary", "age" : 81, "Occupation": "Seamstress" }, { "Name" : "Alice", "Age" : 403, "Occupation" : "Governess" }];
csvData = agnes.jsonToCsv(jsonData);
alert(csvData);

Here's an example of using those last three parameters to specify the row delimiter, the field delimiter, and how the fields are qualified.

var jsonData, csvData;
jsonData = [{ "name" : "fred", "age" : 22}];
csvData = agnes.jsonToCsv(jsonData, "\r\n", "|", '"');
alert(csvData);

If you are sending in an array of Json objects, agnes expects that each object has the same properties as the first object, and that those properties are in the same order each time. Furthermore, no property is itself an object. Otherwise agnes will be most perturbed. For example...

var jsonData, csvData;
jsonData = [{ "name" : "Mary", "age" : 96, "height" : "4ft3", "drunk" : null },
{ "name" : "Alice", "height" : "4ft1", "ideas" : {"political":"yes", religious: "No!"} }];
csvData = agnes.jsonToCsv(jsonData);
alert(csvData);

function: rowDelimiter

agnes.rowDelimiter()

Determines the standard line ending used on your current browser. Does your current browser use just a carriage return? Or does it use a carriage return plus a line feed?

Note that agnes does not use old school 'agent' investigation, but the more mature approach of 'feature detection' -- making sure she doesn't get tricked into a wrong answer.

example:

There's not much to show here. Just one example:

var delim = agnes.rowDelimiter();
// in order to show you the invisible characters
// in the result, i now need to escape it...
delim = delim.replace("\r","\\r");
delim = delim.replace("\n","\\n");
alert("the standard line separator on this browser seems to be... " + delim);

That's all there is to it.

Have fun.

While you're here, here's a sample for converting from Json to CSV and back again.