lp / globalog

 .d8888b.  888          888               888                        
d88P  Y88b 888          888               888                        
888    888 888          888               888                        
888        888  .d88b.  88888b.   8888b.  888       .d88b.   .d88b.  
888  88888 888 d88""88b 888 "88b     "88b 888      d88""88b d88P"88b 
888    888 888 888  888 888  888 .d888888 888      888  888 888  888 
Y88b  d88P 888 Y88..88P 888 d88P 888  888 888      Y88..88P Y88b 888 
 "Y8888P88 888  "Y88P"  88888P"  "Y888888 88888888  "Y88P"   "Y88888 
                                                                 888 
                                                            Y8b d88P 
                                                             "Y88P"
                                                             
///////////////////////////////////////////////////////////////////////////////////////

This gem aims to provide a global cascading logging system, command line arguments aware,
to centralize the settings of your individual loggers.  

It is thought to be compatible with other gems using OptionParser to collect command line arguments, by hijacking the 
ARGV at require time before others grabs it.  (So, it must be required before say, 'Test/Unit' to hijack the ARGV).

Each individual logger can follow the setting's cascade, or not.  If it does, the command line arguments or the first 
globalog to setup its parameters have precedence over the local settings.  And in case no other globalog is setup is 
present, the local parameters are used for logging.

It is essentially compatible with existing Logger, because it uses logger as it base lib.  So all logging is done the 
same way, with all of logger instance methods also working on globalog instances.  You can then transition code logged 
with logger easily, by either replacing the Logger initialisation in your code by a GlobaLog initialisation, or by 
leaving logger where it is and only deriving its output and level settings from globalog class methods of the same 
names, still allowing you to tap into globalog cascading settings.

The logging in GlobaLog is done with Logger so please refer to its documentation for the logging methodologies: 
http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/

///////////////////////////////////////////////////////////////////////////////////////
Example:

  # script1.rb
  require 'globalog'
  $log = GlobaLog.logger(STDERR,:warn)
  
  module Script1
    def example
      $log.warn("Example") {"Printing Warning!!"}
      $log.info("Example") {"Printing Info!!"}
      $log.debug("Example") {"Printing Debug!!"}
    end
  end
  
calling the example method will result in:

  Script1.example   # => Printing Warning!!
  
But if you require script1, inside an other script, setting different GlobaLog init parameters, they will have 
precedence and cascade down as in the example below.

  # script2.rb
  require 'globalog'
  require 'script1'
  
  $log = GlobaLog.logger(STDERR,:info)
  Script1.example
  
running script2 will output:
  
  > ruby script2.rb
  => Printing Warning!!
  => Printing Info!!
  
And you can also run script2 with arguments to get different log level or output:

  > ruby script2.rb -L debug
  => Printing Warning!!
  => Printing Info!!
  => Printing Debug!!
  
So this allow you to set a default Logger setting in your libraries, override them with an other default setting in 
client scripts and still get the flexibility to override both defaults at runtime by providing command line arguments.  
Ideal for testing purposes where you want a default log level for test overriding the Local log level of your tested 
libraries, while allowing you to choose the test log level at runtime. 
# See Logger rdoc for full operation details: http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/

///////////////////////////////////////////////////////////////////////////////////////

Copyright (c) 2009 Louis-Philippe Perron

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.