report

Documentation

Overview

Package report provides helper structs/methods/funcs for formatting output

Examples

To format output for an array of structs:

ExamplePodman:

headers := report.Headers(struct {
	ID string
}{}, nil)

f := report.New(os.Stdout, "Command Name")
f, _ := f.Parse(report.OriginPodman, "{{range .}}{{.ID}}{{end}}")
defer f.Flush()

if f.RenderHeaders {
	f.Execute(headers)
}
f.Execute( map[string]string{
	"ID":"fa85da03b40141899f3af3de6d27852b",
})

// Output:
// ID
// fa85da03b40141899f3af3de6d27852b

ExampleUser:

headers := report.Headers(struct {
	CID string
}{}, map[string]string{"CID":"ID"})

f, _ := report.New(os.Stdout, "Command Name").Parse(report.OriginUser, "table {{.CID}}")
defer f.Flush()

if f.RenderHeaders {
	t.Execute(t, headers)
}
t.Execute(t,map[string]string{
	"CID":"fa85da03b40141899f3af3de6d27852b",
})

// Output:
// ID
// fa85da03b40141899f3af3de6d27852b

Helpers:

if report.IsJSON(cmd.Flag("format").Value.String()) {
	... process JSON and output
}

if report.HasTable(cmd.Flag("format").Value.String()) {
	... "table" keyword prefix in format text
}

Template Functions

The following template functions are added to the template when parsed:

• join strings.Join, {{join .Field separator}}
• json encode field as JSON {{ json .Field }}
• lower strings.ToLower {{ .Field | lower }}
• pad add spaces as prefix and suffix {{ pad . 2 2 }}
• split strings.Split {{ .Field | split }}
• title strings.Title {{ .Field | title }}
• truncate limit field length {{ truncate . 10 }}
• upper strings.ToUpper {{ .Field | upper }}

report.Funcs() may be used to add additional template functions. Adding an existing function will replace that function for the life of that template.

Note: Your code should not ignore errors

Index

• Variables
• func EnforceRange(format string) string
• func HasTable(format string) bool
• func Headers(object any, overrides map[string]string) []map[string]string
• func IsJSON(s string) bool
• func NormalizeFormat(format string) string
• type Flusher
• type Formatter
  • func New(output io.Writer, name string) *Formatter
  • func (f *Formatter) Execute(data any) error
  • func (f *Formatter) Flush() error
  • func (f *Formatter) Funcs(funcMap template.FuncMap) *Formatter
  • func (f *Formatter) Init(w io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Formatter
  • func (f *Formatter) Parse(origin Origin, text string) (*Formatter, error)
  • func (f *Formatter) Writer() io.Writer
• type FuncMap
• type NopFlusher
  • func (f *NopFlusher) Flush() (err error)
• type Origin
  • func (o Origin) String() string
• type Template
  • func NewTemplate(name string) *Template
  • func (t *Template) Funcs(funcMap FuncMap) *Template
  • func (t *Template) IsTable() bool
  • func (t *Template) Parse(text string) (*Template, error)
• type Writer
  • func NewWriter(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) (*Writer, error)
  • func NewWriterDefault(output io.Writer) (*Writer, error)
  • func (w *Writer) Flush() error

Variables

var DefaultFuncs = FuncMap{
	"join": strings.Join,
	"json": func(v any) string {
		buf := new(bytes.Buffer)
		enc := json.NewEncoder(buf)
		enc.SetEscapeHTML(false)
		_ = enc.Encode(v)

		return strings.TrimSpace(buf.String())
	},
	"lower":    strings.ToLower,
	"pad":      padWithSpace,
	"split":    strings.Split,
	"title":    strings.Title,
	"truncate": truncateWithLength,
	"upper":    strings.ToUpper,
}

Functions

func EnforceRange

func EnforceRange(format string) string

EnforceRange ensures that the format string contains a range

func HasTable

func HasTable(format string) bool

HasTable returns whether the format is a table

func Headers

func Headers(object any, overrides map[string]string) []map[string]string

Headers queries the interface for field names. Array of map is returned to support range templates Note: unexported fields can be supported by adding field to overrides Note: It is left to the developer to write out said headers

Podman commands use the general rules of:
1) unchanged --format includes headers
2) --format '{{.ID}"        # no headers
3) --format 'table {{.ID}}' # includes headers

func IsJSON

func IsJSON(s string) bool

JSONFormat test CLI --format string to be a JSON request

if report.IsJSON(cmd.Flag("format").Value.String()) {
  ... process JSON and output
}

func NormalizeFormat

func NormalizeFormat(format string) string

NormalizeFormat reads given go template format provided by CLI and munges it into what we need

Types

type Flusher

type Flusher interface {
	Flush() error
}

Flusher is the interface that wraps the Flush method.

type Formatter

type Formatter struct {
	Origin        Origin // Source of go template. OriginUser or OriginPodman
	RenderHeaders bool   // Hint, default behavior for given template is to include headers
	RenderTable   bool   // Does template have "table" keyword
	// contains filtered or unexported fields
}

Formatter holds the configured Writer and parsed Template, additional state fields are maintained to assist in the podman command report writing.

func New

func New(output io.Writer, name string) *Formatter

New allocates a new, undefined Formatter with the given name and Writer

func (*Formatter) Execute

func (f *Formatter) Execute(data any) error

Execute applies a parsed template to the specified data object, and writes the output to Formatter.Writer.

func (*Formatter) Flush

func (f *Formatter) Flush() error

Flush should be called after the last call to Write to ensure that any data buffered in the Formatter is written to output. Any incomplete escape sequence at the end is considered complete for formatting purposes.

func (*Formatter) Funcs

func (f *Formatter) Funcs(funcMap template.FuncMap) *Formatter

Funcs adds the elements of the argument map to the template's function map. A default template function will be replaced if there is a key collision.

func (*Formatter) Init

func (f *Formatter) Init(w io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) *Formatter

Init either resets the given tabwriter with new values or wraps w in tabwriter with given values

func (*Formatter) Parse

func (f *Formatter) Parse(origin Origin, text string) (*Formatter, error)

Parse parses golang template returning a formatter

• OriginPodman implies text is a template from podman code. Output will be filtered through a tabwriter.

• OriginUser implies text is a template from a user. If template includes keyword "table" output will be filtered through a tabwriter.

func (*Formatter) Writer

func (f *Formatter) Writer() io.Writer

Writer returns the embedded io.Writer from Formatter

type FuncMap

type FuncMap template.FuncMap

FuncMap is aliased from template.FuncMap

type NopFlusher

type NopFlusher struct{}

NopFlusher represents a type which flush operation is nop.

func (*NopFlusher) Flush

func (f *NopFlusher) Flush() (err error)

Flush is a nop operation.

type Origin

type Origin int

const (
	OriginUnknown Origin = iota
	OriginPodman
	OriginUser
)

func (Origin) String

func (o Origin) String() string

type Template

type Template struct {
	*template.Template
	// contains filtered or unexported fields
}

Template embeds template.Template to add functionality to methods

func NewTemplate

func NewTemplate(name string) *Template

NewTemplate creates a new template object

func (*Template) Funcs

func (t *Template) Funcs(funcMap FuncMap) *Template

Funcs adds the elements of the argument map to the template's function map. A default template function will be replace if there is a key collision.

func (*Template) IsTable

func (t *Template) IsTable() bool

IsTable returns true if format string defines a "table"

func (*Template) Parse

func (t *Template) Parse(text string) (*Template, error)

Parse parses text as a template body for t

type Writer

type Writer struct {
	*tabwriter.Writer
}

Writer aliases tabwriter.Writer to provide Podman defaults

func NewWriter

func NewWriter(output io.Writer, minwidth, tabwidth, padding int, padchar byte, flags uint) (*Writer, error)

NewWriter initializes a new report.Writer with given values

func NewWriterDefault

func NewWriterDefault(output io.Writer) (*Writer, error)

NewWriterDefault initializes a new report.Writer with Podman defaults

func (*Writer) Flush

func (w *Writer) Flush() error

Flush any output left in buffers