view release on metacpan or  search on metacpan

lib/App/JobLog.pm  view on Meta::CPAN

 editor                   /usr/bin/vim
 hidden columns                   none
 merge              adjacent same tags
 pay period length                  14
 precision                           2
 start pay period           2009-01-11
 sunday begins week               true
 time zone                       local
 workdays                        MTWHF
 houghton@NorthernSpy:~$ job conf --precision 1
 precision set to 1
 houghton@NorthernSpy:~$ job to
 Sunday,  6 March, 2011
      9:02 - 9:03 am  0.0  messing around; messing around some more
   9:03 am - ongoing  0.0  messing around some more

   TOTAL HOURS 0.0
 houghton@NorthernSpy:~$ job d
 houghton@NorthernSpy:~$ job note maybe I should take more notes
 houghton@NorthernSpy:~$ job to
 Sunday,  6 March, 2011
   9:02 - 9:03 am  0.0  messing around; messing around some more
   9:03 - 9:06 am  0.0  messing around some more

   TOTAL HOURS 0.1
 houghton@NorthernSpy:~$ cat ~/.joblog/log

...

 2011  3  1  8  0  0:widgets:adding handling of simplified pdf docs
 2011  3  1  9 23 24:DONE
 # 2011/03/04
 2011  3  4 13 48 42:widgets:trying to get Eclipse working properly again
 2011  3  4 14 55 34:DONE
 2011  3  4 15 50 46:widgets:figuring out why some files are really, really slow
 2011  3  4 17 30  7:DONE
 # 2011/03/06
 2011  3  6  9  2 58::messing around
 2011  3  6  9  3 13::messing around some more
 2011  3  6  9  3 18:DONE
 2011  3  6  9  3 48::messing around some more
 2011  3  6  9  6 30:DONE
 2011  3  6  9  6 35<NOTE>:maybe I should take more notes

=head1 DESCRIPTION

B<App::JobLog> provides a simple command line utility for keeping track of what you do when. The underlying
design goals were to keep it fast, simple, and idiot proof and to keep the generated documents human readable
and comprehensible. The usual form of such a document is a log -- a series of line-delimited events, each containing
a time stamp, a description, and perhaps other meta-data. The problem with a log is that it's usually a little
numbing to scroll through it for anything but the most recent events, and with a job log what you usually want
isn't time stamps but durations. So in addition to a logging facility we want a report extraction facility. Finally,
we often want to filter out particular activities and categorize them in various ways, so along with the time stamps
and descriptions we want tags. That's about it. Besides this minimal functionality we want the log to impose as few
restrictions as possible so that we don't need to think about how it works. We don't want to worry about characters
with special valence so the log has to handle its own escaping of spaces and colons and so forth. We don't want to
worry about character encoding so the log has to be in Unicode (utf8).

B<App::JobLog> keeps its documents, by default, in a hidden directory in your home directory called F<.joblog/>. These
documents are a README file explaining to anyone who stumbles across the directory what it's function is, a log, called
F<log>, a configuration file, called F<config.ini>, a vacation file, called F<vacation>, and perhaps log backups.

To perform any action with B<App::JobLog> one invokes the executable with a command and a list of options. These commands
are listed below.

=head2 COMMANDS

=over 8

=item B<help>

Provides extended help information for a particular command. E.g.

 houghton@NorthernSpy:~$ job help summary
 job summary [-iMmTtV] [long options...] <date or date range>

 List events with certain properties in a particular time range. Only the portions
 of events falling within the range will be listed.

 Events may be filtered in numerous ways: by tag, time of day, or terms used in descriptions.
 ...

=item B<commands>

Provides the list of available commands.

=item L<add|App::JobLog::Command::add>

Appends an event to the end of the log. See L<App::JobLog::Command::add>.

=item L<configure|App::JobLog::Command::configure>

Lists or modifies configuration parameters. See L<App::JobLog::Command::configure>.

=item L<done|App::JobLog::Command::done>

Appends an event to the log marking the last event as done. See L<App::JobLog::Command::done>.

=item L<edit|App::JobLog::Command::edit>

Edit the log safely. See L<App::JobLog::Command::edit>.

=item L<info|App::JobLog::Command::info>

Provides extended general help text. See L<App::JobLog::Command::info>.

=item L<last|App::JobLog::Command::last>

Describes the last event in the log. See L<App::JobLog::Command::last>.

=item L<modify|App::JobLog::Command::modify>

Modifies the last event in the log. See L<App::JobLog::Command::modify>.

=item L<note|App::JobLog::Command::note>

Adds a note to the log -- text independent of any task. See L<App::JobLog::Command::note>.

=item L<parse|App::JobLog::Command::parse>

Parse a time expression to discover what the application understands it to mean.