treefs

README

Package treefs provides functionality to print a simple graph of an fs.FS using the template of the tree command.

The version of tree whose graph is mimicked is tree v2.0.2 (c) 1996 - 2022 by Steve Baker, Thomas Moore, Francesc Rocher, Florian Sesser, Kyosuke Tokoro.

To get the graph representation and metadata of an fs.FS, construct a TreeFS and use its String method.

Consider the following directory (whose graph was generated by tree v2.0.2)

testdata
└── a
    ├── a1.test
    ├── a2.test
    ├── a3.test
    ├── b
    │   ├── b1.test
    │   ├── b2.test
    │   ├── b3.test
    │   └── d
    │       └── d1.test
    └── c
        ├── c1.test
        └── c2.test

4 directories, 9 files

Its graph could be constructed using treefs in the following way

var testdataFS fs.FS // assume this is embedded or read with os.DirFS
tfs, err := New(testdataFS, "testdata")
if err != nil {
    log.Fatal(err)
}
fmt.Println(tfs)

which would generate the following output

testdata
└── a
    ├── a1.test
    ├── a2.test
    ├── a3.test
    ├── b
    │   ├── b1.test
    │   ├── b2.test
    │   ├── b3.test
    │   └── d
    │       └── d1.test
    └── c
        ├── c1.test
        └── c2.test

4 directories, 9 files

Aggregated trees are allowed as well:

var args []Arg // see internal/examples/multi
multitfs, err := NewMutli(args...)
if err != nil {
    log.Fatal(err)
}
fmt.Println(multitfs)

could result in the following aggregate

.
└── main.go
../../../../treefs
├── LICENSE
├── go.mod
├── internal
│   └── examples
│       ├── multi
│       │   └── main.go
│       └── single
│           └── main.go
├── testdata
│   └── a
│       ├── a1.test
│       ├── a2.test
│       ├── a3.test
│       ├── b
│       │   ├── b1.test
│       │   ├── b2.test
│       │   ├── b3.test
│       │   └── d
│       │       └── d1.test
│       └── c
│           ├── c1.test
│           └── c2.test
├── treefs.go
└── treefs_test.go

9 directories, 16 files

Options can be provided with Opts.

For example, to display hidden directories and files (which are excluded by default), use the Hidden option:

tree, err := Tree(fsys, ".", Hidden)
if err != nil {
    log.Fatal(err)
}
fmt.Println(tree)

.
├── .hidden1
├── .hidden2
├── .hidden3
├── a1.test
├── a2.test
├── a3.test
├── b
│   ├── .hidden1
│   ├── b1.test
│   ├── b2.test
│   ├── b3.test
│   └── d
│       ├── .hidden1
│       └── d1.test
└── c
    ├── .hidden1
    ├── c1.test
    └── c2.test

3 directories, 15 files

The DirOnly option only displays directories:

tree, err := Tree(fsys, ".", DirOnly)
if err != nil {
    log.Fatal(err)
}
fmt.Println(tree)

testdata
└── a
    ├── b
    │   └── d
    └── c

4 directories

FullPathPrefix includes the full path prefix for each file:

tree, err := Tree(fsys, ".", FullPathPrefix)
if err != nil {
    log.Fatal(err)
}
fmt.Println(tree)

testdata
└── testdata/a
    ├── testdata/a/a1.test
    ├── testdata/a/a2.test
    ├── testdata/a/a3.test
    ├── testdata/a/b
    │   ├── testdata/a/b/b1.test
    │   ├── testdata/a/b/b2.test
    │   ├── testdata/a/b/b3.test
    │   └── testdata/a/b/d
    │       └── testdata/a/b/d/d1.test
    └── testdata/a/c
        ├── testdata/a/c/c1.test
        └── testdata/a/c/c2.test

4 directories, 9 files

Level sets the max display depth of the directory tree:

tree, err := Tree(fsys, ".", Level(2))
if err != nil {
    log.Fatal(err)
}
fmt.Println(tree)

testdata
└── a
    ├── a1.test
    ├── a2.test
    ├── a3.test
    ├── b
    └── c

3 directories, 3 files

See examples for example usage.

Documentation

Overview

Package treefs provides functionality to print a simple graph of an fs.FS using the template of the `tree` command.

The version of `tree` whose graph is mimicked is tree v2.0.2 (c) 1996 - 2022 by Steve Baker, Thomas Moore, Francesc Rocher, Florian Sesser, Kyosuke Tokoro.

Index

• func DirOnly(t *TreeFS)
• func FullPathPrefix(t *TreeFS)
• func Graph(fsys fs.FS, name string, opts ...Opt) (string, error)
• func Hidden(t *TreeFS)
• func Meta(fsys fs.FS, name string, opts ...Opt) (string, error)
• func Tree(fsys fs.FS, name string, opts ...Opt) (string, error)
• type Arg
• type Opt
  • func Level(lvl int) Opt
• type TreeFS
  • func New(fsys fs.FS, name string, opts ...Opt) (tfs TreeFS, err error)
  • func NewMulti(args ...Arg) (tfs TreeFS, err error)
  • func (t TreeFS) Graph() string
  • func (t TreeFS) Meta() string
  • func (t TreeFS) String() string

Functions

func DirOnly

func DirOnly(t *TreeFS)

DirOnly includes only directories.

func FullPathPrefix

func FullPathPrefix(t *TreeFS)

FullPathPrefix includes the full path prefix for each file.

func Graph

func Graph(fsys fs.FS, name string, opts ...Opt) (string, error)

Graph returns only the graph of the fs.FS fsys with name name.

func Hidden

func Hidden(t *TreeFS)

Hidden allows hidden directories and entries.

func Meta

func Meta(fsys fs.FS, name string, opts ...Opt) (string, error)

Meta returns only the stringified metadata of the fs.FS fsys with name name.

func Tree

func Tree(fsys fs.FS, name string, opts ...Opt) (string, error)

Tree returns the graph, and metadata, of the fs.FS fsys with name name.

Types

type Arg

type Arg struct {
	Fsys fs.FS
	Name string
	Opts []Opt
}

Arg represents argument pairs for aggregate TreeFS constructs using NewMulti.

type Opt

type Opt func(*TreeFS)

Opt defines an optional argument for generating an fs.FS's tree.

func Level

func Level(lvl int) Opt

Level sets the max display depth of the directory tree.

type TreeFS

type TreeFS struct {
	NDirs  int // the number of directories that exist within an fs.FS
	NFiles int // the number of files that exist within an fs.Fs
	// contains filtered or unexported fields
}

TreeFS contains the required information to construct a graph for an fs.FS.

func New

func New(fsys fs.FS, name string, opts ...Opt) (tfs TreeFS, err error)

New returns a TreeFS whose stringer interface implementation returns the graph for the fs.FS fsys and name name, similar to the `tree` command.

It makes use of fs.ReadDir to walk fsys.

func NewMulti

func NewMulti(args ...Arg) (tfs TreeFS, err error)

NewMulti returns an aggregate TreeFS.

The graph of each fs.FS, name pair are separated by newlines and the metadata is aggregated.

It makes use of fs.ReadDir to walk fsys.

func (TreeFS) Graph

func (t TreeFS) Graph() string

Graph returns the stringified graph of the TreeFS t without any metadata.

func (TreeFS) Meta

func (t TreeFS) Meta() string

Meta returns the stringified metadata for the TreeFS t.

func (TreeFS) String

func (t TreeFS) String() string

String implements the stringer interface for TreeFS.

It returns the stringified graph of the TreeFS t with metadata at the bottom, similar to the `tree` command.