Initial commit

vendor/github.com/cockroachdb/redact/internal/README.md

@@ -0,0 +1,52 @@
+Overall code structure
+======================
+
+This directory imports the "printf" logic as-is from the Go standard
+library and instruments it for redaction of sensitive data.
+
+Overall, the original Go code is structured as follows:
+
+- the top-level API functions (`Printf` `Fprintf` etc) instantiate a
+  "printer" struct called `pp`, then call the `doPrint*()` methods
+  on it.
+
+- the `pp` contains a byte slice (`pp.buf`, type `buffer`) that
+  accumulates the result of formatting *regardless of the final output
+  of the API* - i.e. a buffer is used even when using `Fprint` to an
+  `io.Writer`. Only after the `doPrint()` method finishes, is the
+  `buffer` copied to the final `io.Writer` in the `Fprint*` variants.
+
+- each of the `doPrint` methods does some analysis on the argument
+  list - quite simple for e.g. `doPrintln`, more intricate for
+  `doPrintf`.  As part of the analysis it emits "spacing" or no-op
+  bytes directly on the `pp.buf`. For example `doPrint` emits spaces
+  between arguments directly, `doPrintf` emits the non-formatting
+  characters from the format string, as well as certain *constant*
+  error strings (e.g. `%(BADPREC)`).
+
+At this point **we make the following assumption**: there is no data
+from the printed *arguments* that is emitted to `pp.buf` directly by a
+`doPrint()` method. This is true of the implementation as of Go 1.14.
+
+From this point, this package contains a *custom patch* onto the
+default implementation: the calls to `p.printArg` performed by the
+`doPrint()` methods are redirected to a function callback that is
+injected by the `redact` package.
+
+Refreshing the sources
+======================
+
+The files in this directory have been imported from
+
+`$GOROOT/src/fmt/{format,print}.go`
+
+and
+
+`$GOROOT/src/internal/fmtsort`
+
+And patched using the included `.diff` files.
+
+To upgrade to a newer Go implementation, import the files anew and
+re-apply the patches.
+
+See the script `refresh.sh` for details.