Log::Log4perl::CommandLine - Simple Command Line Interface for Log4perl
# Simple: just use the Module, with all the options use Log::Log4perl::CommandLine qw(:all); # Then run your program my_program.pl --verbose my_program.pl -v my_program.pl --debug my_program.pl -d my_program.pl --quiet my_program.pl -q # Flexible: include specific logging options: use Log::Log4perl::CommandLine qw(q v d); # or use Log::Log4perl::CommandLine qw(:short); use Log::Log4perl::CommandLine qw(quiet verbose); # or use Log::Log4perl::CommandLine qw(:long); use Log::Log4perl::CommandLine qw(trace debug info warn error fatal off); # or use Log::Log4perl::CommandLine qw(:levels); # q = quiet = off # v = verbose = info # d = debug my_program.pl --debug my_program.pl --debug MyModule my_program.pl --debug MyModule,MyOtherModule --debug Foo # Override configuration on command line: use Log::Log4perl::CommandLine qw(logconfig logfile loglevel); or use Log::Log4perl::CommandLine qw(:logopts); my_program.pl --logconfig /some/log4perl.conf my_program.pl --logfile /my/logfile.log my_program.pl --loglevel MyCat=debug # equivalent to "-debug MyCat" my_program.pl --loglevel MyCat=mylevel # can use for custom log levels # Include simple Log4perl configurations: use Log::Log4perl::CommandLine qw(:logconfig /my/default/log4perl.conf); use Log::Log4perl::CommandLine qw(:logfile /my/default/logfile.log); # These match Log::Log4perl->easy_init(): use Log::Log4perl qw(:levels); # needed to define constants use Log::Log4perl::CommandLine ':loginit' => { level => $INFO }; use Log::Log4perl::CommandLine ':loginit' => { layout => '%d %c %m%n' }; use Log::Log4perl::CommandLine ':loginit' => { level => $WARN, layout => '%d %c %m%n' }; use Log::Log4perl::CommandLine ':loginit' => [ { level => $WARN, layout => '%d %c %m%n', category => 'foo', file => '>>foo.log' }, { level => $DEBUG, category => 'bar', file => '>>bar.log' } ]; # or inline a log4perl configuration: use Log::Log4perl::CommandLine ':loginit' => q(...some log4perl config...); # control which logger the unspecified levels affect: use Log::Log4perl::CommandLine qw(:logcategory root); # or use Log::Log4perl::CommandLine qw(:logcategory main); # if you don't specify :logcategory, levels INFO and higher => 'root', # and DEBUG and TRACE => 'main' (see below) # If you want to do your own initialization: use Log::Log4perl::CommandLine qw(:all :noinit); ... initialize Log4perl yourself... # Explicitly handle log command line options now Log::Log4perl::CommandLine::handlelogoptions(); # Also call handlelogoptions() explicitly if you later redefine Log4perl # Export handlelogoptions() to caller's namespace use Log::Log4perl::CommandLine qw(handlelogoptions); handlelogoptions();
Log::Log4perl::CommandLine parses some command line options, allowing for simple configuration of Log4perl using the command line, or easy, temporary overriding of a more complicated Log4perl configuration from a file.
Log::Log4perl::CommandLine
If you want to use the constants ($ERROR, $INFO, etc.), you must use Log::Log4perl.
use Log::Log4perl
Any options parsed and understood by this module are stripped from @ARGV (by Getopt::Long), so they won't interfere with later command line parsing.
@ARGV
Getopt::Long
See Log::Log4perl::CommandLine::Cookbook for examples of usage.
These enable command line options, parsed with Getopt::Long, so you can precede them on the command line with either '-' or '--'.
On the use line, you can explicitly specify just the options you want, or the group (:short :long :levels) or :all to get them all.
use
q = quiet = off
v = verbose = info
d = debug
Each of these "level" options sets the logging level to the specified level. They each take an optional parameter with the category (or categories) to apply the level to, or can be specified multiply.
e.g. --debug --debug MyCategory --debug Foo,Bar --debug Foo --debug Bar
If the optional parameter is not specified, the default behavior is to apply the level to the root logger if the level is OFF, FATAL, ERROR, WARN or INFO and to the 'main' logger if the level is DEBUG or TRACE. This may seem a little weird, and it took me a while to come to this default, but it fits the way I work best.
OFF
FATAL
ERROR
WARN
INFO
DEBUG
TRACE
This means: my_program.pl -q or --quiet
suppresses warnings and errors in the whole logger hierarchy (unless you've explicitly forced them through some other Log4perl setting) -- usually what I want quiet to mean. Likewise, -v tells every module to be a little more verbose.
my_program.pl -d or --debug or --trace
however, just apply to the main program, so I don't get debugging information from other modules I'm not working on.
You can also specifically refer to the root category with 'root':
my_program.pl --trace root
If you don't like this behavior, you can explicitly define the default log category with :logcategory <category>
:logcategory <category>
This is the category to use if one isn't specified in one of the level options.
--loglevel verbose --loglevel MyModule=debug --loglevel Foo=info,main=debug --loglevel foo=info --loglevel main=debug
This is just another way to set the level. This can help avoid option space pollution if you already use the standard options for other purposes, or if you've defined special Log4perl levels beyond the standard ones (but don't do that).
Enable --logconfig /my/log4perl.conf to override the entire Log4perl configuration.
--logconfig /my/log4perl.conf
Enable --logfile /my/logfile.log to create a log file. You can also append a special layout for the log file like this:
--logfile /my/logfile.log
my_program.pl --logfile '/my/logfile.log|%d %m%n'
Be sure to respect your shell's metacharacters and quote when needed.
Specify a Log4perl configuration file. Contrary to normal Log4perl, it is OK if the file is missing, things will just proceed with the default configuration.
Specify a default log file. Similar to the --logfile option, you can append a layout :logfile '/my/logfile.log|%d %m%n'
:logfile '/my/logfile.log|%d %m%n'
See basic examples in SYNOPSIS, Cookbook or Log::Log4perl for more details.
See basic examples in Cookbook or Log::Log4perl for more details.
Disable all the automatic Log4perl initialization. You must call handlelogoptions() explicitly after you initialize Log4perl yourself.
:noinit is incompatible with the '--logconfig' command line option.
Exports the handlelogoptions() subroutine to the caller's namespace. Call handlelogoptions() after re-initializing Log4perl to re-apply the command line overrides.
Curt Tilmes, <ctilmes@cpan.org>
Copyright 2008 by Curt Tilmes
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Log::Log4perl::CommandLine, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Log::Log4perl::CommandLine
CPAN shell
perl -MCPAN -e shell install Log::Log4perl::CommandLine
For more information on module installation, please visit the detailed CPAN module installation guide.