dir_tree

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