diff --git a/docs/src/backend.csv.html b/docs/src/backend.csv.html index 34118c88..091b5ace 100644 --- a/docs/src/backend.csv.html +++ b/docs/src/backend.csv.html @@ -1,18 +1,24 @@ backend.csv.js
Jump To …

backend.csv.js 

this.recline = this.recline || {};
 this.recline.Backend = this.recline.Backend || {};
-this.recline.Backend.CSV = this.recline.Backend.CSV || {};
+this.recline.Backend.CSV = this.recline.Backend.CSV || {};

Note that provision of jQuery is optional (it is only needed if you use fetch on a remote file)

 
(function(my, $) {

fetch

-(function(my) {

fetch

- -

3 options

+

fetch supports 3 options depending on the attribute provided on the dataset argument

    -
  1. CSV local fileobject -> HTML5 file object + CSV parser
    2. -
  2. Already have CSV string (in data) attribute -> CSV parser
    3. -
  3. online CSV file that is ajax-able -> ajax + csv parser
    4. +
  4. dataset.file: file is an HTML5 file object. This is opened and parsed with the CSV parser.
    5. +
  5. dataset.data: data is a string in CSV format. This is passed directly to the CSV parser
    6. +
  6. dataset.url: a url to an online CSV file that is ajax accessible (note this usually requires either local or on a server that is CORS enabled). The file is then loaded using $.ajax and parsed using the CSV parser (NB: this requires jQuery)
-

All options generates similar data and give a memory store outcome

 
  my.fetch = function(dataset) {
+
All options generates similar data and use the memory store outcome, that is they return something like:

+
+
+{
+  records: [ [...], [...], ... ],
+  metadata: { may be some metadata e.g. file name }
+  useMemoryStore: true
+}
+
             
  my.fetch = function(dataset) {
     var dfd = $.Deferred();
     if (dataset.file) {
       var reader = new FileReader();
@@ -47,7 +53,9 @@
       });
     }
     return dfd.promise();
-  };

Converts a Comma Separated Values string into an array of arrays. + };

parseCSV

+ +

Converts a Comma Separated Values string into an array of arrays. Each line in the CSV becomes an array.

Empty fields are converted to nulls and non-quoted numbers are converted to integers or floats.

@@ -66,7 +74,7 @@ Each line in the CSV becomes an array.

quotechar, or which contain new-line characters. It defaults to '"'

Heavily based on uselesscode's JS CSV parser (MIT Licensed): -http://www.uselesscode.org/javascript/csv/

 
  my.parseCSV= function(s, options) {

Get rid of any trailing \n

 
    s = chomp(s);
+http://www.uselesscode.org/javascript/csv/
             
  my.parseCSV= function(s, options) {

Get rid of any trailing \n

 
    s = chomp(s);
 
     var options = options || {};
     var trm = (options.trim === false) ? false : true;
@@ -83,10 +91,10 @@ http://www.uselesscode.org/javascript/csv/
processField; processField = function (field) { - if (fieldQuoted !== true) {

If field is empty set to null

 
        if (field === '') {
-          field = null;

If the field was not quoted and we are trimming fields, trim it

 
        } else if (trm === true) {
+      if (fieldQuoted !== true) {

If field is empty set to null

 
        if (field === '') {
+          field = null;

If the field was not quoted and we are trimming fields, trim it

 
        } else if (trm === true) {
           field = trim(field);
-        }

Convert unquoted numbers to their appropriate types

 
        if (rxIsInt.test(field)) {
+        }

Convert unquoted numbers to their appropriate types

 
        if (rxIsInt.test(field)) {
           field = parseInt(field, 10);
         } else if (rxIsFloat.test(field)) {
           field = parseFloat(field, 10);
@@ -96,30 +104,30 @@ http://www.uselesscode.org/javascript/csv/
}; for (i = 0; i < s.length; i += 1) { - cur = s.charAt(i);

If we are at a EOF or EOR

 
      if (inQuote === false && (cur === delimiter || cur === "\n")) {
-	field = processField(field);

Add the current field to the current row

 
        row.push(field);

If this is EOR append row to output and flush row

 
        if (cur === "\n") {
+      cur = s.charAt(i);

If we are at a EOF or EOR

 
      if (inQuote === false && (cur === delimiter || cur === "\n")) {
+	field = processField(field);

Add the current field to the current row

 
        row.push(field);

If this is EOR append row to output and flush row

 
        if (cur === "\n") {
           out.push(row);
           row = [];
-        }

Flush the field buffer

 
        field = '';
+        }

Flush the field buffer

 
        field = '';
         fieldQuoted = false;
-      } else {

If it's not a quotechar, add it to the field buffer

 
        if (cur !== quotechar) {
+      } else {

If it's not a quotechar, add it to the field buffer

 
        if (cur !== quotechar) {
           field += cur;
         } else {
-          if (!inQuote) {

We are not in a quote, start a quote

 
            inQuote = true;
+          if (!inQuote) {

We are not in a quote, start a quote

 
            inQuote = true;
             fieldQuoted = true;
-          } else {

Next char is quotechar, this is an escaped quotechar

 
            if (s.charAt(i + 1) === quotechar) {
-              field += quotechar;

Skip the next char

 
              i += 1;
-            } else {

It's not escaping, so end quote

 
              inQuote = false;
+          } else {

Next char is quotechar, this is an escaped quotechar

 
            if (s.charAt(i + 1) === quotechar) {
+              field += quotechar;

Skip the next char

 
              i += 1;
+            } else {

It's not escaping, so end quote

 
              inQuote = false;
             }
           }
         }
       }
-    }

Add the last field

 
    field = processField(field);
+    }

Add the last field

 
    field = processField(field);
     row.push(field);
     out.push(row);
 
     return out;
-  };

serializeCSV

+ };

serializeCSV

Convert an Object or a simple array of arrays into a Comma Separated Values string.

@@ -171,9 +179,9 @@ http://www.uselesscode.org/javascript/csv/

 processField; processField = function (field) { - if (field === null) {

If field is null set to empty string

 
        field = '';
-      } else if (typeof field === "string" && rxNeedsQuoting.test(field)) {

Convert string to delimited string

 
        field = quotechar + field + quotechar;
-      } else if (typeof field === "number") {

Convert number to string

 
        field = field.toString(10);
+      if (field === null) {

If field is null set to empty string

 
        field = '';
+      } else if (typeof field === "string" && rxNeedsQuoting.test(field)) {

Convert string to delimited string

 
        field = quotechar + field + quotechar;
+      } else if (typeof field === "number") {

Convert number to string

 
        field = field.toString(10);
       }
 
       return field;
@@ -183,12 +191,12 @@ http://www.uselesscode.org/javascript/csv/
cur = a[i]; for (j = 0; j < cur.length; j += 1) { - field = processField(cur[j]);

If this is EOR append row to output and flush row

 
        if (j === (cur.length - 1)) {
+        field = processField(cur[j]);

If this is EOR append row to output and flush row

 
        if (j === (cur.length - 1)) {
           row += field;
           out += row + "\n";
           row = '';
-        } else {

Add the current field to the current row

 
          row += field + delimiter;
-        }

Flush the field buffer

 
        field = '';
+        } else {

Add the current field to the current row

 
          row += field + delimiter;
+        }

Flush the field buffer

 
        field = '';
       }
     }
 
@@ -196,10 +204,10 @@ http://www.uselesscode.org/javascript/csv/
}; var rxIsInt = /^\d+$/, - rxIsFloat = /^\d*\.\d+$|^\d+\.\d*$/,

If a string has leading or trailing space, + rxIsFloat = /^\d*\.\d+$|^\d+\.\d*$/,

If a string has leading or trailing space, contains a comma double quote or a newline it needs to be quoted in CSV output

 
    rxNeedsQuoting = /^\s|\s$|,|"|\n/,
-    trim = (function () {

Fx 3.1 has a native trim function, it's about 10x faster, use it if it exists

 
      if (String.prototype.trim) {
+    trim = (function () {

Fx 3.1 has a native trim function, it's about 10x faster, use it if it exists

 
      if (String.prototype.trim) {
         return function (s) {
           return s.trim();
         };
@@ -211,12 +219,12 @@ it needs to be quoted in CSV output
}()); function chomp(s) { - if (s.charAt(s.length - 1) !== "\n") {

Does not end with \n, just return string

 
      return s;
-    } else {

Remove the \n

 
      return s.substring(0, s.length - 1);
+    if (s.charAt(s.length - 1) !== "\n") {

Does not end with \n, just return string

 
      return s;
+    } else {

Remove the \n

 
      return s.substring(0, s.length - 1);
     }
   }
 
 
-}(this.recline.Backend.CSV));
+}(this.recline.Backend.CSV, jQuery));
\ No newline at end of file diff --git a/src/backend.csv.js b/src/backend.csv.js index 81e69749..81b9771b 100644 --- a/src/backend.csv.js +++ b/src/backend.csv.js @@ -2,16 +2,26 @@ this.recline = this.recline || {}; this.recline.Backend = this.recline.Backend || {}; this.recline.Backend.CSV = this.recline.Backend.CSV || {}; -(function(my) { +// Note that provision of jQuery is optional (it is **only** needed if you use fetch on a remote file) +(function(my, $) { + // ## fetch // - // 3 options + // fetch supports 3 options depending on the attribute provided on the dataset argument // - // 1. CSV local fileobject -> HTML5 file object + CSV parser - // 2. Already have CSV string (in data) attribute -> CSV parser - // 2. online CSV file that is ajax-able -> ajax + csv parser + // 1. `dataset.file`: `file` is an HTML5 file object. This is opened and parsed with the CSV parser. + // 2. `dataset.data`: `data` is a string in CSV format. This is passed directly to the CSV parser + // 3. `dataset.url`: a url to an online CSV file that is ajax accessible (note this usually requires either local or on a server that is CORS enabled). The file is then loaded using $.ajax and parsed using the CSV parser (NB: this requires jQuery) // - // All options generates similar data and give a memory store outcome + // All options generates similar data and use the memory store outcome, that is they return something like: + // + // 
+  // {
+  //   records: [ [...], [...], ... ],
+  //   metadata: { may be some metadata e.g. file name }
+  //   useMemoryStore: true
+  // }
+  //
my.fetch = function(dataset) { var dfd = $.Deferred(); if (dataset.file) { @@ -49,6 +59,8 @@ this.recline.Backend.CSV = this.recline.Backend.CSV || {}; return dfd.promise(); }; + // ## parseCSV + // // Converts a Comma Separated Values string into an array of arrays. // Each line in the CSV becomes an array. // @@ -155,7 +167,7 @@ this.recline.Backend.CSV = this.recline.Backend.CSV || {}; return out; }; - // ### serializeCSV + // ## serializeCSV // // Convert an Object or a simple array of arrays into a Comma // Separated Values string. @@ -273,4 +285,4 @@ this.recline.Backend.CSV = this.recline.Backend.CSV || {}; } -}(this.recline.Backend.CSV)); +}(this.recline.Backend.CSV, jQuery));