jwalterweatherman

package
v0.0.7 Latest Latest
Warning

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

Go to latest
Published: Feb 6, 2016 License: MIT, MIT Imports: 5 Imported by: 0

README

jWalterWeatherman

Seamless printing to the terminal (stdout) and logging to a io.Writer (file) that’s as easy to use as fmt.Println.

and_that__s_why_you_always_leave_a_note_by_jonnyetc-d57q7um Graphic by JonnyEtc

JWW is primarily a wrapper around the excellent standard log library. It provides a few advantages over using the standard log library alone.

  1. Ready to go out of the box.
  2. One library for both printing to the terminal and logging (to files).
  3. Really easy to log to either a temp file or a file you specify.

I really wanted a very straightforward library that could seamlessly do the following things.

  1. Replace all the println, printf, etc statements thought my code with something more useful
  2. Allow the user to easily control what levels are printed to stdout
  3. Allow the user to easily control what levels are logged
  4. Provide an easy mechanism (like fmt.Println) to print info to the user which can be easily logged as well
  5. Due to 2 & 3 provide easy verbose mode for output and logs
  6. Not have any unnecessary initialization cruft. Just use it.

Usage

Step 1. Use it

Put calls throughout your source based on type of feedback. No initialization or setup needs to happen. Just start calling things.

Available Loggers are:

  • TRACE
  • DEBUG
  • INFO
  • WARN
  • ERROR
  • CRITICAL
  • FATAL

These each are loggers based on the log standard library and follow the standard usage. Eg..

    import (
        jww "github.com/spf13/jwalterweatherman"
    )

    ...

    if err != nil {

        // This is a pretty serious error and the user should know about
        // it. It will be printed to the terminal as well as logged under the
        // default thresholds.

        jww.ERROR.Println(err)
    }

    if err2 != nil {
        // This error isn’t going to materially change the behavior of the
        // application, but it’s something that may not be what the user
        // expects. Under the default thresholds, Warn will be logged, but
        // not printed to the terminal. 

        jww.WARN.Println(err2)
    }

    // Information that’s relevant to what’s happening, but not very
    // important for the user. Under the default thresholds this will be
    // discarded.

    jww.INFO.Printf("information %q", response)

Why 7 levels?

Maybe you think that 7 levels are too much for any application... and you are probably correct. Just because there are seven levels doesn’t mean that you should be using all 7 levels. Pick the right set for your needs. Remember they only have to mean something to your project.

Step 2. Optionally configure JWW

Under the default thresholds :

  • Debug, Trace & Info goto /dev/null
  • Warn and above is logged (when a log file/io.Writer is provided)
  • Error and above is printed to the terminal (stdout)
Changing the thresholds

The threshold can be changed at any time, but will only affect calls that execute after the change was made.

This is very useful if your application has a verbose mode. Of course you can decide what verbose means to you or even have multiple levels of verbosity.

    import (
        jww "github.com/spf13/jwalterweatherman"
    )

    if Verbose {
        jww.SetLogThreshold(jww.LevelTrace)
        jww.SetStdoutThreshold(jww.LevelInfo)
    }

Note that JWW's own internal output uses log levels as well, so set the log level before making any other calls if you want to see what it's up to.

Using a temp log file

JWW conveniently creates a temporary file and sets the log Handle to a io.Writer created for it. You should call this early in your application initialization routine as it will only log calls made after it is executed. When this option is used, the library will fmt.Println where to find the log file.

    import (
        jww "github.com/spf13/jwalterweatherman"
    )

    jww.UseTempLogFile("YourAppName") 

Setting a log file

JWW can log to any file you provide a path to (provided it’s writable). Will only append to this file.

    import (
        jww "github.com/spf13/jwalterweatherman"
    )

    jww.SetLogFile("/path/to/logfile") 

More information

This is an early release. I’ve been using it for a while and this is the third interface I’ve tried. I like this one pretty well, but no guarantees that it won’t change a bit.

I wrote this for use in hugo. If you are looking for a static website engine that’s super fast please checkout Hugo.

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	TRACE      *log.Logger
	DEBUG      *log.Logger
	INFO       *log.Logger
	WARN       *log.Logger
	ERROR      *log.Logger
	CRITICAL   *log.Logger
	FATAL      *log.Logger
	LOG        *log.Logger
	FEEDBACK   Feedback
	LogHandle  io.Writer  = ioutil.Discard
	OutHandle  io.Writer  = os.Stdout
	BothHandle io.Writer  = io.MultiWriter(LogHandle, OutHandle)
	NotePads   []*NotePad = []*NotePad{trace, debug, info, warn, err, critical, fatal}

	DATE  = log.Ldate
	TIME  = log.Ltime
	SFILE = log.Lshortfile
	LFILE = log.Llongfile
	MSEC  = log.Lmicroseconds
)

Functions

func DiscardLogging

func DiscardLogging()

Disables logging for the entire JWW system

func SetLogFile

func SetLogFile(path string)

Conveniently Sets the Log Handle to a io.writer created for the file behind the given filepath Will only append to this file

func SetLogFlag

func SetLogFlag(flags int)

Set the log Flags (Available flag: DATE, TIME, SFILE, LFILE and MSEC)

func SetLogThreshold

func SetLogThreshold(level Level)

Establishes a threshold where anything matching or above will be logged

func SetStdoutThreshold

func SetStdoutThreshold(level Level)

Establishes a threshold where anything matching or above will be output

func UseTempLogFile

func UseTempLogFile(prefix string)

Conveniently Creates a temporary file and sets the Log Handle to a io.writer created for it

Types

type Feedback

type Feedback struct{}

Feedback is special. It writes plainly to the output while logging with the standard extra information (date, file, etc) Only Println and Printf are currently provided for this

func (*Feedback) Printf

func (fb *Feedback) Printf(format string, v ...interface{})

Feedback is special. It writes plainly to the output while logging with the standard extra information (date, file, etc) Only Println and Printf are currently provided for this

func (*Feedback) Println

func (fb *Feedback) Println(v ...interface{})

Feedback is special. It writes plainly to the output while logging with the standard extra information (date, file, etc) Only Println and Printf are currently provided for this

type Level

type Level int

Level describes the chosen log level between debug and critical.

const (
	LevelTrace Level = iota
	LevelDebug
	LevelInfo
	LevelWarn
	LevelError
	LevelCritical
	LevelFatal
	DefaultLogThreshold    = LevelWarn
	DefaultStdoutThreshold = LevelError
)

func LogThreshold

func LogThreshold() Level

Level returns the current global log threshold.

func StdoutThreshold

func StdoutThreshold() Level

Level returns the current global output threshold.

type NotePad

type NotePad struct {
	Handle io.Writer
	Level  Level
	Prefix string
	Logger **log.Logger
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL