App::JobLog - base of work log application
version 1.036
houghton@NorthernSpy:~$ job Available commands: commands: list the application's commands help: display a command's help screen add: log an event configure: set or display various parameters done: mark current task as done edit: open a text editor to edit the log info: describe job log last: describe the last task recorded modify: add details to last event note: take a note parse: parse a time expression resume: resume last task summary: list tasks with certain properties in a particular time range tags: list tags employed in log or some subrange thereof today: what has happened today truncate: shorten the log to contain only those moments after a given date vacation: list or define days off when: report when work is done for the day houghton@NorthernSpy:~$ job summary this week Sunday, 27 February, 2011 8:00 - 9:39 am 1.65 widgets improving debugging rig to handle batches of files and to print all output to files for later comparison; checking code changes into github Monday, 28 February 8:00 - 10:47 am 2.79 widgets gussying up pdf conversion Tuesday, 1 March 8:00 - 9:23 am 1.39 widgets adding handling of simplified pdf docs Friday, 4 March 1:48 - 2:55 pm 1.11 widgets trying to get Eclipse working properly again 3:50 - 5:30 pm 1.66 widgets figuring out why some files are really, really slow TOTAL HOURS 8.60 widgets 8.60 houghton@NorthernSpy:~$ job today No events in interval specified. houghton@NorthernSpy:~$ job add --clear-tags messing around houghton@NorthernSpy:~$ job a messing around some more houghton@NorthernSpy:~$ job done houghton@NorthernSpy:~$ job to Sunday, 6 March, 2011 9:02 - 9:03 am 0.01 messing around; messing around some more TOTAL HOURS 0.01 houghton@NorthernSpy:~$ job resume houghton@NorthernSpy:~$ job to Sunday, 6 March, 2011 9:02 - 9:03 am 0.01 messing around; messing around some more 9:03 am - ongoing 0.00 messing around some more TOTAL HOURS 0.01 houghton@NorthernSpy:~$ job configure --list day length 8 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
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).
App::JobLog keeps its documents, by default, in a hidden directory in your home directory called .joblog/. These documents are a README file explaining to anyone who stumbles across the directory what it's function is, a log, called log, a configuration file, called config.ini, a vacation file, called vacation, and perhaps log backups.
To perform any action with App::JobLog one invokes the executable with a command and a list of options. These commands are listed below.
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. ...
Provides the list of available commands.
Appends an event to the end of the log. See App::JobLog::Command::add.
Lists or modifies configuration parameters. See App::JobLog::Command::configure.
Appends an event to the log marking the last event as done. See App::JobLog::Command::done.
Edit the log safely. See App::JobLog::Command::edit.
Provides extended general help text. See App::JobLog::Command::info.
Describes the last event in the log. See App::JobLog::Command::last.
Modifies the last event in the log. See App::JobLog::Command::modify.
Adds a note to the log -- text independent of any task. See App::JobLog::Command::note.
Parse a time expression to discover what the application understands it to mean. See App::JobLog::Command::parse.
Resumes the last closed event in the log. See App::JobLog::Command::resume.
Presents a portion of the log in more human readable form. See App::JobLog::Command::summary.
List only the tags used to categorize tasks. See App::JobLog::Command::tags.
Summarizes everything done today. See App::JobLog::Command::today.
Pares off and stores the older portion of the log. See App::JobLog::Command::truncate.
Allows viewing and modification of a simple database of vacation times kept separately from the log. See App::JobLog::Command::vacation.
Reports when you'll have worked the expected number of hours given how many hours you put in in the specified period (the same day, by default). See App::JobLog::Command::when.
We basically want database functionality out of our job log -- random access, selecting rows by various properties, nice reports. Why not use SQLite, say, or Berkeley DB? Well first of all, that adds dependencies, and we want fewer of those. And except in extraordinary circumstances we are only adding events in sequence and we will only be interested in the most recent ones. Even when we don't just want the most recent events we don't need truly random access to the whole log but an interval -- all the lines from one point to another. We only need a slightly glorified log. A database is overkill. Finally, as soon as we maintain our data in a database it becomes an opaque blob and our editing interface becomes much more complicated to write, use, and maintain. We need to write a shell, GUI, or ncurses interface and figure out how to provide the editor with search facilities, the context in which she is making edits, and perhaps an undo/redo stack. If it's a text file we just pop up an editor and validate the log on close. So I stuck with a log.
Thanks to Ricardo Signes for the redoubtable App::Cmd which wires this all together, Dave Rolsky for DateTime, which does all the calendar math, and Ingy döt Net for IO::All, which, via Tie::File (thanks, Mark Jason Dominus), makes random access to a log file trivial.
Thanks also to my wife Paula, who was my only beta tester other than myself.
App::Cmd, DateTime, IO::All
David F. Houghton <dfhoughton@gmail.com>
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.
To install App::JobLog, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::JobLog
CPAN shell
perl -MCPAN -e shell install App::JobLog
For more information on module installation, please visit the detailed CPAN module installation guide.