From e7980732ee01350c2797e16cb9d2088d577f8b18 Mon Sep 17 00:00:00 2001 From: Robert Griesemer Date: Tue, 10 Mar 2009 14:55:04 -0700 Subject: [PATCH] tabwriter documentation R=rsc DELTA=62 (31 added, 5 deleted, 26 changed) OCL=26022 CL=26040 --- src/lib/tabwriter/tabwriter.go | 82 ++++++++++++++++++++++------------ 1 file changed, 54 insertions(+), 28 deletions(-) diff --git a/src/lib/tabwriter/tabwriter.go b/src/lib/tabwriter/tabwriter.go index de37204d15..cc20294e0f 100644 --- a/src/lib/tabwriter/tabwriter.go +++ b/src/lib/tabwriter/tabwriter.go @@ -2,6 +2,11 @@ // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. +// The tabwriter package implements a write filter (tabwriter.Writer) +// that translates tabbed columns in input into properly aligned text, +// using the Elastic Tabstops algorithm described at +// http://nickgravgaard.com/elastictabstops/index.html. +// package tabwriter import ( @@ -66,36 +71,31 @@ func (b *byteArray) append(s []byte) { // ---------------------------------------------------------------------------- -// Writer is a filter implementing the io.Write interface. It assumes -// that the incoming bytes represent UTF-8 encoded text consisting of -// lines of tab-terminated "cells". Cells in adjacent lines constitute -// a column. Writer rewrites the incoming text such that all cells in -// a column have the same width; thus it effectively aligns cells. It -// does this by adding padding where necessary. All characters (ASCII -// or not) are assumed to be of the same width - this may not be true -// for arbitrary UTF-8 characters visualized on the screen. +// Filter implementation + +// A Writer is a filter that inserts padding around +// tab-delimited columns in its input to align them +// in the output. // -// Note that any text at the end of a line that is not tab-terminated -// is not a cell and does not enforce alignment of cells in adjacent -// rows. To make it a cell it needs to be tab-terminated. (For more -// information see http://nickgravgaard.com/elastictabstops/index.html) +// The Writer treats incoming bytes as UTF-8 encoded text +// consisting of tab-terminated cells. Cells in adjacent 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. Note that cells are tab-terminated, +// not tab-separated: trailing non-tab text at the end of a line +// is not part of any cell. // -// Formatting can be controlled via parameters: +// The Writer assumes that all characters have the same width; +// this may not be true in some fonts, especially with certain +// UTF-8 characters. +// +// 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. // -// cellwidth minimal cell width -// padding additional cell padding -// padchar ASCII char used for padding -// if padchar == '\t', the Writer will assume that the -// width of a '\t' in the formatted output is cellwidth, -// and cells are left-aligned independent of align_left -// (for correct-looking results, cellwidth must correspond -// to the tabwidth in the viewer displaying the result) -// filter_html ignores html tags and handles entities (starting with '&' -// and ending in ';') as single characters (width = 1) - type Writer struct { // configuration - writer io.Write; + output io.Write; cellwidth int; padding int; padbytes [8]byte; @@ -113,6 +113,7 @@ type Writer struct { widths vector.IntVector; // list of column widths in runes - re-used during formatting } + // Internal representation (current state): // // - all text written is appended to buf; tabs and newlines are stripped away @@ -143,14 +144,29 @@ func (b *Writer) addLine() { } -func (b *Writer) Init(writer io.Write, cellwidth, padding int, padchar byte, align_left, filter_html bool) *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: +// +// cellwidth minimal cell width +// padding additional cell padding +// padchar ASCII char used for padding +// if padchar == '\t', the Writer will assume that the +// width of a '\t' in the formatted output is cellwidth, +// and cells are left-aligned independent of align_left +// (for correct-looking results, cellwidth must correspond +// to the tab width in the viewer displaying the result) +// align_left alignment of cell content +// filter_html ignores html tags and treats entities (starting with '&' +// and ending in ';') as single characters (width = 1) +// +func (b *Writer) Init(output io.Write, cellwidth, padding int, padchar byte, align_left, filter_html bool) *Writer { if cellwidth < 0 { panic("negative cellwidth"); } if padding < 0 { panic("negative padding"); } - b.writer = writer; + b.output = output; b.cellwidth = cellwidth; b.padding = padding; for i := len(b.padbytes) - 1; i >= 0; i-- { @@ -194,7 +210,7 @@ func (b *Writer) dump() { func (b *Writer) write0(buf []byte) *os.Error { - n, err := b.writer.Write(buf); + n, err := b.output.Write(buf); if n != len(buf) && err == nil { err = os.EIO; } @@ -339,6 +355,9 @@ exit: } +// Flush should be called after the last call to Write to ensure +// that any data buffered in the Writer is written to output. +// func (b *Writer) Flush() *os.Error { dummy, err := b.format(0, 0, b.lines_size.Len()); // reset (even in the presence of errors) @@ -373,6 +392,10 @@ func (b *Writer) append(buf []byte) { } +// 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) (written int, err *os.Error) { i0, n := 0, len(buf); @@ -444,6 +467,9 @@ func (b *Writer) Write(buf []byte) (written int, err *os.Error) { } +// New allocates and initializes a new tabwriter.Writer. +// The parameters are the same as for the the Init function. +// func New(writer io.Write, cellwidth, padding int, padchar byte, align_left, filter_html bool) *Writer { return new(Writer).Init(writer, cellwidth, padding, padchar, align_left, filter_html) } -- 2.48.1