README
¶
msg
🚀 A lightweight console printing toolkit for Go CLIs.
- Free software: MIT License
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? 🤨
When writing pytoil I discovered ines/wasabi for this exact purpose and absolutely loved it immediately:
- No dependencies outside the python stdlib
- Configurable if you want but the defaults look great
- Super easy to use and doesn't get in the way of what your CLI is trying to do
Then I started learning go and writing some CLIs I kept wishing I had it there too.
So here it is (mostly) 🎉
I did cheat on the "no dependencies" thing, full credit goes to fatih/color for handling all the difficult colouring stuff for me and to ines/wasabi for the API design.
Installation
To use msg in your code:
go get github.com/FollowTheProcess/msg@latest
Quickstart
The quickest way to get started is to use the top level functions that come pre-configured with colors and symbols:
package main
import "github.com/FollowTheProcess/msg"
func main() {
msg.Title("Your Title here")
// Do some stuff
// Give the user an update
msg.Info("Getting your files")
// Report success
msg.Good("It worked!")
// Uh oh, an error
msg.Fail("Oh no!, file not found")
// Warn a user about something
msg.Warn("This action is irreversible")
}
This will get you something that looks like this:
Not bad! 🚀
User Guide
msg has 5 types of output:
- Title - Section header for a block of output
- Info - General info, status updates etc.
- Good - To report successful completion of something
- Warn - Warn the user about something
- Fail - Tell the user there has been a failure of some kind
- Text - General purpose normal text
All of them have a single newline appended to the end except Title that has a newline before and 2 newlines after, to create separation both from the command you've just run, and from what follows after. You can see how the Your Title here is spaced in the example above.
Print Verbs
msg follow Go's lead when it comes to print verbs (think Printf, Sprintf, Fprintf etc.). As such, each of the 5 output types has these methods available (except they have weird names like Sinfof, but that's part of the fun.)
For example, let's take the Warn message which is the yellow one with the ⚠ above:
package main
import "github.com/FollowTheProcess/msg"
func main() {
// The "normal" one -> fmt.Println
msg.Warn("I'm a Warning")
// When you want to inject some variables -> fmt.Printf
// Note: you don't have to put the '\n' at the end, we do that for you
file := "msg.go"
msg.Warnf("File: %s not found", file)
// When you want the string back to use elsewhere -> fmt.Sprint
// this will strip any newlines and trailing/leading whitespace
s := msg.Swarn("I'm a Warning string")
// But I want a string AND formatting -> fmt.Sprintf
s := msg.Swarnf("Here's a warning string about: %s", file)
}
The functions that return strings have all whitespace and newlines trimmed before returning so you'll get back just the raw colored string (and the symbol if you have one, more on this later)
There is no Fwarnf though, that's because where msg writes to is configured as part of the Printer. More on that down here 👇
Configuration
You can get pretty far with just what we've seen up to now, especially if you agree with my choice of symbols and colors.
But I know that some of you want finer grained control than this. For you folks, you can instantiate your own Printer and have full control over the colors and symbols:
package main
import (
"os"
"github.com/FollowTheProcess/msg"
"github.com/fatih/color"
)
func main() {
// Defaults shown
printer := msg.Printer{
SymbolInfo: "ℹ",
SymbolTitle: "",
SymbolWarn: "⚠️",
SymbolFail: "✘",
SymbolGood: "✔",
// Any fg color from fatih/color will work here
ColorInfo: color.FgHiCyan,
ColorTitle: color.FgCyan,
ColorWarn: color.FgYellow,
ColorFail: color.FgRed,
ColorGood: color.FgGreen,
// Mainly used for testing but you can set it if you want
Out: os.Stdout,
}
// Now your printer is set up, just call the normal methods
// all the same methods are available
printer.Warn("Warning from my custom printer!")
}
But what if I change my mind half way through?
That's cool, all of the fields in Printer are exported so you can just change them whenever you want:
// Code above omitted
printer.Info("Old symbol")
// I want a different symbol for Info for this section only
printer.SymbolInfo = "🔎"
printer.Info("New symbol")
And you'll get:
That's about all there is really 🎉
I hope you enjoy it!
Contributing
Developing
msg is a very simple project and the goal of the project is to remain very simple in line with the good old unix philosophy:
Write programs that do one thing and do it well.
Ken Thompson
Contributions are very much welcomed but please keep this goal in mind 🎯
msg is run as a fairly standard Go project:
- We use all the standard go tools (go test, go build etc.)
- Linting is done with the help of golangci-lint (see docs for install help)
- Testing helpers provided by the excellent matryer/is package
We use just as the command runner (mainly because makefiles make me ill, but also because it's great!)
Collaborating
No hard and fast rules here but a few guidelines:
- Raise an issue before doing a load of work on a PR, saves everyone bother
- If you add a feature, be sure to add tests to cover what you've added
- If you fix a bug, add a test that would have caught the bug you just squashed
- Be nice 😃
Credits
This package was created with cookiecutter and the FollowTheProcess/go_cookie project template.
Documentation
¶
Index ¶
- func Fail(text string)
- func Failf(format string, a ...interface{})
- func Good(text string)
- func Goodf(format string, a ...interface{})
- func Info(text string)
- func Infof(format string, a ...interface{})
- func Sfail(text string) string
- func Sfailf(format string, a ...interface{}) string
- func Sgood(text string) string
- func Sgoodf(format string, a ...interface{}) string
- func Sinfo(text string) string
- func Sinfof(format string, a ...interface{}) string
- func Stext(text string) string
- func Stextf(format string, a ...interface{}) string
- func Stitle(text string) string
- func Stitlef(format string, a ...interface{}) string
- func Swarn(text string) string
- func Swarnf(format string, a ...interface{}) string
- func Text(text string)
- func Textf(format string, a ...interface{})
- func Title(text string)
- func Titlef(format string, a ...interface{})
- func Warn(text string)
- func Warnf(format string, a ...interface{})
- type Printer
- func (p *Printer) Fail(text string)
- func (p *Printer) Failf(format string, a ...interface{})
- func (p *Printer) Good(text string)
- func (p *Printer) Goodf(format string, a ...interface{})
- func (p *Printer) Info(text string)
- func (p *Printer) Infof(format string, a ...interface{})
- func (p *Printer) Sfail(text string) string
- func (p *Printer) Sfailf(format string, a ...interface{}) string
- func (p *Printer) Sgood(text string) string
- func (p *Printer) Sgoodf(format string, a ...interface{}) string
- func (p *Printer) Sinfo(text string) string
- func (p *Printer) Sinfof(format string, a ...interface{}) string
- func (p *Printer) Stext(text string) string
- func (p *Printer) Stextf(format string, a ...interface{}) string
- func (p *Printer) Stitle(text string) string
- func (p *Printer) Stitlef(format string, a ...interface{}) string
- func (p *Printer) Swarn(text string) string
- func (p *Printer) Swarnf(format string, a ...interface{}) string
- func (p *Printer) Text(text string)
- func (p *Printer) Textf(format string, a ...interface{})
- func (p *Printer) Title(text string)
- func (p *Printer) Titlef(format string, a ...interface{})
- func (p *Printer) Warn(text string)
- func (p *Printer) Warnf(format string, a ...interface{})
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Fail ¶
func Fail(text string)
Fail prints an error message using the default symbols and colors.
func Failf ¶
func Failf(format string, a ...interface{})
Failf prints a formatted error message using the default symbols and colors.
func Good ¶
func Good(text string)
Good prints a success message using the default symbols and colors.
func Goodf ¶
func Goodf(format string, a ...interface{})
Goodf prints a formatted success message using the default symbols and colors.
func Info ¶
func Info(text string)
Info prints an information message using the default symbols and colors.
func Infof ¶
func Infof(format string, a ...interface{})
Infof prints a formatted information message using the default symbols and colors.
func Textf ¶
func Textf(format string, a ...interface{})
Textf prints a formatted normal, uncoloured message.
func Title ¶
func Title(text string)
Title prints a Title message using the default symbols and colors
A Title is distinguishable from all other constructs in msg as it will has 1 newline before and 2 newlines after it.
func Titlef ¶
func Titlef(format string, a ...interface{})
Titlef prints a formatted Title message using the default symbols and colors.
Types ¶
type Printer ¶
type Printer struct {
Out io.Writer // Stdout
SymbolInfo string // Symbol for the Info output
SymbolTitle string // Symbol for the Title output
SymbolWarn string // Symbol for the Warn output
SymbolFail string // Symbol for the Fail output
SymbolGood string // Symbol for the Good output
ColorInfo color.Attribute // Color for the Info output
ColorTitle color.Attribute // Color for the Title output
ColorWarn color.Attribute // Color for the Warn output
ColorFail color.Attribute // Color for the Fail output
ColorGood color.Attribute // Color for the Good output
}
Printer is the primary construct in msg, it allows you to configure the colors and symbols used for each of the printing methods attached to it.
func Default ¶ added in v0.2.0
func Default() *Printer
Default constructs and returns a default Printer with sensible colors and symbols configured to print to os.Stdout.
func (*Printer) Stitle ¶
Stitle is like Title but it returns a string rather than printing it
The returned string will have all it's leading and trailing whitespace/newlines trimmed so you have access to the raw string.
func (*Printer) Stitlef ¶
Stitlef returns a formatted title string, stripped of all leading/trailing whitespace.
func (*Printer) Text ¶
Text prints a normal, uncoloured message you could argue we don't need this as all is does is call fmt.Fprintln but we're here now.
func (*Printer) Textf ¶
Textf prints a formatted normal message a newline is automatically appended to the end of 'format' so you don't have to.
func (*Printer) Title ¶
Title prints a Title message
A Title is distinguishable from all other constructs in msg as it will has 1 newline before and 2 newlines after it to create separation
If the Printer has a SymbolTitle, it will be prefixed onto 'text' with 2 spaces separating them.
Source Files