gulp-filetree

Gulp VFS Tree

Not everything in this documentation works yet. Have a look at the source, Luke. It's readable and documented! :-)

Quickstart

Quick! Start!

$ npm i --save-dev gulp-load-plugins gulp-map gulp-filetree archy

Quick, edit gulpfile.js!

var gulp = require('gulp');
var archy = require('archy');
var $ = require('gulp-load-plugins')();
 
gulp.task('default', function(){
    var once = true; // lalz0r
    return gulp.src('node_modules/gulp-map/**')
        .pipe($.map(function(file){
            if(file.path.match(/package\.json/))
                return file
        }))
        .pipe($.filetree({cwdRelative: true}))
        .pipe($.map(function(file){
            // file.tree: tree of files passed into $.filetree
            // file.subtree: subtree rooted at this file
 
            if(once) {
                console.log(archy(file.tree));
                once = !once;
            }
 
            return file;
        }))
});

Output

[22:01:01] Using gulpfile /tmp/test/gulpfile.js
[22:01:01] Starting 'default'...
node_modules
└─┬ gulp-map
  ├── package.json
  └─┬ node_modules
    ├─┬ is-promise
    │ └── package.json
    ├─┬ kew
    │ └── package.json
    └─┬ through2
      ├── package.json
      └─┬ node_modules
        ├─┬ readable-stream
        │ ├── package.json
        │ └─┬ node_modules
        │   ├─┬ core-util-is
        │   │ └── package.json
        │   ├─┬ inherits
        │   │ └── package.json
        │   ├─┬ isarray
        │   │ └── package.json
        │   └─┬ string_decoder
        │     └── package.json
        └─┬ xtend
          └── package.json

[22:01:01] Finished 'default' after 81 ms

What happened?

Suppose you have this tree in a subdirectory test.

.
├── a.txt
├── b.txt
└── c
    ├── d.txt
    └── e.txt

This plugin will then compute a tree like this:

    { label: '.',
      leaf: undefined,
      parent: undefined,
      nodes: [
          { label: 'a.txt',
            leaf: <File ..>,
            parent: <Tree ..>, // reference
            nodes: []
          },
          { label: 'b.txt',
            leaf: <File ..>,
            parent: <Tree ..>, // reference
            nodes: [ { label: 'd.txt', ... } ,
                     { label: 'e.txt', ... } ]
          }
      ]
    }

This tree is then used to add properties 'tree' and 'subtree' to the files passing though this filter.

Okay, then what?

Once all files are collected and a tree of them has been constructed, that tree is traversed in the given order (options.order, default is BFS).

Each visited file then gets a property tree (option tree_property) pointing to the complete tree.

The is also a property subtree (option subtree_property), which has the tree restricted to the subtree rooted at that file.

Options

You can set some basic options.

var options = {
    // name of the 'tree' property
    tree_property: "tree",
 
    // name of 'subtree' property
    subtree_property: "subtree",
 
    // file emitting order: breath-first / depth-first ("DFS")
    order: "DFS",
 
    // compute filepath path relative to current working directory
    cwdRelative: true // relative to file.base path if false
};

Showing the tree

Archy can render it fine. Pretty-tree doesn't like the circular structure of the parent and leaf.tree/leaf.subtree properties.

Tapping the tree, transforming the tree

I've had limited succes with t. Traversals work, mapping doesn't. Be sure to pass the option {childName:'nodes'}.

var path = require('path');
var t = require('t');
 
.pipe($.map(function(file){
    // this should be a persistent datastructure
    t.bfs(file.subtree, function(node){
        var basename = path.basename(node.leaf.path);
        console.log('\t' + basename);
    });
});
 
// this below fo sho doesn't work, but I want to be able to do this
.pipe($.map(function(file){
    // write to a file and pass through untouched on success.
    return Q
        .nfcall(fs.writeFile,
            'siteIndex.json',
            JSON.stringify(file.tree)
        ))
        .then(function(){
            return tree;
        });
}