fs-utilities/readme.md

utility module for interacting with the file system e.g. asynchronously retreiving list of folders

## Installation

```bash
$ npm install fs-utilities
```

## Usage

```js
var fs_utils = require('fs-utilities')

    fs_utils.getSubfolders( __dirname, function ( err, folders ){
    if( err ) throw err;

    folders.forEach( folder, ... );
});
```


## API Overview


### checkIfIsDirectory( directoryPath, callback )

Asynchronously tests if the specified file is a directory.

__Arguments__
* `directoryPath` - fullpath to file which should be tested
* `callback(err, directoryPath)` - will be executed after test finished. If `directoryPath` is not a folder,
  second callback argument will be undefined.

__Example__
```js
fs_utils.checkIfIsDirectory( "fullFilePath" , function ( err, directory ){
    if( err ) {
        // "fullFilePath" is not a directory
    } else {
        console.log( "'" + directory + "' is a directory" );
    }
});
```


### checkIfIsDirectorySync( directoryPath )

Synchron function to test if the specified file is a directory.

__Arguments__
* `directoryPath` - fullpath to file which should be tested

__Example__
```js
if( fs_utils.checkIfIsDirectorySync( "fullFilePath" ) ){
    console.log( "'fullFilePath' is a directory" );
}
```


### getSubfolders( directoryPath, callback )

Asynchron function which will pass an array containing all subfolders of the given directory
to the also passed callback function.

__Arguments__
* `directoryPath` - path to look for subfolders
* `callback(err, subFolderList)` - will be executed after all subfolders have been detected.
  If case of an error, the search will be aborted and the second argument of the callback function will be undefined.

__Example__
```js
fs_utils.getSubfolders( __dirname , function ( err, folders ){
    if( err ) throw err;

    console.log( "found following subfolders: " + folders );
});
```


### getSubfoldersSync( directoryPath )

Synchronously generates and returns an array containing all subfolders of the given directory.

__Arguments__
* `directoryPath` - path to look for subfolders

__Example__
```js
var folders = fs_utils.getSubfoldersSync( __dirname );
console.log( "found following subfolders: " + folders );
```


### traverseAllSubFolders( directoryPath, callback, [opt_excludedDirectories, [opt_finishedCallback]] )

Asynchron function which will recursively traverse all subfolers.

__Arguments__
* `directoryPath` - path from where to start traversing
* `callback(subFolder)` - will be called for each traversed `subfolder`
* `opt_excludedDirectories` - list of folders that will be skiped
* `opt_finishedCallback` - function that is called after all subfolders have been traversed or an error occured

__Example__
```js
function callForEachSubfolder( folder ){
    console.log( "currently traversing folder '" + folder + "'" );
}

function callOnFinishedTraversing( err ){
    if( err ) throw err;

    console.log( "finished traversing all subfolders" );
}

var excludedFolders = ["excludedFolder0", "excludedFolder1", ...];
fs_utils.traverseAllSubFolders( __dirname,
                                callForEachSubfolder,
                                excludedFolders,
                                callOnFinishedTraversing );
```


### traverseAllSubFoldersSync( directoryPath, callback, [opt_excludedDirectories] )

Synchronous function which will recursively traverse all subfolers.

__Arguments__
* `directoryPath` - path from where to start traversing
* `callback(subFolder)` - will be called for each traversed folder
* `opt_excludedDirectories` - list of folders that will be skiped

__Example__
```js
function callForEachSubfolder( folder ){
    console.log( "currently traversing folder '" + folder + "'" );
}

var excludedFolders = ["excludedFolder0", "excludedFolder1", ...];
fs_utils.traverseAllSubFoldersSync( __dirname,
                                    callForEachSubfolder,
                                    excludedFolders );
console.log( "finished traversing all subfolders" );
```



## Tests

To run the test suite, first install the dependencies, then run `npm test`:

```bash
$ npm install
$ npm test
```



## Coverage

To run a code coverage analysis execute following commands:

```bash
$ npm install
$ npm run coverage
```



## JSDoc

To generate a complete API documentation using JSDoc execute following commands:

```bash
$ npm install
$ npm run jsdoc
```