view release on metacpan or  search on metacpan

lib/App/GitFind/Base.pm  view on Meta::CPAN

=cut

sub croak {
    require Carp;
    goto &Carp::croak;
}

=head2 vlog

Log information to STDERR if L</$VERBOSE> is set.  Usage:

    vlog { <list of things to log> }
        [optional min verbosity level (default 1)]
        [, log-routine args];

The items in the list are joined by C<' '> on output, and a C<'\n'> is added.
Each line is prefixed with C<'# '> for the benefit of test runs.
To break the list across multiple lines, specify C<\n> at the beginning of
a list item.

The list is in C<{}> so that it won't be evaluated if logging is turned off.
It is a full block, so you can run arbitrary code to decide what to log.
If the block returns an empty list, vlog will not produce any output.
However, if the block returns at least one element, vlog will produce at
least a C<'# '>.

The message will be output only if L</$VERBOSE> is at least the given minimum
verbosity level (1 by default).

If C<< $VERBOSE >= 4 >>, the filename and line from which vlog was called
will also be printed.

If more arguments are provided than two, the extras are the arguments
to the subroutine.  This permits you to pass arguments from the caller's
C<@_> that would otherwise be shadowed inside the logging routine.  E.g.:

    sub foo {
        vlog { $_[0] } 1, $_[1];    # log foo's $_[1]
    }

=cut

sub vlog (&;@) {
    return if $QUIET;
    my ($crRoutine, $level) = splice @_, 0, 2;
    return unless $VERBOSE >= ($level // 1);

    my @log = $crRoutine->(@_);
    return unless @log;

    chomp $log[$#log] if $log[$#log];
    # TODO add an option to number the lines of the output
    my $msg = join(' ', @log);
    $msg =~ s/^/# /gm;

    if($VERBOSE >= 4) {
        my ($package, $filename, $line) = caller;
        $msg .= " (at $filename:$line)";
    }

    say STDERR $msg;
} #vlog()

=head2 vwarn

As L</vlog>, but warns regardless of L</$VERBOSE>.  Does respect L</$QUIET>.

=cut

sub vwarn (&) {
    return if $QUIET;

    my @log = &{$_[0]}();
    return unless @log;

    vlog { "Warning:", @log } $VERBOSE;
} #vwarn()

=head2 import

See L</SYNOPSIS>

=cut

#sub import {
#    my $target = caller;
#    $_[0]->export_to_level(1, @_);                              # Symbols
#
#    #$_->import::into($target) foreach qw(strict warnings);      # Pragmas
#        # ... each module has to import those anyway to satisfy Kwalitee.
#
#    #Carp->import::into($target, qw(carp croak confess cluck));  # Packages
#    #Data::Dumper::Compact->import::into($target, 'ddc');
#    #Getargs::Mixed->import::into($target);
#} #import()

1;
__END__
# === Rest of the docs === {{{1

=head1 AUTHOR

Christopher White, C<< <cxw at cpan.org> >>

=head1 LICENSE AND COPYRIGHT

Copyright 2019 Christopher White.
Portions copyright 2019 D3 Engineering, LLC.

This program is distributed under the MIT (X11) License:
L<http://www.opensource.org/licenses/mit-license.php>

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions: