##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

##========================================================================
## NAME
=pod

=head1 NAME

DiaColloDB::Logger - DiaColloDB logging (using Log::Log4perl)

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Logger;
 
 ##========================================================================
 ## Globals
 
 $DEFAULT_LOG_CONF = PACKAGE->defaultLogConf(%opts);
 $bool = CLASS::haveFileRotate();
 $bool = CLASS::haveSyslog();
 
 ##========================================================================
 ## Functions: Initialization
 
 undef = PACKAGE->logInit(%opts)  ##-- use default configuration with %opts;
 undef = PACKAGE->ensureLog(@args)        ##-- ensure a Log::Log4perl has been initialized;
 
 ##========================================================================
 ## Methods: get logger
 
 $logger = $class_or_obj->logger();
 
 ##========================================================================
 ## Methods: messages
 
 undef = $class_or_obj->trace(@msg);
 undef = $class_or_obj->llog($level, @msg);
 undef = $class_or_obj->vlog($methodname_or_coderef_or_undef, @msg);
 
 ##========================================================================
 ## Methods: carp & friends
 
 undef = $class_or_obj->logwarn(@msg);
 undef = $class_or_obj->logcarp(@msg);
 undef = $class_or_obj->logcluck(@msg);
 
 undef = $class_or_obj->logdie(@msg);
 undef = $class_or_obj->logcroak(@msg);
 undef = $class_or_obj->logconfess(@msg);
 
 ##========================================================================
 ## Utils: Getopt::Long specification
 
 %getoptLongHash = $PACKAGE->cldbLogOptions(%localOpts);
 
 ##========================================================================
 ## Utils: Profiling
 
 undef = $logger->logProfile($level, $elapsed_secs, $ntoks, $nchrs);
 

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Logger: Globals
=pod

=head2 Globals

=over 4

=item Variable: $MIN_LEVEL

symbolic name of minimum log level (default = minimum-valued key of %Log::Log4perl::Level::LEVELS).

=item Variable: %defaultLogOpts

default log options.

=item defaultLogConf

 $DEFAULT_LOG_CONF = PACKAGE->defaultLogConf(%opts);

Return default configuration for Log::Log4perl;
see L<Log::Log4perl(3pm)|Log::Log4perl>, L<Log::Log4perl::Config(3pm)|Log::Log4perl::Config> for details.

%opts:

 rootLevel => $LEVEL_OR_UNDEF,  ##-- min root log level (default='WARN' or 'FATAL', depending on $^W)
 level     => $LEVEL_OR_UNDEF,  ##-- min log level (default=$MIN_LEVEL or 'INFO', depending on $^W)
 stderr    => $bool,            ##-- whether to log to stderr (default=1)
 logtime   => $bool,            ##-- whether to log time-stamps on stderr (default=0)
 logdate   => $bool,            ##-- whether to log date+time-stamps on stderr (default=0)
 logwhich  => \@classes,        ##-- log4perl-style classes to log (default=qw(DiaColloDB DocClassify DTA.CAB DTA.TokWrap))
 file      => $filename,        ##-- log to $filename if true
 rotate    => $bool,            ##-- use Log::Dispatch::FileRotate if available and $filename is true
 syslog    => $bool,            ##-- use Log::Dispatch::Syslog if available and true (default=false)
 sysLevel  => $level,           ##-- minimum level for syslog (default='debug' or 'info', depending on $^W)
                                ##   : available levels: debug,info,notice,warning,error,critical,alert,emergency (== 0..7)
 sysName   => $sysName,         ##-- name for syslog (default=basename($0))
 sysIdent  => $sysIdent,        ##-- ident string for syslog (default=$sysName)
 sysFacility => $facility,      ##-- facility for syslog (default='daemon')

=item haveFileRotate

 $bool = CLASS::haveFileRotate();

returns true if Log::Dispatch::FileRotate is available

=item haveSyslog

 $bool = CLASS::haveSyslog();

returns true if Log::Dispatch::Syslog is available

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Logger: Functions: Initialization
=pod

=head2 Functions: Initialization

=over 4

=item logInit

 undef = PACKAGE->logInit(%opts)  ##-- use default configuration with %opts;

=over 4

=item *

%opts: see defaultLogConf()

=item *

all log calls in the DiaColloDB namespace should use a subcategory of 'DiaColloDB'

=item *

only needs to be called once; see Log::Log4perl-E<gt>initialized()

=back

=item ensureLog

 undef = PACKAGE->ensureLog(@args)

ensures that Log::Log4perl has been initialized.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Logger: Methods: get logger
=pod

=head2 Methods: get logger

=over 4

=item logger

 $logger = $class_or_obj->logger();
 $logger = $class_or_obj->logger($category);

=over 4

=item *

wrapper for Log::Log4perl::get_logger($category)

=item *

$category defaults to ref($class_or_obj)||$class_or_obj

=back

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Logger: Methods: messages
=pod

=head2 Methods: messages

=over 4

=item trace

=item debug

=item info

=item warn

=item error

=item fatal

 undef = $class_or_obj->trace(@msg);

Log::Log4perl wrappers.
Be sure you have called Log::Log4perl::init() or similar first.

=item llog

 undef = $class_or_obj->llog($level, @msg);

Log at level $level,
which should be some constant exported by Log::Log4perl::Level.

=item vlog

 undef = $class_or_obj->vlog($methodname_or_coderef_or_undef, @msg);

Log via $methodname_or_coderef_or_undef;
calls $methodname_or_coderef_or_undef($class_or_obj,@msg) if defined,
e.g.

 $class_or_obj->vlog('trace', @msg);

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Logger: Methods: carp & friends
=pod

=head2 Methods: carp & friends

=over 4

=item logwarn

=item logcarp

=item logcluck

=item logdie

=item logcroak

=item logconfess

 $class_or_obj->logwarn(@msg);

Wraps $class_or_obj-E<gt>logger-E<gt>logwarn(@msg), etc.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Logger: Utils: Getopt::Long specification
=pod

=head2 Utils: Getopt::Long specification

=over 4

=item cldbLogOptions

 %getoptLongHash = $PACKAGE->cldbLogOptions(%localOpts);

Return Getopt::Long|Getopt::Long> option hash for common logging options.

%localOpts:

 verbose => $bool,   ##-- if true, add 'verbose|v' as alias for 'log-level'

Supports the following options:

 'log-level|loglevel|ll|L=s' => \$defaultLogOpts{level},
 'log-config|logconfig|log4perl-config|l4p-config|l4p=s' => \$defaultLogOpts{l4pfile},
 'log-watch|logwatch|watch|lw=i' => \$defaultLogOpts{watch},
 'nolog-watch|nologwatch|nowatch|nolw' => sub { $defaultLogOpts{watch}=undef; },
 'log-stderr|stderr|lse!' => \$defaultLogOpts{stderr},
 'log-file|lf=s' => \$defaultLogOpts{file},
 'nolog-file|nolf' => sub { $defaultLogOpts{file}=undef; },
 'log-rotate|rotate|lr!' => \$defaultLogOpts{rotate},
 'log-syslog|syslog|ls!' => \$defaultLogOpts{syslog},
 'log-option|logopt|lo=s' => \%defaultLogOpts,


=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Logger: Utils: Profiling
=pod

=head2 Utils: Profiling

=over 4

=item logProfile

 undef = $logger->logProfile($level, $elapsed_secs, $ntoks, $nchrs);

Produces a profiling string used by command-line utilities, logged at level $level
via vlog().

=back

=cut

##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2015-2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.14.2 or,
at your option, any later version of Perl 5 you may have available.

=head1 SEE ALSO

L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
