plog

Documentation

Overview

plog provides thread-safe log instances for any writer

Index

• Variables
• func D(format string, a ...interface{})
• func GetLog(writer io.Writer) *log.Logger
• func NoPrint(format string, a ...interface{})
• func Sprintf(format string, a ...any) (s string)
• type LogInstance
  • func NewLog(writers ...io.Writer) (lg *LogInstance)
  • func NewLogFrames(writer io.Writer, extraStackFramesToSkip int) (lg *LogInstance)
  • func (g *LogInstance) D(format string, a ...interface{})
  • func (g *LogInstance) Debug(format string, a ...any)
  • func (g *LogInstance) GetD(skipFrames int) (debug func(format string, a ...interface{}))
  • func (g *LogInstance) GetDebug(skipFrames int) (debug func(format string, a ...any))
  • func (g *LogInstance) Info(format string, a ...interface{})
  • func (g *LogInstance) IsSilent() (isSilent bool)
  • func (g *LogInstance) IsThisDebug() (isDebug bool)
  • func (g *LogInstance) IsThisDebugN(skipFrames int) (isDebug bool)
  • func (g *LogInstance) Log(format string, a ...interface{})
  • func (g *LogInstance) Logw(format string, a ...interface{})
  • func (g *LogInstance) SetDebug(debug bool)
  • func (g *LogInstance) SetRegexp(regExp string) (err error)
  • func (g *LogInstance) SetSilent(silent bool)
• type OutputInvoker
  • func NewOutputInvoker(codeLocation *pruntime.CodeLocation, invokeOutput func(s string)) (outputInvoker *OutputInvoker)
  • func (o *OutputInvoker) Invoke(format string, a ...any)

Variables

var EnglishSprintf = message.NewPrinter(language.English).Sprintf

EnglishSprintf is like fmt.Sprintf with thousands separator

Functions

func D

func D(format string, a ...interface{})

D prints to stderr with code location. Thread-safe.

• D is like parl.D but can be used by packages imported by parl
• D is meant for temporary output intended to be removed before check-in

func GetLog

func GetLog(writer io.Writer) *log.Logger

GetLog returns shared log.Logger instances for file descriptors os.Stdout and os.Stderr.

• if Logger instance is shared, output is thread-safe.
• if other means of output is used, the result is unpredictably intermingled output

func NoPrint

func NoPrint(format string, a ...interface{})

func Sprintf

func Sprintf(format string, a ...any) (s string)

sprintf is like fmt.Sprintf and:

• does not interpret format if a is empty, and
• has thousands separator for numbers
• is like parl.Sprintf but usable to packages imported by parl

Types

type LogInstance

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

LogInstance provide logging delegating to log.Output

func NewLog

func NewLog(writers ...io.Writer) (lg *LogInstance)

NewLog gets a logger for Fatal and Warning for specific output

func NewLogFrames

func NewLogFrames(writer io.Writer, extraStackFramesToSkip int) (lg *LogInstance)

NewLog gets a logger for Fatal and Warning for specific output

func (*LogInstance) D

func (g *LogInstance) D(format string, a ...interface{})

D always prints with code location. Thread-safe

• D is meant for temporary output intended to be removed prior to check-in

func (*LogInstance) Debug

func (g *LogInstance) Debug(format string, a ...any)

Debug outputs only if debug is configured globally or for the executing function

• code location is appended

func (*LogInstance) GetD

func (g *LogInstance) GetD(skipFrames int) (debug func(format string, a ...interface{}))

GetD returns a function value that always invokes logging

• the caller frame is appended
• D is meant for temporary output intended to be removed prior to check-in
• the function value can be passed around or invoked later

func (*LogInstance) GetDebug

func (g *LogInstance) GetDebug(skipFrames int) (debug func(format string, a ...any))

GetDebug returns a function value that can be used to invokes logging

• outputs if debug is enabled for the specified caller frame
• the caller frame is appended
• the function value can be passed around or invoked later

func (*LogInstance) Info

func (g *LogInstance) Info(format string, a ...interface{})

Info prints unless silence has been configured with SetSilence(true)

• IsSilent determines the state of silence
• if debug is enabled, code location is appended

func (*LogInstance) IsSilent

func (g *LogInstance) IsSilent() (isSilent bool)

IsSilent if true it means that Info does not print

func (*LogInstance) IsThisDebug

func (g *LogInstance) IsThisDebug() (isDebug bool)

IsThisDebug returns whether the executing code location has debug logging enabled

• true when -debug globally enabled using SetDebug(true)
• true when the -verbose regexp set with SetRegexp matches

func (*LogInstance) IsThisDebugN

func (g *LogInstance) IsThisDebugN(skipFrames int) (isDebug bool)

IsThisDebugN returns whether the specified stack frame has debug logging enabled. 0 means caller of IsThisDebugN.

• true when -debug globally enabled using SetDebug(true)
• true when the -verbose regexp set with SetRegexp matches

func (*LogInstance) Log

func (g *LogInstance) Log(format string, a ...interface{})

Log always prints

• if debug is enabled, code location is appended

func (*LogInstance) Logw

func (g *LogInstance) Logw(format string, a ...interface{})

Logw always prints

• Logw does not ensure ending newline

func (*LogInstance) SetDebug

func (g *LogInstance) SetDebug(debug bool)

if SetDebug is true, Debug prints everywhere produce output

• other printouts have location appended
• More selective debug printing can be achieved using SetInfoRegexp that matches on function names.

func (*LogInstance) SetRegexp

func (g *LogInstance) SetRegexp(regExp string) (err error)

SetRegexp defines a regular expression for function-level debug printing to stderr.

• SetRegexp affects Debug() GetDebug() IsThisDebug() IsThisDebugN() functions.

Regular Expression

Regular expression is the RE2 syntax used by golang. command-line documentation: “go doc regexp/syntax”. The regular expression is matched against code location.

Code Location Format

Code location is the fully qualified function name for the executing code line being evaluated. This is a fully qualified golang package path, ".", a possible type name in parenthesis ending with "." and the function name.

• method with pointer receiver:
• — "github.com/haraldrudell/parl/mains.(*Executable).AddErr"
• — sample regexp: mains...Executable..AddErr
• top-level function:
• — "github.com/haraldrudell/parl/g0.NewGoGroup"
• — sample regexp: g0.NewGoGroup

To obtain the fully qualified function name for a particular location:

parl.Log(pruntime.NewCodeLocation(0).String())

func (*LogInstance) SetSilent

func (g *LogInstance) SetSilent(silent bool)

SetSilent(true) prevents Info() invocations from printing

type OutputInvoker

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

OutputInvoker provides Invoke function for specific code location

func NewOutputInvoker

func NewOutputInvoker(
	codeLocation *pruntime.CodeLocation,
	invokeOutput func(s string),
) (outputInvoker *OutputInvoker)

NewOutputInvoker returns a [LogInstance.invokeOutput] function for a specific code location

func (*OutputInvoker) Invoke

func (o *OutputInvoker) Invoke(format string, a ...any)

Invoke invokes the [LogInstance.invokeOutput] function for a stored code location