Subversion Repositories DevTools

########################################################################

# COPYRIGHT - VIX IP PTY LTD ("VIX"). ALL RIGHTS RESERVED.

#

# Module name   : JatsError

# Module type   : Perl Package

# Compiler(s)   : Perl

# Environment(s): jats

#

# Description   : A Perl Package to perform error handling within JATS

#

#                 Uses global variables

#                       $::ScmVerbose;

#                       $::ScmQuiet;

#                       $::ScmDebug;

#                 For use with existing scripts

#

#......................................................................#

package JatsError;

use base qw(Exporter);

require 5.006_001;

use strict;

use warnings;

use Data::Dumper;

use IO::Handle;

# exported package globals go here

#our $ScmVerbose;

#our $ScmDebug;

#our $ScmQuiet;

our $ScmOnExit;

our $ScmDelayExit;

our $ScmErrorCount;

our $ScmExitCode;

my $EPrefix = '';

my $EName = '';

my $EFn = '';

my $ElPrefix = '';

my $EIndent = '';

my $EOffset = '';

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

# Function        : BEGIN

#

# Description     : Standard Package Interface

#

# Inputs          :

#

# Returns         :

#

BEGIN {

    our ($VERSION, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);

    # set the version for version checking

    $VERSION     = 1.00;

    @EXPORT      = qw(ErrorConfig ErrorReConfig ErrorDoExit

                      ReportError Fatal Error Warning

                      Message Message1

                      Information Information1

                      Question

                      Verbose0 Verbose Verbose2 Verbose3

                      Debug0 Debug Debug2 Debug3

                      IsVerbose IsDebug IsQuiet

                      DebugDumpData DebugDumpPackage DebugTraceBack

                      DebugPush DebugPop

                      StartCapture

                      DumpCapture

                      );

    %EXPORT_TAGS = ( );     # eg: TAG => [ qw!name1 name2! ],

    # your exported package globals go here,

    # as well as any optionally exported functions

    @EXPORT_OK   = qw();

    #

    #   Ensure globals have a defined value

    #

    $::ScmVerbose = $ENV{GBE_VERBOSE} || 0  unless defined( $::ScmVerbose );

    $::ScmDebug = $ENV{GBE_DEBUG} || 0      unless defined( $::ScmDebug );

    $::ScmQuiet = 0                         unless defined( $::ScmQuiet );

    $ScmErrorCount = 0;

    $ScmExitCode = 1;

    #

    #   Force autoflush in an attempt to limit the intermingling of

    #   Error and non-error output.

    #

    STDOUT->autoflush(1);

    STDERR->autoflush(1);

}

# non-exported package globals go here

my @captured;

my $capturing;

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

# Function        : import

#

# Description     : Package import function

#                   This function will examine arguments provided in the

#                   invoking 'uses' list and will configure the package

#                   accordingly.

#

# Inputs          : $pack           - Name of this package

#                   @vars           - User Config Options

#                   Config Options:

#                       :name=xxxx

#                       :function=xxxx

#                       :prefix=xxxx

#                       :indent=nn/xxx

#                       :offset=nn/xxx

#                       :quiet=xxx

#                       :debug=xxx

#                       :verbose=xxx

#                       :delay_exit=xxx

#

# Returns         : 

#

sub import {

    my $pack = shift;

    my @vars;

    my @config;

    #

    #   Extract options of the form: :name=value and pass them to the

    #   ErrorConfig function. All other arguments will be passed to the

    #

    foreach ( @_ )

    {

        if ( m/^:(.+)=(.+)/ ) {

            push @config, $1, $2;

        } else {

            push @vars, $_;

        }

    }

    ErrorConfig( @config )

        if ( @config );

    #

    #   Invoke Exporter function to handle the arguments that I don't understand

    #

    $pack->export_to_level(1, $pack , @vars);

}

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

# Function        : ErrorConfig

#

# Description     : Configure aspects of the JATS error handle

#                   See ErrorReConfig

#

# Inputs          : A hash of option,value pairs

#                   Valid options

#                       name        - Name to report in error

#                       function    - Name of enclosing function

#                       prefix      - 1st line prefix

#                       verbose     - vebosity level

#                       debug       - debug level

#                       on_exit     - Register on-exit function

#                       delay_exit  - Delay exit on error

#                       prefix      - Optional prefix. First line only

#                       indent      - Optional. All lines (number or text)

#                       offset      - Optional. Extra lines (number or text)

#

# Returns         :

#

sub ErrorConfig

{

    my %args = @_;

    while (my($key, $value) = each %args)

    {

        if ( $key =~ /^name/ ) {

            $EName = $value;

        } elsif ( $key =~ /^function/ ) {

            $EFn = ':' . $value;

        } elsif ( $key =~ /^prefix/ ) {

            $ElPrefix = $value;

        } elsif ( $key =~ /^indent/ ) {

            my $pad = $value;

            if ($pad =~ m~^\d+$~) {

                $pad = ' ' x $value;

            }

            $EIndent = $EIndent . $pad;

        } elsif ( $key =~ /^offset/ ) {

            $EOffset = $value;

            if ($EOffset =~ m~^\d+$~) {

                $EOffset = ' ' x $value;

            }

        } elsif ( $key =~ /^debug/ ) {

            $::ScmDebug = $value

                if ( defined $value && $value > $::ScmDebug  );

        } elsif ( $key =~ /^verbose/ ) {

            $::ScmVerbose = $value

                if ( defined $value && $value > $::ScmVerbose  );

        } elsif ( $key =~ /^quiet/ ) {

            $::ScmQuiet = $value || 0;

        } elsif ( $key =~ /^on_exit/ ) {

            $ScmOnExit = $value;

        } elsif ( $key =~ /^delay_exit/ ) {

            $ScmDelayExit = $value;

        } elsif ( $key =~ /^exitCode/i ) {

            $ScmExitCode = $value || 1;

        } else {

            Error("ErrorConfig, Unknown option: $key");

        }

    }

    #

    #   Calculate the prefix to all messages

    #   Based on Name and Function( if provided

    #

    $EPrefix = "[$EName$EFn] " if $EName;

    #

    #   Extract program specfic debug flags from the environment

    #   These will be based on the reporting 'name'

    #       GBE_name_DEBUG

    #       GBE_name_VERBOSE

    #

    if ( $EName )

    {

        my ($value, $tag);

        $tag = "GBE_${EName}_DEBUG" ;

        $tag =~ s~\s+~~g;

        $value = $ENV{ $tag };

        if (defined $value)

        {

            $::ScmDebug = $value;

            Warning("Envar: $tag setting debug: $value");

        }

        $tag = "GBE_${EName}_VERBOSE" ;

        $tag =~ s~\s+~~g;

        $value = $ENV{ $tag };

        if (defined $value)

        {

            $::ScmVerbose = $value;

            Warning("Envar: $tag setting verbose: $value");

        }

    }

    #

    #   Sanitise quiet and verbose

    #   Any verboseness disables quiet

    #

    $::ScmQuiet = 0 if ( $::ScmVerbose );

    $::ScmQuiet = 0 if ( $::ScmDebug );

}

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

# Function        : ErrorReConfig

#

# Description     : Similar to ErrorConfig , except it is used to push and

#                   automatically pop the current state

#

#                   Intended to be used to control error reporting

#                   within a function. Let the class go out of scope

#                   at the end of the function.

#

#                   Not intended that the user hold and pass around the

#                   class ref as this may confuse all.

#

# Inputs          : As for ErrorConfig

#

# Returns         : Ref to a class

#                   When this goes out of scope the Error State will be

#                   restored.

#

sub ErrorReConfig

{

    #

    #   Create a small class to hold existing Error Information

    #   The error information will be restored when the handle returned to

    #   the user goes out of scope.

    #

    my $self;

    $self->{EPrefix}        =  $EPrefix;

    $self->{ElPrefix}       =  $ElPrefix;

    $self->{EIndent}        =  $EIndent;

    $self->{EOffset}        =  $EOffset;

    $self->{ScmVerbose}     =  $::ScmVerbose;

    $self->{ScmDebug}       =  $::ScmDebug;

    $self->{ScmQuiet}       =  $::ScmQuiet;

    $self->{ScmOnExit}      =  $ScmOnExit;

    $self->{ScmDelayExit}   =  $ScmDelayExit;

    $self->{ScmErrorCount}  =  $ScmErrorCount;

    $self->{ScmExitCode}    =  $ScmExitCode;

    $self->{EName}          =  $EName;

    $self->{EFn}            =  $EFn;

    bless ($self, __PACKAGE__);

    #

    #   Invoke ErrorConfig to do the hard work

    #

    ErrorConfig (@_);

    #

    #   Return ref to stored data

    #

    return $self;

}

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

# Function        : DESTROY

#

# Description     : Called when the handle returned by ErrorConfig goes out of

#                   scope.

#

#                   Restores the state of the Error Reporting information

#

# Inputs          : $self               - Created by ErrorReConfig

#

# Returns         : Nothing

#

sub DESTROY

{

    my ($self) = @_;

    $EPrefix          = $self->{EPrefix};

    $ElPrefix         = $self->{ElPrefix};

    $EIndent          = $self->{EIndent};

    $EOffset          = $self->{EOffset};

    $::ScmVerbose     = $self->{ScmVerbose};

    $::ScmDebug       = $self->{ScmDebug};

    $::ScmQuiet       = $self->{ScmQuiet};

    $ScmOnExit        = $self->{ScmOnExit};

    $ScmDelayExit     = $self->{ScmDelayExit};

    $ScmErrorCount    = $self->{ScmErrorCount};

    $ScmExitCode      = $self->{ScmExitCode};

    $EFn              = $self->{EFn};

    $EName            = $self->{EName};

}

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

# Function        : Information

#                   Message

#                   Question

#                   Warning

#                   Error

#                   Verbose

#                   Debug

#                   _Message ( Internal use only )

#

# Description     : Error, Warning and Message routines

#                   These routines will display a message to the user

#                   with the module name.

#

#                   Multiple arguments are displayed on their own line

#                   with suitable spacing.

#

# Inputs          : Lines of text to display

#

# Returns         : Nothing

#

sub _Message

{

    my $tag = shift;                # First argument is a tag

    my $count = 0;

    #

    #   Generate the message prefix

    #   This will only be used on the first line

    #   All other lines will have a space filled prefix

    #

    my $prefix = $EPrefix . $tag. $EIndent;

    #

    #   Kill the eol if the Question is being asked

    #

    my $eol = ( $tag =~ m/Q/ ) ? "" : "\n";

    foreach my $nextline ( @_ ) {

        next unless ( defined $nextline );              # Ignore undefined arguments

        chomp( my $line = $nextline );

        if ( $count == 0 ) {

            $line = ($ElPrefix || '') . $line;

        } elsif ( $count == 1 ) {

            my $bol = $eol ? "" : "\n";

            $prefix = $bol . ' ' x length($prefix) . $EOffset;

        }

        $count++;

        if ($capturing && $tag =~ m/[MWEF]/) {

            push @captured, "$prefix $line$eol" 

        } else {

            print "$prefix $line$eol";

        }

    }

}

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

# Function        : Information

#                   Information1

#

# Description     : Will display informational messages

#                   These are normal operational messages. These may be

#                   supressed through the use of QUIET options

#

# Inputs          : An array of strings to display

#

sub Information

{

    _Message '(I)', @_ unless ( $::ScmQuiet);

}

sub Information1

{

    _Message '(I)', @_ unless ( $::ScmQuiet > 1);

}

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

# Function        : Message

#                   Message1

#

# Description     : Same as Information, except a different prefix

#

# Inputs          : An array of strings to display

#

sub Message

{

    _Message '(M)', @_ unless ( $::ScmQuiet > 1);

}

sub Message1

{

    _Message '(M)', @_ unless ( $::ScmQuiet);

}

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

# Function        : IsQuiet

#

# Description     : Determine if an Infrmation or Message will be displayed

#                   May be used to reduce excessive processing that may be

#                   discarded

#

# Inputs          : $level      - Level to test

#

# Returns         : TRUE:       A Message at $level would be displayed

#

sub IsQuiet

{

    my( $level) = @_;

    return $::ScmQuiet >= $level;

}

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

# Function        : Warning

#

# Description     : Display a warning message

#                   These may be disabled with a high quiet level

#

# Inputs          : An array of strings to display

#

sub Warning

{

    _Message '(W)', @_ unless ( $::ScmQuiet > 2);

}

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

# Function        : Question

#

# Description     : Display a Question message

#                   These cannot be disabled

#

# Inputs          : An array of strings to display

#

sub Question

{

    _Message '(Q)', @_;

    STDERR->flush;              # Force output to be displayed

    STDOUT->flush;              # Force output to be displayed

}

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

# Function        : Fatal

#

# Description     : Display a multi line fatal message

#                   This will cause the program to exit.

#

#                   Similar to Error(), except

#                       Display a (F) prefix

#                       Alters the exit code to "2"

#                       Will terminate program execution.

#                       Will not honor delayed exit configuration.

#

#                   Fatal is to be used to indicate to consumer processes that

#                   the error is a function of the infrastructure and cannot be

#                   corrected by a user. ie:

#                       clearcase is not available

#                           Not just a bad user parameter

#                       dpkg_archive is not available

#                       release manager database is not available

#

#                   Intended to be used by build deamons to determine if building

#                   should continue, or if the entire build process should be

#                   terminated.

#

# Inputs          : An array of strings to display

#

# Returns         : May not return

#

sub Fatal

{

    _Message '(F)', @_;

    $ScmErrorCount++;

    $ScmExitCode = 2;

    ErrorDoExit() unless ( $ScmDelayExit );

}

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

# Function        : Error

#

# Description     : Display a multi line error message

#                   This may cause the program to exit, or the user may have

#                   configured the package to accumulate error messages

#

#                   This could be used to generate multiple error messages

#                   while parsing a file, and then terminate program execution at

#                   the end of the phase.

#

# Inputs          : An array of strings to display

#                   First entry May be an exist code of the form

#                       ExitCode=nnn

#

# Returns         : May not return

#

sub Error

{

    if ( $_[0] =~ m~^ExitCode=(\d+)$~i )

    {

        $ScmExitCode = $1 || 1;

        shift @_;

    }

    _Message '(E)', @_;

    $ScmErrorCount++;

    ErrorDoExit() unless ( $ScmDelayExit );

}

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

# Function        : ReportError

#

# Description     : Like Error, but the error exit is delayed

#

# Inputs          : An array of strings to display

#

sub ReportError

{

    _Message '(E)', @_;

    $ScmErrorCount++;

}

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

# Function        : ErrorDoExit

#

# Description     : Will terminate the program if delayed error messages

#                   have been seen.

#

# Inputs          : None

#

# Returns         : Will return if no errors have been reported

#

sub ErrorDoExit

{

    if ( $ScmErrorCount )

    {

        # If capturing, then force the captured messages to be displayed

        DumpCapture();

        #

        #   Prevent recusion.

        #   Kill error processing while doing error exit processing

        #

        if ( my $func = $ScmOnExit )

        {

            $ScmOnExit = undef;

            &$func( $ScmExitCode );

        }

        exit $ScmExitCode;

    }

}

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

# Function        : ArgsToString

#

# Description     : Convert an array of arguments to a string

#                   Main purpose is to allow Debug and Verbose

#                   calls to pass undef values without causing warnings

#

# Inputs          : REF to a list of scalar values

#                   Passing a REF is faster

#

# Returns         : A string

#

sub ArgsToString

{

    my $result = '';

    $result .= (defined ($_) ? $_ : '\'undef\'') . ' ' foreach  ( @{$_[0]} );

    return $result;

}

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

# Function        : Verbose0

#                   Verbose

#                   Verbose2

#                   Verbose3

#

# Description     : Various levels of progress reporting

#                   By default none are displayed

#

# Inputs          : A single line string

#                   Multi-line output is not supported

#                   Arguments will be processed such that undef is handled well

#

sub Verbose0

{

    _Message '------', ArgsToString (\@_);

}

sub Verbose

{

    _Message '(V)', ArgsToString (\@_) if ($::ScmVerbose);

}

sub Verbose2

{

    _Message '(V)', ArgsToString (\@_) if ($::ScmVerbose >= 2);

}

sub Verbose3

{

    _Message '(V)', ArgsToString (\@_) if ($::ScmVerbose >= 3);

}

sub IsVerbose

{

    my( $level) = @_;

    return $::ScmVerbose >= $level;

}

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

# Function        : Debug

#                   Debug0

#                   Debug1

#                   Debug2

#                   Debug3

#

# Description     : Various levels of debug reporting

#                   By default none are displayed

#

# Inputs          : A single line string

#                   Multi-line output is not supported

#                   Arguments will be processed such that undef is handled well

#

sub Debug0

{

    _Message '------', ArgsToString (\@_);

}

sub Debug

{

    _Message '(D)', ArgsToString (\@_) if ($::ScmDebug >= 1 ) ;

}

sub Debug2

{

    _Message '(D)', ArgsToString (\@_) if ($::ScmDebug >= 2) ;

}

sub Debug3

{

    _Message '(D)', ArgsToString (\@_) if ($::ScmDebug >= 3) ;

}

sub IsDebug

{

    my( $level) = @_;

    return $::ScmDebug >= $level;

}

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

# Function        : StartCapture 

#

# Description     : Start capturing non-debug non-verbose messages 

#

# Inputs          : mode    - True: Start 

#

# Returns         : 

#

sub StartCapture

{

    my ($mode) = @_;

    $capturing = $mode;

}

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

# Function        : DumpCapture 

#

# Description     : Dump the captured output

#

# Inputs          : None

#

# Returns         : Nothing

#

sub DumpCapture

{

    foreach my $line ( @captured) {

        print $line;

    }

    @captured = ();

    $capturing = 0;

}

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

# Function        : DebugDumpData

#

# Description     : Dump a data structure

#

# Inputs          : $name           - A name to give the structure

#                   @refp           - An array of references

#

# Returns         :

#

sub DebugDumpData

{

    my ($name, @refp) = @_;

    my $ii = 0;

    $Data::Dumper::Sortkeys = 1;

    foreach  ( @refp )

    {

        print Data::Dumper->Dump ( [$_], ["*[Arg:$ii] $name" ]);

        $ii++

    }

}

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

# Function        : DebugTraceBack

#

# Description     : Display the call stack

#

# Inputs          : $tag

#

# Returns         : Nothing

#

sub DebugTraceBack

{

    my ($tag) = @_;

    $tag = 'TraceBack' unless ( $tag );

    #

    #   Limit the stack stace.

    #   It can't go on forever

    #

    foreach my $ii ( 0 .. 20 )

    {

         my ($package, $filename, $line) = caller($ii);

         last unless ( $package );

         print "$tag: $ii: $package, $filename, $line\n";

    }

}

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

# Function        : DebugPush

#

# Description     : Save the current debug level and then use a new name and

#                   debug level for future reporting

#

#                   Provided for backward compatability

#                   Preferred solution is ErrorReConfig

#

# Inputs          : $name       - New program name

#                   $level      - New program debug level

#

# Returns         : Current debug level

#

my @DebugStack = ();

sub DebugPush

{

    my ($name, $new_level) = @_;

    my %args;

    #

    #   Save current state on a stack

    #

    my $estate = ErrorReConfig ();

    push @DebugStack, $estate;

    $::ScmDebug = $new_level if ( defined $new_level && $new_level );

    $EPrefix =   $name        if ( defined $name && $name );

    return $::ScmDebug;

}

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

# Function        : DebugPop

#

# Description     : Restores the operation of the DebugPush

#

# Inputs          : None

#

sub DebugPop

{

    pop @DebugStack;

}

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

# Function        : DebugDumpPackage

#

# Description     : Dump data within the scope of a given package

#

# Inputs          : $packageName            - To dump

#

# Returns         : 

#

sub DebugDumpPackage

{

    no strict "vars";

    no strict "refs";

    my ($packageName) = @_;

    print "==DebugDumpPackage: $packageName =============================\n";

    local $Data::Dumper::Pad = "\t ";

    local $Data::Dumper::Maxdepth = 2;

    local $Data::Dumper::Indent  = 1;

    # We want to get access to the stash corresponding to the package name

    *stash = *{"${packageName}::"};  # Now %stash is the symbol table

    # Iterate through the symbol table, which contains glob values

    # indexed by symbol names.

    foreach my $varName ( sort keys %stash)

    {

        my $globValue = $stash{$varName};

        print "$varName =============================\n";

        next if ( $varName eq 'stash' );

        local *alias = $globValue;

        if (defined ($alias)) {

            print Data::Dumper->Dump ( [$alias], ["*$varName" ]);

#            print "\t \$$varName $alias \n";

        } 

        if (@alias) {

            print Data::Dumper->Dump ( [\@alias], ["*$varName" ]);

#            print "\t \@$varName @alias \n";

        } 

        if (%alias) {

            print Data::Dumper->Dump ( [\%alias], ["*$varName" ]);

#            print "\t \%$varName ",%alias," \n";

        }

        if (defined (&alias)) {

#            print Data::Dumper->Dump ( [\&alias], ["*$varName" ]);

            print "\t \&$varName ","Code Fragment"," \n";

        }

     }

}

#

#

1;