NAME

    Logging::Simple - A simple but flexible logging mechanism.

SYNOPSIS

        use Logging::Simple;
    
        my $log = Logging::Simple->new(name => 'whatever'); # name is optional
    
        $log->warning("default level (4)");
    
        $log->_4("all levels can be called by number. This is warning()");
    
        $log->_7("this is debug(). Default level is 4, so this won't print");
    
        $log->level(7);
    
        $log->debug("same as _7(). It'll print now");
    
        $log->level('=3');
        $log->_3("with a prepending '=' on level, we'll log this level ONLY");
    
        $log->fatal("log a message along with confess() output, and terminate");
    
        $log->level(-1); # disables all levels from doing anything
    
        $log->file('file.log');
        $log->info("this will go to file");
        $log->file(0); # back to STDOUT
    
        $log->_6("info facility, example output");
        #[2016-03-17 16:49:32.491][info][whatever] info facility, example output
    
        $log->display(0);
        $log->info("display(0) disables all output but this msg");
        $log->info("see display() method for disabling, enabling individual tags");
    
        $log->display(1);
        $log->info("all tags enabled");
        #[2016-03-17 16:52:06.356][info][whatever][5689][t/syn.pl|29] all tags enabled
    
        $log->print(0);
        my $log_entry = $log->info("print(0) disables printing and returns the entry");

DESCRIPTION

    Lightweight (core-only) and very simple yet flexible debug tool for
    printing or writing to file log type entries based on a configurable
    level (0-7).

    It provides the ability to programmatically change which output tags to
    display, provides numbered methods so you don't have to remember the
    name to number level translation, provides the ability to create
    descendent children, easily enable/disable file output, levels, display
    etc.

 Logging entry format

    By default, log entries appear as such, with a timestamp, the name of
    the facility, the name (if specified in the constructor) and finally
    the actual log entry message.

        [2016-03-17 17:01:21.959][info][whatever] info facility, example output

    All of the above tags can be enabled/disabled programatically at any
    time, and there are others that are not enabled by default. See display
    method for details.

 Levels

    Verbosity levels and associated named equivalents:

    -1, disables all levels

    0, 'emergency|emerg'

    1, 'alert'

    2, 'critical|crit'

    3, 'error|err'

    4, 'warning|warn'

    5, 'notice'

    6, 'info'

    7, 'debug'

    Note that all named level methods have an associated _N method, so you
    don't have to remember the names at all. Using the numbers is often
    much easier.

    Setting the level will display all messages related to that level and
    below.

INITIALIZATION METHODS

 new(%args)

    Builds and returns a new Logging::Simple object. All arguments are
    optional, and they can all be set using accessor methods after
    instantiation. These params are:

        name        => $str  # optional, default is undef
        level       => $num  # default 4, options, 0..7, -1 to disable all
        file        => $str  # optional, default undef, send in a filename
        write_mode  => $str  # defaults to append, other option is 'write'
        print       => $bool # default on, enable/disable output and return instead
        display     => $bool # default on, enable/disable log message tags

    Each of the above parameters have associated methods described below
    with more details.

 level($num)

    Set and return the facility level. Will return the current value with a
    param sent in or not. It can be changed at any time. Note that you can
    set this with the LS_LEVEL environment variable, at any time. the next
    method call regardless of what it is will set it appropriately.

 file('file.log', 'mode')

    By default, we write to STDOUT. Send in the name of a file to write
    there instead. Mode is optional; we'll append to the file by default.
    Send in 'w' or 'write' to overwrite the file.

 display(%hash|$bool)

    List of log entry tags, and default printing status:

        name  => 1, # specified in new() or name()
        time  => 1, # timestamp
        label => 1, # the string value of the level being called
        pid   => 0, # process ID
        proc  => 0, # "filename|line number" of the caller

    In hash param mode, send in any or all of the tags with 1 (enable) or 0
    (disable).

    You can also send in 1 to enable all of the tags, or 0 to disable them
    all.

 fatal($msg)

    Log the message, along with the trace confess() produces, and die
    immediately.

 custom_display($str|$false)

    This will create a custom tag in your output, and place it at the first
    column of the output. Send in 0 (false) to disable/clear it.

 print($bool)

    Default is enabled. If disabled, we won't print at all, and instead,
    return the log entry as a scalar string value.

 child($name)

    This method will create a clone of the existing Logging::Simple object,
    and then concatenate the parent's name with the optional name sent in
    here for easy identification in the logs.

    All settings employed by the parent will be used in the child, unless
    explicity changed via the methods.

    In a module or project, you can create a top-level log object, then in
    all subs, create a child with the sub's name to easily identify flow
    within the log. In an OO project, stuff the parent log into the main
    object, and clone it from there.

LOGGING METHODS

 emergency($msg)

    Level 0

    aka: _0(), emerg()

 alert($msg)

    Level 1

    aka: _1()

 critical($msg)

    Level 2

    aka: _2(), crit()

 error($msg)

    Level 3

    aka: _3(), err()

 warning($msg)

    Level 4

    aka: _4(), warn()

 notice($msg)

    Level 5

    aka: _5()

 info($msg)

    Level 6

    aka: _6()

 debug($msg)

    Level 7

    aka: _7()

HELPER METHODS

    These methods may be handy to the end user, but aren't required for
    end-use.

 levels('names')

    Returns the hash of level_num => level_name mapping.

    If the optional string names is sent in, we'll return an array of just
    the names, in numeric order from lowest to highest.

 timestamp

    Returns the current time in the following format: 2016-03-17
    17:51:02.241

AUTHOR

    Steve Bertrand, <steveb at cpan.org>

BUGS

    Please report any bugs or feature requests to
    https://github.com/stevieb9/p5-logging-simple/issues

REPOSITORY

    https://github.com/stevieb9/p5-logging-simple

BUILD RESULTS (THIS VERSION)

    CPAN Testers: http://matrix.cpantesters.org/?dist=Logging-Simple

SUPPORT

    You can find documentation for this module with the perldoc command.

        perldoc Logging::Simple

SEE ALSO

    There are too many other logging modules to list here, but the idea for
    this one came from Log::Basic. However, this one was written completely
    from scratch.

LICENSE AND COPYRIGHT

    Copyright 2016 Steve Bertrand.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.