README
¶
clio
Common Fate CLI logging library.
Documentation
¶
Overview ¶
Package clio contains helpers for printing CLI output messages.
Example (CheckingLogLevel) ¶
You can use `clio.IsDebug()` to check whether debug logging is enabled. This can be useful to configure other packages to enable debug logging in them. Don't use this to conditionally print log messages - just call `clio.Debug()` and let the built-in log levels do their thing.
package main
import (
"fmt"
"github.com/common-fate/clio"
)
func main() {
clio.SetLevelFromString("info")
fmt.Printf("default debug logging: %v\n", clio.IsDebug())
clio.SetLevelFromString("debug")
if clio.IsDebug() {
fmt.Println("debug logging enabled!")
}
}
Output: default debug logging: false debug logging enabled!
Example (DynamicLevel) ¶
You can use `clio.Level.SetLevel()` to set the log level dynamically.
package main
import (
"os"
"github.com/common-fate/clio"
"go.uber.org/zap/zapcore"
)
func main() {
clio.SetWriter(os.Stdout) // print to stdout just to show logs in the example.
clio.Level.SetLevel(zapcore.InfoLevel)
clio.Debug("this isn't printed")
clio.Level.SetLevel(zapcore.DebugLevel)
clio.Debug("debug logs now printed!")
}
Output: [DEBUG] debug logs now printed!
Example (LevelFromEnv) ¶
You can use `clio.SetLevelFromEnv` to set the log level from environment variables. If the environment variables aren't found, this package defaults to the 'info' level.
package main
import (
"github.com/common-fate/clio"
)
func main() {
clio.SetLevelFromEnv("CF_LOG")
// running CF_LOG=debug <your Go binary> will print debug logs.
}
Output:
Example (LevelFromString) ¶
You can use `clio.SetLevelFromString()` to set the log level dynamically from a provided string.
package main
import (
"os"
"github.com/common-fate/clio"
)
func main() {
clio.SetWriter(os.Stdout) // print to stdout just to show logs in the example.
clio.SetLevelFromString("info")
clio.Debug("this isn't printed")
clio.SetLevelFromString("debug")
clio.Debug("debug logs now printed!")
}
Output: [DEBUG] debug logs now printed!
Example (Usage) ¶
Here's the basics on how to use clio for logging.
package main
import (
"os"
"github.com/common-fate/clio"
)
func main() {
clio.SetLevelFromString("debug")
clio.SetWriter(os.Stdout) // print to stdout just to show logs in the example.
// you can print basic logs like this
clio.Info("here's an info message")
// add separate messages together with the 'ln' variant, e.g. clio.Errorln
clio.Errorln("hello", "world")
// format messages with the 'f' variant (same as how fmt.Printf works), e.g. clio.Debugf
clio.Debugf("hello %s", "world")
// add key-values pairs with the 'w' variant, e.g. clio.Infow
clio.Infow("calling an API", "url", "http://example.com")
}
Output: [i] here's an info message [✘] hello world [DEBUG] hello world [i] calling an API url:http://example.com
Index ¶
- Variables
- func Debug(args ...any)
- func Debugf(template string, args ...any)
- func Debugln(args ...any)
- func Debugw(msg string, keysAndValues ...any)
- func Error(args ...any)
- func Errorf(template string, args ...any)
- func Errorln(args ...any)
- func Errorw(msg string, keysAndValues ...any)
- func G() *zap.Logger
- func Info(args ...any)
- func Infof(template string, args ...interface{})
- func Infoln(args ...any)
- func Infow(msg string, keysAndValues ...any)
- func IsDebug() bool
- func Log(args ...any)
- func Logf(template string, args ...any)
- func Logln(args ...any)
- func NewLine()
- func ReplaceGlobals(logger *zap.Logger) func()
- func S() *zap.SugaredLogger
- func SetFileLogging(fcfg cliolog.FileLoggerConfig)
- func SetLevelFromEnv(vars ...string) func()
- func SetLevelFromString(level string) func()
- func SetWriter(w io.Writer)
- func Success(args ...any)
- func Successf(template string, args ...interface{})
- func Successln(args ...any)
- func Successw(msg string, keysAndValues ...any)
- func Warn(args ...any)
- func Warnf(template string, args ...any)
- func Warnln(args ...any)
- func Warnw(msg string, keysAndValues ...any)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // Level is the global logging level. Level = zap.NewAtomicLevel() )
var NoColor = noColorExists() || os.Getenv("TERM") == "dumb" || (!isatty.IsTerminal(os.Stdout.Fd()) && !isatty.IsCygwinTerminal(os.Stdout.Fd()))
NoColor defines if the output is colorized or not. It's dynamically set to false or true based on the stdout's file descriptor referring to a terminal or not. It's also set to true if the NO_COLOR environment variable is set (regardless of its value). This is a global option and affects all colors. For more control over each color block use the methods DisableColor() individually.
Functions ¶
func Debug ¶
func Debug(args ...any)
Debug prints to stderr with a [DEBUG] indicator using fmt.Sprint. Messages will be shown if the GRANTED_LOG or CF_LOG environment variable is set to 'debug'.
func Debugf ¶ added in v1.0.0
Debug prints to stderr with a [DEBUG] indicator. Messages will be shown if the GRANTED_LOG or CF_LOG environment variable is set to 'debug'.
func Debugln ¶ added in v0.4.0
func Debugln(args ...any)
Debugln prints to stderr with a [DEBUG] indicator using fmt.Sprintln. Messages will be shown if the GRANTED_LOG or CF_LOG environment variable is set to 'debug'.
func Debugw ¶ added in v1.0.0
Debug prints to stderr with a [DEBUG] indicator with additional key-value pairs. Messages will be shown if the GRANTED_LOG or CF_LOG environment variable is set to 'debug'.
func Errorln ¶ added in v0.4.0
func Errorln(args ...any)
Errorln prints to stderr with a [✘] indicator using fmt.Sprintln.
func Errorw ¶ added in v1.0.0
Error prints to stderr with a [✘] indicator with additional key-value pairs.
func Infof ¶ added in v1.0.0
func Infof(template string, args ...interface{})
Info prints to stderr with an [i] indicator.
func Infoln ¶ added in v0.4.0
func Infoln(args ...any)
Infoln prints to stderr with an [i] indicator using fmt.Sprintln.
func Infow ¶ added in v1.0.0
Infow prints to stderr with an [i] indicator with additional key-value pairs.
func IsDebug ¶ added in v1.0.0
func IsDebug() bool
IsDebug returns true if clio.Level is set to debug or lower.
func Logln ¶ added in v0.4.0
func Logln(args ...any)
Logln prints with no prefix using fmt.Sprintln.
func ReplaceGlobals ¶ added in v1.0.0
ReplaceGlobals replaces the global Logger and SugaredLogger, and returns a function to restore the original values. It's safe for concurrent use.
func S ¶ added in v1.0.0
func S() *zap.SugaredLogger
S returns the global stderr logger as a sugared zap logger.
func SetFileLogging ¶ added in v1.2.0
func SetFileLogging(fcfg cliolog.FileLoggerConfig)
func SetLevelFromEnv ¶ added in v1.0.0
func SetLevelFromEnv(vars ...string) func()
SetLevelFromEnv configures the global logging level based on the provided environment variables. The env vars should be provided in priority order. It returns a function which restores the previous log level.
func SetLevelFromString ¶ added in v1.0.0
func SetLevelFromString(level string) func()
SetLevelFromString configures the global logging level based on the provided string. Under the hood it uses zapcore.Parse() to try and parse the log level. Does nothing if the log level can't be parsed. It returns a function which restores the previous log level.
func SetWriter ¶ added in v1.1.0
SetWriter rebuilds the global zap logger with a specific writer. All Info, Error, Warn, Debug, etc messages are sent here. clio.Log messages are sent to stdout.
func Success ¶
func Success(args ...any)
Success prints to stderr with a [✔] indicator using fmt.Sprint.
func Successf ¶ added in v1.0.0
func Successf(template string, args ...interface{})
Success prints to stderr with a [✔] indicator.
func Successln ¶ added in v0.4.0
func Successln(args ...any)
Successln prints to stderr with a [✔] indicator using fmt.Sprintln.
func Successw ¶ added in v1.0.0
Success prints to stderr with a [✔] indicator with additional key-value pairs.
Types ¶
This section is empty.
Source Files
Directories