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 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 Err

func Err(err error)

Err is a convenience wrapper around Error allowing passing an error directly without the need for the %v format verb.

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

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 is a convenience wrapper around Ferror allowing passing an error directly without the new for the %v format verb.

It is the 'F' equivalent of Err, taking an io.Writer to print the error to.

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

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