version: 1.10

package tabwriter

import "text/tabwriter"

Overview

Package tabwriter implements a write filter (tabwriter.Writer) that translates
tabbed columns in input into properly aligned text.

The package is using the Elastic Tabstops algorithm described at
http://nickgravgaard.com/elastictabstops/index.html.

The text/tabwriter package is frozen and is not accepting new features.


Example:

  1. // Observe how the b's and the d's, despite appearing in the
  2. // second cell of each line, belong to different columns.
  3. w := tabwriter.NewWriter(os.Stdout, 0, 0, 1, '.', tabwriter.AlignRight|tabwriter.Debug)
  4. fmt.Fprintln(w, "a\tb\tc")
  5. fmt.Fprintln(w, "aa\tbb\tcc")
  6. fmt.Fprintln(w, "aaa\t") // trailing tab
  7. fmt.Fprintln(w, "aaaa\tdddd\teeee")
  8. w.Flush()
  10. // output:
  11. // ....a|..b|c
  12. // ...aa|.bb|cc
  13. // ..aaa|
  14. // .aaaa|.dddd|eeee


Example:

  1. // Observe that the third line has no trailing tab,
  2. // so its final cell is not part of an aligned column.
  3. const padding = 3
  4. w := tabwriter.NewWriter(os.Stdout, 0, 0, padding, '-', tabwriter.AlignRight|tabwriter.Debug)
  5. fmt.Fprintln(w, "a\tb\taligned\t")
  6. fmt.Fprintln(w, "aa\tbb\taligned\t")
  7. fmt.Fprintln(w, "aaa\tbbb\tunaligned") // no trailing tab
  8. fmt.Fprintln(w, "aaaa\tbbbb\taligned\t")
  9. w.Flush()
  11. // output:
  12. // ------a|------b|---aligned|
  13. // -----aa|-----bb|---aligned|
  14. // ----aaa|----bbb|unaligned
  15. // ---aaaa|---bbbb|---aligned|

Index

Examples

Package files

tabwriter.go

Constants

  1. const (
  2.     // Ignore html tags and treat entities (starting with '&'
  3.     // and ending in ';') as single characters (width = 1).
  4.     FilterHTML uint = 1 << iota
  5.  
  6.     // Strip Escape characters bracketing escaped text segments
  7.     // instead of passing them through unchanged with the text.
  8.     StripEscape
  9.  
  10.     // Force right-alignment of cell content.
  11.     // Default is left-alignment.
  12.     AlignRight
  13.  
  14.     // Handle empty columns as if they were not present in
  15.     // the input in the first place.
  16.     DiscardEmptyColumns
  17.  
  18.     // Always use tabs for indentation columns (i.e., padding of
  19.     // leading empty cells on the left) independent of padchar.
  20.     TabIndent
  21.  
  22.     // Print a vertical bar ('|') between columns (after formatting).
  23.     // Discarded columns appear as zero-width columns ("||").
  24.     Debug
  25. )

Formatting can be controlled with these flags.

  1. const Escape = '\xff'

To escape a text segment, bracket it with Escape characters. For instance, the
tab in this string “Ignore this tab: \xff\t\xff” does not terminate a cell and
constitutes a single character of width one for formatting purposes.

The value 0xff was chosen because it cannot appear in a valid UTF-8 sequence.

type Writer

  1. type Writer struct {
  2.     // contains filtered or unexported fields
  3. }

A Writer is a filter that inserts padding around tab-delimited columns in its
input to align them in the output.

The Writer treats incoming bytes as UTF-8-encoded text consisting of cells
terminated by horizontal (‘\t’) or vertical (‘\v’) tabs, and newline (‘\n’) or
formfeed (‘\f’) characters; both newline and formfeed act as line breaks.

Tab-terminated cells in contiguous lines constitute a column. The Writer inserts
padding as needed to make all cells in a column have the same width, effectively
aligning the columns. It assumes that all characters have the same width, except
for tabs for which a tabwidth must be specified. Column cells must be
tab-terminated, not tab-separated: non-tab terminated trailing text at the end
of a line forms a cell but that cell is not part of an aligned column. For
instance, in this example (where | stands for a horizontal tab):

  1. aaaa|bbb|d
  2. aa  |b  |dd
  3. a   |
  4. aa  |cccc|eee

the b and c are in distinct columns (the b column is not contiguous all the
way). The d and e are not in a column at all (there’s no terminating tab, nor
would the column be contiguous).

The Writer assumes that all Unicode code points have the same width; this may
not be true in some fonts or if the string contains combining characters.

If DiscardEmptyColumns is set, empty columns that are terminated entirely by
vertical (or “soft”) tabs are discarded. Columns terminated by horizontal (or
“hard”) tabs are not affected by this flag.

If a Writer is configured to filter HTML, HTML tags and entities are passed
through. The widths of tags and entities are assumed to be zero (tags) and one
(entities) for formatting purposes.

A segment of text may be escaped by bracketing it with Escape characters. The
tabwriter passes escaped text segments through unchanged. In particular, it does
not interpret any tabs or line breaks within the segment. If the StripEscape
flag is set, the Escape characters are stripped from the output; otherwise they
are passed through as well. For the purpose of formatting, the width of the
escaped text is always computed excluding the Escape characters.

The formfeed character acts like a newline but it also terminates all columns in
the current line (effectively calling Flush). Tab- terminated cells in the next
line start new columns. Unless found inside an HTML tag or inside an escaped
text segment, formfeed characters appear as newlines in the output.

The Writer must buffer input internally, because proper spacing of one line may
depend on the cells in future lines. Clients must call Flush when done calling
Write.

func NewWriter

  1. func NewWriter(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Writer

NewWriter allocates and initializes a new tabwriter.Writer. The parameters are
the same as for the Init function.

func (*Writer) Flush

  1. func (b *Writer) Flush() error

Flush should be called after the last call to Write to ensure that any data
buffered in the Writer is written to output. Any incomplete escape sequence at
the end is considered complete for formatting purposes.

func (*Writer) Init

  1. func (b *Writer) Init(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Writer

A Writer must be initialized with a call to Init. The first parameter (output)
specifies the filter output. The remaining parameters control the formatting:

  1. minwidth    minimal cell width including any padding
  2. tabwidth    width of tab characters (equivalent number of spaces)
  3. padding        padding added to a cell before computing its width
  4. padchar        ASCII char used for padding
  5.         if padchar == '\t', the Writer will assume that the
  6.         width of a '\t' in the formatted output is tabwidth,
  7.         and cells are left-aligned independent of align_left
  8.         (for correct-looking results, tabwidth must correspond
  9.         to the tab width in the viewer displaying the result)
  10. flags        formatting control


Example:

  1. w := new(tabwriter.Writer)
  3. // Format in tab-separated columns with a tab stop of 8.
  4. w.Init(os.Stdout, 0, 8, 0, '\t', 0)
  5. fmt.Fprintln(w, "a\tb\tc\td\t.")
  6. fmt.Fprintln(w, "123\t12345\t1234567\t123456789\t.")
  7. fmt.Fprintln(w)
  8. w.Flush()
  10. // Format right-aligned in space-separated columns of minimal width 5
  11. // and at least one blank of padding (so wider column entries do not
  12. // touch each other).
  13. w.Init(os.Stdout, 5, 0, 1, ' ', tabwriter.AlignRight)
  14. fmt.Fprintln(w, "a\tb\tc\td\t.")
  15. fmt.Fprintln(w, "123\t12345\t1234567\t123456789\t.")
  16. fmt.Fprintln(w)
  17. w.Flush()
  19. // output:
  20. // a    b    c    d        .
  21. // 123    12345    1234567    123456789    .
  22. //
  23. //     a     b       c         d.
  24. //   123 12345 1234567 123456789.

func (*Writer) Write

  1. func (b *Writer) Write(buf []byte) (n int, err error)

Write writes buf to the writer b. The only errors returned are ones encountered
while writing to the underlying output stream.