textio

README

textio

Go package providing tools for advanced text manipulations

Motivation

This package aims to provide a sutie of tools to deal with text parsing and formatting. It is intended to extend what the standard library already offers, and make it easy to integrate with it.

Examples

This sections presents a couple of examples about how to use this package.

Indenting

Indentation is often a complex problem to solve when dealing with stream of text that may be composed of multiple lines. To address this problem, this package provides the textio.PrefixWriter type, which implements the io.Writer interface and automatically prepends every line of output with a predefined prefix.

Here is an example:

func copyIndent(w io.Writer, r io.Reader) error {
    p := textio.NewPrefixWriter(w, "\t")

    // Copy data from an input stream into the PrefixWriter, all lines will
    // be prefixed with a '\t' character.
    if _, err := io.Copy(p, r); err != nil {
        return err
    }

    // Flushes any data buffered in the PrefixWriter, this is important in
    // case the last line was not terminated by a '\n' character.
    return p.Flush()
}

Tree Formatting

A common way to represent tree-like structures is the formatting used by the tree(1) unix command. The textio.TreeWriter type is an implementation of an io.Writer which supports this kind of output. It works in a recursive fashion where nodes created from a parent tree writer are formatted as part of that tree structure.

Here is an example:

func ls(w io.Writer, path string) {
	tree := NewTreeWriter(w)
	tree.WriteString(filepath.Base(path))
	defer tree.Close()

	files, _ := ioutil.ReadDir(path)

	for _, f := range files {
		if f.Mode().IsDir() {
			ls(tree, filepath.Join(path, f.Name()))
		}
	}

	for _, f := range files {
		if !f.Mode().IsDir() {
			io.WriteString(NewTreeWriter(tree), f.Name())
		}
	}
}

...

ls(os.Stdout, "examples")

Which gives this output:

examples
├── A
│   ├── 1
│   └── 2
└── message

Documentation

Index

• func Base(w io.Writer) io.Writer
• func Parent(w io.Writer) io.Writer
• func Root(w io.Writer) io.Writer
• type PrefixWriter
  • func NewPrefixWriter(w io.Writer, s string) *PrefixWriter
  • func (w *PrefixWriter) Base() io.Writer
  • func (w *PrefixWriter) Buffered() []byte
  • func (w *PrefixWriter) Flag(c int) bool
  • func (w *PrefixWriter) Flush() error
  • func (w *PrefixWriter) Precision() (int, bool)
  • func (w *PrefixWriter) Width() (int, bool)
  • func (w *PrefixWriter) Write(b []byte) (int, error)
  • func (w *PrefixWriter) WriteString(s string) (int, error)
• type TreeWriter
  • func NewTreeWriter(w io.Writer) *TreeWriter
  • func (w *TreeWriter) Base() io.Writer
  • func (w *TreeWriter) Close() (err error)
  • func (w *TreeWriter) Flag(c int) bool
  • func (w *TreeWriter) Parent() io.Writer
  • func (w *TreeWriter) Precision() (int, bool)
  • func (w *TreeWriter) Root() io.Writer
  • func (w *TreeWriter) Width() (int, bool)
  • func (w *TreeWriter) Write(b []byte) (int, error)
  • func (w *TreeWriter) WriteByte(b byte) error
  • func (w *TreeWriter) WriteRune(r rune) (int, error)
  • func (w *TreeWriter) WriteString(s string) (int, error)

Examples

• NewTreeWriter

Functions

func Base

func Base(w io.Writer) io.Writer

Base returns the direct base of w, which may be w itself if it had no base writer.

func Parent

func Parent(w io.Writer) io.Writer

Parent returns the parent writer of w, which is usually a writer of a similar type on tree-like writer structures.

func Root

func Root(w io.Writer) io.Writer

Root returns the root writer of w, which is found by going up the list of base writers.

The node is usually the writer where the content ends up being written.

Types

type PrefixWriter

type PrefixWriter struct {
	// contains filtered or unexported fields
}

PrefixWriter is an implementation of io.Writer which places a prefix before every line.

Instances of PrefixWriter are not safe to use concurrently from multiple goroutines.

func NewPrefixWriter

func NewPrefixWriter(w io.Writer, s string) *PrefixWriter

NewPrefixWriter constructs a PrefixWriter which outputs to w and prefixes every line with s.

func (*PrefixWriter) Base

func (w *PrefixWriter) Base() io.Writer

Base returns the underlying writer that w outputs to.

func (*PrefixWriter) Buffered

func (w *PrefixWriter) Buffered() []byte

Buffered returns a byte slice of the data currently buffered in the writer.

func (*PrefixWriter) Flag

func (w *PrefixWriter) Flag(c int) bool

Flag satisfies the fmt.State interface.

func (*PrefixWriter) Flush

func (w *PrefixWriter) Flush() error

Flush forces all buffered data to be flushed to the underlying writer.

func (*PrefixWriter) Precision

func (w *PrefixWriter) Precision() (int, bool)

Precision satisfies the fmt.State interface.

func (*PrefixWriter) Width

func (w *PrefixWriter) Width() (int, bool)

Width satisfies the fmt.State interface.

func (*PrefixWriter) Write

func (w *PrefixWriter) Write(b []byte) (int, error)

Write writes b to w, satisfies the io.Writer interface.

func (*PrefixWriter) WriteString

func (w *PrefixWriter) WriteString(s string) (int, error)

WriteString writes s to w.

type TreeWriter

type TreeWriter struct {
	// contains filtered or unexported fields
}

TreeWriter is an implementation of an io.Writer which prints a tree-like representation of the content.

Instances of TreeWriter are not safe to use concurrently from multiple goroutines.

func NewTreeWriter

func NewTreeWriter(w io.Writer) *TreeWriter

NewTreeWriter constructs a new TreeWriter which outputs to w. If w is an instance of TreeWriter itself the new writer is added to the list of child nodes that will be renderend.

Example

var ls func(io.Writer, string)

ls = func(w io.Writer, path string) {
	tree := NewTreeWriter(w)
	tree.WriteString(filepath.Base(path))
	defer tree.Close()

	files, _ := ioutil.ReadDir(path)

	for _, f := range files {
		if f.Mode().IsDir() {
			ls(tree, filepath.Join(path, f.Name()))
		}
	}

	for _, f := range files {
		if !f.Mode().IsDir() {
			io.WriteString(NewTreeWriter(tree), f.Name())
		}
	}
}

ls(os.Stdout, "examples")

Output:

examples
├── A
│   ├── 1
│   └── 2
└── message

func (*TreeWriter) Base

func (w *TreeWriter) Base() io.Writer

Base returns the base writer of w.

func (*TreeWriter) Close

func (w *TreeWriter) Close() (err error)

Close closes w, causing all buffered content to be flushed to its underlying writer, and future write operations to error with io.ErrClosedPipe.

func (*TreeWriter) Flag

func (w *TreeWriter) Flag(c int) bool

Flag satisfies the fmt.State interface.

func (*TreeWriter) Parent

func (w *TreeWriter) Parent() io.Writer

Parent returns the parent node of w, which its most direct base of type *TreeWriter.

func (*TreeWriter) Precision

func (w *TreeWriter) Precision() (int, bool)

Precision satisfies the fmt.State interface.

func (*TreeWriter) Root

func (w *TreeWriter) Root() io.Writer

Root returns the root of w, which is the node on which calling Close will cause the tree to be rendered to the underlying writer.

func (*TreeWriter) Width

func (w *TreeWriter) Width() (int, bool)

Width satisfies the fmt.State interface.

func (*TreeWriter) Write

func (w *TreeWriter) Write(b []byte) (int, error)

Write writes b to w, satisfies the io.Writer interface.

func (*TreeWriter) WriteByte

func (w *TreeWriter) WriteByte(b byte) error

WriteByte writes b to w.

func (*TreeWriter) WriteRune

func (w *TreeWriter) WriteRune(r rune) (int, error)

WriteRune writes r to w.

func (*TreeWriter) WriteString

func (w *TreeWriter) WriteString(s string) (int, error)

WriteString writes s to w.