Sindbad~EG File Manager

.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Log::ger 3pm"
.TH Log::ger 3pm "2022-06-10" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Log::ger \- A lightweight, flexible logging framework
.SH "VERSION"
.IX Header "VERSION"
version 0.040
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "Producing logs"
.IX Subsection "Producing logs"
In your module (producer):
.PP
.Vb 1
\& package MyModule;
\&
\& # this will install some logger routines. by default: log_trace, log_debug,
\& # log_info, log_warn, log_error, and log_fatal. level checker routines are also
\& # installed: log_is_trace, log_is_debug, and so on.
\& use Log::ger;
\&
\& sub foo {
\&     ...
\&     # produce some logs. no need to configure output or level. by default
\&     # output goes nowhere.
\&     log_error "an error occured: %03d \- %s", $errcode, $errmsg;
\&     ...
\&
\&     # the logging routines (log_*) can automatically dump of data structure
\&     log_debug "http response: %s", $http;
\&
\&     # log_fatal does not die by default, if you want to then die() explicitly.
\&     # but there are plugins that let you do this or provide log_die etc.
\&     if (blah) { log_fatal "..."; die }
\&
\&     # use the level checker routines (log_is_*) to avoid doing unnecessary
\&     # heavy calculation
\&     if (log_is_trace) {
\&         my $res = some_heavy_calculation();
\&         log_trace "The result is %s", $res;
\&     }
\&
\& }
\& 1;
.Ve
.SS "Consuming logs"
.IX Subsection "Consuming logs"
\fIChoosing an output\fR
.IX Subsection "Choosing an output"
.PP
In your application (consumer/listener):
.PP
.Vb 4
\& use MyModule;
\& use Log::ger::Output \*(AqScreen\*(Aq; # configure output
\& # level is by default \*(Aqwarn\*(Aq
\& foo(); # the error message is shown, but debug/trace messages are not.
.Ve
.PP
\fIChoosing multiple outputs\fR
.IX Subsection "Choosing multiple outputs"
.PP
Instead of screen, you can output to multiple outputs (including multiple
files):
.PP
.Vb 10
\& use Log::ger::Output \*(AqComposite\*(Aq => (
\&     outputs => {
\&         Screen => {},
\&         File   => [
\&             {conf=>{path=>\*(Aq/path/to/app.log\*(Aq}},
\&             ...
\&         ],
\&         ...
\&     },
\& );
.Ve
.PP
See Log::ger::Manual::Tutorial::481_Output_Composite for more examples.
.PP
There is also Log::ger::App that wraps this in a simple interface so you just
need to do:
.PP
.Vb 3
\& # In your application or script:
\& use Log::ger::App;
\& use MyModule;
.Ve
.PP
\fIChoosing level\fR
.IX Subsection "Choosing level"
.PP
One way to set level:
.PP
.Vb 3
\& use Log::ger::Util;
\& Log::ger::Util::set_level(\*(Aqdebug\*(Aq); # be more verbose
\& foo(); # the error message as well as debug message are now shown, but the trace is not
.Ve
.PP
There are better ways, e.g. letting users configure log level via configuration
file or command-line option. See Log::ger::Manual::Tutorial::300_Level for
more details.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Log::ger is yet another logging framework with the following features:
.IP "\(bu" 4
Separation of producers and consumers/listeners
.Sp
Like Log::Any, this offers a very easy way for modules to produce some logs
without having to configure anything. Configuring output, level, etc can be done
in the application as log consumers/listeners. To read more about this, see the
documentation of Log::Any or Log::ger::Manual (but nevertheless see
Log::ger::Manual on why you might prefer Log::ger to Log::Any).
.IP "\(bu" 4
Lightweight and fast
.Sp
\&\fBSlim distribution.\fR No non-core dependencies, extra functionalities are
provided in separate distributions to be pulled as needed.
.Sp
\&\fBLow startup overhead.\fR Only ~0.5\-1ms. For comparison, strict ~0.2\-0.5ms,
warnings ~2ms, Log::Any (v0.15) ~2\-3ms, Log::Any (v1.049) ~8\-10ms,
Log::Log4perl ~35ms. This is measured on a 2014\-2015 \s-1PC\s0 and before doing any
output configuration. I strive to make \f(CW\*(C`use Log::ger;\*(C'\fR statement to be roughly
as light as \f(CW\*(C`use strict;\*(C'\fR or \f(CW\*(C`use warnings;\*(C'\fR so the impact of adding the
statement is really minimal and you can just add logging without much thought to
most of your modules. This is important to me because I want logging to be
pervasive.
.Sp
To test for yourself, try e.g. with bencher-code:
.Sp
.Vb 1
\& % bencher\-code \*(Aquse Log::ger\*(Aq \*(Aquse Log::Any\*(Aq \-\-startup
.Ve
.Sp
\&\fBFast\fR. Low null\-/stealth\-logging overhead, about 1.5x faster than Log::Any, 3x
faster than Log4perl, 5x faster than Log::Fast, ~40x faster than
Log::Contextual, and ~100x faster than Log::Dispatch.
.Sp
For more benchmarks, see Bencher::Scenarios::LogGer.
.Sp
\&\fBConditional compilation.\fR There is a plugin to optimize away unneeded logging
statements, like assertion/conditional compilation, so they have zero runtime
performance cost. See Log::ger::Plugin::OptAway.
.Sp
Being lightweight means the module can be used more universally, from \s-1CLI\s0 to
long-running daemons to inside routines with tight loops.
.IP "\(bu" 4
Flexible
.Sp
\&\fBCustomizable levels and routine/method names.\fR Can be used in a procedural or
\&\s-1OO\s0 style. Log::ger can mimic the interface of Log::Any, Log::Contextual,
Log::Log4perl, or some other popular logging frameworks, to ease migration or
adjust with your personal style.
.Sp
\&\fBPer-package settings.\fR Each importer package can use its own format/layout,
output. For example, a module that is migrated from Log::Any uses Log::Any\-style
logging, while another uses native Log::ger style, and yet some other uses block
formatting like Log::Contextual. This eases code migration and teamwork. Each
module author can preserve her own logging style, if wanted, and all the modules
still use the same framework.
.Sp
\&\fBDynamic.\fR Outputs and levels can be changed anytime during run-time and logger
routines will be updated automatically. This is useful in situation like a
long-running server application: you can turn on tracing logs temporarily to
debug problems, then turn them off again, without restarting your server.
.Sp
\&\fBInteroperability.\fR There are modules to interop with Log::Any, either consume
Log::Any logs (see Log::Any::Adapter::LogGer) or produce logs to be consumed
by Log::Any (see Log::ger::Output::LogAny).
.Sp
\&\fBMany output modules and plugins.\fR See \f(CW\*(C`Log::ger::Output::*\*(C'\fR,
\&\f(CW\*(C`Log::ger::Format::*\*(C'\fR, \f(CW\*(C`Log::ger::Layout::*\*(C'\fR, \f(CW\*(C`Log::ger::Plugin::*\*(C'\fR. Writing
an output module in Log::ger is easier than writing a Log::Any::Adapter::*.
.PP
For more documentation, start with Log::ger::Manual.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Some other popular logging frameworks: Log::Any, Log::Contextual,
Log::Log4perl, Log::Dispatch, Log::Dispatchouli.
.PP
If you still prefer debugging using the good old \f(CW\*(C`print()\*(C'\fR, there's
Debug::Print.
.SH "AUTHOR"
.IX Header "AUTHOR"
perlancar <perlancar@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2022, 2020, 2019, 2018, 2017 by perlancar <perlancar@cpan.org>.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.