/ 
Finance-Shares-Log-0.03
/ Finance::Shares::Log

NAME

Finance::Shares::Log - Keep track of activity in Finance::Share modules

SYNOPSIS

This module houses three groups of functions. The main object handles Log files. Exported functions are provided that assist with date and file handling.

    use Finance::Shares::Log qw(:date :file);

    use Finance::Shares::Log qw(
	    today_as_days
	    today_as_string
	    days_from_time
	    time_from_days
	    string_from_days
	    days_from_string
	    ymd_from_days
	    days_from_ymd
	    ymd_from_string
	    string_from_ymd
	    expand_tilde
	    check_file
	    fetch_line
	);

Log methods

The simplest usage sends messages to a specified file. Sending a message with level 0 is equivalent to the builtin die.

my $lf = Finance::Shares::Log->new("logfile.txt");
$lf->log(1, $message);
$lf->log(0, $fatal_message);

This can be expanded by adding level() and file().

my $lf = Finance::Shares::Log->new();
$lf->file("myprog.log", "~/logs");
$lf->level(5);
$lf->log(5, "This message gets through");
$lf->log(6, "While this is ignored");

Although the main uses are given above, lower level access is available.

my $lf = Finance::Shares::Log->new();
$lf->open("~/myprog.log");
$lf->print("Own level monitoring") unless ($lf->level() > 2);
my using_file = $lf->is_file();
my open_file = $lf->is_open();
$lf->close();

Frills include the ability to duplicate log entries allowing multiple destinations, as well as logging in simulated time.

my $l1 = new Finance::Shares::Log('main.log');
my $l2 = new Finance::Shares::Log('second.log');
$l1->copy_to( $l2 );
$l1->copy_remove( $l2 );

$l1->tick( $my_date );

Date functions

$days = today_as_days();
$date = today_as_string();

$days = days_from_time( $time );
$time = time_from_days( $days );

$date = string_from_days( $days );
$days = days_from_string( $date );

($year, $month, $day) = ymd_from_days( $days );
$days = days_from_ymd( $year, $month, $day );
($year, $month, $day) = ymd_from_string( $date );
$date = string_from_ymd( $year, $month, $day );

File functions

$abs_file = check_file( $rel_file );
$abs_file = check_file( $abs_file );
$abs_file = check_file( $file, $rel_dir );
$abs_file = check_file( $file, $abs_dir );
$abs_file = check_file( $rel_file, $abs_dir );

$abs_file = expand_tilde( $shell_name );

$line = fetch_line( FILE_HANDLE );

DESCRIPTION

A centralized logging system is used to keep track of which stock prices are fetched from the internet and what processing has been done on them. It is possible to route messages to any number of destinations.

Example

my $l1 = new Finance::Shares::Log();
my $l2 = new Finance::Shares::Log('debug.log');
my $l3 = new Finance::Shares::Log('shares.log');
$l1->copy_to( $l2 );
$l1->copy_to( $l3 );

$l1->level(99);
$l2->level(5);
$l3->level(1);

$l1->log(1, "hello");
$l1->log(4, "something wrong?");

'Hello' would appear on the console from $1 as well as being written to the other two files. The second message will go to all except 'shares.log'.

CONSTRUCTOR

new( [file, [dir, [level]]] )

file

An optional fully qualified path-and-file, a simple file name, or "" for null device.

dir

An optional directory. If present (and file is not already an absolute path), it is prepended to file.

level

The logging threshold. Messages with numbers greater than this will be ignored. (Default: 2)

Create a new log object. If filename already exists, logging will just be appended. Any leading '~' is expanded, otherwise any arguments are handled using File::Spec so should be portable.

Logged data will be sent to STDOUT if no file is given. If file is given the value "", all logged data is suppressed.

OBJECT METHODS

log( priority, string_or_array )

priority

This is compared with the value passed to level() to determine whether the data gets logged or ignored. Higher numbers should be used for greater detail; lower numbers for messages that are more important. A value of '0' signifies a fatal error message - the method calls die.

string_or_array

The data to be sent to the log. A timestamp and a trailing "\n" will be added.

The main logging function. This opens the file, send the data to it and closes it again (if necessary). Use the lower level print() method if this proves inappropriate.

ACCESS METHODS

file( [file [, dir]] )

file

An optional fully qualified path-and-file, a simple file name, or "" for null device.

dir

An optional directory. If present (and file is not already an absolute path), it is prepended to file.

Specify the file to use. If it doesn't already exist, it is created. With no arguments, this redirects output to STDERR, while "" is interpreted as the NULL device.

Returns the name of the log file.

level( [level] )

level should be a number 0 or greater. Data sent to log() with a number less than or equal to this will be output. Messages with levels greater than this will be suppressed.

A level of 0 supresses all except fatal messages.

Returns the priority threshold.

copy_to( other_log )

Register another log which will receive copies of all log calls made to this object. other_log must be another Finance::Shares::Log object.

copy_remove( other_log )

Stop log calls being copied to the Finance::Shares::Log object previously registered with copy_to.

tick( prompt )

Messages are prefixed by a timestamp by default. This method allows logging of simulated time. Calling tick with a suitable string such as a date, registers that as the prefix to use. All log messages will use that until another tick is called.

Setting prompt to false ('' or 0) restores the automatic timestamp.

SUPPORT METHODS

open( [file, [dir]] )

file

An optional fully qualified path-and-file, a simple file name, or "" for null device.

dir

An optional directory dir. If present (and file is not already an absolute path), it is prepended to file.

If a file has been given, an attempt is made to open it for appending data. The special name "" sends all logged data to /dev/null. Alternatively, if the file is a handle such as STDOOUT, the data will be sent there. The method either dies (if no file has been specified or it cannot be opened) or data may be written.

is_open()

Return true if the log file is open.

is_file()

Return true if the log file is an actual file.

close()

Closes the log file.

print( string_or_array )

Unlike the builtin print, a timestamp is output before the parameter(s) and a "\n" is added on the end.

open() must have been called beforehand, and close() should be called after the printing is done.

DATE FUNCTIONS

There are three types of dates here. A 'days' value is the number of days from some arbitrary day zero. A 'date' is a string in YYYY-MM-DD format while 'ymd' refers to an array holding a year, month and day such as (2002, 12, 31). See SYNOPSIS for all the functions.

All the work is done by David Eisenberg's Date::Pcalc module. These function just provide an interface convenient for the Finance::Shares modules.

today_as_days

Return the number of days in the date, as used by Date::Pcalc.

today_as_string

Return today's date in YYYY-MM-DD format.

string_from_days( days )

Convert the number of Date::Pcalc days into YYYY-MM-DD format.

days_from_string ( date )

Convert a YYYY-MM-DD date into a number of days, as used by Date::Pcalc.

days_from_ymd( year, month, day )

Convert the numeric year, month and day date into Date::Pcalc days.

ymd_from_days( days )

Convert the number of Date::Pcalc days into an array of numeric values in the form:

(year, month, day)

string_from_ymd( year, month, day )

Convert the numeric representation of year, month and day into a YYYY-MM-DD date.

ymd_from_string( date )

Convert a YYYY-MM-DD date into an array of numeric values in the form:

(year, month, day)

increment_date( date, days )

Add the number of days given to the YYYY-MM-DD date and return the new date in YYYY-MM-DD format.

FILE FUNCTIONS

check_file( file, [dir] )

file

An optional fully qualified path-and-file, a simple file name, or "".

dir

An optional directory dir. If present (and file is not already an absolute path), it is prepended to file.

If no directory is given either way, the current directory is assumed. Any leading '~' is expanded to the users home directory, and the file is created (with any intervening directories) if it doesn't exist.

If file is given "" the special file File::Spec->devnull() is returned.

File::Spec is used throughout so file access should be portable.

expand_tilde( dir )

Expands any leading '~' to the home directory.

fetch_line( FILE_HANDLE )

Return the next line of data from an open file. Blank lines and '#' comments are skipped and leading and trailing space is removed.

BUGS

Please report those you find to the author.

AUTHOR

Chris Willmot, chris@willmot.co.uk

SEE ALSO

Finance::Shares::MySQL and Finance::Shares::Sample.