Tweaks based on some early feedback. Update to read me.
diff --git a/README.md b/README.md
index 15a378d..2f6c9c8 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,29 @@
jWalterWeatherman
=================
-A simple printing and logging library for go
+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 convenience wrapper around the
-excellent standard log library.
+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
+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 good feedback (which can easily be logged) to the user
+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.
@@ -24,6 +31,7 @@
## 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:
@@ -46,23 +54,46 @@
...
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)
}
- // this isn’t that important, but they may want to know
+ 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?_
-## Step 2. Optionally configure it
+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.
-By default:
+## 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
@@ -80,7 +111,7 @@
if Verbose {
jww.SetLogThreshold(jww.LevelTrace)
- jww.SetOutputThreshold(jww.LevelInfo)
+ jww.SetStdoutThreshold(jww.LevelInfo)
}
```
@@ -89,6 +120,8 @@
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.
```go
import (
diff --git a/jww_test.go b/jww_test.go
index 91c6b9b..b6d118a 100644
--- a/jww_test.go
+++ b/jww_test.go
@@ -12,13 +12,13 @@
)
func TestLevels(t *testing.T) {
- SetOutputThreshold(LevelError)
- assert.Equal(t, OutputThreshold(), LevelError)
+ SetStdoutThreshold(LevelError)
+ assert.Equal(t, StdoutThreshold(), LevelError)
SetLogThreshold(LevelCritical)
assert.Equal(t, LogThreshold(), LevelCritical)
- assert.NotEqual(t, OutputThreshold(), LevelCritical)
- SetOutputThreshold(LevelWarn)
- assert.Equal(t, OutputThreshold(), LevelWarn)
+ assert.NotEqual(t, StdoutThreshold(), LevelCritical)
+ SetStdoutThreshold(LevelWarn)
+ assert.Equal(t, StdoutThreshold(), LevelWarn)
}
func TestDefaultLogging(t *testing.T) {
@@ -28,7 +28,7 @@
OutHandle = outputBuf
SetLogThreshold(LevelWarn)
- SetOutputThreshold(LevelError)
+ SetStdoutThreshold(LevelError)
FATAL.Println("fatal err")
CRITICAL.Println("critical err")
diff --git a/thatswhyyoualwaysleaveanote.go b/thatswhyyoualwaysleaveanote.go
index 9a2e2f1..09fb542 100644
--- a/thatswhyyoualwaysleaveanote.go
+++ b/thatswhyyoualwaysleaveanote.go
@@ -38,7 +38,7 @@
LevelCritical
LevelFatal
DefaultLogThreshold = LevelWarn
- DefaultOutputThreshold = LevelError
+ DefaultStdoutThreshold = LevelError
)
var (
@@ -64,18 +64,18 @@
critical *NotePad = &NotePad{Level: LevelCritical, Handle: os.Stdout, Logger: &CRITICAL, Prefix: "CRITICAL: "}
fatal *NotePad = &NotePad{Level: LevelFatal, Handle: os.Stdout, Logger: &FATAL, Prefix: "FATAL: "}
logThreshold Level = DefaultLogThreshold
- outputThreshold Level = DefaultOutputThreshold
+ outputThreshold Level = DefaultStdoutThreshold
)
func init() {
- SetOutputThreshold(DefaultOutputThreshold)
+ SetStdoutThreshold(DefaultStdoutThreshold)
}
-// Initialize will setup the jWalterWeatherman standard approach of providing the user
+// initialize will setup the jWalterWeatherman standard approach of providing the user
// some feedback and logging a potentially different amount based on independent log and output thresholds.
// By default the output has a lower threshold than logged
// Don't use if you have manually set the Handles of the different levels as it will overwrite them.
-func Initialize() {
+func initialize() {
BothHandle = io.MultiWriter(LogHandle, OutHandle)
for _, n := range NotePads {
@@ -105,7 +105,7 @@
}
// Level returns the current global output threshold.
-func OutputThreshold() Level {
+func StdoutThreshold() Level {
return outputThreshold
}
@@ -124,13 +124,13 @@
// Establishes a threshold where anything matching or above will be logged
func SetLogThreshold(level Level) {
logThreshold = levelCheck(level)
- Initialize()
+ initialize()
}
// Establishes a threshold where anything matching or above will be output
-func SetOutputThreshold(level Level) {
+func SetStdoutThreshold(level Level) {
outputThreshold = levelCheck(level)
- Initialize()
+ initialize()
}
// Conveniently Sets the Log Handle to a io.writer created for the file behind the given filepath
@@ -144,7 +144,7 @@
}
LogHandle = file
- Initialize()
+ initialize()
}
// Conveniently Creates a temporary file and sets the Log Handle to a io.writer created for it
@@ -157,13 +157,13 @@
fmt.Println("Logging to", file.Name())
LogHandle = file
- Initialize()
+ initialize()
}
// Disables logging for the entire JWW system
func DiscardLogging() {
LogHandle = ioutil.Discard
- Initialize()
+ initialize()
}
// Feedback is special. It writes plainly to the output while
