file-utils
This is a Grunt.file forks to allow the creation of scoped file utilities and the ability to add write filters.
Same as Grunt.file, this is a set of synchronous utility. As so, it should never be used on a Node.js server. This is meant for users/command line utilities.
File API
Upcoming. Meanwhile, check Grunt.file documentation as the same methods are available.
Setting options - file.option( name, [ value ])
// Set option
file.option('write', false);
// Get option
file.option('write');
Available Options
write
(Boolean): If write is set to false
, then no file will be written or deleted. Useful for test run without side effets.logger
(Logger object): Used internally to log information to the console. API still work in progressencoding
(String): Defaults utf8
. Set the default encoding used for reading/writing. Note most methods allow you to overwridde it for a single run.force
(Boolean): force: true
Force the deletion of folders and file outside the utility scope (or CWD if no scope).
ENV scope and filters
Creating an Env - file#createEnv([ options ]);
var file = require('file-utils');
var env = file.createEnv({
base: 'my/scoped/path',
dest: 'destination/path'
});
var env = file.createEnv({
base: function() {
return 'my/scoped/path';
},
dest: function() {
return 'destination/path';
}
});
The base
directory will prefix any paths passed to mkdir
, recurse
, read
, readJSON
, write
, delete
, exists
, isLink
, isDir
and isFile
methods.
The dest
directory will prefix the destination
path provided in the copy
method. Note that this option is optionnal and will default to the current working directory.
If options (logger
, write
, etc) are not passed, each Env
instance inherit those of its parent.
Write Filters
Write filters are applied on env.write
and env.copy
.
They're used to modifiy the content or the filepath of a file.
Add a write filter - env.registerWriteFilter( name, filter )
options
name
(String): The name under which registering the filterfilter
(Function): The filter function
The filter function take a file object as parameter. This file object is a hash containing a path
and a contents
property. You can modify these two property as you like and returning the modified object.
env.registerWriteFilter( 'coffee', function( file ) {
if (!path.extname(file) !== '.js') return file;
file.path = file.path.replace(/(\.js)$/, '.coffee');
file.content = convertJsToCoffee( file.contents );
return file;
});
Remove a write filter - env.removeWriteFilter( name )
env.removeWriteFilter('coffee');
Async filter
The filter can also be asynchronous. This is done by calling this.async()
and passing the return value to the callback provided.
env.registerWriteFilter( 'coffee', function( file ) {
var done = this.async();
setTimeout(function() {
done({ path: '/newfile', contents: 'filtered content' });
}, 1000);
});
Caution: Using an asynchronous filter will change the way write and copy method are called to. This will make both of those method to run asynchronously too.
Validation Filters
Validation filters are applied on env.write
and env.copy
.
They're used to allow or disallow the write action.
Add a validation filter - env.registerValidationFilter( name, filter )
options
name
(String): The name under which registering the filterfilter
(Function): The filter function
The filter function take a file object as parameter. This file object is a hash containing a path
(String) and a contents
(String if text file, Buffer otherwise) property.
Return true
to allow the file to be written. Return false
or an error message String
to disallow the write action.
env.registerValidationFilter( 'checkConflicts', function( toOutput ) {
if ( file.exists(toOutput.path) ) {
return 'file is already present';
}
return true;
});
Just like the write filters, this filter can be asynchronous.
Remove a validation filter - env.removeValidationFilter( name )
env.removeValidationFilter('checkConflicts');
Todos