PageRenderTime 27ms CodeModel.GetById 18ms RepoModel.GetById 0ms app.codeStats 0ms

Markdown | 150 lines | 105 code | 45 blank | 0 comment | 0 complexity | 84193d3a2345f4a9d3e8c784e35b44b3 MD5 | raw file
  1. ---
  2. language: en
  3. layout: page
  4. title: "Reading data from a source"
  5. date: 2013-07-30T09:03:48.121Z
  6. comments: false
  7. sharing: false
  8. footer: false
  9. navigation: csv
  10. github:
  11. source: ./src/
  12. ---
  13. The `csv().from` property provides functions to read from an external
  14. source and write to a CSV instance. The source may be a string, a file,
  15. a buffer or a readable stream.
  16. You may call the `from` function or one of its sub function. For example,
  17. here are two identical ways to read from a file:
  18. ```javascript
  19. csv().from('/tmp/data.csv').on('data', console.log);
  20. csv().from.path('/tmp/data.csv').on('data', console.log);
  21. ```
  22. <a name="from"></a>
  23. `from(mixed)`
  24. -------------
  25. Read from any sort of source. It should be considered as a convenient function which
  26. will discover the nature of the data source to parse.
  27. If the parameter is a string, check if a file of that path exists. If so, read the file contents,
  28. otherwise, treat the string as CSV data. If the parameter is an instance of `stream`, consider the
  29. object to be an input stream. If it is an array, then treat each line as a record.
  30. Here are some examples on how to use this function:
  31. ```javascript
  32. csv()
  33. .from('"1","2","3","4"\n"a","b","c","d"')
  34. .on('end', function(){ console.log('done') })
  35. csv()
  36. .from('./path/to/file.csv')
  37. .on('end', function(){ console.log('done') })
  38. csv()
  39. .from(fs.createReadStream('./path/to/file.csv'))
  40. .on('end', function(){ console.log('done') })
  41. csv()
  42. .from(['"1","2","3","4","5"',['1','2','3','4','5']])
  43. .on('end', function(){ console.log('done') })
  44. ```
  45. <a name="from.options"></a>
  46. `from.options([options])`
  47. -------------------------
  48. Update and retrieve options relative to the input source. Return
  49. the options as an object if no argument is provided.
  50. * `delimiter` Set the field delimiter. One character only, defaults to comma.
  51. * `rowDelimiter` String used to delimit record rows or a special value; special values are 'auto', 'unix', 'mac', 'windows', 'unicode'; defaults to 'auto' (discovered in source or 'unix' if no source is specified).
  52. * `quote` Optionnal character surrounding a field, one character only, defaults to double quotes.
  53. * `escape` Set the escape character, one character only, defaults to double quotes.
  54. * `columns` List of fields or true if autodiscovered in the first CSV line, default to null. Impact the `transform` argument and the `data` event by providing an object instead of an array, order matters, see the transform and the columns sections for more details.
  55. * `comment` Treat all the characteres after this one as a comment, default to '#'
  56. * `flags` Used to read a file stream, default to the r charactere.
  57. * `encoding` Encoding of the read stream, defaults to 'utf8', applied when a readable stream is created.
  58. * `trim` If true, ignore whitespace immediately around the delimiter, defaults to false.
  59. * `ltrim` If true, ignore whitespace immediately following the delimiter (i.e. left-trim all fields), defaults to false.
  60. * `rtrim` If true, ignore whitespace immediately preceding the delimiter (i.e. right-trim all fields), defaults to false.
  61. Additionnally, in case you are working with stream, you can pass all
  62. the options accepted by the `stream.pipe` function.
  63. <a name="from.array"></a>
  64. `from.array(data, [options])`
  65. ------------------------------
  66. Read from an array. Take an array as first argument and optionally
  67. an object of options as a second argument. Each element of the array
  68. represents a CSV record. Those elements may be a string, a buffer, an
  69. array or an object.
  70. <a name="from.string"></a>
  71. `from.string(data, [options])`
  72. -------------------------------
  73. Read from a string or a buffer. Take a string as first argument and
  74. optionally an object of options as a second argument. The string
  75. must be the complete csv data, look at the streaming alternative if your
  76. CSV is large.
  77. ```javascript
  78. csv()
  79. .from( '"1","2","3","4"\n"a","b","c","d"' )
  80. .to( function(data){} )
  81. ```
  82. <a name=""></a>
  83. `, [options])`
  84. --------------------------------
  85. Read from a stream. Take a readable stream as first argument and optionally
  86. an object of options as a second argument.
  87. Additionnal options may be defined. See the [`readable.pipe`
  88. documentation][srpdo] for additionnal information.
  89. [srpdo]:
  90. <a name="from.path"></a>
  91. `from.path(path, [options])`
  92. ----------------------------
  93. Read from a file path. Take a file path as first argument and optionally an object
  94. of options as a second argument.
  95. Additionnal options may be defined with the following default:
  96. ```javascript
  97. { flags: 'r',
  98. encoding: null,
  99. fd: null,
  100. mode: 0666,
  101. bufferSize: 64 * 1024,
  102. autoClose: true }
  103. ```
  104. See the [`fs.createReadStream` documentation][fscpo] for additionnal information.
  105. [fscpo]: