polyfmt

README

Polyfmt

A convenience package that provides multiple forms of formatted output. Useful for CLI applications where you might want to provide JSON output for machine users, but pretty output for interactive users.

Why

In a command line application you usually want to provide some well-formatted output to users. This may include progress bars, timers, spinners, or tables so that interactive users can better parse your programs output. For non-interactive users or automation this might make your CLI application difficult to parse, build automation around, or just unnecessarily verbose. To this end, you might want to provide a common serialization format to users who use your CLI app from within a non-interactive environment.

Polyfmt aims to simplify the API around multiple formatting options and make it easy to switch between them.

Usage

Polyfmt provides a very simple API, full of print functions.

Initiate a new formatter instance, passing in what type of formatter you want back. This is usually passed in by your user at runtime via flags or config.

pfmt, _ := polyfmt.NewFormatter(polyfmt.JSON, polyfmt.DefaultOptions())
defer pfmt.Finish() // Finish flushes the output and cleans up safely.

Use the returned formatter to print a simple json formatted hello.

pfmt.Println("hello")
// Output:
// {"label":"info","data": "hello"}

You can also pass the printer any interface and it will attempt to print it (providing that it is printable).

pfmt.Println(struct {
    Test string `json:"test"`
}{
    Test: "Some text",
})
// Output:
// {"label":"info","data":{"test":"Some text"}}

Sometimes you'll want to output something only for specific formatters. Most commands take a list of formatters, which tells the command to only print for those formatters.

pfmt.Println("hello", Pretty)
// Output:
//

Additional Details

You can turn off color by using the popular NO_COLOR environment variable.

Documentation

Overview

Package polyfmt is a convenience package that provides multiple forms of formatted output. Useful for CLI applications where you might want to provide JSON output for machine users, but pretty output for interactive users.

Why

In a command line application you usually want to provide some well-formatted output to users. This may include progress bars, timers, spinners, or tables so that interactive users can better parse your programs output. For non-interactive users or automation this might make your CLI application difficult to parse, build automation around, or just unnecessarily verbose. To this end, you might want to provide a common serialization format to users who use your CLI app from within a non-interactive environment.

Polyfmt aims to simplify the API around multiple formatting options and make it easy to switch between them.

Usage

Polyfmt provides a very simple API, full of print functions.

Initiate a new formatter instance, passing in what type of formatter you want back. This is usually passed in by your user at runtime via flags or config.

pfmt, _ := polyfmt.NewFormatter(JSON, false)
defer pfmt.Finish() // Finish flushes the output and cleans up safely.

Use the returned formatter to print a simple json formatted hello.

pfmt.Println("hello")
// Output:
// {"label":"info","data":"hello"}

You can also pass the printer any interface and it will attempt to print it (providing that it is printable).

pfmt.Println(struct {
    Test string `json:"test"`
}{
    Test: "Some text",
})
// Output:
// {"label":"info","data":{"test":"Some text"}}

Sometimes you'll want to output something only for specific formatters. Most commands take a list of formatters, which tells the command to only print for those formatters.

pfmt.Println("hello", Pretty)
// Output:
//

Additional Details

You can turn off color by using the popular `NO_COLOR` environment variable.

Index

• type Formatter
  • func NewFormatter(mode Mode, options Options) (Formatter, error)
• type Mode
• type Options
  • func DefaultOptions() Options

Examples

• NewFormatter

Types

type Formatter

type Formatter interface {
	// Print will attempt to intelligently print objects passed to it.
	// Adding modes to the filter restricts the object being printed only
	// to those modes.
	Print(msg any, filter ...Mode)

	// Println prints the message adding a newline to the end.
	// Adding modes to the filter restricts the object being printed only
	// to those modes.
	Println(msg any, filter ...Mode)

	// Err prints the message noting it as an error to the user.
	// Adding modes to the filter restricts the object being printed only
	// to those modes.
	Err(msg any, filter ...Mode)

	// Success prints the message noting it as an error to the user.
	// Adding modes to the filter restricts the object being printed only
	// to those modes.
	Success(msg any, filter ...Mode)

	// Warning prints the message noting it as a warning to the user.
	// Adding modes to the filter restricts the object being printed only
	// to those modes.
	Warning(msg any, filter ...Mode)

	// Debugln prints a message only if debug is turned on in the formatter options.
	// Newline included.
	Debugln(msg any, filter ...Mode)

	// Question prints the message noting it as a question to the user.
	// It also collects user input using bufio.Scanner and returns it.
	//
	// Adding modes to the filter restricts the object being printed only
	// to those modes. This is especially important for this mode,
	// since even in JSON output it will stop and wait for user input.
	//
	// If filtered will return an empty string.
	Question(msg any, filter ...Mode) string

	// Cleans up and flushes any last bit of formatting.
	// Should be called as the before program exit.
	Finish()
}

func NewFormatter

func NewFormatter(mode Mode, options Options) (Formatter, error)

NewFormatter create a new formatter with the appropriate mode. if we detect that the output is being piped into a non-interactive context. (as in the case of piping to another command)

Example

// Invoke the JSON printer. This is usually supplied by the user
// at runtime. Ex. --json, --pretty, --silent
pfmt, _ := polyfmt.NewFormatter(polyfmt.JSON, polyfmt.DefaultOptions())
defer pfmt.Finish() // Finish flushes the output and cleans up safely.

// Prints a simple json formatted hello.
pfmt.Println("hello")

// Prints the data structure passed to it if it can be displayed.
pfmt.Println(struct {
	Test string `json:"test"`
}{
	Test: "Some text",
})

// Most commands also have the ability to not print under specific settings.
// This example prints hello ONLY if the "Pretty" mode is on, if any other mode
// is enabled it will be skipped.
pfmt.Println("hello", polyfmt.Pretty)

Output:

{"data":"hello","label":"info"}
{"data":{"test":"Some text"},"label":"info"}

type Mode

type Mode string

const (
	// Plain outputs text in a humanized fashion without spinners.
	Plain Mode = "plain"
	// Pretty outputs text in a more humanized fashion and provides spinners for longer actions.
	Pretty Mode = "pretty"
	// JSON outputs json formatted text, mainly suitable to be read by computers.
	JSON Mode = "json"
	// Dummy formatter that doesn't print anything
	Silent Mode = "silent"
)

type Options

type Options struct {
	// Allows the user to opt-in to the ability for polyfmt to detect non interactive terminals and
	// auto switch to JSON output. Default is false.
	AutoDetectTTY *bool

	// Turn on printing for debug lines
	Debug *bool
}

func DefaultOptions

func DefaultOptions() Options