Flexible Node.js file reading library.
This project is maintained by benjreinhart
Flexible Node.js file reading library.
Readr is a library that abstracts reading files from disk. It supports recursively reading multiple files in a directory or reading an individual file via a clean API. It uses globber as its glob engine. Readr's API provides both sync and async operations.
readr is a tool to read files and return a formatted object with the following properties:
path
- the absolute path of the filecontents
- the contents of the file (specified by the encoding
option, defaults to 'utf8)friendlyPath
(optional) a formatted string better suited for referencing the fileIt provides a nice abstraction around sync and async file reading, as well as reading individual files and globbing directories. It is compatible with node 0.8 upward.
Given the following directory tree:
/path/to/files/
* some_directory/
* file.txt
* another_file.txt
* csv_file.csv
And a current working directory of /path/to
find all .txt files
var readr = require('readr');
readr('files', {extension: 'txt'}, function(err, files) {
console.log(files)
});
/*
[
{
path: 'files/some_directory/file.txt',
contents: 'Contents of file.txt',
friendlyPath: 'files/some_directory/file'
},
{
path: 'files/some_directory/another_file.txt',
contents: 'Contents of another_file.txt',
friendlyPath: 'files/some_directory/another_file'
}
]
*/
Get a single file
readr('files/some_director/csv_file.csv', {friendlyPath: 'csv_file'}, function(err, files){
console.log(files)
});
/*
[
{
path: 'files/some_directory/csv_file.csv',
contents: '',
friendlyPath: 'files/some_directory/csv_file'
}
]
*/
Or just get the paths and their corresponding friendlyPath
of a directory
readr.getPaths('files', function(err, paths){
console.log(paths)
});
/*
[
{path: 'files/some_directory/another_file.txt', friendlyPath: 'files/some_directory/another_file.txt'},
{path: 'files/some_directory/csv_file.csv', friendlyPath: 'files/some_directory/csv_file.csv'},
{path: 'files/some_directory/file.txt', friendlyPath: 'files/some_directory/file.txt'}
]
*/
What really makes readr
powerful is its globbing engine, globber. For a much more comprehensive set of examples, see the test suite.
npm install readr
var readr = require('readr');
The path
and options
arguments are the same as the path
and options
arguments for globber (plus an additional friendlyPath
and encoding
option).
options
can be the following:
Accepts all options globber accepts (except the includeDirectories
option, which will always be false).
encoding
{String} - the encoding to use for fs#readFile
and fs#readFileSync
, defaults to 'utf8' (to get a raw buffer, the value of the encoding
option should be 'buffer').friendlyPath
{Function|Boolean}
path
argument where path
is the path relative to the current working directory (or the absolute path of the file if the absolute
option is true) minus the extension. The result of this call will be the friendlyPath
of the file object.false
, the resulting file objects will have no friendlyPath
attributeSynchronous version of readr
.
Similar to readr
except it will not open and read the contents of the files found, rather it will just return the absolute path and (optionally) friendlyPath
attribute of the files found.
Synchronous version of readr.getPaths
.