Source file src/pkg/tabwriter/tabwriter.go
1 // Copyright 2009 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package tabwriter implements a write filter (tabwriter.Writer) that 6 // translates tabbed columns in input into properly aligned text. 7 // 8 // The package is using the Elastic Tabstops algorithm described at 9 // http://nickgravgaard.com/elastictabstops/index.html. 10 // 11 package tabwriter 12 13 import ( 14 "bytes" 15 "io" 16 "os" 17 "utf8" 18 ) 19 20 // ---------------------------------------------------------------------------- 21 // Filter implementation 22 23 // A cell represents a segment of text terminated by tabs or line breaks. 24 // The text itself is stored in a separate buffer; cell only describes the 25 // segment's size in bytes, its width in runes, and whether it's an htab 26 // ('\t') terminated cell. 27 // 28 type cell struct { 29 size int // cell size in bytes 30 width int // cell width in runes 31 htab bool // true if the cell is terminated by an htab ('\t') 32 } 33 34 // A Writer is a filter that inserts padding around tab-delimited 35 // columns in its input to align them in the output. 36 // 37 // The Writer treats incoming bytes as UTF-8 encoded text consisting 38 // of cells terminated by (horizontal or vertical) tabs or line 39 // breaks (newline or formfeed characters). Cells in adjacent lines 40 // constitute a column. The Writer inserts padding as needed to 41 // make all cells in a column have the same width, effectively 42 // aligning the columns. It assumes that all characters have the 43 // same width except for tabs for which a tabwidth must be specified. 44 // Note that cells are tab-terminated, not tab-separated: trailing 45 // non-tab text at the end of a line does not form a column cell. 46 // 47 // The Writer assumes that all Unicode code points have the same width; 48 // this may not be true in some fonts. 49 // 50 // If DiscardEmptyColumns is set, empty columns that are terminated 51 // entirely by vertical (or "soft") tabs are discarded. Columns 52 // terminated by horizontal (or "hard") tabs are not affected by 53 // this flag. 54 // 55 // If a Writer is configured to filter HTML, HTML tags and entities 56 // are simply passed through. The widths of tags and entities are 57 // assumed to be zero (tags) and one (entities) for formatting purposes. 58 // 59 // A segment of text may be escaped by bracketing it with Escape 60 // characters. The tabwriter passes escaped text segments through 61 // unchanged. In particular, it does not interpret any tabs or line 62 // breaks within the segment. If the StripEscape flag is set, the 63 // Escape characters are stripped from the output; otherwise they 64 // are passed through as well. For the purpose of formatting, the 65 // width of the escaped text is always computed excluding the Escape 66 // characters. 67 // 68 // The formfeed character ('\f') acts like a newline but it also 69 // terminates all columns in the current line (effectively calling 70 // Flush). Cells in the next line start new columns. Unless found 71 // inside an HTML tag or inside an escaped text segment, formfeed 72 // characters appear as newlines in the output. 73 // 74 // The Writer must buffer input internally, because proper spacing 75 // of one line may depend on the cells in future lines. Clients must 76 // call Flush when done calling Write. 77 // 78 type Writer struct { 79 // configuration 80 output io.Writer 81 minwidth int 82 tabwidth int 83 padding int 84 padbytes [8]byte 85 flags uint 86 87 // current state 88 buf bytes.Buffer // collected text excluding tabs or line breaks 89 pos int // buffer position up to which cell.width of incomplete cell has been computed 90 cell cell // current incomplete cell; cell.width is up to buf[pos] excluding ignored sections 91 endChar byte // terminating char of escaped sequence (Escape for escapes, '>', ';' for HTML tags/entities, or 0) 92 lines [][]cell // list of lines; each line is a list of cells 93 widths []int // list of column widths in runes - re-used during formatting 94 } 95 96 func (b *Writer) addLine() { b.lines = append(b.lines, []cell{}) } 97 98 // Reset the current state. 99 func (b *Writer) reset() { 100 b.buf.Reset() 101 b.pos = 0 102 b.cell = cell{} 103 b.endChar = 0 104 b.lines = b.lines[0:0] 105 b.widths = b.widths[0:0] 106 b.addLine() 107 } 108 109 // Internal representation (current state): 110 // 111 // - all text written is appended to buf; tabs and line breaks are stripped away 112 // - at any given time there is a (possibly empty) incomplete cell at the end 113 // (the cell starts after a tab or line break) 114 // - cell.size is the number of bytes belonging to the cell so far 115 // - cell.width is text width in runes of that cell from the start of the cell to 116 // position pos; html tags and entities are excluded from this width if html 117 // filtering is enabled 118 // - the sizes and widths of processed text are kept in the lines list 119 // which contains a list of cells for each line 120 // - the widths list is a temporary list with current widths used during 121 // formatting; it is kept in Writer because it's re-used 122 // 123 // |<---------- size ---------->| 124 // | | 125 // |<- width ->|<- ignored ->| | 126 // | | | | 127 // [---processed---tab------------<tag>...</tag>...] 128 // ^ ^ ^ 129 // | | | 130 // buf start of incomplete cell pos 131 132 // Formatting can be controlled with these flags. 133 const ( 134 // Ignore html tags and treat entities (starting with '&' 135 // and ending in ';') as single characters (width = 1). 136 FilterHTML uint = 1 << iota 137 138 // Strip Escape characters bracketing escaped text segments 139 // instead of passing them through unchanged with the text. 140 StripEscape 141 142 // Force right-alignment of cell content. 143 // Default is left-alignment. 144 AlignRight 145 146 // Handle empty columns as if they were not present in 147 // the input in the first place. 148 DiscardEmptyColumns 149 150 // Always use tabs for indentation columns (i.e., padding of 151 // leading empty cells on the left) independent of padchar. 152 TabIndent 153 154 // Print a vertical bar ('|') between columns (after formatting). 155 // Discarded columns appear as zero-width columns ("||"). 156 Debug 157 ) 158 159 // A Writer must be initialized with a call to Init. The first parameter (output) 160 // specifies the filter output. The remaining parameters control the formatting: 161 // 162 // minwidth minimal cell width including any padding 163 // tabwidth width of tab characters (equivalent number of spaces) 164 // padding padding added to a cell before computing its width 165 // padchar ASCII char used for padding 166 // if padchar == '\t', the Writer will assume that the 167 // width of a '\t' in the formatted output is tabwidth, 168 // and cells are left-aligned independent of align_left 169 // (for correct-looking results, tabwidth must correspond 170 // to the tab width in the viewer displaying the result) 171 // flags formatting control 172 // 173 // To format in tab-separated columns with a tab stop of 8: 174 // b.Init(w, 8, 1, 8, '\t', 0); 175 // 176 // To format in space-separated columns with at least 4 spaces between columns: 177 // b.Init(w, 0, 4, 8, ' ', 0); 178 // 179 func (b *Writer) Init(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Writer { 180 if minwidth < 0 || tabwidth < 0 || padding < 0 { 181 panic("negative minwidth, tabwidth, or padding") 182 } 183 b.output = output 184 b.minwidth = minwidth 185 b.tabwidth = tabwidth 186 b.padding = padding 187 for i := range b.padbytes { 188 b.padbytes[i] = padchar 189 } 190 if padchar == '\t' { 191 // tab padding enforces left-alignment 192 flags &^= AlignRight 193 } 194 b.flags = flags 195 196 b.reset() 197 198 return b 199 } 200 201 // debugging support (keep code around) 202 func (b *Writer) dump() { 203 pos := 0 204 for i, line := range b.lines { 205 print("(", i, ") ") 206 for _, c := range line { 207 print("[", string(b.buf.Bytes()[pos:pos+c.size]), "]") 208 pos += c.size 209 } 210 print("\n") 211 } 212 print("\n") 213 } 214 215 // local error wrapper so we can distinguish os.Errors we want to return 216 // as errors from genuine panics (which we don't want to return as errors) 217 type osError struct { 218 err os.Error 219 } 220 221 func (b *Writer) write0(buf []byte) { 222 n, err := b.output.Write(buf) 223 if n != len(buf) && err == nil { 224 err = os.EIO 225 } 226 if err != nil { 227 panic(osError{err}) 228 } 229 } 230 231 func (b *Writer) writeN(src []byte, n int) { 232 for n > len(src) { 233 b.write0(src) 234 n -= len(src) 235 } 236 b.write0(src[0:n]) 237 } 238 239 var ( 240 newline = []byte{'\n'} 241 tabs = []byte("\t\t\t\t\t\t\t\t") 242 ) 243 244 func (b *Writer) writePadding(textw, cellw int, useTabs bool) { 245 if b.padbytes[0] == '\t' || useTabs { 246 // padding is done with tabs 247 if b.tabwidth == 0 { 248 return // tabs have no width - can't do any padding 249 } 250 // make cellw the smallest multiple of b.tabwidth 251 cellw = (cellw + b.tabwidth - 1) / b.tabwidth * b.tabwidth 252 n := cellw - textw // amount of padding 253 if n < 0 { 254 panic("internal error") 255 } 256 b.writeN(tabs, (n+b.tabwidth-1)/b.tabwidth) 257 return 258 } 259 260 // padding is done with non-tab characters 261 b.writeN(b.padbytes[0:], cellw-textw) 262 } 263 264 var vbar = []byte{'|'} 265 266 func (b *Writer) writeLines(pos0 int, line0, line1 int) (pos int) { 267 pos = pos0 268 for i := line0; i < line1; i++ { 269 line := b.lines[i] 270 271 // if TabIndent is set, use tabs to pad leading empty cells 272 useTabs := b.flags&TabIndent != 0 273 274 for j, c := range line { 275 if j > 0 && b.flags&Debug != 0 { 276 // indicate column break 277 b.write0(vbar) 278 } 279 280 if c.size == 0 { 281 // empty cell 282 if j < len(b.widths) { 283 b.writePadding(c.width, b.widths[j], useTabs) 284 } 285 } else { 286 // non-empty cell 287 useTabs = false 288 if b.flags&AlignRight == 0 { // align left 289 b.write0(b.buf.Bytes()[pos : pos+c.size]) 290 pos += c.size 291 if j < len(b.widths) { 292 b.writePadding(c.width, b.widths[j], false) 293 } 294 } else { // align right 295 if j < len(b.widths) { 296 b.writePadding(c.width, b.widths[j], false) 297 } 298 b.write0(b.buf.Bytes()[pos : pos+c.size]) 299 pos += c.size 300 } 301 } 302 } 303 304 if i+1 == len(b.lines) { 305 // last buffered line - we don't have a newline, so just write 306 // any outstanding buffered data 307 b.write0(b.buf.Bytes()[pos : pos+b.cell.size]) 308 pos += b.cell.size 309 } else { 310 // not the last line - write newline 311 b.write0(newline) 312 } 313 } 314 return 315 } 316 317 // Format the text between line0 and line1 (excluding line1); pos 318 // is the buffer position corresponding to the beginning of line0. 319 // Returns the buffer position corresponding to the beginning of 320 // line1 and an error, if any. 321 // 322 func (b *Writer) format(pos0 int, line0, line1 int) (pos int) { 323 pos = pos0 324 column := len(b.widths) 325 for this := line0; this < line1; this++ { 326 line := b.lines[this] 327 328 if column < len(line)-1 { 329 // cell exists in this column => this line 330 // has more cells than the previous line 331 // (the last cell per line is ignored because cells are 332 // tab-terminated; the last cell per line describes the 333 // text before the newline/formfeed and does not belong 334 // to a column) 335 336 // print unprinted lines until beginning of block 337 pos = b.writeLines(pos, line0, this) 338 line0 = this 339 340 // column block begin 341 width := b.minwidth // minimal column width 342 discardable := true // true if all cells in this column are empty and "soft" 343 for ; this < line1; this++ { 344 line = b.lines[this] 345 if column < len(line)-1 { 346 // cell exists in this column 347 c := line[column] 348 // update width 349 if w := c.width + b.padding; w > width { 350 width = w 351 } 352 // update discardable 353 if c.width > 0 || c.htab { 354 discardable = false 355 } 356 } else { 357 break 358 } 359 } 360 // column block end 361 362 // discard empty columns if necessary 363 if discardable && b.flags&DiscardEmptyColumns != 0 { 364 width = 0 365 } 366 367 // format and print all columns to the right of this column 368 // (we know the widths of this column and all columns to the left) 369 b.widths = append(b.widths, width) // push width 370 pos = b.format(pos, line0, this) 371 b.widths = b.widths[0 : len(b.widths)-1] // pop width 372 line0 = this 373 } 374 } 375 376 // print unprinted lines until end 377 return b.writeLines(pos, line0, line1) 378 } 379 380 // Append text to current cell. 381 func (b *Writer) append(text []byte) { 382 b.buf.Write(text) 383 b.cell.size += len(text) 384 } 385 386 // Update the cell width. 387 func (b *Writer) updateWidth() { 388 b.cell.width += utf8.RuneCount(b.buf.Bytes()[b.pos:b.buf.Len()]) 389 b.pos = b.buf.Len() 390 } 391 392 // To escape a text segment, bracket it with Escape characters. 393 // For instance, the tab in this string "Ignore this tab: \xff\t\xff" 394 // does not terminate a cell and constitutes a single character of 395 // width one for formatting purposes. 396 // 397 // The value 0xff was chosen because it cannot appear in a valid UTF-8 sequence. 398 // 399 const Escape = '\xff' 400 401 // Start escaped mode. 402 func (b *Writer) startEscape(ch byte) { 403 switch ch { 404 case Escape: 405 b.endChar = Escape 406 case '<': 407 b.endChar = '>' 408 case '&': 409 b.endChar = ';' 410 } 411 } 412 413 // Terminate escaped mode. If the escaped text was an HTML tag, its width 414 // is assumed to be zero for formatting purposes; if it was an HTML entity, 415 // its width is assumed to be one. In all other cases, the width is the 416 // unicode width of the text. 417 // 418 func (b *Writer) endEscape() { 419 switch b.endChar { 420 case Escape: 421 b.updateWidth() 422 if b.flags&StripEscape == 0 { 423 b.cell.width -= 2 // don't count the Escape chars 424 } 425 case '>': // tag of zero width 426 case ';': 427 b.cell.width++ // entity, count as one rune 428 } 429 b.pos = b.buf.Len() 430 b.endChar = 0 431 } 432 433 // Terminate the current cell by adding it to the list of cells of the 434 // current line. Returns the number of cells in that line. 435 // 436 func (b *Writer) terminateCell(htab bool) int { 437 b.cell.htab = htab 438 line := &b.lines[len(b.lines)-1] 439 *line = append(*line, b.cell) 440 b.cell = cell{} 441 return len(*line) 442 } 443 444 func handlePanic(err *os.Error) { 445 if e := recover(); e != nil { 446 *err = e.(osError).err // re-panics if it's not a local osError 447 } 448 } 449 450 // Flush should be called after the last call to Write to ensure 451 // that any data buffered in the Writer is written to output. Any 452 // incomplete escape sequence at the end is simply considered 453 // complete for formatting purposes. 454 // 455 func (b *Writer) Flush() (err os.Error) { 456 defer b.reset() // even in the presence of errors 457 defer handlePanic(&err) 458 459 // add current cell if not empty 460 if b.cell.size > 0 { 461 if b.endChar != 0 { 462 // inside escape - terminate it even if incomplete 463 b.endEscape() 464 } 465 b.terminateCell(false) 466 } 467 468 // format contents of buffer 469 b.format(0, 0, len(b.lines)) 470 471 return 472 } 473 474 var hbar = []byte("---\n") 475 476 // Write writes buf to the writer b. 477 // The only errors returned are ones encountered 478 // while writing to the underlying output stream. 479 // 480 func (b *Writer) Write(buf []byte) (n int, err os.Error) { 481 defer handlePanic(&err) 482 483 // split text into cells 484 n = 0 485 for i, ch := range buf { 486 if b.endChar == 0 { 487 // outside escape 488 switch ch { 489 case '\t', '\v', '\n', '\f': 490 // end of cell 491 b.append(buf[n:i]) 492 b.updateWidth() 493 n = i + 1 // ch consumed 494 ncells := b.terminateCell(ch == '\t') 495 if ch == '\n' || ch == '\f' { 496 // terminate line 497 b.addLine() 498 if ch == '\f' || ncells == 1 { 499 // A '\f' always forces a flush. Otherwise, if the previous 500 // line has only one cell which does not have an impact on 501 // the formatting of the following lines (the last cell per 502 // line is ignored by format()), thus we can flush the 503 // Writer contents. 504 if err = b.Flush(); err != nil { 505 return 506 } 507 if ch == '\f' && b.flags&Debug != 0 { 508 // indicate section break 509 b.write0(hbar) 510 } 511 } 512 } 513 514 case Escape: 515 // start of escaped sequence 516 b.append(buf[n:i]) 517 b.updateWidth() 518 n = i 519 if b.flags&StripEscape != 0 { 520 n++ // strip Escape 521 } 522 b.startEscape(Escape) 523 524 case '<', '&': 525 // possibly an html tag/entity 526 if b.flags&FilterHTML != 0 { 527 // begin of tag/entity 528 b.append(buf[n:i]) 529 b.updateWidth() 530 n = i 531 b.startEscape(ch) 532 } 533 } 534 535 } else { 536 // inside escape 537 if ch == b.endChar { 538 // end of tag/entity 539 j := i + 1 540 if ch == Escape && b.flags&StripEscape != 0 { 541 j = i // strip Escape 542 } 543 b.append(buf[n:j]) 544 n = i + 1 // ch consumed 545 b.endEscape() 546 } 547 } 548 } 549 550 // append leftover text 551 b.append(buf[n:]) 552 n = len(buf) 553 return 554 } 555 556 // NewWriter allocates and initializes a new tabwriter.Writer. 557 // The parameters are the same as for the the Init function. 558 // 559 func NewWriter(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Writer { 560 return new(Writer).Init(output, minwidth, tabwidth, padding, padchar, flags) 561 }