Mercurial > repos > adam-novak > hexagram
diff hexagram-6ae12361157c/hexagram/jquery.tsv.js @ 0:1407e3634bcf draft default tip
Uploaded r11 from test tool shed.
author | adam-novak |
---|---|
date | Tue, 22 Oct 2013 14:17:59 -0400 |
parents | |
children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/hexagram-6ae12361157c/hexagram/jquery.tsv.js Tue Oct 22 14:17:59 2013 -0400 @@ -0,0 +1,357 @@ +/** + * jQuery-tsv (jQuery Plugin) + * + * Inspired by jQuery-csv by Evan Plaice. + * + * Copyright 2012 by Bob Kerns + * + * This software is licensed as free software under the terms of the MIT License: + * http://www.opensource.org/licenses/mit-license.php + */ + +(function ($) { + // Make sure we have a copy, not original, of $.tsv.options. + function copyOptions(options) { + return $.extend({__copy: true}, options); + } + // Default the options. + function tsvOptions(options) { + if (options) { + if (options.__defaults_applied) { + return options; + } + return $.extend(copyOptions($.tsv.options), options); + } + return copyOptions($.tsv.options); + } + + function tsvColumn(options, index) { + var opts = tsvOptions(options); + return String(opts.columns ? opts.columns[index] : index); + } + + function tsvColumns(options, top) { + if (options.columns) { + return options.columns; + } else { + var cols = Object.keys(top || {}).sort(); + options.columns = cols; + return cols; + } + } + + $.tsv = { + version: "0.957", + /** + * The default set of options. It is not recommended to change these, as the impact will be global + */ + options: { + /** + * If supplied, a function to format a value on output. + * The returned value is used in the output instead of the supplied value. + * If not supplied, it is simply converted to a string. + * + * @param value the value to be formatted. + * @param the options + * @param colnum the column number + * @param colname the column name, if known, or the column number as a string. + * @param rownum the row number + * @returns the value, formatted + */ + formatValue: null, + /** + * If supplied, a function to parse or canonicalize a value on input. + * The returned value is used in place of the input. + * + * @param value the value to be formatted. + * @param the options + * @param colnum the column number + * @param colname the column name, if known, or the column number as a string. + * @param rownum the row number + * @returns the value, parsed + */ + parseValue: null, + /** + * The character sequence to use to separate lines. + */ + lineSeparator: "\n", + /** A RegExp to recognize line separators */ + lineSplitter: /\r?\n/, + /** The character sequence to use to separate values. */ + valueSeparator: "\t", + /** A RegExp to recognize value separators. */ + valueSplitter: /\t/, + /** + * If supplied, a function of one argument to convert a row to an object. + * + * @param row an array of values, e.g. ["1", "2", "3.14"] + * @param options { columns: ["id", "count", "price"] } + * @returns e.g. {id: "1", count: "2", price: "3.14"} + */ + arrayToObject: null, + /** + * If supplied, a function of one argument to convert an object to a row. Typically, this will implement a variant + * of the contract for $.tsv.objectToArray. + * + * @param object an object to be converted to a row, e.g. {id: "1", count: "2", price: "3.14"} + * @param options { columns: ["id", "count", "price"] } + * @returns an array of values, e.g. ["1", "2", "3.14"]. Typically these would be ordered by options.column + */ + objectToArray: null, + /** + * If true, when converting from an array of objects to a TSV string, include the column names as the + * first line. For most purposes, you won't want to override this, but if you're working with tables in sections, + * for example, you'd want to suppress this for the latter segments. + * + * But you are strongly encouraged to use column names whenever possible, especially if you work with objects. + */ + includeHeader: true, + /** + * The starting row number, not counting the header, if any (which is always numbered -1). + * This can be useful for computing subranges of a table, or appending to a table. + */ + startRownum: 0, + // An internal flag, to avoid multiple defaulting steps. + // values are true, if it is this default, or 'copy'. + ___defaults_applied: true, + extend: $.extend + }, + + /** + * Parse one value. This can be overridden in the options. + * @param value the string to parse + * @param options optional: { parseValue: <substitute function> } + * @param colnum the column number + * @param colname the column name, if known, or the column number as a string. + * @param rownum the row number + * @returns the string + */ + parseValue: function parseValue(value, options, colnum, colname, rownum) { + var opts = tsvOptions(options); + if (opts.parseValue) { + // We have an override; use that instead. + return options.parseValue(value, opts, colnum, colname, rownum); + } + return value; + }, + + /** + * Format one value. This can be overridden in the options. + * @param value the value to format + * @param options optional: { formatValue: <substitute function> } + * @param colnum the column number + * @param colname the column name, if known, or the column number as a string. + * @param rownum the row number + */ + formatValue: function formatValue(value, options, rownum, colnum, colname, rownum) { + var opts = tsvOptions(options); + if (opts.formatValue) { + // We have an override; use that instead. + return options.formatValue(value, opts, colnum, colname, rownum); + } + return String(value); + }, + + /** + * $.tsv.toArray(line, options) parses one line of TSV input into an array of values. + * @param line A line with values separated by single tab characters, e.g. "11\t12\t13" + * @param options optional: { valueSplitter: /\t/, parseValue: <a function to parse each value>} + * @param rownum optional: the row number (defaults to 0); + * @returns an array of values, e.g. ["11" "12", "13"] + */ + toArray: function toArray(line, options, rownum) { + var opts = tsvOptions(options); + var valueSplitter = opts.valueSplitter; + rownum = rownum || 0; + var colnum = 0; + function doValue(val) { + var c = colnum++; + return $.tsv.parseValue(val, opts, c, tsvColumn(opts, c), rownum); + } + return line.split(valueSplitter).map(doValue); + }, + + /** + * $.tsv.fromArray(row, options) returns one line of TSV input from an array of values. + * @param array an array of values, e.g. ["11" "12", "13"] + * @param options optional: { valueSeparator: "\t", formatValue: <a function to format each value>} + * @param rownum optional: the row number (defaults to 0); + * @returns A line with values separated by single tab characters, e.g. "11\t12\t13" + */ + fromArray: function fromArray(array, options, rownum) { + var opts = tsvOptions(options); + var valueSeparator = opts.valueSeparator; + var colnum = 0; + function doValue(val) { + var c = colnum++; + return $.tsv.formatValue(val, opts, c, tsvColumn(c), rownum); + } + return array.map(doValue).join(valueSeparator); + }, + + /** + * $.tsv.toArrays(tsv, options) returns an array of arrays, one per line, each containing values from one row. + * @param tsv a tab-separated-values input, e.g. "11\t\12\t13\n21\t22\t23" + * @param options optional: { valueSplitter: /\t/, lineSplitter: /\r?\n/, parseValue: <a function to parse each value> } + * @returns an array of arrays, e.g. [["11", "12", "13"], ["21", "22", "23"]] + */ + toArrays: function toArrays(tsv, options) { + var opts = tsvOptions(options); + var lines = tsv.split(opts.lineSplitter); + var rownum = opts.startRownum || 0; + return lines.map(function doLine(line) { + return $.tsv.toArray(line, opts, rownum++); + }); + }, + + /** + * $.tsv.fromArrays(array, options) returns a TSV string representing the array of row arrays. + * @param array an array of arrays of values. To produce valid TSV, all the arrays should be of the same length. + * @param options optional: { valueSeparator: "\t", lineSeparator: "\n", columns: ["c1", "c2", "c3"], formatValue: <a function to format each value> } + * @returns An tsv string, e.g. "c1\tc2\tc3\n11\t\12\t13\n21\t22\t23" + */ + fromArrays: function fromArrays(array, options) { + var opts = tsvOptions(options); + var first = array.length ? array[0] : []; + var cols = tsvColumns(opts, first); + var rownum = opts.startRownum || 0; + var header = opts.includeHeader ? $.tsv.fromArray(cols, opts, -1) : undefined; + function doRow(row) { + return $.tsv.fromArray(row, opts, rownum++); + } + var rtemp = array.map(doRow); + if (header) { + rtemp.unshift(header); + } + return rtemp.join(opts.lineSeparator); + }, + + /** + * $.tsv.arrayToObject(row, options) returns an object whose fields are named in options.columns, and + * whose values come from the corresponding position in row (an array of values in the same order). + * + * If the columns are not supplied, "0", "1", etc. will be used. + * @param row the values, e.g. ["v1", "v2"] + * @param options optional: { columns: ["name1", "name2"], rowToObject: <optional conversion function to call instead> } + * @param rownum optional: the row number + * @returns an object derived from the elements of the row. + */ + arrayToObject: function arrayToObject(row, options, rownum) { + var opts = tsvOptions(options); + rownum = rownum || 0; + var columns = tsvColumns(opts, row); + if (opts.arrayToObject) { + // We have an override; use that instead. + return opts.arrayToObject(row, opts, rownum); + } + var dict = {}; + for (var j = 0; j < columns.length; j++) { + dict[columns[j]] = row[j]; + } + return dict; + }, + + /** + * $.tsv.arraysToObjects(array, options) returns an array of objects, derived from the array. + * The array must either have the first row be column names, or columns: ["name1", "name2", ...] must be supplied + * in the options. + * @param array an array of arrays of values. [ ["name1", "name2" ...],? ["val1", "val2" ...] ...] + * @param options optional: { columns: ["name1", "name2", ...] } + * @returns An array of objects, [ { name1: val1, name2: val2 ... } ... ] + */ + arraysToObjects: function arraysToObjects(array, options) { + var opts = tsvOptions(options); + if (! opts.columns) { + opts.columns = array.shift(); + } + var rownum = opts.startRownum || 0; + return array.map(function convert(row) { + return $.tsv.arrayToObject(row, opts, rownum++); + }); + }, + + /** + * $.tsv.toObjects(tsv, options) returns an array of objects from a tsv string. + * The string must either have the first row be column names, or columns: ["name1", "name2", ...] must be supplied + * in the options. + * + * @param A TSV string, e.g. "val1\tval2..." or "name1\tname2...\n\val1\val2..." + * @param options optional: { columns ["name1", "name2" ...] } + * @returns an array of objects, e.g. [ {name1: val1, name2: val2 ...} ...] + */ + toObjects: function toObjects(tsv, options) { + var opts = tsvOptions(options); + return $.tsv.arraysToObjects($.tsv.toArrays(tsv, opts), opts); + }, + + /** + * $.tsv.objectToArray(obj, options) Convert one object to an array representation for storing as a TSV line. + * + * @param obj an object to convert to an array representations, e.g. { name1: "val1", name2: "val2" ... } + * @param options optional: { columns: ["name1", "name2"], objectToArray: <a function to use instead> } + * @param rownum optional: the row number + * @result an array, e.g. ["val1", "val2"] + */ + objectToArray: function objectToArray(obj, options, rownum) { + var opts = tsvOptions(options); + var columns = tsvColumns(opts, obj); + rownum = rownum || 0; + if (opts.objectToArray) { + // We have an override; use that instead. + return opts.objectToArray(obj, opts, rownum); + } + var row = []; + for (var j = 0; j < columns.length; j++) { + row.push(obj[columns[j]]); + } + return row; + }, + + /** + * $.tsv.objectsToArrays(array, options) converts an array of objects into an array of row arrays. + * + * @param array An array of objects, e.g. [ { name1: "val1", name2: "val2", ...} ...] + * @param options { columns: ["name1", "name2"...], includeHeaders: true, objectToArray: <optional function to convert each object> } + */ + objectsToArrays: function objectsToArrays(array, options) { + var opts = tsvOptions(options); + var rownum = options.startRownum; + var result = array.map(function convert(obj) { + return $.tsv.objectToArray(obj, opts, rownum++); + }); + return result; + }, + + fromObject: function fromObject(array, options) { + var opts = tsvOptions(options); + return $.tsv.fromArray($.tsv.objectToArray(array, opts), opts); + }, + + /** + * $.tsv.fromObjects(array, options) converts an array of objects into a tsv string. + * + * @param array An array of objects, e.g. [ { name1: "val1", name2: "val2", ...} ...] + * @param options { columns: ["name1", "name2"...], includeHeaders: true, objectToArray: <optional function to convert each object> } + */ + fromObjects: function fromObjects(array, options) { + var opts = tsvOptions(options); + var first = array.length ? array[0] : {}; + // Calculate the columns while we still have the original objects. This is being called for side-effect! + tsvColumns(opts, first); + return $.tsv.fromArrays($.tsv.objectsToArrays(array, opts), opts); + }, + + extend: $.extend + }; + // Compatibility with initial release. + $.tsv.parseRow = $.tsv.toArray; + $.tsv.parseRows = $.tsv.toArrays; + $.tsv.parseObject = $.tsv.toObject; + $.tsv.parseObjects = $.tsv.toObjects; + $.tsv.formatValue = $.tsv.formatValue; + $.tsv.formatRow = $.tsv.fromArray; + $.tsv.formatRows = $.tsv.fromArrays; + $.tsv.formatObject = $.tsv.fromObject; + $.tsv.formatObjects = $.tsv.fromObjects; + +})(jQuery);