DirTree
Translate a directory structure into a tree object.
This module translates a directory structure into a tree object and provides an interface to search and load leaves (files) within that tree.
Installation
$ npm install dirtree
Usage
To create a new tree generator,
var createTree = ;var tree = ;
A tree
is configurable and has the following methods...
tree.root( [root] )
This method is a setter/getter. If no root
directory is provided, returns the tree root
. To set the tree root
,
tree;
The root
should be an absolute path.
tree.include( type[, filter] )
This method is a setter/getter for regular expression filters to include particular files and directories. The method accepts two types: files
and dirs
. If no filter
is provided, returns the inclusion filter
for the specified type
. To set an inclusion filter
,
// Only include CSS files from build or styles directories:tree; // /build, /styles, /styles/build, /build/stylestree;
tree.exclude( type[, filter] )
This method is a setter/getter for regular expression filters to exclude particular files and directories. The method accepts two types: files
and dirs
. If no filter
is provided, returns the exclusion filter
for the specified type
. To set an exclusion filter
,
// Exclude any hidden directories and dot files:tree;tree;
tree.create()
This method creates a directory tree. To create a tree,
tree;
You must first set a root
directory before running this method.
tree.leaves()
This method returns all tree leaves. If a tree has not been created, leaves
will be an empty array. To return all tree leaves,
tree;
Note: the array elements will be relative paths from the root
directory.
tree.search( include[, exclude] )
This method searches a tree for leaves matching the provided regular expression filters. Either an include
or exclude
or both filters are required. To only specify an exclude
filter, set the include
filter to null
. To perform a search,
// Search inclusively for `*.md` files:tree;// Search for any files which are not `*.txt` files:tree;// Search both inclusively and exclusively for all files having `foo` but not `bar` in their relative paths:tree;
tree.read( [options,] clbk )
This method searches a tree for leaves matching provided filters and reads the leaves ( files), returning the file content. The options
object may have one or more of the following fields:
var options ='include': /foo/'exclude': /bar/'encoding': 'utf8''concat': true;
The filters are the same as for tree.search()
. The encoding
option is the file encoding. The concat
flag indicates whether the file content should be concatenated and returned as a string
. If set to false
, the file content is returned as an object
, where each field is the absolute file path and each value is the corresponding file content.
To read leaves and concatentate the file content into a single string,
var options ='include': /.+\.css$/'exclude': /src/'encoding': 'utf8''concat': true;// Read and concatenate all CSS files not in a `src` directory:tree;{if errorconsole;return;console;}
tree.toJSON()
This method serializes a directory tree as JSON. To get the JSON tree,
tree;
Examples
var createTree = ;// Create a new tree generator:var tree = ;// Configure and create a tree:tree;// Serialize the tree:console;// List the leaves:console;// Search the leaves:console;// Read the leaves:console;
To run example code from the top-level application directory,
$ node ./examples/index.js
Notes
This module currently only supports directories and files and does not support symlinks, devices, FIFO, or sockets.
Tests
Unit
Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:
$ make test
All new feature development should have corresponding unit tests to validate correct functionality.
Test Coverage
This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:
$ make test-cov
Istanbul creates a ./reports/coverage
directory. To access an HTML version of the report,
$ open reports/coverage/lcov-report/index.html
Prior Art
Event-emitters:
Filesystem:
License
Copyright
Copyright © 2014. Athan Reines.