dir_tree
Version:
Creates a Searchable, Sortable & Printable Tree For Stated Directory Path.
606 lines (410 loc) • 15.1 kB
Markdown
```
---------------------------
T E R M I N O L O G Y
---------------------------
Dir,
is used as the short form for the word Directory.
Files of a dir,
means the direct descendant files to the dir.
Total files of a dir,
means both the direct & the indirect descendant files to the dir.
Dirs of a dir,
means the direct descendant dirs to the dir.
Total dirs of a dir,
means both the direct & the indirect descendant dirs to the dir.
DTNO,
is used as the acronym of the words Dir Tree Node Object.
Difference between path starting from a dir & path relative to a dir,
Take, A/B/C
Path of C relative to A is B/C.
Path of C starting from A is A/B/C.
-----------------------------
I N T R O D U C T I O N
-----------------------------
This is a NodeJS module.
It can create a 'tree' out of the stated dir path,
which will be searchable, sortable & printable.
The module exports an EventEmitter Class - DirTree.
Its constructor takes the target dir path as its argument.
Its object will emit either an error event or a data event depending
on whether it failed or succeeded in compiling the tree for its
target dir path.
---------------
U S A G E
---------------
var DirTree = require('dir_tree')
var DirTreeNode = DirTree.DirTreeNode
// DirTreeNode is the Class whose Objects make up the Tree.
var dir_tree_obj = new DirTree(dir_path, filter)
// Both these parameters are discussed below.
dir_tree_obj.on('error', function(error) {
// The error is an Error Object.
// The error handling can be done here.
})
dir_tree_obj.on('data', function(Root_DTNO) {
// The Root_DTNO is the root of the Tree.
// It can be null in the case patterns are specified & match
// nothing. The properties & methods of a DirTreeNode Object are
// discussed below.
})
-------------------------
P A R A M E T E R S
-------------------------
[01] dir_path
--------
A string.
It is the path of the target dir.
[02] filter
------
An Object that should have the following structure:
{
idr, // RegExp Object
edr, // RegExp Object
ifr, // RegExp Object
efr, // RegExp Object
max_depth // Integer > 0
}
It's an optional argument.
Also all the properties are optional too.
Through filter you can:
1. choose only the specific file & dir paths,
2. ignore specific file & dir paths completely.
These --> idr, edr, ifr, efr <-- are RegExp Objects or patterns
that one can use to filter files & directories, while processing.
See the DirTreeNode.filter_files() method below for their
elaboration.
In short terms, they are the patterns that determine which file
paths to include &/or exclude in the dir tree.
The filter.max_depth is a non-zero natural number that can control
the depth of the dir tree i.e, how deep inside to go from the root
dir.
-------------------------
P R O P E R T I E S
-------------------------
[01] DTNO.path_from_root
-------------------
A string.
It is the path of this DTNO starting from the root directory.
[02] DTNO.path
---------
A string.
It is the path of this DTNO.
[03] DTNO.name
---------
A string.
It is the name of this DTNO.
[04] DTNO.is_a_dir
-------------
A boolean.
For a dir type DTNO, it is true, otherwise it is false.
[05] DTNO.files
----------
An Array of file type DTNOs.
For a dir type DTNO, they are the "files of the dir".
[06] DTNO.dirs
---------
An Array of dir type DTNOs.
For a dir type DTNO, they are the "dirs of the dir".
[07] DTNO.size
---------
An integer >= 0.
For a file type DTNO, it is the size of the file, in bytes.
For a dir type DTNO, it is the sum of the sizes of the "total files
of the dir", in bytes.
[08] DTNO.size_of_files
------------------
An integer >= 0.
For a dir type DTNO, it is the sum of the sizes of the "files of the
dir", in bytes.
[09] DTNO.no_of_total_files
----------------------
An integer >= 0.
For a dir type DTNO, it is the no of the "total files of the dir".
[10] DTNO.no_of_total_dirs
---------------------
An integer >= 0.
For a dir type DTNO, it is the no of the "total dirs of the dir".
[11] DTNO.created_on
---------------
A Date.
It is the creation time of this DTNO.
[12] DTNO.modified_on
----------------
A Date.
It is the modification time of this DTNO.
[13] DTNO.parent
-----------
A DTNO.
Each DTNO has a parent dir type DTNO (as in each file/dir has a parent
dir), except the root DTNO.
[14] DTNO.unread_paths
-----------------
An Array of strings.
For a dir type DTNO, these are the direct descendant paths to the dir
that resulted in error when attempted to read.
These paths start from the root.
[15] DTNO.no_of_total_unread_paths
-----------------------------
An integer >= 0.
For a dir type DTNO, this is the no of both the direct and the
indirect descendant paths to the dir that resulted in error when
attempted to read.
[16] DTNO.hide
---------
A boolean.
If true DirTreeNode.tree() will not embed this DTNO.
DirTreeNode.tree() is documented below.
-------------------
M E T H O D S
-------------------
Note:
----
The following methods are intended to be used only on the dir type
DTNOs.
They will throw a 'Not a Directory!' Error if such is not the case.
[01] DTNO.total_files()
----------------
Used to find the "total files of the dir".
Returns Array of Objects:
FA_S: [
// Let's call this structure the Files-Array Structure
{
path_from_root: string,
// path of the file starting from the DTNO on which
// the total_files() was invoked.
path: string,
// path of the file
name: string,
// name of the file
size: integer,
// size of the file
created_on: Date,
// time the file was created
modified_on: Date
// time the file was modified
},
...
]
[02] DTNO.serial()
-----------
Used to get a JSON-serializable Object representing the dir.
Returns an Object having the following structure:
SDTN_S: {
// Let's call this structure the Serializable-Dir-Tree-Node
// Structure
path_from_root: string,
// path of the file starting from the DTNO on which
// the serial() was invoked.
path: string,
// path of the dir
name: string,
// name of the dir
size: integer,
// sum of the sizes of the "total files of the dir"
size_of_files: integer,
// sum of the sizes of the "files of the dir"
no_of_total_files: integer,
// the no of the "files of the dir"
no_of_total_dirs: integer,
// the no of the "dirs of the dir"
created_on: Date,
// creation time of the dir
modified_on: Date,
// modification time of the dir
no_of_total_unread_paths: integer,
// the no of the direct & the indirect descendant paths to the
// the dir that couldn't be read
unread_paths: [ strings, ... ],
// the direct descendant paths to the dir that couldn't be read
files: FA_S,
// the direct descendant files to the dir
dirs: [ SDTN_S, ... ]
// the direct descendant dirs to the dir, dubbed in SDTN_S
}
[03] DTNO.dirs_creation_order()
------------------------
Used to find a valid creation order of the "total dirs of the dir".
To replicate a dir hierarchy, we must create its dirs in a valid
order, as in, the parent dir must exist before it can have any child
dirs in it.
Thus this method gives the paths of the "total dirs of the dir"
arranged in a valid creation order.
These paths are relative to the path of the root dir i.e., to the
DTNO on which the dirs_creation_order() was invoked.
Returns an Array of strings.
[04] DTNO.tree([indent])
--------- ------
Used to generate the 'print ready' tree of the dir.
The indent is a string that will be used to fill the left side of
the tree.
The DTNOs which have the DTNO.hide property set to true will not
be embedded into the dir tree.
Returns a string - A printable dir tree.
[05] DTNO.fileless_tree([indent])
------------------ ------
Used to generate a 'hollow' tree of this dir i.e., one w/o any files.
The indent is a string that will be used to fill the left side of the
tree.
Returns a string - A printable dir tree.
[06] DTNO.filter_files(filter)
----------------- ------
Used to filter files using patterns.
The filter is an Object that should have the following structure:
{
idr, // RegExp Object
edr, // RegExp Object
ifr, // RegExp Object
edr, // RegExp Object
max_depth // Integer > 0
}
Please mind that the patterns test the paths relative to the path
of this DTNO dir i.e., those paths will be relative the DTNO on
which the filter_files() was invoked.
Let's call,
idr - include dir regex
edr - exclude dir regex
ifr - include file regex
efr - exclude file regex
File filtering logic:
--------------------
A dir will be searched only if it's not excluded.
(its path isn't like edr)
An excluded dir will not be searched at all.
After that, if the dir is not included (path isn't like idr),
then the "files of this dir" will be skipped.
Though the "dirs of this dir" will be considered for search.
Whenever a compatible dir is found (path is idr-edr passed),
each of the "files of this dir" is tested:
to be not excluded (path isn't like efr) and
to be included (path is like ifr).
If so then the file is considered a successful match.
If you do not want to utilize some argument, pass null or undefined
instead.
Note:
----
Each argument should be either null or undefined or a RegExp Object.
If not then the method will throw an Error stating the invalid
argument.
If no files match,
Returns null.
Otherwise,
Returns a new DTNO, of the same dir path as of the DTNO whose
filter_files() was invoked. Difference being, the returned DTNO
will have only the targeted files.
[07] DTNO.filter_dirs(idr, edr)
---------------- --- ---
Used to filter dirs using patterns.
Please mind that the patterns test the paths relative to the path
of this DTNO dir i.e., those paths will be relative the DTNO on
which the filter_dirs() was invoked.
Let's call,
idr - include dir regex
edr - exclude dir regex
Dir filtering logic:
-------------------
A dir will be searched only if it's not excluded.
(its path isn't like edr)
An excluded dir will not be searched at all.
After that, if the dir is included (path is like idr),
it will be remembered.
& then the "dirs of this dir" will be searched.
If you do not want to utilize some argument, pass null or undefined
instead.
Returns an Array of dir type DTNOs.
Notes:
-----
1. Each argument should be either null or undefined or a
RegExp Object. If not then the method will throw an Error
stating the invalid argument.
2. Do note that the returned DTNOs still belong inside the
DTNO on which the filter_dirs() was invoked. They are not
copies or cloned DTNOs but the very ones that make up the
dir tree. The filter_files() method returns a new dir tree
altogether but the filter_dirs() method merely returns the
matched DTNOs packed in an Array.
[08] DTNO.sort(dir_comparator_func, file_comparator_func)
--------- ------------------- --------------------
Used to custom sort the dirs & the files.
The dir_comparator_func will sort the "dirs of the dir" & the
"dirs of each of the total dirs of the dir".
The file_comparator_func will sort the "files of the dir" & the
"files of each of the total dirs of the dir".
If some comparator_func isn't specified, alphabetical sort will be
performed instead.
Please mind that this method does affect the DTNOs because,
the DTNO.files & the DTNO.dirs both Arrays will be shuffled
internally for the DTNO dir itself & each of the "total dirs of
the DTNO dir".
Note:
----
The first time when the root DTNO is handed over via the callback,
these both Arrays will have been sorted already in the alphabetical
order.
Returns nothing.
[09] DTNO.total_unread_paths()
-----------------------
This method returns the direct & the indirect descendant paths to
this DTNO dir that resulted in error when attempted to read.
These paths start from the root.
Returns an Array of strings.
[10] DTNO.disjoin()
------------
This method can be used to disjoin this DTNO from the tree.
Returns nothing.
[11] DTNO.total_dirs()
---------------
Used to find the "total dirs of this dir".
Returns Array of Objects:
DA_S: [
// Let's call this structure the Dirs-Array Structure
{
path_from_root: string,
// path of the dir starting from the DTNO on which
// the total_dirs() was invoked.
path: string,
// path of the dir
name: string,
// name of the dir
size: integer,
// size of the dir
no_of_dirs: integer,
// no of the direct descenadnt dirs
no_of_files: integer,
// no of the direct descenadnt files
no_of_total_dirs: integer,
// no of the direct & the indirect descenadnt dirs
no_of_total_files: integer,
// no of the direct & the indirect descenadnt files
created_on: Date,
// time the dir was created
modified_on: Date
// time the dir was modified
},
...
]
[12] DTNO.remove_fileless_dirs()
-------------------------
Used to disjoin the direct & the indirect descendant dirs with no
files within them from the DTNO dir.
Returns nothing.
----------------------------
A C.L.I. T H I N G Y
----------------------------
There's also a CLI tool in the package, named:
dtree
It can do a few things, such as:
Printing a tree for the stated dir.
Filtering files & dirs using patterns.
Re-searching the file search results, which are again file
searchable.
Listing statistics such as:
The direct and/or indirect descendant files & dirs.
Their counts, sizes in bytes, creation & modification times.
Finding a valid order of creating dirs inside the stated dir.
Printing the hollow dir tree i.e., one not showing any files.
Etc.
To know more on using the CLI tool, simply execute:
dtree
Finally, you may want to have a look at the demo example packaged
inside.
```