rfmt

README

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)).

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.

Documentation

Index

• func EscapeBytes(s []byte) m.RedactableBytes
• func Fprint(w io.Writer, a ...interface{}) (n int, err error)
• func Fprintf(w io.Writer, format string, a ...interface{}) (n int, err error)
• func Fprintln(w io.Writer, a ...interface{}) (n int, err error)
• func HelperForErrorf(format string, args ...interface{}) (m.RedactableString, error)
• func Print(a ...interface{}) (n int, err error)
• func Printf(format string, a ...interface{}) (n int, err error)
• func Println(a ...interface{}) (n int, err error)
• func RegisterRedactErrorFn(fn func(err error, p i.SafePrinter, verb rune))
• func RegisterSafeType(t reflect.Type)
• func Sprint(a ...interface{}) m.RedactableString
• func Sprintf(format string, a ...interface{}) m.RedactableString
• func Sprintfn(printer func(w i.SafePrinter)) m.RedactableString
• func Sprintln(a ...interface{}) m.RedactableString
• type Formatter
• type GoStringer
• type State
• type Stringer

Functions

func EscapeBytes

func EscapeBytes(s []byte) m.RedactableBytes

EscapeBytes escapes markers inside the given byte slice and encloses the entire byte slice between redaction markers. EscapeBytes escapes markers inside the given byte slice and encloses the entire byte slice between redaction markers.

func Fprint

func Fprint(w io.Writer, a ...interface{}) (n int, err error)

Fprint formats using the default formats for its operands and writes to w. Spaces are added between operands when neither is a string. It returns the number of bytes written and any write error encountered.

func Fprintf

func Fprintf(w io.Writer, format string, a ...interface{}) (n int, err error)

Fprintf formats according to a format specifier and writes to w. It returns the number of bytes written and any write error encountered.

func Fprintln

func Fprintln(w io.Writer, a ...interface{}) (n int, err error)

Fprintln formats using the default formats for its operands and writes to w. Spaces are always added between operands and a newline is appended. It returns the number of bytes written and any write error encountered.

func HelperForErrorf

func HelperForErrorf(format string, args ...interface{}) (m.RedactableString, error)

HelperForErrorf is a helper to implement a redaction-aware fmt.Errorf-compatible function in a different package. It formats the string according to the given format and arguments in the same way as Sprintf, but in addition to this if the format contains %w and an error object in the proper argument position it also returns that error object.

Note: This function only works if an error redaction function has been injected with RegisterRedactErrorFn().

func Print

func Print(a ...interface{}) (n int, err error)

Print formats using the default formats for its operands and writes to standard output. Spaces are added between operands when neither is a string. It returns the number of bytes written and any write error encountered.

func Printf

func Printf(format string, a ...interface{}) (n int, err error)

Printf formats according to a format specifier and writes to standard output. It returns the number of bytes written and any write error encountered.

func Println

func Println(a ...interface{}) (n int, err error)

Println formats using the default formats for its operands and writes to standard output. Spaces are always added between operands and a newline is appended. It returns the number of bytes written and any write error encountered.

func RegisterRedactErrorFn

func RegisterRedactErrorFn(fn func(err error, p i.SafePrinter, verb rune))

RegisterRedactErrorFn registers an error redaction function for use during automatic redaction by this package. Provided e.g. by cockroachdb/errors.

func RegisterSafeType

func RegisterSafeType(t reflect.Type)

RegisterSafeType registers a data type to always be considered safe during the production of redactable strings.

func Sprint

func Sprint(a ...interface{}) m.RedactableString

Sprint formats using the default formats for its operands and returns the resulting string. Spaces are added between operands when neither is a string.

func Sprintf

func Sprintf(format string, a ...interface{}) m.RedactableString

Sprintf formats according to a format specifier and returns the resulting string.

func Sprintfn

func Sprintfn(printer func(w i.SafePrinter)) m.RedactableString

Sprintfn produces a RedactableString using the provided SafeFormat-alike function.

func Sprintln

func Sprintln(a ...interface{}) m.RedactableString

Sprintln formats using the default formats for its operands and returns the resulting string. Spaces are always added between operands and a newline is appended.

Types

type Formatter

type Formatter interface {
	// CUSTOM: refer to the original type, not the one defined here.
	Format(f origFmt.State, verb rune)
}

Formatter is implemented by any value that has a Format method. The implementation controls how State and rune are interpreted, and may call Sprint(f) or Fprint(f) etc. to generate its output.

type GoStringer

type GoStringer interface {
	GoString() string
}

GoStringer is implemented by any value that has a GoString method, which defines the Go syntax for that value. The GoString method is used to print values passed as an operand to a %#v format.

type State

type State interface {
	// Write is the function to call to emit formatted output to be printed.
	Write(b []byte) (n int, err error)
	// Width returns the value of the width option and whether it has been set.
	Width() (wid int, ok bool)
	// Precision returns the value of the precision option and whether it has been set.
	Precision() (prec int, ok bool)

	// Flag reports whether the flag c, a character, has been set.
	Flag(c int) bool
}

State represents the printer state passed to custom formatters. It provides access to the io.Writer interface plus information about the flags and options for the operand's format specifier.

type Stringer

type Stringer interface {
	String() string
}

Stringer is implemented by any value that has a String method, which defines the “native” format for that value. The String method is used to print values passed as an operand to any format that accepts a string or to an unformatted printer such as Print.