go/printer: implement SourcePos mode
If a printer is configured with the SourcePos mode
set, it will emit //-line comments as necessary to
ensure that the result - if reparsed - reflects the
original source position information.
This change required a bit of reworking of the
output section in printer.go. Specifically:
- Introduced new Config mode 'SourcePos'.
- Introduced new position 'out' which tracks the
position of the generated output if it were read
in again. If there is a discrepancy between out
and the current AST/source position, a //line
comment is emitted to correct for it.
- Lazy emission of indentation so that //line
comments can be placed correctly. As a result,
the trimmer will have to do less work.
- Merged writeItem into writeString.
- Merged writeByteN into writeByte.
- Use a []byte instead of a byte.Buffer both in the
printer and in the trimmer (eliminates dependency).
Also: introduced explicit printer.Mode type (in
sync w/ parser.Mode, scanner.Mode, etc.)
Runs all tests. Applied gofmt to src, misc w/o changes.
Fixes #1047.
Fixes #2697.
R=rsc, rsc
CC=golang-dev
https://golang.org/cl/5643066
diff --git a/doc/go1.html b/doc/go1.html
index c864391..fce1c07 100644
--- a/doc/go1.html
+++ b/doc/go1.html
@@ -1050,6 +1050,15 @@
</p>
<p>
+A concrete <code>Mode</code> type was introduced for configuration mode flags
+in the packages
+<a href="/pkg/go/scanner/"><code>go/scanner</code></a>,
+<a href="/pkg/go/parser/"><code>go/parser</code></a>,
+<a href="/pkg/go/printer/"><code>go/printer</code></a>, and
+<a href="/pkg/go/doc/"><code>go/doc</code></a>.
+</p>
+
+<p>
The modes <code>AllowIllegalChars</code> and <code>InsertSemis</code> have been removed
from the <a href="/pkg/go/scanner/"><code>go/scanner</code></a> package. They were mostly
useful for scanning text other then Go source files. Instead, the
@@ -1076,6 +1085,17 @@
</p>
<p>
+The <a href="/pkg/go/printer/"><code>go/printer</code></a> package supports an additional
+configuration mode <a href="/pkg/go/printer/#Mode"><code>SourcePos</code></a>;
+if set, the printer will emit <code>//line</code> comments such that the generated
+output contains the original source code position information. The new type
+<a href="/pkg/go/printer/#CommentedNode"><code>CommentedNode</code></a> can be
+used to provide comments associated with an arbitrary
+<a href="/pkg/go/ast/#Node"><code>ast.Node</code></a> (until now only
+<a href="/pkg/go/ast/#File"><code>ast.File</code></a> carried comment information).
+</p>
+
+<p>
The type names of the <a href="/pkg/go/doc/"><code>go/doc</code></a> package have been
streamlined by removing the <code>Doc</code> suffix: <code>PackageDoc</code>
is now <code>Package</code>, <code>ValueDoc</code> is <code>Value</code>, etc.
