[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 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.17.2', {"requires": ["dataschema-base"]});