Source file src/go/printer/printer.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 printer implements printing of AST nodes.
     6  package printer
     7  
     8  import (
     9  	"fmt"
    10  	"go/ast"
    11  	"go/build/constraint"
    12  	"go/token"
    13  	"io"
    14  	"os"
    15  	"strings"
    16  	"sync"
    17  	"text/tabwriter"
    18  	"unicode"
    19  )
    20  
    21  const (
    22  	maxNewlines = 2     // max. number of newlines between source text
    23  	debug       = false // enable for debugging
    24  	infinity    = 1 << 30
    25  )
    26  
    27  type whiteSpace byte
    28  
    29  const (
    30  	ignore   = whiteSpace(0)
    31  	blank    = whiteSpace(' ')
    32  	vtab     = whiteSpace('\v')
    33  	newline  = whiteSpace('\n')
    34  	formfeed = whiteSpace('\f')
    35  	indent   = whiteSpace('>')
    36  	unindent = whiteSpace('<')
    37  )
    38  
    39  // A pmode value represents the current printer mode.
    40  type pmode int
    41  
    42  const (
    43  	noExtraBlank     pmode = 1 << iota // disables extra blank after /*-style comment
    44  	noExtraLinebreak                   // disables extra line break after /*-style comment
    45  )
    46  
    47  type commentInfo struct {
    48  	cindex         int               // index of the next comment
    49  	comment        *ast.CommentGroup // = printer.comments[cindex-1]; or nil
    50  	commentOffset  int               // = printer.posFor(printer.comments[cindex-1].List[0].Pos()).Offset; or infinity
    51  	commentNewline bool              // true if the comment group contains newlines
    52  }
    53  
    54  type printer struct {
    55  	// Configuration (does not change after initialization)
    56  	Config
    57  	fset *token.FileSet
    58  
    59  	// Current state
    60  	output       []byte       // raw printer result
    61  	indent       int          // current indentation
    62  	level        int          // level == 0: outside composite literal; level > 0: inside composite literal
    63  	mode         pmode        // current printer mode
    64  	endAlignment bool         // if set, terminate alignment immediately
    65  	impliedSemi  bool         // if set, a linebreak implies a semicolon
    66  	lastTok      token.Token  // last token printed (token.ILLEGAL if it's whitespace)
    67  	prevOpen     token.Token  // previous non-brace "open" token (, [, or token.ILLEGAL
    68  	wsbuf        []whiteSpace // delayed white space
    69  	goBuild      []int        // start index of all //go:build comments in output
    70  	plusBuild    []int        // start index of all // +build comments in output
    71  
    72  	// Positions
    73  	// The out position differs from the pos position when the result
    74  	// formatting differs from the source formatting (in the amount of
    75  	// white space). If there's a difference and SourcePos is set in
    76  	// ConfigMode, //line directives are used in the output to restore
    77  	// original source positions for a reader.
    78  	pos          token.Position // current position in AST (source) space
    79  	out          token.Position // current position in output space
    80  	last         token.Position // value of pos after calling writeString
    81  	linePtr      *int           // if set, record out.Line for the next token in *linePtr
    82  	sourcePosErr error          // if non-nil, the first error emitting a //line directive
    83  
    84  	// The list of all source comments, in order of appearance.
    85  	comments        []*ast.CommentGroup // may be nil
    86  	useNodeComments bool                // if not set, ignore lead and line comments of nodes
    87  
    88  	// Information about p.comments[p.cindex]; set up by nextComment.
    89  	commentInfo
    90  
    91  	// Cache of already computed node sizes.
    92  	nodeSizes map[ast.Node]int
    93  
    94  	// Cache of most recently computed line position.
    95  	cachedPos  token.Pos
    96  	cachedLine int // line corresponding to cachedPos
    97  }
    98  
    99  func (p *printer) internalError(msg ...any) {
   100  	if debug {
   101  		fmt.Print(p.pos.String() + ": ")
   102  		fmt.Println(msg...)
   103  		panic("go/printer")
   104  	}
   105  }
   106  
   107  // commentsHaveNewline reports whether a list of comments belonging to
   108  // an *ast.CommentGroup contains newlines. Because the position information
   109  // may only be partially correct, we also have to read the comment text.
   110  func (p *printer) commentsHaveNewline(list []*ast.Comment) bool {
   111  	// len(list) > 0
   112  	line := p.lineFor(list[0].Pos())
   113  	for i, c := range list {
   114  		if i > 0 && p.lineFor(list[i].Pos()) != line {
   115  			// not all comments on the same line
   116  			return true
   117  		}
   118  		if t := c.Text; len(t) >= 2 && (t[1] == '/' || strings.Contains(t, "\n")) {
   119  			return true
   120  		}
   121  	}
   122  	_ = line
   123  	return false
   124  }
   125  
   126  func (p *printer) nextComment() {
   127  	for p.cindex < len(p.comments) {
   128  		c := p.comments[p.cindex]
   129  		p.cindex++
   130  		if list := c.List; len(list) > 0 {
   131  			p.comment = c
   132  			p.commentOffset = p.posFor(list[0].Pos()).Offset
   133  			p.commentNewline = p.commentsHaveNewline(list)
   134  			return
   135  		}
   136  		// we should not reach here (correct ASTs don't have empty
   137  		// ast.CommentGroup nodes), but be conservative and try again
   138  	}
   139  	// no more comments
   140  	p.commentOffset = infinity
   141  }
   142  
   143  // commentBefore reports whether the current comment group occurs
   144  // before the next position in the source code and printing it does
   145  // not introduce implicit semicolons.
   146  func (p *printer) commentBefore(next token.Position) bool {
   147  	return p.commentOffset < next.Offset && (!p.impliedSemi || !p.commentNewline)
   148  }
   149  
   150  // commentSizeBefore returns the estimated size of the
   151  // comments on the same line before the next position.
   152  func (p *printer) commentSizeBefore(next token.Position) int {
   153  	// save/restore current p.commentInfo (p.nextComment() modifies it)
   154  	defer func(info commentInfo) {
   155  		p.commentInfo = info
   156  	}(p.commentInfo)
   157  
   158  	size := 0
   159  	for p.commentBefore(next) {
   160  		for _, c := range p.comment.List {
   161  			size += len(c.Text)
   162  		}
   163  		p.nextComment()
   164  	}
   165  	return size
   166  }
   167  
   168  // recordLine records the output line number for the next non-whitespace
   169  // token in *linePtr. It is used to compute an accurate line number for a
   170  // formatted construct, independent of pending (not yet emitted) whitespace
   171  // or comments.
   172  func (p *printer) recordLine(linePtr *int) {
   173  	p.linePtr = linePtr
   174  }
   175  
   176  // linesFrom returns the number of output lines between the current
   177  // output line and the line argument, ignoring any pending (not yet
   178  // emitted) whitespace or comments. It is used to compute an accurate
   179  // size (in number of lines) for a formatted construct.
   180  func (p *printer) linesFrom(line int) int {
   181  	return p.out.Line - line
   182  }
   183  
   184  func (p *printer) posFor(pos token.Pos) token.Position {
   185  	// not used frequently enough to cache entire token.Position
   186  	return p.fset.PositionFor(pos, false /* absolute position */)
   187  }
   188  
   189  func (p *printer) lineFor(pos token.Pos) int {
   190  	if pos != p.cachedPos {
   191  		p.cachedPos = pos
   192  		p.cachedLine = p.fset.PositionFor(pos, false /* absolute position */).Line
   193  	}
   194  	return p.cachedLine
   195  }
   196  
   197  // writeLineDirective writes a //line directive if necessary.
   198  func (p *printer) writeLineDirective(pos token.Position) {
   199  	if pos.IsValid() && (p.out.Line != pos.Line || p.out.Filename != pos.Filename) {
   200  		if strings.ContainsAny(pos.Filename, "\r\n") {
   201  			if p.sourcePosErr == nil {
   202  				p.sourcePosErr = fmt.Errorf("go/printer: source filename contains unexpected newline character: %q", pos.Filename)
   203  			}
   204  			return
   205  		}
   206  
   207  		p.output = append(p.output, tabwriter.Escape) // protect '\n' in //line from tabwriter interpretation
   208  		p.output = append(p.output, fmt.Sprintf("//line %s:%d\n", pos.Filename, pos.Line)...)
   209  		p.output = append(p.output, tabwriter.Escape)
   210  		// p.out must match the //line directive
   211  		p.out.Filename = pos.Filename
   212  		p.out.Line = pos.Line
   213  	}
   214  }
   215  
   216  // writeIndent writes indentation.
   217  func (p *printer) writeIndent() {
   218  	// use "hard" htabs - indentation columns
   219  	// must not be discarded by the tabwriter
   220  	n := p.Config.Indent + p.indent // include base indentation
   221  	for i := 0; i < n; i++ {
   222  		p.output = append(p.output, '\t')
   223  	}
   224  
   225  	// update positions
   226  	p.pos.Offset += n
   227  	p.pos.Column += n
   228  	p.out.Column += n
   229  }
   230  
   231  // writeByte writes ch n times to p.output and updates p.pos.
   232  // Only used to write formatting (white space) characters.
   233  func (p *printer) writeByte(ch byte, n int) {
   234  	if p.endAlignment {
   235  		// Ignore any alignment control character;
   236  		// and at the end of the line, break with
   237  		// a formfeed to indicate termination of
   238  		// existing columns.
   239  		switch ch {
   240  		case '\t', '\v':
   241  			ch = ' '
   242  		case '\n', '\f':
   243  			ch = '\f'
   244  			p.endAlignment = false
   245  		}
   246  	}
   247  
   248  	if p.out.Column == 1 {
   249  		// no need to write line directives before white space
   250  		p.writeIndent()
   251  	}
   252  
   253  	for i := 0; i < n; i++ {
   254  		p.output = append(p.output, ch)
   255  	}
   256  
   257  	// update positions
   258  	p.pos.Offset += n
   259  	if ch == '\n' || ch == '\f' {
   260  		p.pos.Line += n
   261  		p.out.Line += n
   262  		p.pos.Column = 1
   263  		p.out.Column = 1
   264  		return
   265  	}
   266  	p.pos.Column += n
   267  	p.out.Column += n
   268  }
   269  
   270  // writeString writes the string s to p.output and updates p.pos, p.out,
   271  // and p.last. If isLit is set, s is escaped w/ tabwriter.Escape characters
   272  // to protect s from being interpreted by the tabwriter.
   273  //
   274  // Note: writeString is only used to write Go tokens, literals, and
   275  // comments, all of which must be written literally. Thus, it is correct
   276  // to always set isLit = true. However, setting it explicitly only when
   277  // needed (i.e., when we don't know that s contains no tabs or line breaks)
   278  // avoids processing extra escape characters and reduces run time of the
   279  // printer benchmark by up to 10%.
   280  func (p *printer) writeString(pos token.Position, s string, isLit bool) {
   281  	if p.out.Column == 1 {
   282  		if p.Config.Mode&SourcePos != 0 {
   283  			p.writeLineDirective(pos)
   284  		}
   285  		p.writeIndent()
   286  	}
   287  
   288  	if pos.IsValid() {
   289  		// update p.pos (if pos is invalid, continue with existing p.pos)
   290  		// Note: Must do this after handling line beginnings because
   291  		// writeIndent updates p.pos if there's indentation, but p.pos
   292  		// is the position of s.
   293  		p.pos = pos
   294  	}
   295  
   296  	if isLit {
   297  		// Protect s such that is passes through the tabwriter
   298  		// unchanged. Note that valid Go programs cannot contain
   299  		// tabwriter.Escape bytes since they do not appear in legal
   300  		// UTF-8 sequences.
   301  		p.output = append(p.output, tabwriter.Escape)
   302  	}
   303  
   304  	if debug {
   305  		p.output = append(p.output, fmt.Sprintf("/*%s*/", pos)...) // do not update p.pos!
   306  	}
   307  	p.output = append(p.output, s...)
   308  
   309  	// update positions
   310  	nlines := 0
   311  	var li int // index of last newline; valid if nlines > 0
   312  	for i := 0; i < len(s); i++ {
   313  		// Raw string literals may contain any character except back quote (`).
   314  		if ch := s[i]; ch == '\n' || ch == '\f' {
   315  			// account for line break
   316  			nlines++
   317  			li = i
   318  			// A line break inside a literal will break whatever column
   319  			// formatting is in place; ignore any further alignment through
   320  			// the end of the line.
   321  			p.endAlignment = true
   322  		}
   323  	}
   324  	p.pos.Offset += len(s)
   325  	if nlines > 0 {
   326  		p.pos.Line += nlines
   327  		p.out.Line += nlines
   328  		c := len(s) - li
   329  		p.pos.Column = c
   330  		p.out.Column = c
   331  	} else {
   332  		p.pos.Column += len(s)
   333  		p.out.Column += len(s)
   334  	}
   335  
   336  	if isLit {
   337  		p.output = append(p.output, tabwriter.Escape)
   338  	}
   339  
   340  	p.last = p.pos
   341  }
   342  
   343  // writeCommentPrefix writes the whitespace before a comment.
   344  // If there is any pending whitespace, it consumes as much of
   345  // it as is likely to help position the comment nicely.
   346  // pos is the comment position, next the position of the item
   347  // after all pending comments, prev is the previous comment in
   348  // a group of comments (or nil), and tok is the next token.
   349  func (p *printer) writeCommentPrefix(pos, next token.Position, prev *ast.Comment, tok token.Token) {
   350  	if len(p.output) == 0 {
   351  		// the comment is the first item to be printed - don't write any whitespace
   352  		return
   353  	}
   354  
   355  	if pos.IsValid() && pos.Filename != p.last.Filename {
   356  		// comment in a different file - separate with newlines
   357  		p.writeByte('\f', maxNewlines)
   358  		return
   359  	}
   360  
   361  	if pos.Line == p.last.Line && (prev == nil || prev.Text[1] != '/') {
   362  		// comment on the same line as last item:
   363  		// separate with at least one separator
   364  		hasSep := false
   365  		if prev == nil {
   366  			// first comment of a comment group
   367  			j := 0
   368  			for i, ch := range p.wsbuf {
   369  				switch ch {
   370  				case blank:
   371  					// ignore any blanks before a comment
   372  					p.wsbuf[i] = ignore
   373  					continue
   374  				case vtab:
   375  					// respect existing tabs - important
   376  					// for proper formatting of commented structs
   377  					hasSep = true
   378  					continue
   379  				case indent:
   380  					// apply pending indentation
   381  					continue
   382  				}
   383  				j = i
   384  				break
   385  			}
   386  			p.writeWhitespace(j)
   387  		}
   388  		// make sure there is at least one separator
   389  		if !hasSep {
   390  			sep := byte('\t')
   391  			if pos.Line == next.Line {
   392  				// next item is on the same line as the comment
   393  				// (which must be a /*-style comment): separate
   394  				// with a blank instead of a tab
   395  				sep = ' '
   396  			}
   397  			p.writeByte(sep, 1)
   398  		}
   399  
   400  	} else {
   401  		// comment on a different line:
   402  		// separate with at least one line break
   403  		droppedLinebreak := false
   404  		j := 0
   405  		for i, ch := range p.wsbuf {
   406  			switch ch {
   407  			case blank, vtab:
   408  				// ignore any horizontal whitespace before line breaks
   409  				p.wsbuf[i] = ignore
   410  				continue
   411  			case indent:
   412  				// apply pending indentation
   413  				continue
   414  			case unindent:
   415  				// if this is not the last unindent, apply it
   416  				// as it is (likely) belonging to the last
   417  				// construct (e.g., a multi-line expression list)
   418  				// and is not part of closing a block
   419  				if i+1 < len(p.wsbuf) && p.wsbuf[i+1] == unindent {
   420  					continue
   421  				}
   422  				// if the next token is not a closing }, apply the unindent
   423  				// if it appears that the comment is aligned with the
   424  				// token; otherwise assume the unindent is part of a
   425  				// closing block and stop (this scenario appears with
   426  				// comments before a case label where the comments
   427  				// apply to the next case instead of the current one)
   428  				if tok != token.RBRACE && pos.Column == next.Column {
   429  					continue
   430  				}
   431  			case newline, formfeed:
   432  				p.wsbuf[i] = ignore
   433  				droppedLinebreak = prev == nil // record only if first comment of a group
   434  			}
   435  			j = i
   436  			break
   437  		}
   438  		p.writeWhitespace(j)
   439  
   440  		// determine number of linebreaks before the comment
   441  		n := 0
   442  		if pos.IsValid() && p.last.IsValid() {
   443  			n = pos.Line - p.last.Line
   444  			if n < 0 { // should never happen
   445  				n = 0
   446  			}
   447  		}
   448  
   449  		// at the package scope level only (p.indent == 0),
   450  		// add an extra newline if we dropped one before:
   451  		// this preserves a blank line before documentation
   452  		// comments at the package scope level (issue 2570)
   453  		if p.indent == 0 && droppedLinebreak {
   454  			n++
   455  		}
   456  
   457  		// make sure there is at least one line break
   458  		// if the previous comment was a line comment
   459  		if n == 0 && prev != nil && prev.Text[1] == '/' {
   460  			n = 1
   461  		}
   462  
   463  		if n > 0 {
   464  			// use formfeeds to break columns before a comment;
   465  			// this is analogous to using formfeeds to separate
   466  			// individual lines of /*-style comments
   467  			p.writeByte('\f', nlimit(n))
   468  		}
   469  	}
   470  }
   471  
   472  // Returns true if s contains only white space
   473  // (only tabs and blanks can appear in the printer's context).
   474  func isBlank(s string) bool {
   475  	for i := 0; i < len(s); i++ {
   476  		if s[i] > ' ' {
   477  			return false
   478  		}
   479  	}
   480  	return true
   481  }
   482  
   483  // commonPrefix returns the common prefix of a and b.
   484  func commonPrefix(a, b string) string {
   485  	i := 0
   486  	for i < len(a) && i < len(b) && a[i] == b[i] && (a[i] <= ' ' || a[i] == '*') {
   487  		i++
   488  	}
   489  	return a[0:i]
   490  }
   491  
   492  // trimRight returns s with trailing whitespace removed.
   493  func trimRight(s string) string {
   494  	return strings.TrimRightFunc(s, unicode.IsSpace)
   495  }
   496  
   497  // stripCommonPrefix removes a common prefix from /*-style comment lines (unless no
   498  // comment line is indented, all but the first line have some form of space prefix).
   499  // The prefix is computed using heuristics such that is likely that the comment
   500  // contents are nicely laid out after re-printing each line using the printer's
   501  // current indentation.
   502  func stripCommonPrefix(lines []string) {
   503  	if len(lines) <= 1 {
   504  		return // at most one line - nothing to do
   505  	}
   506  	// len(lines) > 1
   507  
   508  	// The heuristic in this function tries to handle a few
   509  	// common patterns of /*-style comments: Comments where
   510  	// the opening /* and closing */ are aligned and the
   511  	// rest of the comment text is aligned and indented with
   512  	// blanks or tabs, cases with a vertical "line of stars"
   513  	// on the left, and cases where the closing */ is on the
   514  	// same line as the last comment text.
   515  
   516  	// Compute maximum common white prefix of all but the first,
   517  	// last, and blank lines, and replace blank lines with empty
   518  	// lines (the first line starts with /* and has no prefix).
   519  	// In cases where only the first and last lines are not blank,
   520  	// such as two-line comments, or comments where all inner lines
   521  	// are blank, consider the last line for the prefix computation
   522  	// since otherwise the prefix would be empty.
   523  	//
   524  	// Note that the first and last line are never empty (they
   525  	// contain the opening /* and closing */ respectively) and
   526  	// thus they can be ignored by the blank line check.
   527  	prefix := ""
   528  	prefixSet := false
   529  	if len(lines) > 2 {
   530  		for i, line := range lines[1 : len(lines)-1] {
   531  			if isBlank(line) {
   532  				lines[1+i] = "" // range starts with lines[1]
   533  			} else {
   534  				if !prefixSet {
   535  					prefix = line
   536  					prefixSet = true
   537  				}
   538  				prefix = commonPrefix(prefix, line)
   539  			}
   540  
   541  		}
   542  	}
   543  	// If we don't have a prefix yet, consider the last line.
   544  	if !prefixSet {
   545  		line := lines[len(lines)-1]
   546  		prefix = commonPrefix(line, line)
   547  	}
   548  
   549  	/*
   550  	 * Check for vertical "line of stars" and correct prefix accordingly.
   551  	 */
   552  	lineOfStars := false
   553  	if p, _, ok := strings.Cut(prefix, "*"); ok {
   554  		// remove trailing blank from prefix so stars remain aligned
   555  		prefix = strings.TrimSuffix(p, " ")
   556  		lineOfStars = true
   557  	} else {
   558  		// No line of stars present.
   559  		// Determine the white space on the first line after the /*
   560  		// and before the beginning of the comment text, assume two
   561  		// blanks instead of the /* unless the first character after
   562  		// the /* is a tab. If the first comment line is empty but
   563  		// for the opening /*, assume up to 3 blanks or a tab. This
   564  		// whitespace may be found as suffix in the common prefix.
   565  		first := lines[0]
   566  		if isBlank(first[2:]) {
   567  			// no comment text on the first line:
   568  			// reduce prefix by up to 3 blanks or a tab
   569  			// if present - this keeps comment text indented
   570  			// relative to the /* and */'s if it was indented
   571  			// in the first place
   572  			i := len(prefix)
   573  			for n := 0; n < 3 && i > 0 && prefix[i-1] == ' '; n++ {
   574  				i--
   575  			}
   576  			if i == len(prefix) && i > 0 && prefix[i-1] == '\t' {
   577  				i--
   578  			}
   579  			prefix = prefix[0:i]
   580  		} else {
   581  			// comment text on the first line
   582  			suffix := make([]byte, len(first))
   583  			n := 2 // start after opening /*
   584  			for n < len(first) && first[n] <= ' ' {
   585  				suffix[n] = first[n]
   586  				n++
   587  			}
   588  			if n > 2 && suffix[2] == '\t' {
   589  				// assume the '\t' compensates for the /*
   590  				suffix = suffix[2:n]
   591  			} else {
   592  				// otherwise assume two blanks
   593  				suffix[0], suffix[1] = ' ', ' '
   594  				suffix = suffix[0:n]
   595  			}
   596  			// Shorten the computed common prefix by the length of
   597  			// suffix, if it is found as suffix of the prefix.
   598  			prefix = strings.TrimSuffix(prefix, string(suffix))
   599  		}
   600  	}
   601  
   602  	// Handle last line: If it only contains a closing */, align it
   603  	// with the opening /*, otherwise align the text with the other
   604  	// lines.
   605  	last := lines[len(lines)-1]
   606  	closing := "*/"
   607  	before, _, _ := strings.Cut(last, closing) // closing always present
   608  	if isBlank(before) {
   609  		// last line only contains closing */
   610  		if lineOfStars {
   611  			closing = " */" // add blank to align final star
   612  		}
   613  		lines[len(lines)-1] = prefix + closing
   614  	} else {
   615  		// last line contains more comment text - assume
   616  		// it is aligned like the other lines and include
   617  		// in prefix computation
   618  		prefix = commonPrefix(prefix, last)
   619  	}
   620  
   621  	// Remove the common prefix from all but the first and empty lines.
   622  	for i, line := range lines {
   623  		if i > 0 && line != "" {
   624  			lines[i] = line[len(prefix):]
   625  		}
   626  	}
   627  }
   628  
   629  func (p *printer) writeComment(comment *ast.Comment) {
   630  	text := comment.Text
   631  	pos := p.posFor(comment.Pos())
   632  
   633  	const linePrefix = "//line "
   634  	if strings.HasPrefix(text, linePrefix) && (!pos.IsValid() || pos.Column == 1) {
   635  		// Possibly a //-style line directive.
   636  		// Suspend indentation temporarily to keep line directive valid.
   637  		defer func(indent int) { p.indent = indent }(p.indent)
   638  		p.indent = 0
   639  	}
   640  
   641  	// shortcut common case of //-style comments
   642  	if text[1] == '/' {
   643  		if constraint.IsGoBuild(text) {
   644  			p.goBuild = append(p.goBuild, len(p.output))
   645  		} else if constraint.IsPlusBuild(text) {
   646  			p.plusBuild = append(p.plusBuild, len(p.output))
   647  		}
   648  		p.writeString(pos, trimRight(text), true)
   649  		return
   650  	}
   651  
   652  	// for /*-style comments, print line by line and let the
   653  	// write function take care of the proper indentation
   654  	lines := strings.Split(text, "\n")
   655  
   656  	// The comment started in the first column but is going
   657  	// to be indented. For an idempotent result, add indentation
   658  	// to all lines such that they look like they were indented
   659  	// before - this will make sure the common prefix computation
   660  	// is the same independent of how many times formatting is
   661  	// applied (was issue 1835).
   662  	if pos.IsValid() && pos.Column == 1 && p.indent > 0 {
   663  		for i, line := range lines[1:] {
   664  			lines[1+i] = "   " + line
   665  		}
   666  	}
   667  
   668  	stripCommonPrefix(lines)
   669  
   670  	// write comment lines, separated by formfeed,
   671  	// without a line break after the last line
   672  	for i, line := range lines {
   673  		if i > 0 {
   674  			p.writeByte('\f', 1)
   675  			pos = p.pos
   676  		}
   677  		if len(line) > 0 {
   678  			p.writeString(pos, trimRight(line), true)
   679  		}
   680  	}
   681  }
   682  
   683  // writeCommentSuffix writes a line break after a comment if indicated
   684  // and processes any leftover indentation information. If a line break
   685  // is needed, the kind of break (newline vs formfeed) depends on the
   686  // pending whitespace. The writeCommentSuffix result indicates if a
   687  // newline was written or if a formfeed was dropped from the whitespace
   688  // buffer.
   689  func (p *printer) writeCommentSuffix(needsLinebreak bool) (wroteNewline, droppedFF bool) {
   690  	for i, ch := range p.wsbuf {
   691  		switch ch {
   692  		case blank, vtab:
   693  			// ignore trailing whitespace
   694  			p.wsbuf[i] = ignore
   695  		case indent, unindent:
   696  			// don't lose indentation information
   697  		case newline, formfeed:
   698  			// if we need a line break, keep exactly one
   699  			// but remember if we dropped any formfeeds
   700  			if needsLinebreak {
   701  				needsLinebreak = false
   702  				wroteNewline = true
   703  			} else {
   704  				if ch == formfeed {
   705  					droppedFF = true
   706  				}
   707  				p.wsbuf[i] = ignore
   708  			}
   709  		}
   710  	}
   711  	p.writeWhitespace(len(p.wsbuf))
   712  
   713  	// make sure we have a line break
   714  	if needsLinebreak {
   715  		p.writeByte('\n', 1)
   716  		wroteNewline = true
   717  	}
   718  
   719  	return
   720  }
   721  
   722  // containsLinebreak reports whether the whitespace buffer contains any line breaks.
   723  func (p *printer) containsLinebreak() bool {
   724  	for _, ch := range p.wsbuf {
   725  		if ch == newline || ch == formfeed {
   726  			return true
   727  		}
   728  	}
   729  	return false
   730  }
   731  
   732  // intersperseComments consumes all comments that appear before the next token
   733  // tok and prints it together with the buffered whitespace (i.e., the whitespace
   734  // that needs to be written before the next token). A heuristic is used to mix
   735  // the comments and whitespace. The intersperseComments result indicates if a
   736  // newline was written or if a formfeed was dropped from the whitespace buffer.
   737  func (p *printer) intersperseComments(next token.Position, tok token.Token) (wroteNewline, droppedFF bool) {
   738  	var last *ast.Comment
   739  	for p.commentBefore(next) {
   740  		list := p.comment.List
   741  		changed := false
   742  
   743  		if tok != token.IDENT &&
   744  			p.lastTok != token.IMPORT && // do not rewrite cgo's import "C" comments
   745  			p.posFor(p.comment.Pos()).Column == 1 &&
   746  			p.posFor(p.comment.End()+1) == next {
   747  			// Unindented comment abutting next token position:
   748  			// a top-level doc comment.
   749  			list = formatDocComment(list)
   750  			changed = true
   751  
   752  			if len(p.comment.List) > 0 && len(list) == 0 {
   753  				// The doc comment was removed entirely.
   754  				// Keep preceding whitespace.
   755  				p.writeCommentPrefix(p.posFor(p.comment.Pos()), next, last, tok)
   756  				// Change print state to continue at next.
   757  				p.pos = next
   758  				p.last = next
   759  				// There can't be any more comments.
   760  				p.nextComment()
   761  				return p.writeCommentSuffix(false)
   762  			}
   763  		}
   764  		for _, c := range list {
   765  			p.writeCommentPrefix(p.posFor(c.Pos()), next, last, tok)
   766  			p.writeComment(c)
   767  			last = c
   768  		}
   769  		// In case list was rewritten, change print state to where
   770  		// the original list would have ended.
   771  		if len(p.comment.List) > 0 && changed {
   772  			last = p.comment.List[len(p.comment.List)-1]
   773  			p.pos = p.posFor(last.End())
   774  			p.last = p.pos
   775  		}
   776  		p.nextComment()
   777  	}
   778  
   779  	if last != nil {
   780  		// If the last comment is a /*-style comment and the next item
   781  		// follows on the same line but is not a comma, and not a "closing"
   782  		// token immediately following its corresponding "opening" token,
   783  		// add an extra separator unless explicitly disabled. Use a blank
   784  		// as separator unless we have pending linebreaks, they are not
   785  		// disabled, and we are outside a composite literal, in which case
   786  		// we want a linebreak (issue 15137).
   787  		// TODO(gri) This has become overly complicated. We should be able
   788  		// to track whether we're inside an expression or statement and
   789  		// use that information to decide more directly.
   790  		needsLinebreak := false
   791  		if p.mode&noExtraBlank == 0 &&
   792  			last.Text[1] == '*' && p.lineFor(last.Pos()) == next.Line &&
   793  			tok != token.COMMA &&
   794  			(tok != token.RPAREN || p.prevOpen == token.LPAREN) &&
   795  			(tok != token.RBRACK || p.prevOpen == token.LBRACK) {
   796  			if p.containsLinebreak() && p.mode&noExtraLinebreak == 0 && p.level == 0 {
   797  				needsLinebreak = true
   798  			} else {
   799  				p.writeByte(' ', 1)
   800  			}
   801  		}
   802  		// Ensure that there is a line break after a //-style comment,
   803  		// before EOF, and before a closing '}' unless explicitly disabled.
   804  		if last.Text[1] == '/' ||
   805  			tok == token.EOF ||
   806  			tok == token.RBRACE && p.mode&noExtraLinebreak == 0 {
   807  			needsLinebreak = true
   808  		}
   809  		return p.writeCommentSuffix(needsLinebreak)
   810  	}
   811  
   812  	// no comment was written - we should never reach here since
   813  	// intersperseComments should not be called in that case
   814  	p.internalError("intersperseComments called without pending comments")
   815  	return
   816  }
   817  
   818  // writeWhitespace writes the first n whitespace entries.
   819  func (p *printer) writeWhitespace(n int) {
   820  	// write entries
   821  	for i := 0; i < n; i++ {
   822  		switch ch := p.wsbuf[i]; ch {
   823  		case ignore:
   824  			// ignore!
   825  		case indent:
   826  			p.indent++
   827  		case unindent:
   828  			p.indent--
   829  			if p.indent < 0 {
   830  				p.internalError("negative indentation:", p.indent)
   831  				p.indent = 0
   832  			}
   833  		case newline, formfeed:
   834  			// A line break immediately followed by a "correcting"
   835  			// unindent is swapped with the unindent - this permits
   836  			// proper label positioning. If a comment is between
   837  			// the line break and the label, the unindent is not
   838  			// part of the comment whitespace prefix and the comment
   839  			// will be positioned correctly indented.
   840  			if i+1 < n && p.wsbuf[i+1] == unindent {
   841  				// Use a formfeed to terminate the current section.
   842  				// Otherwise, a long label name on the next line leading
   843  				// to a wide column may increase the indentation column
   844  				// of lines before the label; effectively leading to wrong
   845  				// indentation.
   846  				p.wsbuf[i], p.wsbuf[i+1] = unindent, formfeed
   847  				i-- // do it again
   848  				continue
   849  			}
   850  			fallthrough
   851  		default:
   852  			p.writeByte(byte(ch), 1)
   853  		}
   854  	}
   855  
   856  	// shift remaining entries down
   857  	l := copy(p.wsbuf, p.wsbuf[n:])
   858  	p.wsbuf = p.wsbuf[:l]
   859  }
   860  
   861  // ----------------------------------------------------------------------------
   862  // Printing interface
   863  
   864  // nlimit limits n to maxNewlines.
   865  func nlimit(n int) int {
   866  	return min(n, maxNewlines)
   867  }
   868  
   869  func mayCombine(prev token.Token, next byte) (b bool) {
   870  	switch prev {
   871  	case token.INT:
   872  		b = next == '.' // 1.
   873  	case token.ADD:
   874  		b = next == '+' // ++
   875  	case token.SUB:
   876  		b = next == '-' // --
   877  	case token.QUO:
   878  		b = next == '*' // /*
   879  	case token.LSS:
   880  		b = next == '-' || next == '<' // <- or <<
   881  	case token.AND:
   882  		b = next == '&' || next == '^' // && or &^
   883  	}
   884  	return
   885  }
   886  
   887  func (p *printer) setPos(pos token.Pos) {
   888  	if pos.IsValid() {
   889  		p.pos = p.posFor(pos) // accurate position of next item
   890  	}
   891  }
   892  
   893  // print prints a list of "items" (roughly corresponding to syntactic
   894  // tokens, but also including whitespace and formatting information).
   895  // It is the only print function that should be called directly from
   896  // any of the AST printing functions in nodes.go.
   897  //
   898  // Whitespace is accumulated until a non-whitespace token appears. Any
   899  // comments that need to appear before that token are printed first,
   900  // taking into account the amount and structure of any pending white-
   901  // space for best comment placement. Then, any leftover whitespace is
   902  // printed, followed by the actual token.
   903  func (p *printer) print(args ...any) {
   904  	for _, arg := range args {
   905  		// information about the current arg
   906  		var data string
   907  		var isLit bool
   908  		var impliedSemi bool // value for p.impliedSemi after this arg
   909  
   910  		// record previous opening token, if any
   911  		switch p.lastTok {
   912  		case token.ILLEGAL:
   913  			// ignore (white space)
   914  		case token.LPAREN, token.LBRACK:
   915  			p.prevOpen = p.lastTok
   916  		default:
   917  			// other tokens followed any opening token
   918  			p.prevOpen = token.ILLEGAL
   919  		}
   920  
   921  		switch x := arg.(type) {
   922  		case pmode:
   923  			// toggle printer mode
   924  			p.mode ^= x
   925  			continue
   926  
   927  		case whiteSpace:
   928  			if x == ignore {
   929  				// don't add ignore's to the buffer; they
   930  				// may screw up "correcting" unindents (see
   931  				// LabeledStmt)
   932  				continue
   933  			}
   934  			i := len(p.wsbuf)
   935  			if i == cap(p.wsbuf) {
   936  				// Whitespace sequences are very short so this should
   937  				// never happen. Handle gracefully (but possibly with
   938  				// bad comment placement) if it does happen.
   939  				p.writeWhitespace(i)
   940  				i = 0
   941  			}
   942  			p.wsbuf = p.wsbuf[0 : i+1]
   943  			p.wsbuf[i] = x
   944  			if x == newline || x == formfeed {
   945  				// newlines affect the current state (p.impliedSemi)
   946  				// and not the state after printing arg (impliedSemi)
   947  				// because comments can be interspersed before the arg
   948  				// in this case
   949  				p.impliedSemi = false
   950  			}
   951  			p.lastTok = token.ILLEGAL
   952  			continue
   953  
   954  		case *ast.Ident:
   955  			data = x.Name
   956  			impliedSemi = true
   957  			p.lastTok = token.IDENT
   958  
   959  		case *ast.BasicLit:
   960  			data = x.Value
   961  			isLit = true
   962  			impliedSemi = true
   963  			p.lastTok = x.Kind
   964  
   965  		case token.Token:
   966  			s := x.String()
   967  			if mayCombine(p.lastTok, s[0]) {
   968  				// the previous and the current token must be
   969  				// separated by a blank otherwise they combine
   970  				// into a different incorrect token sequence
   971  				// (except for token.INT followed by a '.' this
   972  				// should never happen because it is taken care
   973  				// of via binary expression formatting)
   974  				if len(p.wsbuf) != 0 {
   975  					p.internalError("whitespace buffer not empty")
   976  				}
   977  				p.wsbuf = p.wsbuf[0:1]
   978  				p.wsbuf[0] = ' '
   979  			}
   980  			data = s
   981  			// some keywords followed by a newline imply a semicolon
   982  			switch x {
   983  			case token.BREAK, token.CONTINUE, token.FALLTHROUGH, token.RETURN,
   984  				token.INC, token.DEC, token.RPAREN, token.RBRACK, token.RBRACE:
   985  				impliedSemi = true
   986  			}
   987  			p.lastTok = x
   988  
   989  		case string:
   990  			// incorrect AST - print error message
   991  			data = x
   992  			isLit = true
   993  			impliedSemi = true
   994  			p.lastTok = token.STRING
   995  
   996  		default:
   997  			fmt.Fprintf(os.Stderr, "print: unsupported argument %v (%T)\n", arg, arg)
   998  			panic("go/printer type")
   999  		}
  1000  		// data != ""
  1001  
  1002  		next := p.pos // estimated/accurate position of next item
  1003  		wroteNewline, droppedFF := p.flush(next, p.lastTok)
  1004  
  1005  		// intersperse extra newlines if present in the source and
  1006  		// if they don't cause extra semicolons (don't do this in
  1007  		// flush as it will cause extra newlines at the end of a file)
  1008  		if !p.impliedSemi {
  1009  			n := nlimit(next.Line - p.pos.Line)
  1010  			// don't exceed maxNewlines if we already wrote one
  1011  			if wroteNewline && n == maxNewlines {
  1012  				n = maxNewlines - 1
  1013  			}
  1014  			if n > 0 {
  1015  				ch := byte('\n')
  1016  				if droppedFF {
  1017  					ch = '\f' // use formfeed since we dropped one before
  1018  				}
  1019  				p.writeByte(ch, n)
  1020  				impliedSemi = false
  1021  			}
  1022  		}
  1023  
  1024  		// the next token starts now - record its line number if requested
  1025  		if p.linePtr != nil {
  1026  			*p.linePtr = p.out.Line
  1027  			p.linePtr = nil
  1028  		}
  1029  
  1030  		p.writeString(next, data, isLit)
  1031  		p.impliedSemi = impliedSemi
  1032  	}
  1033  }
  1034  
  1035  // flush prints any pending comments and whitespace occurring textually
  1036  // before the position of the next token tok. The flush result indicates
  1037  // if a newline was written or if a formfeed was dropped from the whitespace
  1038  // buffer.
  1039  func (p *printer) flush(next token.Position, tok token.Token) (wroteNewline, droppedFF bool) {
  1040  	if p.commentBefore(next) {
  1041  		// if there are comments before the next item, intersperse them
  1042  		wroteNewline, droppedFF = p.intersperseComments(next, tok)
  1043  	} else {
  1044  		// otherwise, write any leftover whitespace
  1045  		p.writeWhitespace(len(p.wsbuf))
  1046  	}
  1047  	return
  1048  }
  1049  
  1050  // getDoc returns the ast.CommentGroup associated with n, if any.
  1051  func getDoc(n ast.Node) *ast.CommentGroup {
  1052  	switch n := n.(type) {
  1053  	case *ast.Field:
  1054  		return n.Doc
  1055  	case *ast.ImportSpec:
  1056  		return n.Doc
  1057  	case *ast.ValueSpec:
  1058  		return n.Doc
  1059  	case *ast.TypeSpec:
  1060  		return n.Doc
  1061  	case *ast.GenDecl:
  1062  		return n.Doc
  1063  	case *ast.FuncDecl:
  1064  		return n.Doc
  1065  	case *ast.File:
  1066  		return n.Doc
  1067  	}
  1068  	return nil
  1069  }
  1070  
  1071  func getLastComment(n ast.Node) *ast.CommentGroup {
  1072  	switch n := n.(type) {
  1073  	case *ast.Field:
  1074  		return n.Comment
  1075  	case *ast.ImportSpec:
  1076  		return n.Comment
  1077  	case *ast.ValueSpec:
  1078  		return n.Comment
  1079  	case *ast.TypeSpec:
  1080  		return n.Comment
  1081  	case *ast.GenDecl:
  1082  		if len(n.Specs) > 0 {
  1083  			return getLastComment(n.Specs[len(n.Specs)-1])
  1084  		}
  1085  	case *ast.File:
  1086  		if len(n.Comments) > 0 {
  1087  			return n.Comments[len(n.Comments)-1]
  1088  		}
  1089  	}
  1090  	return nil
  1091  }
  1092  
  1093  func (p *printer) printNode(node any) error {
  1094  	// unpack *CommentedNode, if any
  1095  	var comments []*ast.CommentGroup
  1096  	if cnode, ok := node.(*CommentedNode); ok {
  1097  		node = cnode.Node
  1098  		comments = cnode.Comments
  1099  	}
  1100  
  1101  	if comments != nil {
  1102  		// commented node - restrict comment list to relevant range
  1103  		n, ok := node.(ast.Node)
  1104  		if !ok {
  1105  			goto unsupported
  1106  		}
  1107  		beg := n.Pos()
  1108  		end := n.End()
  1109  		// if the node has associated documentation,
  1110  		// include that commentgroup in the range
  1111  		// (the comment list is sorted in the order
  1112  		// of the comment appearance in the source code)
  1113  		if doc := getDoc(n); doc != nil {
  1114  			beg = doc.Pos()
  1115  		}
  1116  		if com := getLastComment(n); com != nil {
  1117  			if e := com.End(); e > end {
  1118  				end = e
  1119  			}
  1120  		}
  1121  		// token.Pos values are global offsets, we can
  1122  		// compare them directly
  1123  		i := 0
  1124  		for i < len(comments) && comments[i].End() < beg {
  1125  			i++
  1126  		}
  1127  		j := i
  1128  		for j < len(comments) && comments[j].Pos() < end {
  1129  			j++
  1130  		}
  1131  		if i < j {
  1132  			p.comments = comments[i:j]
  1133  		}
  1134  	} else if n, ok := node.(*ast.File); ok {
  1135  		// use ast.File comments, if any
  1136  		p.comments = n.Comments
  1137  	}
  1138  
  1139  	// if there are no comments, use node comments
  1140  	p.useNodeComments = p.comments == nil
  1141  
  1142  	// get comments ready for use
  1143  	p.nextComment()
  1144  
  1145  	p.print(pmode(0))
  1146  
  1147  	// format node
  1148  	switch n := node.(type) {
  1149  	case ast.Expr:
  1150  		p.expr(n)
  1151  	case ast.Stmt:
  1152  		// A labeled statement will un-indent to position the label.
  1153  		// Set p.indent to 1 so we don't get indent "underflow".
  1154  		if _, ok := n.(*ast.LabeledStmt); ok {
  1155  			p.indent = 1
  1156  		}
  1157  		p.stmt(n, false)
  1158  	case ast.Decl:
  1159  		p.decl(n)
  1160  	case ast.Spec:
  1161  		p.spec(n, 1, false)
  1162  	case []ast.Stmt:
  1163  		// A labeled statement will un-indent to position the label.
  1164  		// Set p.indent to 1 so we don't get indent "underflow".
  1165  		for _, s := range n {
  1166  			if _, ok := s.(*ast.LabeledStmt); ok {
  1167  				p.indent = 1
  1168  			}
  1169  		}
  1170  		p.stmtList(n, 0, false)
  1171  	case []ast.Decl:
  1172  		p.declList(n)
  1173  	case *ast.File:
  1174  		p.file(n)
  1175  	default:
  1176  		goto unsupported
  1177  	}
  1178  
  1179  	return p.sourcePosErr
  1180  
  1181  unsupported:
  1182  	return fmt.Errorf("go/printer: unsupported node type %T", node)
  1183  }
  1184  
  1185  // ----------------------------------------------------------------------------
  1186  // Trimmer
  1187  
  1188  // A trimmer is an io.Writer filter for stripping tabwriter.Escape
  1189  // characters, trailing blanks and tabs, and for converting formfeed
  1190  // and vtab characters into newlines and htabs (in case no tabwriter
  1191  // is used). Text bracketed by tabwriter.Escape characters is passed
  1192  // through unchanged.
  1193  type trimmer struct {
  1194  	output io.Writer
  1195  	state  int
  1196  	space  []byte
  1197  }
  1198  
  1199  // trimmer is implemented as a state machine.
  1200  // It can be in one of the following states:
  1201  const (
  1202  	inSpace  = iota // inside space
  1203  	inEscape        // inside text bracketed by tabwriter.Escapes
  1204  	inText          // inside text
  1205  )
  1206  
  1207  func (p *trimmer) resetSpace() {
  1208  	p.state = inSpace
  1209  	p.space = p.space[0:0]
  1210  }
  1211  
  1212  // Design note: It is tempting to eliminate extra blanks occurring in
  1213  //              whitespace in this function as it could simplify some
  1214  //              of the blanks logic in the node printing functions.
  1215  //              However, this would mess up any formatting done by
  1216  //              the tabwriter.
  1217  
  1218  var aNewline = []byte("\n")
  1219  
  1220  func (p *trimmer) Write(data []byte) (n int, err error) {
  1221  	// invariants:
  1222  	// p.state == inSpace:
  1223  	//	p.space is unwritten
  1224  	// p.state == inEscape, inText:
  1225  	//	data[m:n] is unwritten
  1226  	m := 0
  1227  	var b byte
  1228  	for n, b = range data {
  1229  		if b == '\v' {
  1230  			b = '\t' // convert to htab
  1231  		}
  1232  		switch p.state {
  1233  		case inSpace:
  1234  			switch b {
  1235  			case '\t', ' ':
  1236  				p.space = append(p.space, b)
  1237  			case '\n', '\f':
  1238  				p.resetSpace() // discard trailing space
  1239  				_, err = p.output.Write(aNewline)
  1240  			case tabwriter.Escape:
  1241  				_, err = p.output.Write(p.space)
  1242  				p.state = inEscape
  1243  				m = n + 1 // +1: skip tabwriter.Escape
  1244  			default:
  1245  				_, err = p.output.Write(p.space)
  1246  				p.state = inText
  1247  				m = n
  1248  			}
  1249  		case inEscape:
  1250  			if b == tabwriter.Escape {
  1251  				_, err = p.output.Write(data[m:n])
  1252  				p.resetSpace()
  1253  			}
  1254  		case inText:
  1255  			switch b {
  1256  			case '\t', ' ':
  1257  				_, err = p.output.Write(data[m:n])
  1258  				p.resetSpace()
  1259  				p.space = append(p.space, b)
  1260  			case '\n', '\f':
  1261  				_, err = p.output.Write(data[m:n])
  1262  				p.resetSpace()
  1263  				if err == nil {
  1264  					_, err = p.output.Write(aNewline)
  1265  				}
  1266  			case tabwriter.Escape:
  1267  				_, err = p.output.Write(data[m:n])
  1268  				p.state = inEscape
  1269  				m = n + 1 // +1: skip tabwriter.Escape
  1270  			}
  1271  		default:
  1272  			panic("unreachable")
  1273  		}
  1274  		if err != nil {
  1275  			return
  1276  		}
  1277  	}
  1278  	n = len(data)
  1279  
  1280  	switch p.state {
  1281  	case inEscape, inText:
  1282  		_, err = p.output.Write(data[m:n])
  1283  		p.resetSpace()
  1284  	}
  1285  
  1286  	return
  1287  }
  1288  
  1289  // ----------------------------------------------------------------------------
  1290  // Public interface
  1291  
  1292  // A Mode value is a set of flags (or 0). They control printing.
  1293  type Mode uint
  1294  
  1295  const (
  1296  	RawFormat Mode = 1 << iota // do not use a tabwriter; if set, UseSpaces is ignored
  1297  	TabIndent                  // use tabs for indentation independent of UseSpaces
  1298  	UseSpaces                  // use spaces instead of tabs for alignment
  1299  	SourcePos                  // emit //line directives to preserve original source positions
  1300  )
  1301  
  1302  // The mode below is not included in printer's public API because
  1303  // editing code text is deemed out of scope. Because this mode is
  1304  // unexported, it's also possible to modify or remove it based on
  1305  // the evolving needs of go/format and cmd/gofmt without breaking
  1306  // users. See discussion in CL 240683.
  1307  const (
  1308  	// normalizeNumbers means to canonicalize number
  1309  	// literal prefixes and exponents while printing.
  1310  	//
  1311  	// This value is known in and used by go/format and cmd/gofmt.
  1312  	// It is currently more convenient and performant for those
  1313  	// packages to apply number normalization during printing,
  1314  	// rather than by modifying the AST in advance.
  1315  	normalizeNumbers Mode = 1 << 30
  1316  )
  1317  
  1318  // A Config node controls the output of Fprint.
  1319  type Config struct {
  1320  	Mode     Mode // default: 0
  1321  	Tabwidth int  // default: 8
  1322  	Indent   int  // default: 0 (all code is indented at least by this much)
  1323  }
  1324  
  1325  var printerPool = sync.Pool{
  1326  	New: func() any {
  1327  		return &printer{
  1328  			// Whitespace sequences are short.
  1329  			wsbuf: make([]whiteSpace, 0, 16),
  1330  			// We start the printer with a 16K output buffer, which is currently
  1331  			// larger than about 80% of Go files in the standard library.
  1332  			output: make([]byte, 0, 16<<10),
  1333  		}
  1334  	},
  1335  }
  1336  
  1337  func newPrinter(cfg *Config, fset *token.FileSet, nodeSizes map[ast.Node]int) *printer {
  1338  	p := printerPool.Get().(*printer)
  1339  	*p = printer{
  1340  		Config:    *cfg,
  1341  		fset:      fset,
  1342  		pos:       token.Position{Line: 1, Column: 1},
  1343  		out:       token.Position{Line: 1, Column: 1},
  1344  		wsbuf:     p.wsbuf[:0],
  1345  		nodeSizes: nodeSizes,
  1346  		cachedPos: -1,
  1347  		output:    p.output[:0],
  1348  	}
  1349  	return p
  1350  }
  1351  
  1352  func (p *printer) free() {
  1353  	// Hard limit on buffer size; see https://golang.org/issue/23199.
  1354  	if cap(p.output) > 64<<10 {
  1355  		return
  1356  	}
  1357  
  1358  	printerPool.Put(p)
  1359  }
  1360  
  1361  // fprint implements Fprint and takes a nodesSizes map for setting up the printer state.
  1362  func (cfg *Config) fprint(output io.Writer, fset *token.FileSet, node any, nodeSizes map[ast.Node]int) (err error) {
  1363  	// print node
  1364  	p := newPrinter(cfg, fset, nodeSizes)
  1365  	defer p.free()
  1366  	if err = p.printNode(node); err != nil {
  1367  		return
  1368  	}
  1369  	// print outstanding comments
  1370  	p.impliedSemi = false // EOF acts like a newline
  1371  	p.flush(token.Position{Offset: infinity, Line: infinity}, token.EOF)
  1372  
  1373  	// output is buffered in p.output now.
  1374  	// fix //go:build and // +build comments if needed.
  1375  	p.fixGoBuildLines()
  1376  
  1377  	// redirect output through a trimmer to eliminate trailing whitespace
  1378  	// (Input to a tabwriter must be untrimmed since trailing tabs provide
  1379  	// formatting information. The tabwriter could provide trimming
  1380  	// functionality but no tabwriter is used when RawFormat is set.)
  1381  	output = &trimmer{output: output}
  1382  
  1383  	// redirect output through a tabwriter if necessary
  1384  	if cfg.Mode&RawFormat == 0 {
  1385  		minwidth := cfg.Tabwidth
  1386  
  1387  		padchar := byte('\t')
  1388  		if cfg.Mode&UseSpaces != 0 {
  1389  			padchar = ' '
  1390  		}
  1391  
  1392  		twmode := tabwriter.DiscardEmptyColumns
  1393  		if cfg.Mode&TabIndent != 0 {
  1394  			minwidth = 0
  1395  			twmode |= tabwriter.TabIndent
  1396  		}
  1397  
  1398  		output = tabwriter.NewWriter(output, minwidth, cfg.Tabwidth, 1, padchar, twmode)
  1399  	}
  1400  
  1401  	// write printer result via tabwriter/trimmer to output
  1402  	if _, err = output.Write(p.output); err != nil {
  1403  		return
  1404  	}
  1405  
  1406  	// flush tabwriter, if any
  1407  	if tw, _ := output.(*tabwriter.Writer); tw != nil {
  1408  		err = tw.Flush()
  1409  	}
  1410  
  1411  	return
  1412  }
  1413  
  1414  // A CommentedNode bundles an AST node and corresponding comments.
  1415  // It may be provided as argument to any of the [Fprint] functions.
  1416  type CommentedNode struct {
  1417  	Node     any // *ast.File, or ast.Expr, ast.Decl, ast.Spec, or ast.Stmt
  1418  	Comments []*ast.CommentGroup
  1419  }
  1420  
  1421  // Fprint "pretty-prints" an AST node to output for a given configuration cfg.
  1422  // Position information is interpreted relative to the file set fset.
  1423  // The node type must be *[ast.File], *[CommentedNode], [][ast.Decl], [][ast.Stmt],
  1424  // or assignment-compatible to [ast.Expr], [ast.Decl], [ast.Spec], or [ast.Stmt].
  1425  func (cfg *Config) Fprint(output io.Writer, fset *token.FileSet, node any) error {
  1426  	return cfg.fprint(output, fset, node, make(map[ast.Node]int))
  1427  }
  1428  
  1429  // Fprint "pretty-prints" an AST node to output.
  1430  // It calls [Config.Fprint] with default settings.
  1431  // Note that gofmt uses tabs for indentation but spaces for alignment;
  1432  // use format.Node (package go/format) for output that matches gofmt.
  1433  func Fprint(output io.Writer, fset *token.FileSet, node any) error {
  1434  	return (&Config{Tabwidth: 8}).Fprint(output, fset, node)
  1435  }
  1436  

View as plain text