...
Run Format

Source file src/text/tabwriter/tabwriter.go

Documentation: text/tabwriter

  // Copyright 2009 The Go Authors. All rights reserved.
  // Use of this source code is governed by a BSD-style
  // license that can be found in the LICENSE file.
  
  // 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.
  package tabwriter
  
  import (
  	"bytes"
  	"io"
  	"unicode/utf8"
  )
  
  // ----------------------------------------------------------------------------
  // Filter implementation
  
  // A cell represents a segment of text terminated by tabs or line breaks.
  // The text itself is stored in a separate buffer; cell only describes the
  // segment's size in bytes, its width in runes, and whether it's an htab
  // ('\t') terminated cell.
  //
  type cell struct {
  	size  int  // cell size in bytes
  	width int  // cell width in runes
  	htab  bool // true if the cell is terminated by an htab ('\t')
  }
  
  // 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):
  //
  //	aaaa|bbb|d
  //	aa  |b  |dd
  //	a   |
  //	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.
  //
  type Writer struct {
  	// configuration
  	output   io.Writer
  	minwidth int
  	tabwidth int
  	padding  int
  	padbytes [8]byte
  	flags    uint
  
  	// current state
  	buf     bytes.Buffer // collected text excluding tabs or line breaks
  	pos     int          // buffer position up to which cell.width of incomplete cell has been computed
  	cell    cell         // current incomplete cell; cell.width is up to buf[pos] excluding ignored sections
  	endChar byte         // terminating char of escaped sequence (Escape for escapes, '>', ';' for HTML tags/entities, or 0)
  	lines   [][]cell     // list of lines; each line is a list of cells
  	widths  []int        // list of column widths in runes - re-used during formatting
  }
  
  func (b *Writer) addLine() { b.lines = append(b.lines, []cell{}) }
  
  // Reset the current state.
  func (b *Writer) reset() {
  	b.buf.Reset()
  	b.pos = 0
  	b.cell = cell{}
  	b.endChar = 0
  	b.lines = b.lines[0:0]
  	b.widths = b.widths[0:0]
  	b.addLine()
  }
  
  // Internal representation (current state):
  //
  // - all text written is appended to buf; tabs and line breaks are stripped away
  // - at any given time there is a (possibly empty) incomplete cell at the end
  //   (the cell starts after a tab or line break)
  // - cell.size is the number of bytes belonging to the cell so far
  // - cell.width is text width in runes of that cell from the start of the cell to
  //   position pos; html tags and entities are excluded from this width if html
  //   filtering is enabled
  // - the sizes and widths of processed text are kept in the lines list
  //   which contains a list of cells for each line
  // - the widths list is a temporary list with current widths used during
  //   formatting; it is kept in Writer because it's re-used
  //
  //                    |<---------- size ---------->|
  //                    |                            |
  //                    |<- width ->|<- ignored ->|  |
  //                    |           |             |  |
  // [---processed---tab------------<tag>...</tag>...]
  // ^                  ^                         ^
  // |                  |                         |
  // buf                start of incomplete cell  pos
  
  // Formatting can be controlled with these flags.
  const (
  	// Ignore html tags and treat entities (starting with '&'
  	// and ending in ';') as single characters (width = 1).
  	FilterHTML uint = 1 << iota
  
  	// Strip Escape characters bracketing escaped text segments
  	// instead of passing them through unchanged with the text.
  	StripEscape
  
  	// Force right-alignment of cell content.
  	// Default is left-alignment.
  	AlignRight
  
  	// Handle empty columns as if they were not present in
  	// the input in the first place.
  	DiscardEmptyColumns
  
  	// Always use tabs for indentation columns (i.e., padding of
  	// leading empty cells on the left) independent of padchar.
  	TabIndent
  
  	// Print a vertical bar ('|') between columns (after formatting).
  	// Discarded columns appear as zero-width columns ("||").
  	Debug
  )
  
  // A Writer must be initialized with a call to Init. The first parameter (output)
  // specifies the filter output. The remaining parameters control the formatting:
  //
  //	minwidth	minimal cell width including any padding
  //	tabwidth	width of tab characters (equivalent number of spaces)
  //	padding		padding added to a cell before computing its width
  //	padchar		ASCII char used for padding
  //			if padchar == '\t', the Writer will assume that the
  //			width of a '\t' in the formatted output is tabwidth,
  //			and cells are left-aligned independent of align_left
  //			(for correct-looking results, tabwidth must correspond
  //			to the tab width in the viewer displaying the result)
  //	flags		formatting control
  //
  func (b *Writer) Init(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Writer {
  	if minwidth < 0 || tabwidth < 0 || padding < 0 {
  		panic("negative minwidth, tabwidth, or padding")
  	}
  	b.output = output
  	b.minwidth = minwidth
  	b.tabwidth = tabwidth
  	b.padding = padding
  	for i := range b.padbytes {
  		b.padbytes[i] = padchar
  	}
  	if padchar == '\t' {
  		// tab padding enforces left-alignment
  		flags &^= AlignRight
  	}
  	b.flags = flags
  
  	b.reset()
  
  	return b
  }
  
  // debugging support (keep code around)
  func (b *Writer) dump() {
  	pos := 0
  	for i, line := range b.lines {
  		print("(", i, ") ")
  		for _, c := range line {
  			print("[", string(b.buf.Bytes()[pos:pos+c.size]), "]")
  			pos += c.size
  		}
  		print("\n")
  	}
  	print("\n")
  }
  
  // local error wrapper so we can distinguish errors we want to return
  // as errors from genuine panics (which we don't want to return as errors)
  type osError struct {
  	err error
  }
  
  func (b *Writer) write0(buf []byte) {
  	n, err := b.output.Write(buf)
  	if n != len(buf) && err == nil {
  		err = io.ErrShortWrite
  	}
  	if err != nil {
  		panic(osError{err})
  	}
  }
  
  func (b *Writer) writeN(src []byte, n int) {
  	for n > len(src) {
  		b.write0(src)
  		n -= len(src)
  	}
  	b.write0(src[0:n])
  }
  
  var (
  	newline = []byte{'\n'}
  	tabs    = []byte("\t\t\t\t\t\t\t\t")
  )
  
  func (b *Writer) writePadding(textw, cellw int, useTabs bool) {
  	if b.padbytes[0] == '\t' || useTabs {
  		// padding is done with tabs
  		if b.tabwidth == 0 {
  			return // tabs have no width - can't do any padding
  		}
  		// make cellw the smallest multiple of b.tabwidth
  		cellw = (cellw + b.tabwidth - 1) / b.tabwidth * b.tabwidth
  		n := cellw - textw // amount of padding
  		if n < 0 {
  			panic("internal error")
  		}
  		b.writeN(tabs, (n+b.tabwidth-1)/b.tabwidth)
  		return
  	}
  
  	// padding is done with non-tab characters
  	b.writeN(b.padbytes[0:], cellw-textw)
  }
  
  var vbar = []byte{'|'}
  
  func (b *Writer) writeLines(pos0 int, line0, line1 int) (pos int) {
  	pos = pos0
  	for i := line0; i < line1; i++ {
  		line := b.lines[i]
  
  		// if TabIndent is set, use tabs to pad leading empty cells
  		useTabs := b.flags&TabIndent != 0
  
  		for j, c := range line {
  			if j > 0 && b.flags&Debug != 0 {
  				// indicate column break
  				b.write0(vbar)
  			}
  
  			if c.size == 0 {
  				// empty cell
  				if j < len(b.widths) {
  					b.writePadding(c.width, b.widths[j], useTabs)
  				}
  			} else {
  				// non-empty cell
  				useTabs = false
  				if b.flags&AlignRight == 0 { // align left
  					b.write0(b.buf.Bytes()[pos : pos+c.size])
  					pos += c.size
  					if j < len(b.widths) {
  						b.writePadding(c.width, b.widths[j], false)
  					}
  				} else { // align right
  					if j < len(b.widths) {
  						b.writePadding(c.width, b.widths[j], false)
  					}
  					b.write0(b.buf.Bytes()[pos : pos+c.size])
  					pos += c.size
  				}
  			}
  		}
  
  		if i+1 == len(b.lines) {
  			// last buffered line - we don't have a newline, so just write
  			// any outstanding buffered data
  			b.write0(b.buf.Bytes()[pos : pos+b.cell.size])
  			pos += b.cell.size
  		} else {
  			// not the last line - write newline
  			b.write0(newline)
  		}
  	}
  	return
  }
  
  // Format the text between line0 and line1 (excluding line1); pos
  // is the buffer position corresponding to the beginning of line0.
  // Returns the buffer position corresponding to the beginning of
  // line1 and an error, if any.
  //
  func (b *Writer) format(pos0 int, line0, line1 int) (pos int) {
  	pos = pos0
  	column := len(b.widths)
  	for this := line0; this < line1; this++ {
  		line := b.lines[this]
  
  		if column < len(line)-1 {
  			// cell exists in this column => this line
  			// has more cells than the previous line
  			// (the last cell per line is ignored because cells are
  			// tab-terminated; the last cell per line describes the
  			// text before the newline/formfeed and does not belong
  			// to a column)
  
  			// print unprinted lines until beginning of block
  			pos = b.writeLines(pos, line0, this)
  			line0 = this
  
  			// column block begin
  			width := b.minwidth // minimal column width
  			discardable := true // true if all cells in this column are empty and "soft"
  			for ; this < line1; this++ {
  				line = b.lines[this]
  				if column < len(line)-1 {
  					// cell exists in this column
  					c := line[column]
  					// update width
  					if w := c.width + b.padding; w > width {
  						width = w
  					}
  					// update discardable
  					if c.width > 0 || c.htab {
  						discardable = false
  					}
  				} else {
  					break
  				}
  			}
  			// column block end
  
  			// discard empty columns if necessary
  			if discardable && b.flags&DiscardEmptyColumns != 0 {
  				width = 0
  			}
  
  			// format and print all columns to the right of this column
  			// (we know the widths of this column and all columns to the left)
  			b.widths = append(b.widths, width) // push width
  			pos = b.format(pos, line0, this)
  			b.widths = b.widths[0 : len(b.widths)-1] // pop width
  			line0 = this
  		}
  	}
  
  	// print unprinted lines until end
  	return b.writeLines(pos, line0, line1)
  }
  
  // Append text to current cell.
  func (b *Writer) append(text []byte) {
  	b.buf.Write(text)
  	b.cell.size += len(text)
  }
  
  // Update the cell width.
  func (b *Writer) updateWidth() {
  	b.cell.width += utf8.RuneCount(b.buf.Bytes()[b.pos:b.buf.Len()])
  	b.pos = b.buf.Len()
  }
  
  // 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.
  //
  const Escape = '\xff'
  
  // Start escaped mode.
  func (b *Writer) startEscape(ch byte) {
  	switch ch {
  	case Escape:
  		b.endChar = Escape
  	case '<':
  		b.endChar = '>'
  	case '&':
  		b.endChar = ';'
  	}
  }
  
  // Terminate escaped mode. If the escaped text was an HTML tag, its width
  // is assumed to be zero for formatting purposes; if it was an HTML entity,
  // its width is assumed to be one. In all other cases, the width is the
  // unicode width of the text.
  //
  func (b *Writer) endEscape() {
  	switch b.endChar {
  	case Escape:
  		b.updateWidth()
  		if b.flags&StripEscape == 0 {
  			b.cell.width -= 2 // don't count the Escape chars
  		}
  	case '>': // tag of zero width
  	case ';':
  		b.cell.width++ // entity, count as one rune
  	}
  	b.pos = b.buf.Len()
  	b.endChar = 0
  }
  
  // Terminate the current cell by adding it to the list of cells of the
  // current line. Returns the number of cells in that line.
  //
  func (b *Writer) terminateCell(htab bool) int {
  	b.cell.htab = htab
  	line := &b.lines[len(b.lines)-1]
  	*line = append(*line, b.cell)
  	b.cell = cell{}
  	return len(*line)
  }
  
  func handlePanic(err *error, op string) {
  	if e := recover(); e != nil {
  		if nerr, ok := e.(osError); ok {
  			*err = nerr.err
  			return
  		}
  		panic("tabwriter: panic during " + op)
  	}
  }
  
  // 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 (b *Writer) Flush() error {
  	return b.flush()
  }
  
  func (b *Writer) flush() (err error) {
  	defer b.reset() // even in the presence of errors
  	defer handlePanic(&err, "Flush")
  
  	// add current cell if not empty
  	if b.cell.size > 0 {
  		if b.endChar != 0 {
  			// inside escape - terminate it even if incomplete
  			b.endEscape()
  		}
  		b.terminateCell(false)
  	}
  
  	// format contents of buffer
  	b.format(0, 0, len(b.lines))
  	return nil
  }
  
  var hbar = []byte("---\n")
  
  // Write writes buf to the writer b.
  // The only errors returned are ones encountered
  // while writing to the underlying output stream.
  //
  func (b *Writer) Write(buf []byte) (n int, err error) {
  	defer handlePanic(&err, "Write")
  
  	// split text into cells
  	n = 0
  	for i, ch := range buf {
  		if b.endChar == 0 {
  			// outside escape
  			switch ch {
  			case '\t', '\v', '\n', '\f':
  				// end of cell
  				b.append(buf[n:i])
  				b.updateWidth()
  				n = i + 1 // ch consumed
  				ncells := b.terminateCell(ch == '\t')
  				if ch == '\n' || ch == '\f' {
  					// terminate line
  					b.addLine()
  					if ch == '\f' || ncells == 1 {
  						// A '\f' always forces a flush. Otherwise, if the previous
  						// line has only one cell which does not have an impact on
  						// the formatting of the following lines (the last cell per
  						// line is ignored by format()), thus we can flush the
  						// Writer contents.
  						if err = b.Flush(); err != nil {
  							return
  						}
  						if ch == '\f' && b.flags&Debug != 0 {
  							// indicate section break
  							b.write0(hbar)
  						}
  					}
  				}
  
  			case Escape:
  				// start of escaped sequence
  				b.append(buf[n:i])
  				b.updateWidth()
  				n = i
  				if b.flags&StripEscape != 0 {
  					n++ // strip Escape
  				}
  				b.startEscape(Escape)
  
  			case '<', '&':
  				// possibly an html tag/entity
  				if b.flags&FilterHTML != 0 {
  					// begin of tag/entity
  					b.append(buf[n:i])
  					b.updateWidth()
  					n = i
  					b.startEscape(ch)
  				}
  			}
  
  		} else {
  			// inside escape
  			if ch == b.endChar {
  				// end of tag/entity
  				j := i + 1
  				if ch == Escape && b.flags&StripEscape != 0 {
  					j = i // strip Escape
  				}
  				b.append(buf[n:j])
  				n = i + 1 // ch consumed
  				b.endEscape()
  			}
  		}
  	}
  
  	// append leftover text
  	b.append(buf[n:])
  	n = len(buf)
  	return
  }
  
  // NewWriter allocates and initializes a new tabwriter.Writer.
  // The parameters are the same as for the Init function.
  //
  func NewWriter(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Writer {
  	return new(Writer).Init(output, minwidth, tabwidth, padding, padchar, flags)
  }
  

View as plain text