TTY::Tree

Print directory or structured data in a tree like format.

TTY::Tree provides independent directory or hash data rendering component for TTY toolkit.

Installation

Add this line to your application's Gemfile:

gem "tty-tree"

And then execute:

$ bundle

Or install it yourself as:

$ gem install tty-tree

Contents

• 1. Usage
• 2. Interface
  • 2.1 new
    • 2.1.1 :level
    • 2.1.2 :file_limit
    • 2.1.3 :show_hidden
    • 2.1.4 :only_dirs
  • 2.2 render
    • 2.2.1 :indent

1. Usage

TTY::Tree accepts as input a directory path:

tree = TTY::Tree.new(Dir.pwd)
tree = TTY::Tree.new("dir-name")

It can also be given as its input a hash data structure with keys representing directories and values as arrays representing directory contents:

data = {
  dir1: [
    "config.dat",
    {dir2: [
      {dir3: ["file3-1.txt"]},
      "file2-1.txt"
    ]},
    "file1-1.txt",
    "file1-2.txt"
  ]
}

tree = TTY::Tree.new(data)

You can also construct tree with a DSL:

tree = TTY::Tree.new do
  node "dir1" do
    node "config.dat"
    node "dir2" do
      node "dir3" do
        leaf "file3-1.txt"
      end
      leaf "file2-1.txt"
    end
    node "file1-1.txt"
    leaf "file1-2.txt"
  end
end

The TTY::Tree can print the content in various formats. By default, a directory format is used by invoking render:

puts tree.render
# =>
# dir1
# ├── config.dat
# ├── dir2
# │   ├── dir3
# │   │   └── file3-1.txt
# │   └── file2-1.txt
# ├── file1-1.txt
# └── file1-2.txt

The render call returns a string and leaves it up to the consumer how to handle the tree-like output.

2. Interface

2.1 new

In order to create TTY::Tree you need to provide either a path to directory which can be a String, Pathname or Dir:

tree = TTY::Tree.new(Dir.pwd)
tree = TTY::Tree.new("dir-name")
tree = TTY::Tree.new(Pathname.pwd)

Or hash data structure:

data = {
  dir1: [
    "config.dat",
    ...
  ]
}

tree = TTY::Tree.new(data)

As a shortcut notation, you can create a tree using [] like so:

tree = TTY::Tree[Dir.pwd]

You can also use DSL to build a tree by using node and leaf methods:

tree = TTY::Tree.new do
  node "dir1" do
    node "config.dat"
    node "dir2" do
      node "dir3" do
        leaf "file3-1.txt"
      end
      leaf "file2-1.txt"
    end
    node "file1-1.txt"
    leaf "file1-2.txt"
  end
end

2.1.1 :level

The maximum level of depth for this tree when parsing directory. The initial directory is treated as index 0.

tree = TTY::Tree.new("dir-name", level: 2)
# => parse directories as deep as 2 levels

2.1.2 :file_limit

Prevent TTY::Tree descending directories with more than a given number of entries:

tree = TTY::Tree.new("dir-name", file_limit: 2)

2.1.3 :show_hidden

In order to for TTY::Tree to include hidden files in its output use :show_hidden option like so:

tree = TTY::Tree.new("dir-name", show_hidden: true)

2.1.4 :only_dirs

To only display directory entries in the output use :only_dirs option:

tree = TTY::Tree.new("dir-name", only_dirs: true)

By default, hidden directories are not included in the output. If you wish to show hidden directories as well do:

tree = TTY::Tree.new("dir-name", only_dirs: true, show_hidden: true)

2.2 render

By default, content is printed using TTY::PathRenderer. If you prefer a numeric notation of nested content, you can use TTY::NumberRenderer to enumerates each nested node like so:

puts tree.render(as: :number)
# =>
# dir1
# 1.1 config.dat
# 1.2 dir2
#     2.3 dir3
#         3.4 file3-1.txt
#     2.5 file2-1.txt
# 1.6 file1-1.txt
# 1.7 file1-2.txt

2.2.1 :indent

The number of spaces to use when indenting nested directories. By default, 4 spaces are used.

tree.render(as: :dir, indent: 2)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-tree. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Copyright

Copyright (c) 2017 Piotr Murach. See LICENSE for further details.