NAME

VCP::Logger - Update message, bug, and Log file management

SYNOPSIS

   use VCP::Logger qw( shell_quote );

DESCRIPTION

Does not throw exceptions or use the debug module, so this is safe to use with both. Load this as the very first module in your program.

The log file name defaults to "vcp.log", set the environment variable VCPLOGFILE to change it. Here's how to do this in your program:

   BEGIN {
      $ENV{VCPLOGFILE} = "foo.bar"
         unless defined $ENV{VCPLOGFILE} || length $ENV{VCPLOGFILE};
   }

FUNCTIONS

lg

Prints a timestamped message to the log. Adds a trailing newline if need be. The first word of the message should not be capitalized unless it's a name or acronym; this makes grepping a bit easier (same for all error messages).

"lg" is "log" abbreviated so as not to conflict with Perl's builtin log().

The timestamps are in integer seconds since this module was compiled unless you have Time::HiRes install in which case they are in floating point seconds.

Should not throw an exception or alter $@ in the normal course of events (does not call any routines that should do so).

lg_fh

Returns a reference to the log filehandle (*LOG{IO}) so you can emit to the log directly. The log is flushed after every write, so this should be quite safe.

pr

Print a status notification to STDERR (unless in quiet mode) and log it.

pr_doing

   pr_doing "Fooo";
   pr_doing "Fooo", { ...options... };
   pr_doing;  ## to show progress
    

Print a status notification and show progress. Call repeatedly to show continuing progress. Works with pr() to manage lineends.

Call with no parameters to show progress on the current task. Call pr_done or pr_done_failed to finish up.

Options:

    Expect   => $c, # There should be this number of calls, total, not
                    # including the call with the options set..
    

pr_did

    pr_did $what, $status;
    

Adds a message to the progress bar, does not affect progress otherwise.

Useful to display additional progress metrics.

Call before pr_doing.

pr_active

Show that we're active.

pr_done

Called to end a "pr_doing" sucessfully. Logs the completion bug does not emit to STDERR. Prints and logs any message passed.

p4_done_failed

Called to end a "pr_doing" in dismal failure. Logs the (in)completion and and emits a message to the log and STDERR if one is passed.

BUG

Reports a bug using Carp::confess and logging the information.

set_quiet_mode

    set_quiet_mode;
    set_quiet_mode( 1 );
    set_quiet_mode( 0 );
    

Called to quash (or allow) progress bars. See the "--quiet" option on the command line.

start_time

Returns the time the application started. This is a floating point number if Time::HiRes was found.

COPYRIGHT

Copyright 2000, Perforce Software, Inc. All Rights Reserved.

This module and the VCP package are licensed according to the terms given in the file LICENSE accompanying this distribution, a copy of which is included in vcp.