Skip to content
Print directory or structured data in a tree like format
Branch: master
Clone or download

README.md

tty logo

TTY::Tree Gitter

Gem Version Build Status Build status Code Climate Coverage Status Inline docs

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

TTY::Tree accepts as input a directory path:

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

or can 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 api 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 as shortcut notation you can call [] like so:

tree = TTY::Tree[Dir.pwd]

You can also use DSL to build tree by using node & leaf:

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 more than # 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)

Listing directories does not inlucde hidden ones. 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 deafult 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.

You can’t perform that action at this time.