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