out | leveled output

Formatters can be attached at any output level (or to all output levels). They are currently independent of output target meaning they get the raw message that is being given (to screen or log), even before it’s determined if screen or log file output is active (based on thresholds and such) and before the message has been prefixed or augented with flag metadata. The formater can change the message, augment it, make it empty and can also tell the out package to skip prefixes and flags based meta-data additions if desired…​ and can even tell the out package NOT to dump the message to either screen or log file or both if desired. A formatter is a Go interface so if one implements the interface with an empty struct, for example, then one can instantiate that and use SetFormatter() to attach it to any of the log levels (or all of them). Note that the formatter will be told if this is a terminal type issue (IssueExit(), ErrorExit() or Fatal()) so a tool can behave correctly if dying or not. One would use a custom formatter if one wished to do something like: 1. Skip all output prefixing and meta-data markup and use my own custom setup 2. Dynamically morph a message (eg: add error code to msg, morph it to JSON) 3. Take the message and NOT dump it to screen and/or log, redirect it elsewhere 4. Whatever else you can think of. This was created for flexiblity. For example, one CLI tool that I created had the ability to dump human readable output or JSON structured output (the latter allowed any tool running my tool to more easily parse/handle any output, the former allowed a regular user to use the tool sensically). In the case of JSON output, it was important that any terminal Issue/Error/Fatal type of call, from anywhere in the code, resulted in a JSON formatted error and that any non-terminal call stored the issue/error so that the final JSON output dump could have a warning field in it that would contain all of these lesser classes of warnings (ie: non-terminal). To accomplish these non-terminal errors were stored for inclusion in the final JSON output in a warnings key (with log level, error and any code set) along with the tools standard JSON output. Another example use was to create a daemon tool that dumped fairly key/value oriented but still human readlable output (to the screen) but also dumped a JSON formatted form of this output to a log file (rotation managed by this package). The end result was an init log that was more understandable by a human (as well as the ability to run the daemon in a "single run" mode as a user and understand it’s output on-screen)…​ and a JSON formatted log that was then ingested into Elasticsearch via the Beats mechanism. This was a bit more work…​ but basically all output levels ran the output through the formatter, pulling out key/vals into JSON key/vals and logging the entire output line along with that additional data in a JSON format. This has worked fairly well (although improved key/value association with a print might be a possible future improvement here to avoid the extra parsing stage to pull this data back out for the JSON logging used today). Note: this package is currently a singleton…​ for a variety of reasons, but that too could be something that could be considered for improvement to allow key/vals to be associated in a nested way with the output routines (similar to how some nice key/val based loggers work today, eg: gokit’s logger).
One can register a single function to be called just before your tool will exit. This only works if one is always exiting via calls to out.Exit() or out.Fatal() or the out.\*Exit() functions. This can be useful to generate summary data or, really, do anything you want before your tool terminates. Use is pretty easy:. If one wants to clear it set it to nil via SetDeferFunc() and if one wants to see if it’s currently set and what it is set to use DeferFunc() to get it. One should set this up as soon as one has a need for some pre-exit function. Again, it will NOT fire for os.Exit() called directly (or indirectly by something like log.Fatal() and such, only works with the out pkg exit mechanisms).