gtsocial-umbx

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs | README | LICENSE

README.md (4394B)

      1 jWalterWeatherman
      2 =================
      3 
      4 Seamless printing to the terminal (stdout) and logging to a io.Writer
      5 (file) that’s as easy to use as fmt.Println.
      6 
      7 ![and_that__s_why_you_always_leave_a_note_by_jonnyetc-d57q7um](https://cloud.githubusercontent.com/assets/173412/11002937/ccd01654-847d-11e5-828e-12ebaf582eaf.jpg)
      8 Graphic by [JonnyEtc](http://jonnyetc.deviantart.com/art/And-That-s-Why-You-Always-Leave-a-Note-315311422)
      9 
     10 JWW is primarily a wrapper around the excellent standard log library. It
     11 provides a few advantages over using the standard log library alone.
     12 
     13 1. Ready to go out of the box. 
     14 2. One library for both printing to the terminal and logging (to files).
     15 3. Really easy to log to either a temp file or a file you specify.
     16 
     17 
     18 I really wanted a very straightforward library that could seamlessly do
     19 the following things.
     20 
     21 1. Replace all the println, printf, etc statements thoughout my code with
     22    something more useful
     23 2. Allow the user to easily control what levels are printed to stdout
     24 3. Allow the user to easily control what levels are logged
     25 4. Provide an easy mechanism (like fmt.Println) to print info to the user
     26    which can be easily logged as well 
     27 5. Due to 2 & 3 provide easy verbose mode for output and logs
     28 6. Not have any unnecessary initialization cruft. Just use it.
     29 
     30 # Usage
     31 
     32 ## Step 1. Use it
     33 Put calls throughout your source based on type of feedback.
     34 No initialization or setup needs to happen. Just start calling things.
     35 
     36 Available Loggers are:
     37 
     38  * TRACE
     39  * DEBUG
     40  * INFO
     41  * WARN
     42  * ERROR
     43  * CRITICAL
     44  * FATAL
     45 
     46 These each are loggers based on the log standard library and follow the
     47 standard usage. Eg.
     48 
     49 ```go
     50     import (
     51         jww "github.com/spf13/jwalterweatherman"
     52     )
     53 
     54     ...
     55 
     56     if err != nil {
     57 
     58         // This is a pretty serious error and the user should know about
     59         // it. It will be printed to the terminal as well as logged under the
     60         // default thresholds.
     61 
     62         jww.ERROR.Println(err)
     63     }
     64 
     65     if err2 != nil {
     66         // This error isn’t going to materially change the behavior of the
     67         // application, but it’s something that may not be what the user
     68         // expects. Under the default thresholds, Warn will be logged, but
     69         // not printed to the terminal. 
     70 
     71         jww.WARN.Println(err2)
     72     }
     73 
     74     // Information that’s relevant to what’s happening, but not very
     75     // important for the user. Under the default thresholds this will be
     76     // discarded.
     77 
     78     jww.INFO.Printf("information %q", response)
     79 
     80 ```
     81 
     82 NOTE: You can also use the library in a non-global setting by creating an instance of a Notebook:
     83 
     84 ```go
     85 notepad = jww.NewNotepad(jww.LevelInfo, jww.LevelTrace, os.Stdout, ioutil.Discard, "", log.Ldate|log.Ltime)
     86 notepad.WARN.Println("Some warning"")
     87 ```
     88 
     89 _Why 7 levels?_
     90 
     91 Maybe you think that 7 levels are too much for any application... and you
     92 are probably correct. Just because there are seven levels doesn’t mean
     93 that you should be using all 7 levels. Pick the right set for your needs.
     94 Remember they only have to mean something to your project.
     95 
     96 ## Step 2. Optionally configure JWW
     97 
     98 Under the default thresholds :
     99 
    100  * Debug, Trace & Info goto /dev/null
    101  * Warn and above is logged (when a log file/io.Writer is provided)
    102  * Error and above is printed to the terminal (stdout)
    103 
    104 ### Changing the thresholds
    105 
    106 The threshold can be changed at any time, but will only affect calls that
    107 execute after the change was made.
    108 
    109 This is very useful if your application has a verbose mode. Of course you
    110 can decide what verbose means to you or even have multiple levels of
    111 verbosity.
    112 
    113 
    114 ```go
    115     import (
    116         jww "github.com/spf13/jwalterweatherman"
    117     )
    118 
    119     if Verbose {
    120         jww.SetLogThreshold(jww.LevelTrace)
    121         jww.SetStdoutThreshold(jww.LevelInfo)
    122     }
    123 ```
    124 
    125 Note that JWW's own internal output uses log levels as well, so set the log
    126 level before making any other calls if you want to see what it's up to.
    127 
    128 
    129 ### Setting a log file
    130 
    131 JWW can log to any `io.Writer`:
    132 
    133 
    134 ```go
    135 
    136     jww.SetLogOutput(customWriter) 
    137 
    138 ```
    139 
    140 
    141 # More information
    142 
    143 This is an early release. I’ve been using it for a while and this is the
    144 third interface I’ve tried. I like this one pretty well, but no guarantees
    145 that it won’t change a bit.
    146 
    147 I wrote this for use in [hugo](https://gohugo.io). If you are looking
    148 for a static website engine that’s super fast please checkout Hugo.