frog

README

frog

Overview

Frog is a package for logging output. When connected to a terminal, it supports marking one or more lines as bring fixed to the bottom of the output, with new sequential log lines appearing above the fixed lines. The fixed lines can be redrawn individually, allowing for one or more progress bars and other real-time status displays.

When not connected to a terminal, any superfluous fixed-line logs can be skipped.

Frog uses ANSI/VT-100 commands to change colors and move the cursor. Most terminals support this, although Windows cmd prompt has only supported it recently, and even then apps have to specifically enable the support via a call to SetConsoleMode (which frog does). For older versions of Windows, you can use ConEmu, Cmdr, and other third-party terminal apps that parse ANSI/VT-100 commands. I have no plans to add Win32 console API support for older versions of Windows.

Features

• Multiple logging levels:
  • Progress: Intended for status animations (skipped if stdout not connected to a terminal).
  • Verbose: Intended for debugging of your app's behavior.
  • Info: Intended for typical log lines.
  • Warning: Intended for calling attention to something non-critical, but unusual or important.
  • Error: Intended for calling attention to something that went wrong.
  • Fatal: Causes app to immediately exit with non-zero exit code.
• Fixing one or more lines in place
  • Intended for real-time display of progress/status/percentage/time/etc.
  • Non-fixed log lines continue to output above the fixed lines.
• Optional use of ANSI colors
  • On Windows
    • cmd.exe: ANSI support requires one of the more recent releases of Windows 10.
    • ConEmu/Cmdr: Should work regardless of Windows version.
  • Any other environment
    • relies on your terminal supporting ANSI/VT-100 support
  • Colors disabled when NO_COLOR env var is set (ANSI cursor movement for fixed lines still present)

TODO

• Structured logging
• JSON Printer
• Write to both stdout and log file simultaneously
• Ensure all lines are written even if app crashes
• Only re-draw the parts of fixed lines that have changed

Documentation

Index

• Variables
• type Buffered
  • func NewBuffered(cfg Config, prn Printer) *Buffered
  • func (l *Buffered) AddFixedLine() Logger
  • func (l *Buffered) Close()
  • func (l *Buffered) Errorf(format string, a ...interface{}) Logger
  • func (l *Buffered) Fatalf(format string, a ...interface{})
  • func (l *Buffered) Infof(format string, a ...interface{}) Logger
  • func (l *Buffered) MinLevel() Level
  • func (l *Buffered) Printf(level Level, format string, a ...interface{}) Logger
  • func (l *Buffered) Progressf(format string, a ...interface{}) Logger
  • func (l *Buffered) RootLogger() Logger
  • func (l *Buffered) SetMinLevel(level Level) Logger
  • func (l *Buffered) Verbosef(format string, a ...interface{}) Logger
  • func (l *Buffered) Warningf(format string, a ...interface{}) Logger
• type Config
• type FixedLine
  • func (l *FixedLine) AddFixedLine() Logger
  • func (l *FixedLine) Close()
  • func (l *FixedLine) Errorf(format string, a ...interface{}) Logger
  • func (l *FixedLine) Fatalf(format string, a ...interface{})
  • func (l *FixedLine) Infof(format string, a ...interface{}) Logger
  • func (l *FixedLine) MinLevel() Level
  • func (l *FixedLine) Printf(level Level, format string, a ...interface{}) Logger
  • func (l *FixedLine) Progressf(format string, a ...interface{}) Logger
  • func (l *FixedLine) RootLogger() Logger
  • func (l *FixedLine) SetMinLevel(level Level) Logger
  • func (l *FixedLine) Verbosef(format string, a ...interface{}) Logger
  • func (l *FixedLine) Warningf(format string, a ...interface{}) Logger
• type Level
• type Logger
  • func New() Logger
• type Msg
• type MsgType
• type Printer
  • func (p *Printer) Render(useAnsi bool, useColor bool, level Level, format string, a ...interface{}) string

Variables

var IsNoColorSet = false

Types

type Buffered

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

func NewBuffered

func NewBuffered(cfg Config, prn Printer) *Buffered

func (*Buffered) AddFixedLine

func (l *Buffered) AddFixedLine() Logger

AddFixedLine creates a Logger that, when connected to a terminal, draws over itself. Thread safe.

func (*Buffered) Close

func (l *Buffered) Close()

Close should be called before the app exits, to ensure any buffered output is flushed. Thread safe.

func (*Buffered) Errorf

func (l *Buffered) Errorf(format string, a ...interface{}) Logger

func (*Buffered) Fatalf

func (l *Buffered) Fatalf(format string, a ...interface{})

func (*Buffered) Infof

func (l *Buffered) Infof(format string, a ...interface{}) Logger

func (*Buffered) MinLevel

func (l *Buffered) MinLevel() Level

func (*Buffered) Printf

func (l *Buffered) Printf(level Level, format string, a ...interface{}) Logger

func (*Buffered) Progressf

func (l *Buffered) Progressf(format string, a ...interface{}) Logger

func (*Buffered) RootLogger

func (l *Buffered) RootLogger() Logger

func (*Buffered) SetMinLevel

func (l *Buffered) SetMinLevel(level Level) Logger

func (*Buffered) Verbosef

func (l *Buffered) Verbosef(format string, a ...interface{}) Logger

func (*Buffered) Warningf

func (l *Buffered) Warningf(format string, a ...interface{}) Logger

type Config

type Config struct {
	Writer   io.Writer
	UseAnsi  bool
	UseColor bool
}

type FixedLine

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

FixedLine is a Logger that attempts to overwrite the same line in the terminal, allowing progress bars and other simple UI for the human to consume.

If the Printer's CanUseAnsi is false, then it simply redirects to the normal behavior of the parent Buffered Logger.

If the Printer's CanUseAnsi is true, then the Progress level is always printed, regardless of the MinLevel. This allows progress bars that do not pollute logs with garbage when not connected to a terminal.

func (*FixedLine) AddFixedLine

func (l *FixedLine) AddFixedLine() Logger

func (*FixedLine) Close

func (l *FixedLine) Close()

func (*FixedLine) Errorf

func (l *FixedLine) Errorf(format string, a ...interface{}) Logger

func (*FixedLine) Fatalf

func (l *FixedLine) Fatalf(format string, a ...interface{})

func (*FixedLine) Infof

func (l *FixedLine) Infof(format string, a ...interface{}) Logger

func (*FixedLine) MinLevel

func (l *FixedLine) MinLevel() Level

func (*FixedLine) Printf

func (l *FixedLine) Printf(level Level, format string, a ...interface{}) Logger

func (*FixedLine) Progressf

func (l *FixedLine) Progressf(format string, a ...interface{}) Logger

func (*FixedLine) RootLogger

func (l *FixedLine) RootLogger() Logger

func (*FixedLine) SetMinLevel

func (l *FixedLine) SetMinLevel(level Level) Logger

func (*FixedLine) Verbosef

func (l *FixedLine) Verbosef(format string, a ...interface{}) Logger

func (*FixedLine) Warningf

func (l *FixedLine) Warningf(format string, a ...interface{}) Logger

type Level

type Level byte

const (
	Progress Level = iota // real-time progress bars, more verbose than a log file would need
	Verbose               // debugging info
	Info                  // normal message
	Warning               // something unusual happened
	Error                 // something bad happened
	Fatal                 // it's all over

)

type Logger

type Logger interface {
	// Close should be called before the process ends, to ensure everything is flushed.
	Close()

	// RootLogger returns the parent Logger, or itself if it has no parent.
	RootLogger() Logger

	// AddFixedLine creates a logger that always overwrites the same terminal line,
	// and always writes line level Progress.
	// Returned Logger should have its Close() called before its parent.
	AddFixedLine() Logger

	// MinLevel returns the lowest Level that will be logged.
	MinLevel() Level
	// SetMinLevel sets the lowest Level that will be logged.
	SetMinLevel(level Level) Logger

	// Printf is how log lines are added.
	Printf(level Level, format string, a ...interface{}) Logger

	Progressf(format string, a ...interface{}) Logger
	Verbosef(format string, a ...interface{}) Logger
	Infof(format string, a ...interface{}) Logger
	Warningf(format string, a ...interface{}) Logger
	Errorf(format string, a ...interface{}) Logger
	Fatalf(format string, a ...interface{})
}

func New

func New() Logger

New creates a Buffered logger that writes to os.Stdout, and autodetects any attached Terminal on stdout to decide if ANSI should be used. The caller is responsible for calling Close() before the process ends.

type Msg

type Msg struct {
	Type  MsgType
	Line  int32
	Level Level
	Msg   string
}

type MsgType

type MsgType byte

const (
	MsgPrint      MsgType = iota // string to print
	MsgFatal                     // stop processor without closing channel
	MsgAddLine                   // add a fixed line
	MsgRemoveLine                // remove a fixed line
)

type Printer

type Printer struct {
	PrintTime  bool
	PrintLevel bool
}

func (*Printer) Render

func (p *Printer) Render(useAnsi bool, useColor bool, level Level, format string, a ...interface{}) string