++ed by:
SHARYANTO PERLANCAR

2 PAUSE users

David F. Houghton

NAME

App::JobLog::Log - the code that lets us interact with the log

VERSION

version 1.036

DESCRIPTION

App::JobLog::Log uses an IO::All object to extract information from the log file or add lines to it.

This wasn't written to be used outside of App::JobLog. The code itself contains interlinear comments if you want the details.

METHODS

new

new is the constructor, naturally. It touches the log file into existence if it does not yet exist, initializing the hidden job log directory in the process, which means creating the directory and the README file. It also opens an IO::All object to read or modify the log with.

all_taglines

all_taglines returns a list of all lines in the log that may have tags.

all_events

all_events processes the log as a stream, extracting all events and returning them as an array reference.

all_notes

all_notes processes the log as a stream, extracting all notes and returning them as an array reference.

validate

validate makes sure the log contains only valid lines, all events are in chronological order, and every ending follows a beginning. Invalid lines are commented out and a warning is emitted. The number of errors found is returned.

first_event

first_event returns the first event in the log and the index of its line. Its return object is an App::JobLog::Log::Event.

last_ts

Returns last DateTime timestamp in log and the index of this timestamp.

first_ts

Returns first DateTime timestamp in log.

last_event

last_event returns the last event in the log and the index of its line. Its return object is an App::JobLog::Log::Event.

last_note

Returns most recent note in log and its index, or the empty list if none is found.

reverse_iterator

reverse_iterator returns a closure that allows you to iterate over the events in the log in reverse. Every time you call the closure it returns the next unvisited event.

If you pass this method an optional argument, either a DateTime or a App::JobLog::Log::Event, it will iterate from the event beginning at or after this event or time.

find_events

find_events expects two DateTime objects representing the termini of an interval. It returns an array reference containing the portion of all logged events falling within this interval. These portions are represented as App::JobLog::Log::Event objects.

find_notes

find_notes expects two DateTime objects representing the termini of an interval. It returns an array reference containing the portion of all logged notes falling within this interval. These portions are represented as App::JobLog::Log::Note objects.

find_previous

find_previous looks for the logged event previous to a given moment, returning the App::JobLog::Log::Event objects and the appropriate log line number, or the empty list if no such event exists. It expects a DateTime object as its parameter.

find_previous

find_previous looks for the logged event previous to a given moment, returning the App::JobLog::Log::Event objects and the appropriate log line number, or the empty list if no such event exists. It expects a DateTime object as its parameter.

append_event

append_event expects an array of event properties. It constructs an event object and appends its stringification to the log, returning a DateTime::Duration object if the previous event was left open and spanned more than one day.

append_note

Takes a description and a set of tags and appends it to the log as a note with the current timestamp.

close

close closes the IO::All object, if it exists and is open, forcing all content to be written to the log.

insert

insert takes an insertion index and a list of App::JobLog::Log::Line objects and inserts the latter into the log at the index preceded by a comment explaining that these lines have been inserted.

replace

Replace one line with another.

AUTHOR

David F. Houghton <dfhoughton@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by David F. Houghton.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.