1 YUI.add('dataschema-text', function (Y, NAME) {

     2 

     3 /**

     4  * Provides a DataSchema implementation which can be used to work with

     5  * delimited text data.

     6  *

     7  * @module dataschema

     8  * @submodule dataschema-text

     9  */

    10 

    11 /**

    12 Provides a DataSchema implementation which can be used to work with

    13 delimited text data.

    14 

    15 See the `apply` method for usage.

    16 

    17 @class DataSchema.Text

    18 @extends DataSchema.Base

    19 @static

    20 **/

    21 

    22 var Lang = Y.Lang,

    23     isString = Lang.isString,

    24     isUndef  = Lang.isUndefined,

    25 

    26     SchemaText = {

    27 

    28         ////////////////////////////////////////////////////////////////////////

    29         //

    30         // DataSchema.Text static methods

    31         //

    32         ////////////////////////////////////////////////////////////////////////

    33         /**

    34         Applies a schema to a string of delimited data, returning a normalized

    35         object with results in the `results` property. The `meta` property of

    36         the response object is present for consistency, but is assigned an

    37         empty object.  If the input data is absent or not a string, an `error`

    38         property will be added.

    39 

    40         Use _schema.resultDelimiter_ and _schema.fieldDelimiter_ to instruct

    41         `apply` how to split up the string into an array of data arrays for

    42         processing.

    43 

    44         Use _schema.resultFields_ to specify the keys in the generated result

    45         objects in `response.results`. The key:value pairs will be assigned

    46         in the order of the _schema.resultFields_ array, assuming the values

    47         in the data records are defined in the same order.

    48 

    49         _schema.resultFields_ field identifiers are objects with the following

    50         properties:

    51 

    52           * `key`   : <strong>(required)</strong> The property name you want

    53                 the data value assigned to in the result object (String)

    54           * `parser`: A function or the name of a function on `Y.Parsers` used

    55                 to convert the input value into a normalized type.  Parser

    56                 functions are passed the value as input and are expected to

    57                 return a value.

    58 

    59         If no value parsing is needed, you can use just the desired property

    60         name string as the field identifier instead of an object (see example

    61         below).

    62 

    63         @example

    64             // Process simple csv

    65             var schema = {

    66                     resultDelimiter: "\n",

    67                     fieldDelimiter: ",",

    68                     resultFields: [ 'fruit', 'color' ]

    69                 },

    70                 data = "Banana,yellow\nOrange,orange\nEggplant,purple";

    71 

    72             var response = Y.DataSchema.Text.apply(schema, data);

    73 

    74             // response.results[0] is { fruit: "Banana", color: "yellow" }

    75 

    76 

    77             // Use parsers

    78             schema.resultFields = [

    79                 {

    80                     key: 'fruit',

    81                     parser: function (val) { return val.toUpperCase(); }

    82                 },

    83                 'color' // mix and match objects and strings

    84             ];

    85 

    86             response = Y.DataSchema.Text.apply(schema, data);

    87 

    88             // response.results[0] is { fruit: "BANANA", color: "yellow" }

    89 

    90         @method apply

    91         @param {Object} schema Schema to apply.  Supported configuration

    92             properties are:

    93           @param {String} schema.resultDelimiter Character or character

    94               sequence that marks the end of one record and the start of

    95               another.

    96           @param {String} [schema.fieldDelimiter] Character or character

    97               sequence that marks the end of a field and the start of

    98               another within the same record.

    99           @param {Array} [schema.resultFields] Field identifiers to

   100               assign values in the response records. See above for details.

   101         @param {String} data Text data.

   102         @return {Object} An Object with properties `results` and `meta`

   103         @static

   104         **/

   105         apply: function(schema, data) {

   106             var data_in = data,

   107                 data_out = { results: [], meta: {} };

   108 

   109             if (isString(data) && schema && isString(schema.resultDelimiter)) {

   110                 // Parse results data

   111                 data_out = SchemaText._parseResults.call(this, schema, data_in, data_out);

   112             } else {

   113                 Y.log("Text data could not be schema-parsed: " + Y.dump(data) + " " + Y.dump(data), "error", "dataschema-text");

   114                 data_out.error = new Error("Text schema parse failure");

   115             }

   116 

   117             return data_out;

   118         },

   119 

   120         /**

   121          * Schema-parsed list of results from full data

   122          *

   123          * @method _parseResults

   124          * @param schema {Array} Schema to parse against.

   125          * @param text_in {String} Text to parse.

   126          * @param data_out {Object} In-progress parsed data to update.

   127          * @return {Object} Parsed data object.

   128          * @static

   129          * @protected

   130          */

   131         _parseResults: function(schema, text_in, data_out) {

   132             var resultDelim = schema.resultDelimiter,

   133                 fieldDelim  = isString(schema.fieldDelimiter) &&

   134                                 schema.fieldDelimiter,

   135                 fields      = schema.resultFields || [],

   136                 results     = [],

   137                 parse       = Y.DataSchema.Base.parse,

   138                 results_in, fields_in, result, item,

   139                 field, key, value, i, j;

   140 

   141             // Delete final delimiter at end of string if there

   142             if (text_in.slice(-resultDelim.length) === resultDelim) {

   143                 text_in = text_in.slice(0, -resultDelim.length);

   144             }

   145 

   146             // Split into results

   147             results_in = text_in.split(schema.resultDelimiter);

   148 

   149             if (fieldDelim) {

   150                 for (i = results_in.length - 1; i >= 0; --i) {

   151                     result = {};

   152                     item = results_in[i];

   153 

   154                     fields_in = item.split(schema.fieldDelimiter);

   155 

   156                     for (j = fields.length - 1; j >= 0; --j) {

   157                         field = fields[j];

   158                         key = (!isUndef(field.key)) ? field.key : field;

   159                         // FIXME: unless the key is an array index, this test

   160                         // for fields_in[key] is useless.

   161                         value = (!isUndef(fields_in[key])) ?

   162                                     fields_in[key] :

   163                                     fields_in[j];

   164 

   165                         result[key] = parse.call(this, value, field);

   166                     }

   167 

   168                     results[i] = result;

   169                 }

   170             } else {

   171                 results = results_in;

   172             }

   173 

   174             data_out.results = results;

   175 

   176             return data_out;

   177         }

   178     };

   179 

   180 Y.DataSchema.Text = Y.mix(SchemaText, Y.DataSchema.Base);

   181 

   182 

   183 }, '@VERSION@', {"requires": ["dataschema-base"]});