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.
5
// The printer package implements printing of AST nodes.
21
const debug = false // enable for debugging
27
ignore = whiteSpace(0)
28
blank = whiteSpace(' ')
29
vtab = whiteSpace('\v')
30
newline = whiteSpace('\n')
31
formfeed = whiteSpace('\f')
32
indent = whiteSpace('>')
33
unindent = whiteSpace('<')
38
esc2 = '\xfe' // an escape byte that cannot occur in regular UTF-8
39
_ = 1 / (esc2 - tabwriter.Escape) // cause compiler error if esc2 == tabwriter.Escape
44
esc = []byte{tabwriter.Escape}
46
htabs = []byte("\t\t\t\t\t\t\t\t")
47
newlines = []byte("\n\n\n\n\n\n\n\n") // more than the max determined by nlines
48
formfeeds = []byte("\f\f\f\f\f\f\f\f") // more than the max determined by nlines
53
var noPos token.Position // use noPos when a position is needed but not known
54
var infinity = 1 << 30
57
// Use ignoreMultiLine if the multiLine information is not important.
58
var ignoreMultiLine = new(bool)
61
// A pmode value represents the current printer mode.
65
inLiteral pmode = 1 << iota
71
// Configuration (does not change after initialization)
78
nesting int // nesting level (0: top-level (package scope), >0: functions/decls.)
79
written int // number of bytes written
80
indent int // current indentation
81
mode pmode // current printer mode
82
lastTok token.Token // the last token printed (token.ILLEGAL if it's whitespace)
84
// Buffered whitespace
87
// The (possibly estimated) position in the generated output;
88
// in AST space (i.e., pos is set whenever a token position is
89
// known accurately, and updated dependending on what has been
93
// The value of pos immediately after the last item has been
94
// written using writeItem.
98
lastTaggedLine int // last line for which a line tag was written
100
// The list of all source comments, in order of appearance.
101
comments []*ast.CommentGroup // may be nil
102
cindex int // current comment index
103
useNodeComments bool // if not set, ignore lead and line comments of nodes
107
func (p *printer) init(output io.Writer, cfg *Config, fset *token.FileSet) {
111
p.errors = make(chan os.Error)
112
p.buffer = make([]whiteSpace, 0, 16) // whitespace sequences are short
116
func (p *printer) internalError(msg ...interface{}) {
118
fmt.Print(p.pos.String() + ": ")
125
// nlines returns the adjusted number of linebreaks given the desired number
126
// of breaks n such that min <= result <= max where max depends on the current
129
func (p *printer) nlines(n, min int) int {
133
max := 3 // max. number of newlines at the top level (p.nesting == 0)
135
max = 2 // max. number of newlines everywhere else
144
// write0 writes raw (uninterpreted) data to p.output and handles errors.
145
// write0 does not indent after newlines, and does not HTML-escape or update p.pos.
147
func (p *printer) write0(data []byte) {
149
n, err := p.output.Write(data)
159
// write interprets data and writes it to p.output. It inserts indentation
160
// after a line break unless in a tabwriter escape sequence.
161
// It updates p.pos as a side-effect.
163
func (p *printer) write(data []byte) {
165
for i, b := range data {
168
// write segment ending in b
169
p.write0(data[i0 : i+1])
172
p.pos.Offset += i + 1 - i0
176
if p.mode&inLiteral == 0 {
178
// use "hard" htabs - indentation columns
179
// must not be discarded by the tabwriter
181
for ; j > len(htabs); j -= len(htabs) {
187
p.pos.Offset += p.indent
188
p.pos.Column += p.indent
191
// next segment start
194
case tabwriter.Escape:
197
// ignore escape chars introduced by printer - they are
198
// invisible and must not affect p.pos (was issue #1089)
204
// write remaining segment
214
func (p *printer) writeNewlines(n int, useFF bool) {
218
p.write(formfeeds[0:n])
220
p.write(newlines[0:n])
226
// writeItem writes data at position pos. data is the text corresponding to
227
// a single lexical token, but may also be comment text. pos is the actual
228
// (or at least very accurately estimated) position of the data in the original
229
// source text. writeItem updates p.last to the position immediately following
232
func (p *printer) writeItem(pos token.Position, data []byte) {
234
// continue with previous position if we don't have a valid pos
235
if p.last.IsValid() && p.last.Filename != pos.Filename {
236
// the file has changed - reset state
237
// (used when printing merged ASTs of different files
238
// e.g., the result of ast.MergePackageFiles)
241
p.buffer = p.buffer[0:0]
246
// do not update p.pos - use write0
247
_, filename := filepath.Split(pos.Filename)
248
p.write0([]byte(fmt.Sprintf("[%s:%d:%d]", filename, pos.Line, pos.Column)))
255
// writeCommentPrefix writes the whitespace before a comment.
256
// If there is any pending whitespace, it consumes as much of
257
// it as is likely to help position the comment nicely.
258
// pos is the comment position, next the position of the item
259
// after all pending comments, prev is the previous comment in
260
// a group of comments (or nil), and isKeyword indicates if the
261
// next item is a keyword.
263
func (p *printer) writeCommentPrefix(pos, next token.Position, prev *ast.Comment, isKeyword bool) {
265
// the comment is the first item to be printed - don't write any whitespace
269
if pos.IsValid() && pos.Filename != p.last.Filename {
270
// comment in a different file - separate with newlines (writeNewlines will limit the number)
271
p.writeNewlines(10, true)
275
if pos.Line == p.last.Line && (prev == nil || prev.Text[1] != '/') {
276
// comment on the same line as last item:
277
// separate with at least one separator
280
// first comment of a comment group
282
for i, ch := range p.buffer {
285
// ignore any blanks before a comment
289
// respect existing tabs - important
290
// for proper formatting of commented structs
294
// apply pending indentation
302
// make sure there is at least one separator
304
if pos.Line == next.Line {
305
// next item is on the same line as the comment
306
// (which must be a /*-style comment): separate
307
// with a blank instead of a tab
315
// comment on a different line:
316
// separate with at least one line break
318
// first comment of a comment group
320
for i, ch := range p.buffer {
323
// ignore any horizontal whitespace before line breaks
327
// apply pending indentation
330
// if the next token is a keyword, apply the outdent
331
// if it appears that the comment is aligned with the
332
// keyword; otherwise assume the outdent is part of a
333
// closing block and stop (this scenario appears with
334
// comments before a case label where the comments
335
// apply to the next case instead of the current one)
336
if isKeyword && pos.Column == next.Column {
339
case newline, formfeed:
340
// TODO(gri): may want to keep formfeed info in some cases
348
// use formfeeds to break columns before a comment;
349
// this is analogous to using formfeeds to separate
350
// individual lines of /*-style comments - but make
351
// sure there is at least one line break if the previous
352
// comment was a line comment
353
n := pos.Line - p.last.Line // if !pos.IsValid(), pos.Line == 0, and n will be 0
354
if n <= 0 && prev != nil && prev.Text[1] == '/' {
357
p.writeNewlines(n, true)
362
func (p *printer) writeCommentLine(comment *ast.Comment, pos token.Position, line []byte) {
363
// line must pass through unchanged, bracket it with tabwriter.Escape
364
line = bytes.Join([][]byte{esc, line, esc}, nil)
365
p.writeItem(pos, line)
369
// Split comment text into lines
370
func split(text []byte) [][]byte {
371
// count lines (comment text never ends in a newline)
373
for _, c := range text {
380
lines := make([][]byte, n)
383
for j, c := range text {
385
lines[n] = text[i:j] // exclude newline
386
i = j + 1 // discard newline
396
func isBlank(s []byte) bool {
397
for _, b := range s {
406
func commonPrefix(a, b []byte) []byte {
408
for i < len(a) && i < len(b) && a[i] == b[i] && (a[i] <= ' ' || a[i] == '*') {
415
func stripCommonPrefix(lines [][]byte) {
417
return // at most one line - nothing to do
421
// The heuristic in this function tries to handle a few
422
// common patterns of /*-style comments: Comments where
423
// the opening /* and closing */ are aligned and the
424
// rest of the comment text is aligned and indented with
425
// blanks or tabs, cases with a vertical "line of stars"
426
// on the left, and cases where the closing */ is on the
427
// same line as the last comment text.
429
// Compute maximum common white prefix of all but the first,
430
// last, and blank lines, and replace blank lines with empty
431
// lines (the first line starts with /* and has no prefix).
432
// In case of two-line comments, consider the last line for
433
// the prefix computation since otherwise the prefix would
436
// Note that the first and last line are never empty (they
437
// contain the opening /* and closing */ respectively) and
438
// thus they can be ignored by the blank line check.
441
for i, line := range lines[1 : len(lines)-1] {
444
lines[1+i] = nil // range starts at line 1
446
prefix = commonPrefix(line, line)
448
prefix = commonPrefix(prefix, line)
451
} else { // len(lines) == 2
453
prefix = commonPrefix(line, line)
457
* Check for vertical "line of stars" and correct prefix accordingly.
460
if i := bytes.Index(prefix, []byte{'*'}); i >= 0 {
461
// Line of stars present.
462
if i > 0 && prefix[i-1] == ' ' {
463
i-- // remove trailing blank from prefix so stars remain aligned
468
// No line of stars present.
469
// Determine the white space on the first line after the /*
470
// and before the beginning of the comment text, assume two
471
// blanks instead of the /* unless the first character after
472
// the /* is a tab. If the first comment line is empty but
473
// for the opening /*, assume up to 3 blanks or a tab. This
474
// whitespace may be found as suffix in the common prefix.
476
if isBlank(first[2:]) {
477
// no comment text on the first line:
478
// reduce prefix by up to 3 blanks or a tab
479
// if present - this keeps comment text indented
480
// relative to the /* and */'s if it was indented
481
// in the first place
483
for n := 0; n < 3 && i > 0 && prefix[i-1] == ' '; n++ {
486
if i == len(prefix) && i > 0 && prefix[i-1] == '\t' {
491
// comment text on the first line
492
suffix := make([]byte, len(first))
493
n := 2 // start after opening /*
494
for n < len(first) && first[n] <= ' ' {
498
if n > 2 && suffix[2] == '\t' {
499
// assume the '\t' compensates for the /*
502
// otherwise assume two blanks
503
suffix[0], suffix[1] = ' ', ' '
506
// Shorten the computed common prefix by the length of
507
// suffix, if it is found as suffix of the prefix.
508
if bytes.HasSuffix(prefix, suffix) {
509
prefix = prefix[0 : len(prefix)-len(suffix)]
514
// Handle last line: If it only contains a closing */, align it
515
// with the opening /*, otherwise align the text with the other
517
last := lines[len(lines)-1]
518
closing := []byte("*/")
519
i := bytes.Index(last, closing)
520
if isBlank(last[0:i]) {
521
// last line only contains closing */
524
// insert an aligning blank
527
lines[len(lines)-1] = bytes.Join([][]byte{prefix, closing}, sep)
529
// last line contains more comment text - assume
530
// it is aligned like the other lines
531
prefix = commonPrefix(prefix, last)
534
// Remove the common prefix from all but the first and empty lines.
535
for i, line := range lines[1:] {
537
lines[1+i] = line[len(prefix):] // range starts at line 1
543
func (p *printer) writeComment(comment *ast.Comment) {
546
// shortcut common case of //-style comments
548
p.writeCommentLine(comment, p.fset.Position(comment.Pos()), text)
552
// for /*-style comments, print line by line and let the
553
// write function take care of the proper indentation
555
stripCommonPrefix(lines)
557
// write comment lines, separated by formfeed,
558
// without a line break after the last line
559
linebreak := formfeeds[0:1]
560
pos := p.fset.Position(comment.Pos())
561
for i, line := range lines {
567
p.writeCommentLine(comment, pos, line)
573
// writeCommentSuffix writes a line break after a comment if indicated
574
// and processes any leftover indentation information. If a line break
575
// is needed, the kind of break (newline vs formfeed) depends on the
576
// pending whitespace. writeCommentSuffix returns true if a pending
577
// formfeed was dropped from the whitespace buffer.
579
func (p *printer) writeCommentSuffix(needsLinebreak bool) (droppedFF bool) {
580
for i, ch := range p.buffer {
583
// ignore trailing whitespace
585
case indent, unindent:
586
// don't loose indentation information
587
case newline, formfeed:
588
// if we need a line break, keep exactly one
589
// but remember if we dropped any formfeeds
591
needsLinebreak = false
600
p.writeWhitespace(len(p.buffer))
602
// make sure we have a line break
604
p.write([]byte{'\n'})
611
// intersperseComments consumes all comments that appear before the next token
612
// tok and prints it together with the buffered whitespace (i.e., the whitespace
613
// that needs to be written before the next token). A heuristic is used to mix
614
// the comments and whitespace. intersperseComments returns true if a pending
615
// formfeed was dropped from the whitespace buffer.
617
func (p *printer) intersperseComments(next token.Position, tok token.Token) (droppedFF bool) {
618
var last *ast.Comment
619
for ; p.commentBefore(next); p.cindex++ {
620
for _, c := range p.comments[p.cindex].List {
621
p.writeCommentPrefix(p.fset.Position(c.Pos()), next, last, tok.IsKeyword())
628
if last.Text[1] == '*' && p.fset.Position(last.Pos()).Line == next.Line {
629
// the last comment is a /*-style comment and the next item
630
// follows on the same line: separate with an extra blank
633
// ensure that there is a line break after a //-style comment,
634
// before a closing '}' unless explicitly disabled, or at eof
636
last.Text[1] == '/' ||
637
tok == token.RBRACE && p.mode&noExtraLinebreak == 0 ||
639
return p.writeCommentSuffix(needsLinebreak)
642
// no comment was written - we should never reach here since
643
// intersperseComments should not be called in that case
644
p.internalError("intersperseComments called without pending comments")
649
// whiteWhitespace writes the first n whitespace entries.
650
func (p *printer) writeWhitespace(n int) {
653
for i := 0; i < n; i++ {
654
switch ch := p.buffer[i]; ch {
662
p.internalError("negative indentation:", p.indent)
665
case newline, formfeed:
666
// A line break immediately followed by a "correcting"
667
// unindent is swapped with the unindent - this permits
668
// proper label positioning. If a comment is between
669
// the line break and the label, the unindent is not
670
// part of the comment whitespace prefix and the comment
671
// will be positioned correctly indented.
672
if i+1 < n && p.buffer[i+1] == unindent {
673
// Use a formfeed to terminate the current section.
674
// Otherwise, a long label name on the next line leading
675
// to a wide column may increase the indentation column
676
// of lines before the label; effectively leading to wrong
678
p.buffer[i], p.buffer[i+1] = unindent, formfeed
689
// shift remaining entries down
691
for ; n < len(p.buffer); n++ {
692
p.buffer[i] = p.buffer[n]
695
p.buffer = p.buffer[0:i]
699
// ----------------------------------------------------------------------------
700
// Printing interface
703
func mayCombine(prev token.Token, next byte) (b bool) {
706
b = next == '.' // 1.
708
b = next == '+' // ++
710
b = next == '-' // --
712
b = next == '*' // /*
714
b = next == '-' || next == '<' // <- or <<
716
b = next == '&' || next == '^' // && or &^
722
// print prints a list of "items" (roughly corresponding to syntactic
723
// tokens, but also including whitespace and formatting information).
724
// It is the only print function that should be called directly from
725
// any of the AST printing functions in nodes.go.
727
// Whitespace is accumulated until a non-whitespace token appears. Any
728
// comments that need to appear before that token are printed first,
729
// taking into account the amount and structure of any pending white-
730
// space for best comment placement. Then, any leftover whitespace is
731
// printed, followed by the actual token.
733
func (p *printer) print(args ...interface{}) {
734
for _, f := range args {
735
next := p.pos // estimated position of next item
739
switch x := f.(type) {
741
// toggle printer mode
745
// don't add ignore's to the buffer; they
746
// may screw up "correcting" unindents (see
751
if i == cap(p.buffer) {
752
// Whitespace sequences are very short so this should
753
// never happen. Handle gracefully (but possibly with
754
// bad comment placement) if it does happen.
758
p.buffer = p.buffer[0 : i+1]
761
data = []byte(x.Name)
764
// escape all literals so they pass through unchanged
765
// (note that valid Go programs cannot contain
766
// tabwriter.Escape bytes since they do not appear in
767
// legal UTF-8 sequences)
768
data = make([]byte, 0, len(x.Value)+2)
769
data = append(data, tabwriter.Escape)
770
data = append(data, x.Value...)
771
data = append(data, tabwriter.Escape)
773
// If we have a raw string that spans multiple lines and
774
// the opening quote (`) is on a line preceded only by
775
// indentation, we don't want to write that indentation
776
// because the following lines of the raw string are not
777
// indented. It's easiest to correct the output at the end
778
// via the trimmer (because of the complex handling of
780
// Mark multi-line raw strings by replacing the opening
781
// quote with esc2 and have the trimmer take care of fixing
782
// it up. (Do this _after_ making a copy of data!)
783
if data[1] == '`' && bytes.IndexByte(data, '\n') > 0 {
788
if mayCombine(p.lastTok, s[0]) {
789
// the previous and the current token must be
790
// separated by a blank otherwise they combine
791
// into a different incorrect token sequence
792
// (except for token.INT followed by a '.' this
793
// should never happen because it is taken care
794
// of via binary expression formatting)
795
if len(p.buffer) != 0 {
796
p.internalError("whitespace buffer not empty")
798
p.buffer = p.buffer[0:1]
805
next = p.fset.Position(x) // accurate position of next item
809
fmt.Fprintf(os.Stderr, "print: unsupported argument type %T\n", f)
810
panic("go/printer type")
816
droppedFF := p.flush(next, tok)
818
// intersperse extra newlines if present in the source
819
// (don't do this in flush as it will cause extra newlines
820
// at the end of a file) - use formfeeds if we dropped one
822
p.writeNewlines(next.Line-p.pos.Line, droppedFF)
824
p.writeItem(next, data)
830
// commentBefore returns true iff the current comment occurs
831
// before the next position in the source code.
833
func (p *printer) commentBefore(next token.Position) bool {
834
return p.cindex < len(p.comments) && p.fset.Position(p.comments[p.cindex].List[0].Pos()).Offset < next.Offset
838
// Flush prints any pending comments and whitespace occurring
839
// textually before the position of the next token tok. Flush
840
// returns true if a pending formfeed character was dropped
841
// from the whitespace buffer as a result of interspersing
844
func (p *printer) flush(next token.Position, tok token.Token) (droppedFF bool) {
845
if p.commentBefore(next) {
846
// if there are comments before the next item, intersperse them
847
droppedFF = p.intersperseComments(next, tok)
849
// otherwise, write any leftover whitespace
850
p.writeWhitespace(len(p.buffer))
856
// ----------------------------------------------------------------------------
859
// A trimmer is an io.Writer filter for stripping tabwriter.Escape
860
// characters, trailing blanks and tabs, and for converting formfeed
861
// and vtab characters into newlines and htabs (in case no tabwriter
862
// is used). Text bracketed by tabwriter.Escape characters is passed
863
// through unchanged.
865
type trimmer struct {
873
// trimmer is implemented as a state machine.
874
// It can be in one of the following states:
876
inSpace = iota // inside space
877
atEscape // inside space and the last char was an opening tabwriter.Escape
878
inEscape // inside text bracketed by tabwriter.Escapes
879
inText // inside text
883
var backquote = []byte{'`'}
886
// Design note: It is tempting to eliminate extra blanks occurring in
887
// whitespace in this function as it could simplify some
888
// of the blanks logic in the node printing functions.
889
// However, this would mess up any formatting done by
892
func (p *trimmer) Write(data []byte) (n int, err os.Error) {
894
// p.state == inSpace, atEscape:
895
// p.space is unwritten
896
// p.hasText indicates if there is any text on this line
897
// p.state == inEscape, inText:
898
// data[m:n] is unwritten
901
for n, b = range data {
903
b = '\t' // convert to htab
909
p.space.WriteByte(b) // WriteByte returns no errors
911
p.space.Reset() // discard trailing space
912
_, err = p.output.Write(newlines[0:1]) // write newline
914
case tabwriter.Escape:
917
_, err = p.output.Write(p.space.Bytes())
922
// discard indentation if we have a multi-line raw string
923
// (see printer.print for details)
924
if b != esc2 || p.hasText {
925
_, err = p.output.Write(p.space.Bytes())
930
_, err = p.output.Write(backquote) // convert back
934
if b == tabwriter.Escape {
935
_, err = p.output.Write(data[m:n])
943
_, err = p.output.Write(data[m:n])
946
p.space.WriteByte(b) // WriteByte returns no errors
949
_, err = p.output.Write(data[m:n])
952
_, err = p.output.Write(newlines[0:1]) // write newline
954
case tabwriter.Escape:
955
_, err = p.output.Write(data[m:n])
968
case inEscape, inText:
969
_, err = p.output.Write(data[m:n])
979
// ----------------------------------------------------------------------------
982
// General printing is controlled with these Config.Mode flags.
984
RawFormat uint = 1 << iota // do not use a tabwriter; if set, UseSpaces is ignored
985
TabIndent // use tabs for indentation independent of UseSpaces
986
UseSpaces // use spaces instead of tabs for alignment
990
// A Config node controls the output of Fprint.
992
Mode uint // default: 0
993
Tabwidth int // default: 8
997
// Fprint "pretty-prints" an AST node to output and returns the number
998
// of bytes written and an error (if any) for a given configuration cfg.
999
// Position information is interpreted relative to the file set fset.
1000
// The node type must be *ast.File, or assignment-compatible to ast.Expr,
1001
// ast.Decl, ast.Spec, or ast.Stmt.
1003
func (cfg *Config) Fprint(output io.Writer, fset *token.FileSet, node interface{}) (int, os.Error) {
1004
// redirect output through a trimmer to eliminate trailing whitespace
1005
// (Input to a tabwriter must be untrimmed since trailing tabs provide
1006
// formatting information. The tabwriter could provide trimming
1007
// functionality but no tabwriter is used when RawFormat is set.)
1008
output = &trimmer{output: output}
1010
// setup tabwriter if needed and redirect output
1011
var tw *tabwriter.Writer
1012
if cfg.Mode&RawFormat == 0 {
1013
minwidth := cfg.Tabwidth
1015
padchar := byte('\t')
1016
if cfg.Mode&UseSpaces != 0 {
1020
twmode := tabwriter.DiscardEmptyColumns
1021
if cfg.Mode&TabIndent != 0 {
1023
twmode |= tabwriter.TabIndent
1026
tw = tabwriter.NewWriter(output, minwidth, cfg.Tabwidth, 1, padchar, twmode)
1030
// setup printer and print node
1032
p.init(output, cfg, fset)
1034
switch n := node.(type) {
1037
p.useNodeComments = true
1038
p.expr(n, ignoreMultiLine)
1041
p.useNodeComments = true
1042
// A labeled statement will un-indent to position the
1043
// label. Set indent to 1 so we don't get indent "underflow".
1044
if _, labeledStmt := n.(*ast.LabeledStmt); labeledStmt {
1047
p.stmt(n, false, ignoreMultiLine)
1050
p.useNodeComments = true
1051
p.decl(n, ignoreMultiLine)
1054
p.useNodeComments = true
1055
p.spec(n, 1, false, ignoreMultiLine)
1058
p.comments = n.Comments
1059
p.useNodeComments = n.Comments == nil
1062
p.errors <- fmt.Errorf("printer.Fprint: unsupported node type %T", n)
1065
p.flush(token.Position{Offset: infinity, Line: infinity}, token.EOF)
1066
p.errors <- nil // no errors
1068
err := <-p.errors // wait for completion of goroutine
1070
// flush tabwriter, if any
1072
tw.Flush() // ignore errors
1075
return p.written, err
1079
// Fprint "pretty-prints" an AST node to output.
1080
// It calls Config.Fprint with default settings.
1082
func Fprint(output io.Writer, fset *token.FileSet, node interface{}) os.Error {
1083
_, err := (&Config{Tabwidth: 8}).Fprint(output, fset, node) // don't care about number of bytes written