forked from Shiloh/githaven
149 lines
4.3 KiB
Markdown
149 lines
4.3 KiB
Markdown
|
jWalterWeatherman
|
|||
|
|
=================
|
|||
|
|
|
|||
|
|
Seamless printing to the terminal (stdout) and logging to a io.Writer
|
|||
|
|
(file) that’s as easy to use as fmt.Println.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Graphic by [JonnyEtc](http://jonnyetc.deviantart.com/art/And-That-s-Why-You-Always-Leave-a-Note-315311422)
|
|||
|
|
|
|||
|
|
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 thoughout 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.
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
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)
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
NOTE: You can also use the library in a non-global setting by creating an instance of a Notebook:
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
notepad = jww.NewNotepad(jww.LevelInfo, jww.LevelTrace, os.Stdout, ioutil.Discard, "", log.Ldate|log.Ltime)
|
|||
|
|
notepad.WARN.Println("Some warning"")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
_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.
|
|||
|
|
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
|
|||
|
|
### Setting a log file
|
|||
|
|
|
|||
|
|
JWW can log to any `io.Writer`:
|
|||
|
|
|
|||
|
|
|
|||
|
|
```go
|
|||
|
|
|
|||
|
|
jww.SetLogOutput(customWriter)
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
|
|||
|
|
# 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](https://gohugo.io). If you are looking
|
|||
|
|
for a static website engine that’s super fast please checkout Hugo.
|