Topiary

Topiary is a utility that shapes tree structures into a prettified format ala npm list. It is used by npm-graph.

Usage

Given a tree structure and a key to recurse on, call topiary on that object:

var topiary = require('topiary');

var tree = {
  name: "root",
  deps: [
    {
      name : 'sub1',
      deps : []
    },
    {
      name : 'sub2',
      deps : [ { name : 'sub2sub', deps : [] } ]
    },
    {
      name : 'sub3',
      deps : []
    }
  ]
};
console.log(topiary(tree, 'deps'));

Output:

root
 ├──sub1
 ├─┬sub2
 │ └──sub2sub
 └──sub3

The 'deps' string is the key to recurse on, expected to hold an array of objects of the same structure.

Options

A third options object can be supplied to topiary with the following key/value combinations:

name

If labelling by the default name key is not working, you can supply your own labeller:

var namer = function (obj) {
  return '#' + obj.name; // combine stuff from object into a sensible string
};
console.log(topiary(tree, 'deps', { name: namer }));

root
 ├──#sub1
 ├─┬#sub2
 │ └──#sub2sub
 └──#sub3

filter

You can optionally pass in a function to help filter certain branches or leaf nodes:

var isNotSub2 = function (el) {
  return (el.name !== 'sub2');
};
console.log(topiary(tree, 'deps', { filter: isNotSub2 }));

Output:

root
 ├──sub1
 └──sub3

sort

You can ask topiary to sort the recurseName array before starting to work on it. This solves non-deterministic outputs sometimes produced if it is generated in a non-deterministic manner:

console.log(topiary(tree, 'deps', { label: namer, sort: true }));

Note that sorting is done lexicographically based on the labels output by the label functions.

Installation

$ npm install topiary

License

MIT-Licensed. See LICENSE file for details.

1.1.2 / 2015-11-14

• Added npmignore

1.1.1 / 2014-07-12

• Misnamed keys in documentation

1.1.0 / 2014-07-12

• Third input changed - is now an object of optionals:
  • label: function producing string from obj (old nameFn - old 3rd arg)
  • filter: function returning bool from obj (old filterFn - old 4th arg)
  • sort: boolean for whether to sort 'recurseName' by label lexicographically

1.0.1 / 2014-07-11

• Fix turnChar bug introduced in rewrite

1.0.0 / 2014-07-11

• Rewritten to recurse into an array rather an object - see readme
• Now throws when given a recurse key not present on root
• Test coverage and documentation improvements

0.0.2 / 2012-10-20

• Docmuntation maintenance

0.0.1 / 2012-01-28

• First release