add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / util / DelimitedValue.js

/**\r
 * This base class contains utility methods for dealing with formats such as CSV (Comma\r
 * Separated Values) as specified in <a href="http://tools.ietf.org/html/rfc4180">RFC 4180</a>.\r
 *\r
 * The base class implements the mechanics and is governed by these config options:\r
 *\r
 *  * `{@link #delimiter}`\r
 *  * `{@link #lineBreak}`\r
 *  * `{@link #quote}`\r
 *\r
 * These options affect the `{@link #method-encode}` and `{@link #method-decode}` methods.\r
 * When *decoding*, however, `{@link #lineBreak}` is ignored and instead each line can\r
 * be separated by any standard line terminator character or character sequence:\r
 *\r
 *  * ```\u000a```\r
 *  * ```\u000d```\r
 *  * ```\u000d\u000a```\r
 *\r
 * Strings which contain the {@link #delimiter} character are quoted using the\r
 * {@link #quote} character, and any internal {@link #quote} characters are doubled.\r
 *\r
 * *Important*\r
 * While the primary use case is to encode strings, other atomic data types can be encoded\r
 * as values within a line such as:\r
 *\r
 *  * Number\r
 *  * Boolean\r
 *  * Date (encoded as an <a href="http://www.iso.org/iso/home/standards/iso8601.htm">ISO 8601</a> date string.)\r
 *  * null (encoded as an empty string.)\r
 *  * undefined (encoded as an empty string.)\r
 *\r
 * Not that when *decoding*, all data is read as strings. This class does not convert\r
 * incoming data. To do that, use an {@link Ext.data.reader.Array ArrayReader}.\r
 *\r
 * See `{@link Ext.util.CSV}` and  `{@link Ext.util.TSV}` for pre-configured instances.\r
 *\r
 * @since 5.1.0\r
 */\r
Ext.define('Ext.util.DelimitedValue', {\r
    /**\r
     * @cfg {String} dateFormat\r
     * The {@link Ext.Date#format format} to use for dates\r
     */\r
    dateFormat: 'C',\r
\r
    /**\r
     * @cfg {String} delimiter\r
     * The string used to separate the values in a row. Common values for this config\r
     * are comma (",") and tab ("\t"). See `{@link Ext.util.CSV}` and  `{@link Ext.util.TSV}`\r
     * for pre-configured instances of these formats.\r
     */\r
    delimiter: '\t',\r
\r
    /**\r
     * @cfg {String} lineBreak\r
     * The string used by `{@link #encode}` to separate each row. The `{@link #decode}`\r
     * method accepts all forms of line break.\r
     */\r
    lineBreak: '\n',\r
\r
    /**\r
     * @cfg {String} quote\r
     * The character to use as to quote values that contain the special `delimiter`\r
     * or `{@link #lineBreak}` characters.\r
     */\r
    quote: '"',\r
    \r
    parseREs: {},\r
    quoteREs: {},\r
\r
    lineBreakRe: /\r?\n/g,\r
\r
    constructor: function (config) {\r
        if (config) {\r
            Ext.apply(this, config);\r
        }\r
    },\r
\r
    /**\r
     * Decodes a string of encoded values into an array of rows. Each row is an array of\r
     * strings.\r
     *\r
     * Note that this function does not convert the string values in each column into\r
     * other data types. To do that, use an {@link Ext.data.reader.Array ArrayReader}.\r
     *\r
     * For example:\r
     *\r
     *     Ext.util.CSV.decode('"foo ""bar"", bletch",Normal String,2010-01-01T21:45:32.004Z\u000a3.141592653589793,1,false');\r
     *\r
     * produces the following array of string arrays:\r
     *\r
     *     [\r
     *         ['foo "bar", bletch','Normal String', '2010-01-01T21:45:32.004Z'],\r
     *         ['3.141592653589793', '1', 'false']\r
     *     ]\r
     *\r
     * @param {String} input The string to parse.\r
     *\r
     * @param {String} [delimiter] The column delimiter to use if the default value\r
     * of {@link #cfg-delimiter delimiter} is not desired.\r
     *\r
     * @return {String[][]} An array of rows where each row is an array of Strings.\r
     */\r
    decode: function (input, delimiter) {\r
        var me = this,\r
            // Check to see if the column delimiter is defined. If not,\r
            // then default to comma.\r
            delim = (delimiter || me.delimiter),\r
            row = [],\r
            result = [row],\r
            quote = me.quote,\r
            quoteREs = me.quoteREs,\r
            parseREs = me.parseREs,\r
\r
            // Create a regular expression to parse the CSV values unless we already have\r
            // one for this delimiter.\r
            parseRE = parseREs[delim] ||\r
                (parseREs[delim] = new RegExp(\r
                    // Delimiters.\r
                    "(\\" + delim + "|\\r?\\n|\\r|^)" +\r
\r
                    // Quoted fields.\r
                    "(?:\\" + quote + "([^\\" + quote + "]*(?:\\" + quote + "\\" + quote +\r
                            "[^\\" + quote + "]*)*)\\" + quote + "|" +\r
\r
                    // Standard fields.\r
                    "([^\"\\" + delim + "\\r\\n]*))",\r
                "gi")),\r
\r
            dblQuoteRE = quoteREs[quote] ||\r
                (quoteREs[quote] = new RegExp('\\' + quote + '\\' + quote, 'g')),\r
\r
            arrMatches, strMatchedDelimiter, strMatchedValue;\r
\r
        // Keep looping over the regular expression matches\r
        // until we can no longer find a match.\r
        while (arrMatches = parseRE.exec(input)) {\r
            strMatchedDelimiter = arrMatches[1];\r
\r
            // Check to see if the given delimiter has a length\r
            // (is not the start of string) and if it matches\r
            // field delimiter. If id does not, then we know\r
            // that this delimiter is a row delimiter.\r
            if (strMatchedDelimiter.length && strMatchedDelimiter !== delim) {\r
                // Since we have reached a new row of data,\r
                // add an empty row to our data array.\r
                result.push(row = []);\r
            }\r
\r
            // Now that we have our delimiter out of the way,\r
            // let's check to see which kind of value we\r
            // captured (quoted or unquoted).\r
            if (arrMatches[2]) {\r
                // We found a quoted value. When we capture\r
                // this value, unescape any double quotes.\r
                strMatchedValue = arrMatches[2].replace(dblQuoteRE, '"');\r
            } else {\r
                // We found a non-quoted value.\r
                strMatchedValue = arrMatches[3];\r
            }\r
\r
            row.push(strMatchedValue);\r
        }\r
\r
        return result;\r
    },\r
\r
    /**\r
     * Converts a two-dimensional array into an encoded string.\r
     *\r
     * For example:\r
     *\r
     *     Ext.util.CSV.encode([\r
     *         ['foo "bar", bletch', 'Normal String', new Date()],\r
     *         [Math.PI, 1, false]\r
     *     ]);\r
     *\r
     * The above produces the following string:\r
     *\r
     *     '"foo ""bar"", bletch",Normal String,2010-01-01T21:45:32.004Z\u000a3.141592653589793,1,false'\r
     *\r
     * @param {Mixed[][]} input An array of row data arrays.\r
     *\r
     * @param {String} [delimiter] The column delimiter to use if the default value\r
     * of {@link #cfg-delimiter delimiter} is not desired.\r
     *\r
     * @return {String} A string in which data items are separated by {@link #delimiter}\r
     * characters, and rows are separated by {@link #lineBreak} characters.\r
     */\r
    encode: function (input, delimiter) {\r
        var me = this,\r
            delim = delimiter || me.delimiter,\r
            dateFormat = me.dateFormat,\r
            quote = me.quote,\r
            twoQuotes = quote + quote,\r
            rowIndex = input.length,\r
            lineBreakRe = me.lineBreakRe,\r
            result = [],\r
            outputRow = [],\r
            col, columnIndex, inputRow;\r
\r
        while (rowIndex-- > 0) {\r
            inputRow = input[rowIndex];\r
            outputRow.length = columnIndex = inputRow.length;\r
\r
            while (columnIndex-- > 0) {\r
                col = inputRow[columnIndex];\r
\r
                if (col == null) { // == null || === undefined\r
                    col = '';\r
                } else if (typeof col === 'string') {\r
                    if (col) {\r
                        // If the value contains quotes, double them up, and wrap with quotes\r
                        if (col.indexOf(quote) > -1) {\r
                            col = quote + col.split(quote).join(twoQuotes) + quote;\r
                        } else if (col.indexOf(delim) > -1 || lineBreakRe.test(col)) {\r
                            col = quote + col + quote;\r
                        }\r
                    }\r
                } else if (Ext.isDate(col)) {\r
                    col = Ext.Date.format(col, dateFormat);\r
                }\r
                //<debug>\r
                else if (col && (isNaN(col) || Ext.isArray(col))) {\r
                    Ext.raise('Cannot serialize ' + Ext.typeOf(col) + ' into CSV');\r
                }\r
                //</debug>\r
\r
                outputRow[columnIndex] = col;\r
            }\r
\r
            result[rowIndex] = outputRow.join(delim);\r
        }\r
\r
        return result.join(me.lineBreak);\r
    }\r
});