plain

package module
v1.6.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 3, 2026 License: MPL-2.0 Imports: 20 Imported by: 0

README

A tiny, super fast logger for Go with a couple of handy input helpers.

Install

go get -u github.com/coalaura/plain

Quick start

import (
	"github.com/coalaura/plain"
)

func main() {
	pl := plain.New()

	pl.Debugln("Hello from Debug")
	pl.Println("Hello from Print")
	pl.Warnln("Hello from Warn")
	pl.Errorln("Hello from Error")

	confirmed, _ := pl.ConfirmWithEcho("Confirm", true, " ")

	if confirmed {
		pl.Println("You confirmed")
	} else {
		pl.Println("You declined")
	}

	input, _ := pl.Read("Input: ", 64)

	pl.Printf("You entered '%s'\n", input)

	key, _ := pl.ReadOne("Key: ", true)

	pl.Printf("You entered '%s'\n", string(key))

	hidden, _ := pl.ReadHidden("Hidden: ")

	pl.Printf("You entered '%s'\n", hidden)

	masked, _ := pl.ReadMask("Masked: ", plain.MaskStar)

	pl.Printf("You entered '%s'\n", masked)

	options := []string{"Red", "Green", "Blue", "Yellow"}

	index, _ := pl.Select("Select: ", options)

	pl.Printf("You selected '%s'\n", options[index])

	// shortcut to block till we receive an interrupt
	pl.WaitForInterrupt()

	// cleanup code on exit...
}

Options

// Set output target (defaults to os.Stdout)
pl := plain.New(plain.WithTarget(os.Stderr))

// Enable timestamps with a custom format
pl := plain.New(plain.WithDate(plain.RFC3339Local))

// Update at runtime
pl.SetTarget(os.Stderr)
pl.SetDate("")

HTTP middleware

pl := plain.New()

mux := http.NewServeMux()
// ...

handler := pl.Middleware()(mux)

handler = plain.RealIPMiddleware()(handler)

http.ListenAndServe(":8080", handler)

Pass WithHostAsPeer() to log the incoming request's Host instead of its remote address, with the same port stripping. Options are applied once when creating the middleware.

handler := pl.Middleware(plain.WithHostAsPeer())(mux)

RealIPMiddleware updates http.Request.RemoteAddr from the first valid X-Real-IP or X-Forwarded-For address. By default, forwarded headers are trusted only from 127.0.0.1; configure the proxies and headers you trust when deploying behind another proxy:

handler := pl.Middleware()(mux)

handler = plain.RealIPMiddleware(
	plain.WithTrustedProxies("10.0.0.0/8", "192.0.2.10"),
	plain.WithTrustedHeaders(plain.HeaderXForwardedFor),
)(handler)

http.ListenAndServe(":8080", handler)

Error helpers

// Panics if err is not nil
pl.MustFail(err)

// Logs the error and exits with code 1 if err is not nil
pl.MustExit(err)

// Check if an error came from an interrupted read
if plain.IsInterrupted(err) {
	// user pressed Ctrl+C
}

Performance tips

  • Prefer Println/Printf for hot paths to avoid extra formatting work.
  • Keep WithDate("") (default) when you do not need timestamps.
  • Avoid embedding ANSI sequences in messages if color is disabled.
  • Reuse a single Plain instance instead of creating per call.
  • For high-throughput logging, direct output to buffered IO (e.g. bufio.Writer).

Documentation

Index

Constants

View Source 
const (
	MaskStar = '*'
	MaskDot  = '-'
	MaskHash = '#'
)

Mask constants for ReadMask. Pass any rune to ReadMask; these are convenience values for common masking characters. MaskNone disables on-screen echoing entirely (behaviour equivalent to ReadHidden, but with backspace handling).

View Source 
const (
	// HeaderXRealIP is the X-Real-IP header.
	HeaderXRealIP = "X-Real-IP"

	// HeaderXForwardedFor is the X-Forwarded-For header.
	HeaderXForwardedFor = "X-Forwarded-For"
)
View Source 
const (
	Dimmed themeColor = iota
	Success
	Highlight
	Input
	Warn
	Error
	Reset
)
View Source 
const AnsiReset = ansi.AnsiReset
View Source 
const RFC3339Local = "2006-01-02T15:04:05"

RFC3339Local is an RFC3339-like time format without timezone information

Variables

View Source 
var (
	// ErrInterrupted indicates that an input operation was cancelled.
	ErrInterrupted = internal.ErrInterrupted

	// ErrNoOptions indicates that a selector was opened without any options.
	ErrNoOptions = errors.New("no options")
)

Functions

func AsStrings 

func AsStrings[T any](input []T) []string

AsStrings converts a slice/array of any type to a slice of strings

func IsInterrupted added in v1.2.1 

func IsInterrupted(err error) bool

IsInterrupted checks if the given err is ErrInterrupted

func RealIPMiddleware added in v1.6.4 

func RealIPMiddleware(opts ...realIPOption) func(http.Handler) http.Handler

RealIPMiddleware replaces the request's remote address with the first valid IP found in the trusted headers. It defaults to X-Real-IP and X-Forwarded-For for requests originating from 127.0.0.1/32.

func WithDate 

func WithDate(format string) option

WithDate sets the timestamp format used in log headers (empty disables timestamps)

func WithHostAsPeer added in v1.6.5 

func WithHostAsPeer() middlewareOption

WithHostAsPeer logs request.Host instead of the remote address, using the same port stripping.

func WithLevel added in v1.5.0 

func WithLevel(level Level) option

WithLevel sets the minimum log level. Messages below this level are discarded.

func WithTarget 

func WithTarget(out io.Writer) option

WithTarget sets the output writer used by the logger

func WithTrustedHeaders added in v1.6.4 

func WithTrustedHeaders(headers ...string) realIPOption

WithTrustedHeaders sets the headers used to determine the client's IP address.

func WithTrustedProxies added in v1.6.4 

func WithTrustedProxies(proxies ...string) realIPOption

WithTrustedProxies restricts trusted headers to requests from the given IP addresses or CIDR ranges. Invalid proxies are ignored.

Types

type Level added in v1.5.0 

type Level uint8
const (
	LevelDebug Level = iota
	LevelPrint
	LevelWarn
	LevelError
)

type Plain 

type Plain struct {
	// contains filtered or unexported fields
}

Plain is a small, allocation-conscious logger with optional ANSI color output

func New 

func New(opts ...option) *Plain

New creates a Plain logger configured by the provided options

func (*Plain) Confirm 

func (p *Plain) Confirm(prompt string, defaultYes bool) (bool, error)

Confirm displays a prompt aligned with the logger's format, reads y/n confirmation from stdin and prints a newline

func (*Plain) ConfirmWithEcho added in v1.1.8 

func (p *Plain) ConfirmWithEcho(prompt string, defaultYes bool, prefix string) (bool, error)

ConfirmWithEcho displays a prompt aligned with the logger's format, reads y/n confirmation from stdin and echoes the chosen input (optionally prefixed) before printing a newline.

func (*Plain) Debug 

func (p *Plain) Debug(a ...any)

Debug formats using the default formats for its operands and writes to the target output as a debug log.

func (*Plain) Debugf 

func (p *Plain) Debugf(format string, a ...any)

Debugf formats according to a format specifier and writes to the target output as a debug log.

func (*Plain) Debugln 

func (p *Plain) Debugln(a ...any)

Debugln formats using the default formats for its operands and writes to the target output as a debug log with a trailing newline.

func (*Plain) Error 

func (p *Plain) Error(a ...any)

Error formats using the default formats for its operands and writes to the target output as an error.

func (*Plain) Errorf 

func (p *Plain) Errorf(format string, a ...any)

Errorf formats according to a format specifier and writes to the target output as an error.

func (*Plain) Errorln 

func (p *Plain) Errorln(a ...any)

Errorln formats using the default formats for its operands and writes to the target output as an error with a trailing newline.

func (*Plain) Info added in v1.5.0 

func (p *Plain) Info(a ...any)

func (*Plain) Infof added in v1.5.0 

func (p *Plain) Infof(format string, a ...any)

func (*Plain) Infoln added in v1.5.0 

func (p *Plain) Infoln(a ...any)

func (*Plain) LogRequest 

func (p *Plain) LogRequest(request *http.Request, metrics *httpsnoop.Metrics)

LogRequest writes a single formatted access log line for request using the provided metrics

func (*Plain) Middleware 

func (p *Plain) Middleware(opts ...middlewareOption) func(http.Handler) http.Handler

Middleware returns an http middleware that logs each request after it has been handled

func (*Plain) MustExit added in v1.1.5 

func (p *Plain) MustExit(err error)

MustExit logs the error and exits with code 1 if the error is not nil.

func (*Plain) MustFail 

func (p *Plain) MustFail(err error)

MustFail panics if err is not nil

func (*Plain) OnSignal added in v1.5.0 

func (p *Plain) OnSignal(sig os.Signal, handler func())

OnSignal registers a non-blocking handler that executes the provided callback every time the specified signal is received.

func (*Plain) OnSignalContext added in v1.6.0 

func (p *Plain) OnSignalContext(ctx context.Context, sig os.Signal, handler func())

OnSignalContext registers a non-blocking handler until ctx is cancelled.

func (*Plain) Print 

func (p *Plain) Print(a ...any)

Print formats using the default formats for its operands and writes to the target output.

func (*Plain) Printf 

func (p *Plain) Printf(format string, a ...any)

Printf formats according to a format specifier and writes to the target output.

func (*Plain) Println 

func (p *Plain) Println(a ...any)

Println formats using the default formats for its operands and writes to the target output with a trailing newline.

func (*Plain) Read 

func (p *Plain) Read(prompt string, max int) (string, error)

Read displays a prompt aligned with the logger's format and reads max bytes from stdin.

func (*Plain) ReadHidden added in v1.4.4 

func (p *Plain) ReadHidden(prompt string) (string, error)

ReadHidden displays a prompt aligned with the logger's format, reads a line from stdin without echoing input and prints a newline.

func (*Plain) ReadMask added in v1.4.4 

func (p *Plain) ReadMask(prompt string, mask rune) (string, error)

ReadMask displays a prompt aligned with the logger's format, reads a line from stdin masking each typed byte on screen, and prints a newline.

func (*Plain) ReadOne 

func (p *Plain) ReadOne(prompt string, echo bool) (rune, error)

ReadOne displays a prompt aligned with the logger's format and reads 1 byte from stdin.

func (*Plain) Select 

func (p *Plain) Select(prompt string, options []string) (int, error)

Select displays a cyclic selector aligned with the logger's format.

func (*Plain) SelectWithDescription added in v1.5.1 

func (p *Plain) SelectWithDescription(prompt string, options []SelectOption) (int, error)

SelectWithDescription displays a cyclic selector with the selected option's description on the line below it.

func (*Plain) SetDate added in v1.1.9 

func (p *Plain) SetDate(format string)

SetDate updates the timestamp format used in log headers (empty disables timestamps)

func (*Plain) SetLevel added in v1.5.0 

func (p *Plain) SetLevel(level Level)

SetLevel updates the minimum log level.

func (*Plain) SetTarget added in v1.1.9 

func (p *Plain) SetTarget(out io.Writer)

SetTarget updates the output writer used by the logger

func (*Plain) Theme added in v1.3.0 

func (p *Plain) Theme(c themeColor) string

Theme returns a theme color as ansi code

func (*Plain) WaitForInterrupt added in v1.1.6 

func (p *Plain) WaitForInterrupt()

WaitForInterrupt blocks until SIGINT or SIGTERM is received

func (*Plain) Warn 

func (p *Plain) Warn(a ...any)

Warn formats using the default formats for its operands and writes to the target output as a warning.

func (*Plain) Warnf 

func (p *Plain) Warnf(format string, a ...any)

Warnf formats according to a format specifier and writes to the target output as a warning.

func (*Plain) Warnln 

func (p *Plain) Warnln(a ...any)

Warnln formats using the default formats for its operands and writes to the target output as a warning with a trailing newline.

func (*Plain) Write 

func (p *Plain) Write(code, msg string, reset, newline, noHeader bool)

Write writes a formatted log line with an optional reset code

func (*Plain) Writeln added in v1.4.2 

func (p *Plain) Writeln(code, msg string, reset, noHeader bool)

Writeln writes a formatted log line with an optional reset code and a newline

type SelectOption added in v1.5.1 

type SelectOption interface {
	Label() string
	Description() string
}

SelectOption provides the label and description for SelectWithDescription.

type Theme 

type Theme struct {
	Success   string
	Highlight string
	Input     string

	Dimmed string
	Warn   string
	Error  string
}

Theme defines the ANSI color sequences used by the logger

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.