NAME

ScriptUtil - Object Orientated class to make typical command line scripts easier to write

SYNOPSIS

 use ScriptUtil;
 # All of these parameters are optional:
 my $script = ScriptUtil->new(
    'verbose'               => 1,            # Output messages to STDOUT
    'nolog'                 => 1,            # Disable logging
    'nolock'                => 1,            # Disable script locking
    'log_debug'             => 5             # Debug level for logging
    'log_filename'          => 'foo.log',    # Log file name
    'log_path'              => '/tmp',       # Location of log files
    'log_mode'              => '>>',         # Log file mode
    'log_stderrredirect'    => 0,            # Redirect stderr into log
    'log_storeexptext'      => 1,            # Log store internally all exp text
    'log_datetimestamp'     => 1,            # Timestamp log data entries
    'log_logfiledatetime'   => 1,            # Timestamp the log file name
    'log_rotation'          => 1,            # Do log rotation if logging is enabled
    'log_zip_after_days'    => 2,            # Zip log files older than X days if log_rotation is enabled
    'log_rm_after_days'     => 5,            # Delete log files older than X days if log_rotation is enabled
 );

 # Put a message into the log file unless the 'nolog' flag has been set
 # Also print to STDOUT if the verbose flag has been set
 
 $script->echo("Boo");
 
 # Put a message into the log file unless the 'nolog' flag has been set
 # And 'log_debug' is greater than or equal to 10
 
 $script->echo("Boo", 10);

DESCRIPTION

ScriptUtil is a class to make typical command line scripts easier to write.

The aim of this module is to reduce the amount of copy & paste and repeated 'scaffolding code' at the top of your scripts.

As time goes by I intend to add more methods for common operations, if you have some suggestions feel free to drop me a line.

Common operations such as:

• log file initialization (File::Log)

• log file rotation

• locking (so only one instance of your scripts runs at a time)

• benchmarking performance (Benchmark)

• cleaning white space out of strings

Will be taken care of for you when you instantiate a new ScriptUtil object.

You can override some or all of the defaults, or leave them as is, see the examples section for more information

EXAMPLES

 use ScriptUtil;

 my $script = ScriptUtil->new(
                              verbose       => 1,
                              log_path      => '/var/logs/foo',
                              log_rotation  => 1,
                              log_debug     => 1,
                              );

 $script->echo("Cleaning up a string", 1);
 
 my $string = "\t Foo Bar              \t\t    \n\n\n";
 $script->echo("String Before Cleanup: [" . $string . "]", 10); # log_debug = 1 so you won't see this
 
 $string = $script->trim($string);
 $script->echo("String After Cleanup: [" . $string . "]"); # uses default debug level you will see this
 
 $script->verbose(0);
 $script->echo("You will only see this message in the log file", 1);

METHODS

There are no class methods, the object methods are described below. Private methods start with the underscore character '_' and should be treated as Private.

new

Called to create a ScriptUtil object. The following named parameters can be passed to the constructor in Moose style and they are all optional:

verbose

Used to determine how noisy the script should be. when echo is called this attribute will determine if messages should be printed to STDOUT. The default behavior is off (false).

nolog

Logging is done via Greg George's handy File::Log object by default. If you don't want logging set this to false. The default is on (true) IE logging will be done by default.

nolock

Disable script locking, when your script instantiates a ScriptUtil object, ScriptUtil will open your script in append mode and attempt to get get an exclusive lock. If it is unable to get a lock, ScriptUtil will confess about it. The default behavior is off (false) IE scripts will be locked by default.

log_debug

Debug level for logging, see File::Log for more information. Default level is 5.

log_filename

Log file name if logging is enabled, see File::Log for more information. The default value is your_script_name.log. Or your_script_name_YYYYMMDD-HHMMSS.log if log_datetimestamp is true.

log_path

Location of log files if logging is enabled. The default value is /path/to/your/script/.

log_mode

Log file mode, see File::Log for more information. The default value is >> IE append mode.

log_stderrredirect

Redirect STDERR into log file, see File::Log for more information. You should probably leave this off if you are running in verbose mode. The default behavior is off (false) IE STDERR will not be redirected into logs.

log_storeexptext

Log store internally all exp text, see File::Log for more information. The default value is on (true).

log_datetimestamp

Timestamp log data entries, see File::Log for more information. The default value is on (true).

log_logfiledatetime

Timestamp the log file name, see File::Log for more information. If you are using log rotation this will be set to on automatically. The default value is on (true).

log_rotation

Do log rotation if logging is enabled. The default value is off (false).

log_zip_after_days

Zip log files older than X days if log_rotation is enabled. The default value is 2 days.

This can be set to 0 days if you don't want zipping.

log_rm_after_days

Delete log files older than X days if log_rotation is enabled. The default value is 31 days.

This can be set to 0 days if you don't want deletion.

echo

Outputs print messages into the log file unless nolog has been set, and to STDOUT if verbose has been set.

Takes a string and an optional integer as arguments.

 # Usage:
 echo(STRING message, INTEGER debug level)

 # Examples:
 $script->echo("This is a message");
 $script->echo("This is a message with a debug level", 10);

trim

Trims white space (tabs and spaces) out of a string.

Takes a string as an argument, returns a string.

 # Usage:
 STRING = trim(STRING text)

 # Example:
 my $trimmed_string = $script->trim("\t  \t This is a string that needs trimming    ");

REQUIRED MODULES

• Moose

• Carp

• File::Log

• Fcntl

• Archive::Zip

• File::Spec

• File::Basename

VERSION

 0.02
 

CHANGE LOG

0.01

Initial release

0.02

Updated Makfile.PL to correct dependancy problems

AUTHOR

Cameron Stuart cam@asoftware.net.au

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Cameron Stuart

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm ScriptUtil

perl -MCPAN -e shell
install ScriptUtil