README
_ _ _ _____ _______ __
| \ | | | | / ____|/ ____\ \ / /
| \| | ___ __| | ___ | | | (___ \ \ / /
| . ` |/ _ \ / _` |/ _ \| | \___ \ \ \/ /
| |\ | (_) | (_| | __/| |____ ____) | \ /
|_| \_|\___/ \__,_|\___| \_____|_____/ \/ New BSD License
This project provides CSV generation, parsing, transformation and serialization. It has been tested and used on by a large community over the years and should be considered reliable. It provides every option you would expect from an advanced CSV parser and stringifier.
The project is splitted into 4 packages:
csv-generate, a flexible generator of CSV string and Javascript objects.csv-parse, a parser converting CSV text into arrays or objects.stream-transform, a transformation framework.csv-stringify, a stringifier converting records into a CSV text.
The full documentation for the current version 0.4 isn't yet available other then the links to the README provided just above. The official documentation still cover the version 0.3.
Call for feedback
The redesign is an important step forward for this package. A lot of sugar has been removed in favor of straightforward implementations of the Stream API into the 4 sub-packages.
We now need your input. Help us with the documentation, write your impressions discuss additionnal APIs.
Usage
Installation command is npm install csv.
Each modules are fully be compatible with the stream 2 and 3 specifications. Also, a simple callback-based API is alwasy provided for conveniency.
Callback example
Execute this script with the command node samples/callback.js.
var csv = require('csv');
csv.generate({seed: 1, columns: 2, length: 20}, function(err, data){
csv.parse(data, function(err, data){
csv.transform(data, function(data){
return data.map(function(value){return value.toUpperCase()});
}, function(err, data){
csv.stringify(data, function(err, data){
process.stdout.write(data);
});
});
});
});
Stream example
Execute this script with the command node samples/stream.js.
var csv = require('csv');
var generator = csv.generate({seed: 1, columns: 2, length: 20});
var parser = csv.parse();
var transformer = csv.transform(function(data){
return data.map(function(value){return value.toUpperCase()});
});
var stringifier = csv.stringify();
generator.on('readable', function(){
while(data = generator.read()){
parser.write(data);
}
});
parser.on('readable', function(){
while(data = parser.read()){
transformer.write(data);
}
});
transformer.on('readable', function(){
while(data = transformer.read()){
stringifier.write(data);
}
});
stringifier.on('readable', function(){
while(data = stringifier.read()){
process.stdout.write(data);
}
});
Pipe example
Execute this script with the command node samples/pipe.js.
var csv = require('csv');
csv.generate ({seed: 1, columns: 2, length: 20}).pipe(
csv.parse ()).pipe(
csv.transform (function(record){
return record.map(function(value){return value.toUpperCase()});
})).pipe(
csv.stringify ()).pipe(process.stdout);
Migration
This README covers the current version 0.2.x of the node csv parser. The documentation for the previous version (0.1.0) is
available here. The
documentation for the incoming 0.3.x version is not yet released.
The functions 'from*' and 'to*' are now rewritten as 'from.' and 'to.'. The 'data' event is now the 'record' event. The 'data' now receives a stringified version of the 'record' event.
The documentation for olders version are available on GitHub: 0.1.x, 0.2.x.
Development
Tests are executed with mocha. To install it, simple run npm install, it will
install mocha and its dependencies in your project "node_modules" directory.
To run the tests:
npm test
The tests run against the CoffeeScript source files.
To generate the JavaScript files:
make build
The test suite is run online with Travis against Node.js version 0.6, 0.7, 0.8 and 0.9.
Contributors
- David Worms: https://github.com/wdavidw
Related projects
- Pavel Kolesnikov "ya-csv": http://github.com/koles/ya-csv
- Chris Williams "node-csv": http://github.com/voodootikigod/node-csv