file-utils

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 progress
- encoding (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
=========

$3

`javascript
var file = require('file-utils');

var env = file.createEnv({
base: 'my/scoped/path',
dest: 'destination/path' // optionnal
});

// Alternatively, they can be functions returning a path:

var env = file.createEnv({
base: function() {
return 'my/scoped/path';
},
dest: function() { // optionnal
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 filter
- filter (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.

`javascript
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 )

`javascript
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.

`javascript
env.registerWriteFilter( 'coffee', function( file ) {
var done = this.async();

// some process
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 filter
- filter (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.

`javascript
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 )

`javascript
env.removeValidationFilter('checkConflicts');
``

Todos
=========

- Real Logging system