lib/yuilib/3.13.0/dataschema-text/dataschema-text.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('dataschema-text', function (Y, NAME) {
   9
  10 /**
  11  * Provides a DataSchema implementation which can be used to work with
  12  * delimited text data.
  13  *
  14  * @module dataschema
  15  * @submodule dataschema-text
  16  */
  17
  18 /**
  19 Provides a DataSchema implementation which can be used to work with
  20 delimited text data.
  21
  22 See the `apply` method for usage.
  23
  24 @class DataSchema.Text
  25 @extends DataSchema.Base
  26 @static
  27 **/
  28
  29 var Lang = Y.Lang,
  30     isString = Lang.isString,
  31     isUndef  = Lang.isUndefined,
  32
  33     SchemaText = {
  34
  35         ////////////////////////////////////////////////////////////////////////
  36         //
  37         // DataSchema.Text static methods
  38         //
  39         ////////////////////////////////////////////////////////////////////////
  40         /**
  41         Applies a schema to a string of delimited data, returning a normalized
  42         object with results in the `results` property. The `meta` property of
  43         the response object is present for consistency, but is assigned an
  44         empty object.  If the input data is absent or not a string, an `error`
  45         property will be added.
  46
  47         Use _schema.resultDelimiter_ and _schema.fieldDelimiter_ to instruct
  48         `apply` how to split up the string into an array of data arrays for
  49         processing.
  50
  51         Use _schema.resultFields_ to specify the keys in the generated result
  52         objects in `response.results`. The key:value pairs will be assigned
  53         in the order of the _schema.resultFields_ array, assuming the values
  54         in the data records are defined in the same order.
  55
  56         _schema.resultFields_ field identifiers are objects with the following
  57         properties:
  58
  59           * `key`   : <strong>(required)</strong> The property name you want
  60                 the data value assigned to in the result object (String)
  61           * `parser`: A function or the name of a function on `Y.Parsers` used
  62                 to convert the input value into a normalized type.  Parser
  63                 functions are passed the value as input and are expected to
  64                 return a value.
  65
  66         If no value parsing is needed, you can use just the desired property
  67         name string as the field identifier instead of an object (see example
  68         below).
  69
  70         @example
  71             // Process simple csv
  72             var schema = {
  73                     resultDelimiter: "\n",
  74                     fieldDelimiter: ",",
  75                     resultFields: [ 'fruit', 'color' ]
  76                 },
  77                 data = "Banana,yellow\nOrange,orange\nEggplant,purple";
  78
  79             var response = Y.DataSchema.Text.apply(schema, data);
  80
  81             // response.results[0] is { fruit: "Banana", color: "yellow" }
  82
  83
  84             // Use parsers
  85             schema.resultFields = [
  86                 {
  87                     key: 'fruit',
  88                     parser: function (val) { return val.toUpperCase(); }
  89                 },
  90                 'color' // mix and match objects and strings
  91             ];
  92
  93             response = Y.DataSchema.Text.apply(schema, data);
  94
  95             // response.results[0] is { fruit: "BANANA", color: "yellow" }
  96
  97         @method apply
  98         @param {Object} schema Schema to apply.  Supported configuration
  99             properties are:
 100           @param {String} schema.resultDelimiter Character or character
 101               sequence that marks the end of one record and the start of
 102               another.
 103           @param {String} [schema.fieldDelimiter] Character or character
 104               sequence that marks the end of a field and the start of
 105               another within the same record.
 106           @param {Array} [schema.resultFields] Field identifiers to
 107               assign values in the response records. See above for details.
 108         @param {String} data Text data.
 109         @return {Object} An Object with properties `results` and `meta`
 110         @static
 111         **/
 112         apply: function(schema, data) {
 113             var data_in = data,
 114                 data_out = { results: [], meta: {} };
 115
 116             if (isString(data) && schema && isString(schema.resultDelimiter)) {
 117                 // Parse results data
 118                 data_out = SchemaText._parseResults.call(this, schema, data_in, data_out);
 119             } else {
 120                 data_out.error = new Error("Text schema parse failure");
 121             }
 122
 123             return data_out;
 124         },
 125
 126         /**
 127          * Schema-parsed list of results from full data
 128          *
 129          * @method _parseResults
 130          * @param schema {Array} Schema to parse against.
 131          * @param text_in {String} Text to parse.
 132          * @param data_out {Object} In-progress parsed data to update.
 133          * @return {Object} Parsed data object.
 134          * @static
 135          * @protected
 136          */
 137         _parseResults: function(schema, text_in, data_out) {
 138             var resultDelim = schema.resultDelimiter,
 139                 fieldDelim  = isString(schema.fieldDelimiter) &&
 140                                 schema.fieldDelimiter,
 141                 fields      = schema.resultFields || [],
 142                 results     = [],
 143                 parse       = Y.DataSchema.Base.parse,
 144                 results_in, fields_in, result, item,
 145                 field, key, value, i, j;
 146
 147             // Delete final delimiter at end of string if there
 148             if (text_in.slice(-resultDelim.length) === resultDelim) {
 149                 text_in = text_in.slice(0, -resultDelim.length);
 150             }
 151
 152             // Split into results
 153             results_in = text_in.split(schema.resultDelimiter);
 154
 155             if (fieldDelim) {
 156                 for (i = results_in.length - 1; i >= 0; --i) {
 157                     result = {};
 158                     item = results_in[i];
 159
 160                     fields_in = item.split(schema.fieldDelimiter);
 161
 162                     for (j = fields.length - 1; j >= 0; --j) {
 163                         field = fields[j];
 164                         key = (!isUndef(field.key)) ? field.key : field;
 165                         // FIXME: unless the key is an array index, this test
 166                         // for fields_in[key] is useless.
 167                         value = (!isUndef(fields_in[key])) ?
 168                                     fields_in[key] :
 169                                     fields_in[j];
 170
 171                         result[key] = parse.call(this, value, field);
 172                     }
 173
 174                     results[i] = result;
 175                 }
 176             } else {
 177                 results = results_in;
 178             }
 179
 180             data_out.results = results;
 181
 182             return data_out;
 183         }
 184     };
 185
 186 Y.DataSchema.Text = Y.mix(SchemaText, Y.DataSchema.Base);
 187
 188
 189 }, '3.13.0', {"requires": ["dataschema-base"]});