package Msg;

#==============================================================================
# Copyright and license info is available in the LICENSE file included with
# the Server Deployment Package (SDP), and also available online:
# https://swarm.workshop.perforce.com/projects/perforce-software-sdp/view/main/LICENSE
#------------------------------------------------------------------------------

=head1 NAME

Msg.pm - Output messages with verbosity control.

=head1 VERSION

2.6.2

=head1 DESCRIPTION

This package provides a standard way to write log messages, and sets the global $Cmd::Verbosity setting.

Other variations of this package provide additional logging channels (e.g. file appenders, screen appenders, etc.).  This version is optimized to minizme external dependencies.

=head1 PUBLIC DATA

=head1 EXAMPLES

Here is a typical usage example:

=over 4

C<$Msg = Msg::new();> # Done once at the start of a program.

C<$Msg->info("This is a normal info message.");>

C<$Msg->logdie ("Famous last words:  Ahhhhhh!");>

=back

=head1 PUBLIC FUNCTIONS

=cut

require Exporter;

use strict;
use File::Path;
use File::Basename;
use POSIX qw(uname);

# The next line avoids problems with 'use strict'.
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $FATAL $ERROR $WARN $INFO $DEBUG $TRACE $Msg $Level %MsgLevelText);

# Initialization processing occurs in the BEGIN block.
BEGIN
{
   # Keep $VERSION value the same as at the top of this file.
   $VERSION = "2.6.2";

   ($FATAL, $ERROR, $WARN, $INFO, $DEBUG, $TRACE) = (1, 2, 3, 4, 5, 6);
   $Level = $INFO;

   $MsgLevelText{'1'} = "FATAL";
   $MsgLevelText{'2'} = "ERROR";
   $MsgLevelText{'3'} = "WARN";
   $MsgLevelText{'4'} = "INFO";
   $MsgLevelText{'5'} = "DEBUG";
   $MsgLevelText{'6'} = "TRACE";
}

# Package interface standards.
@ISA = qw(Exporter);
@EXPORT = qw($Msg $FATAL $ERROR $WARN $INFO $DEBUG $TRACE);
@EXPORT_OK = qw(GetLevel SetLevel $LogFile $Level %MsgLevelText);

# Prototypes for public functions.
sub new();
sub GetLevel ();
sub SetLevel ($$;);
sub fatal ($$;);
sub error ($$;);
sub warn ($$;);
sub info ($$;);
sub debug ($$;);
sub trace ($$;);
sub logdie ($$;);

#==============================================================================
# Public Functions
#==============================================================================

#------------------------------------------------------------------------------
sub new ()
{
   my $self = {};
   shift;
   bless ($self);
   return $self;
}

#------------------------------------------------------------------------------

=head2 GetLevel()

GetLevel()

=head3 Description-GetLevel

Get the logging/output verbosity level set previously with SetLevel().

=head3 Parameters-GetLevel

None

=head3 Returns-GetLevel

None

=head3 Examples-GetLevel

C<if (Msg::GetLevel() &gt;= $INFO) { make_noise();} ;>

=cut

#------------------------------------------------------------------------------
sub GetLevel ()
{
   return $Level;
}

#------------------------------------------------------------------------------

=head2 SetLevel()

SetLevel($I<verbosity>;)

=head3 Description-SetLevel

Set the logging/output verbosity level.  Each log message has an assigned verbosity level.  Messages at or below the current verobsity level are displayed.  Messages above the specified level are suppressed.  A higher numeric value generally results in increased log output.

For example, specifying a value of 4 causes FATAL, ERROR, WARN, and INFO messages to be displayed, while DEBUG and TRACE messages are suppressed.

=head3 Parameters-SetLevel

$I<verbosity> - Specify the verbosity as a numeric value from 1-6.  Each numeric value corresponds to a certain type of message:

=over 4

=item 1 = FATAL

=item 2 = ERROR

=item 3 = WARN

=item 4 = INFO

=item 5 = DEBUG

=item 6 = TRACE

=back

For example, specifying a value of 4 causes FATAL, ERROR, WARN, and INFO messages to be displayed, while DEBUG and TRACE messages are suppressed.

=head3 Returns-SetLevel

None

=head3 Examples-SetLevel

To enable INFO-level logging:

C<Msg::SetLevel (4);>

=cut

#------------------------------------------------------------------------------
sub SetLevel ($$;)
{
   shift;
   $Level = shift;
   $Cmd::Verbosity = $Level;
}

#------------------------------------------------------------------------------
sub fatal ($$;)
{
   shift;
   my ($msg) = @_;
   print "FATAL: $msg\n" if ($Level >= $FATAL);
}

#------------------------------------------------------------------------------
sub error ($$;)
{
   shift;
   my ($msg) = @_;
   print "ERROR: $msg\n" if ($Level >= $ERROR);
}

#------------------------------------------------------------------------------
sub warn ($$;)
{
   shift;
   my ($msg) = @_;
   print "WARN: $msg\n" if ($Level >= $WARN);
}

#------------------------------------------------------------------------------
sub info ($$;)
{
   shift;
   my ($msg) = @_;
   print "INFO: $msg\n" if ($Level >= $INFO);
}

#------------------------------------------------------------------------------
sub debug ($$;)
{
   shift;
   my ($msg) = @_;
   print "DEBUG: $msg\n" if ($Level >= $DEBUG);
}

#------------------------------------------------------------------------------
sub trace ($$;)
{
   shift;
   my ($msg) = @_;
   print "TRACE: $msg\n" if ($Level >= $TRACE);
}

sub logdie ($$;)
{
   shift;
   my ($msg) = @_;
   die "\n\nFATAL:  $msg\n\n";
}

# Return package load success.
1;