msg

README

msg

🚀 A lightweight terminal printing toolkit for Go CLIs.

Project Description

Who else is bored with boring grey text in CLIs? 🙋🏻‍♂️

We all have fancy terminals, utf-8 is everywhere, no one is still using the stock windows command prompt any more... are they? 🤨

msg is a tiny toolkit to make rendering beautiful looking output from CLIs as easy as possible in Go.

It's so easy, you already know how it works!

Installation

go get github.com/FollowTheProcess/msg@latest

Quickstart

The demo screenshot at the top of the page will get you:

Not bad! 🚀

User Guide

msg has 5 message types:

• Title - Section header for a block of output
• Info - General info, status updates etc.
• Success - Your CLI has successfully done something
• Warn - Warn the user about something e.g. ignoring hidden files
• Error - Something has gone wrong in your application

All have a single trailing newline automatically applied except Title which has 1 leading and 2 trailing newlines to create separation.

msg.Error("My error message, underlying error: %v", err) // Newlines are handled for you

// i.e. you don't need to do this
msg.Error("My error message, underlying error: %v\n", err)

// Titles are effectively "\n{your title}\n\n"
msg.Title("My title") // Is enough to get separation in sections of output

Stdout/Stderr

By default, every function in msg prints to os.Stdout with the exception of msg.Error which prints to os.Stderr.

msg also exports "F-style" print functions which can write to any io.Writer e.g:

buf := &bytes.Buffer{} // is an io.Writer

msg.Ferror(buf, "My error message")

Credits

This package was created with copier and the FollowTheProcess/go_copier project template.

Documentation

Overview

Package msg is a simple, easy to use, opinionated console printing toolkit for Go CLIs rendering pretty formatted output with colours specific to the particular message type:

• Info: For general user information and progress updates
• Title: Separation between sections of output
• Warn: User warnings
• Success: Report success
• Error: Report failure

All message types default to stdout other than the `Error` type which prints to stderr by default.

There are also "F-style" print methods that allow you to specify an io.Writer to print the messages to.

Index

• func ColorEnabled(v bool)
• func Err(err error)
• func Error(format string, a ...any)
• func Ferr(w io.Writer, err error)
• func Ferror(w io.Writer, format string, a ...any)
• func Finfo(w io.Writer, format string, a ...any)
• func Fsuccess(w io.Writer, format string, a ...any)
• func Ftitle(w io.Writer, format string, a ...any)
• func Fwarn(w io.Writer, format string, a ...any)
• func Info(format string, a ...any)
• func Success(format string, a ...any)
• func Title(format string, a ...any)
• func Warn(format string, a ...any)

Functions

func ColorEnabled

func ColorEnabled(v bool)

ColorEnabled sets whether the output from this package is colourised.

msg defaults to automatic detection based on a number of attributes:

• The value of $NO_COLOR and/or $FORCE_COLOR
• The value of $TERM (xterm enables colour)
• Whether os.Stdout is pointing to a terminal

This means that msg should do a reasonable job of auto-detecting when to colourise output and should not write escape sequences when piping between processes or when writing to files etc.

This function may be called to bypass the above detection and explicitly set the value, useful in CLI applications where a --no-color flag might be expected.

ColorEnabled may be called safely from concurrently executing goroutines.

func Err

func Err(err error)

Err prints a nicely formatted error message from an actual error to os.Stderr, bypassing the need for the caller to construct the format string.

err := errors.New("Uh oh!")
msg.Err(err) // Equivalent to msg.Error("%v", err)

In the case of wrapped errors with fmt.Errorf, Err recursively unwraps the error, showing each of the errors in the causal chain in a tree-like structure.

root := errors.New("some deep error")
wrapped := fmt.Errorf("could not process file: %w", root)
again := fmt.Errorf("failed to do thing: %w", wrapped)
msg.Err(again) // Unwraps the above and shows each cause as a new indented line

The intended use case for Err is at the top level of a CLI application where all errors are eventually bubbled up to with the appropriate context, which Err can then show to end users in a very clear, concise way.

func Error

func Error(format string, a ...any)

Error prints an error message with optional format args to stderr.

msg.Error("Invalid config")
msg.Error("Could not find file: %s", "missing.txt")

func Ferr

func Ferr(w io.Writer, err error)

Ferr prints a nicely formatted error message from an actual error to w, bypassing the need for the caller to construct the format string.

err := errors.New("Uh oh!")
msg.Ferr(os.Stderr, err) // Equivalent to msg.Err(err)

In the case of wrapped errors with fmt.Errorf, Ferr recursively unwraps the error, showing each of the errors in the causal chain in a tree-like structure.

root := errors.New("some deep error")
wrapped := fmt.Errorf("could not process file: %w", root)
again := fmt.Errorf("failed to do thing: %w", wrapped)
msg.Ferr(os.Stderr, again) // Unwraps the above and shows each cause as a new indented line

The intended use case for Ferr and Err is at the top level of a CLI application where all errors are eventually bubbled up to with the appropriate context, which can then be shown to end users in a very clear, concise way.

func Ferror

func Ferror(w io.Writer, format string, a ...any)

Ferror prints an error message with optional format args to w.

msg.Ferror(os.Stderr, "Uh oh! %s", "something wrong")

func Finfo

func Finfo(w io.Writer, format string, a ...any)

Finfo prints an info message with optional format args to w.

msg.Finfo(os.Stdout, "The meaning of life is %v", 42)

func Fsuccess

func Fsuccess(w io.Writer, format string, a ...any)

Fsuccess prints a success message with optional format args to w.

msg.Fsuccess(os.Stdout, "Compiled project: %s", "msg")

func Ftitle

func Ftitle(w io.Writer, format string, a ...any)

Ftitle prints a title message to w.

A title message differs from every other message type in msg as it has 1 leading newline and 2 trailing newlines to create separation between the sections it is differentiating in your CLI.

msg.Ftitle(os.Stdout, "Some section")

func Fwarn

func Fwarn(w io.Writer, format string, a ...any)

Fwarn prints a warning message with optional format args to w.

msg.Fwarn(os.Stderr, "hmmmm: %v", true)

func Info

func Info(format string, a ...any)

Info prints an info message with optional format args to stdout.

msg.Info("You have %d repos on GitHub", 42)

func Success

func Success(format string, a ...any)

Success prints a success message with optional format args to stdout.

msg.Success("Compiled project: %s", "msg")

func Title

func Title(format string, a ...any)

Title prints a title message to stdout.

A title message differs from every other message type in msg as it has 1 leading newline and 2 trailing newlines to create separation between the sections it is differentiating in your CLI.

msg.Title("Some section")

func Warn

func Warn(format string, a ...any)

Warn prints a warning message with optional format args to stdout.

msg.Warn("Skipping %s, directory is empty", "some/empty/dir")