A reader for the timeclock file format.

What exactly is this format ? It was introduced in timeclock.el (http://www.emacswiki.org/emacs/TimeClock). The old specification in timeclock.el 2.6 was:

A timeclock contains data in the form of a single entry per line.
Each entry has the form:

  CODE YYYYMMDD HH:MM:SS [COMMENT]

CODE is one of: b, h, i, o or O.  COMMENT is optional when the code is
i, o or O.  The meanings of the codes are:

  b  Set the current time balance, or "time debt".  Useful when
     archiving old log data, when a debt must be carried forward.
     The COMMENT here is the number of seconds of debt.

  h  Set the required working time for the given day.  This must
     be the first entry for that day.  The COMMENT in this case is
     the number of hours in this workday.  Floating point amounts
     are allowed.

  i  Clock in.  The COMMENT in this case should be the name of the
     project worked on.

  o  Clock out.  COMMENT is unnecessary, but can be used to provide
     a description of how the period went, for example.

  O  Final clock out.  Whatever project was being worked on, it is
     now finished.  Useful for creating summary reports.

Ledger's timeclock format is different, and hledger's timeclock format is different again. For example: in a clock-in entry, after the time,

• timeclock.el's timeclock has 0-1 fields: [COMMENT]
• Ledger's timeclock has 0-2 fields: [ACCOUNT[ PAYEE]]
• hledger's timeclock has 1-3 fields: ACCOUNT[ DESCRIPTION[;COMMENT]]

hledger's timeclock format is:

# Comment lines like these, and blank lines, are ignored:
# comment line
; comment line
* comment line

# Lines beginning with b, h, or capital O are also ignored, for compatibility:
b SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT]
h SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT]
O SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT]

# Lines beginning with i or o are are clock-in / clock-out entries:
i SIMPLEDATE HH:MM[:SS][+-ZZZZ] ACCOUNT[  DESCRIPTION][;COMMENT]]
o SIMPLEDATE HH:MM[:SS][+-ZZZZ][ ACCOUNT][;COMMENT]

The date is a hledger simple date (YYYY-MM-DD or similar). The time parts must use two digits. The seconds are optional. A + or - four-digit time zone is accepted for compatibility, but currently ignored; times are always interpreted as a local time.

In clock-in entries (i), the account name is required. A transaction description, separated from the account name by 2+ spaces, is optional. A transaction comment, beginning with `;`, is also optional.

In clock-out entries (o) have no description, but can have a comment if you wish. A clock-in and clock-out pair form a "transaction" posting some number of hours to an account - also known as a session. Eg:

```timeclock i 20150330 09:00:00 session1 o 20150330 10:00:00 ```

```cli $ hledger -f a.timeclock print 2015-03-30 * 09:00-10:00 (session1) 1.00h ```

Clock-ins and clock-outs are matched by their account/session name. If a clock-outs does not specify a name, the most recent unclosed clock-in is closed. Also, sessions spanning more than one day are automatically split at day boundaries. Eg, the following time log:

```timeclock i 20150330 09:00:00 some account optional description after 2 spaces ; optional comment, tags: o 20150330 09:20:00 i 20150331 22:21:45 another:account o 20150401 02:00:34 i 20150402 12:00:00 another:account ; this demonstrates multple sessions being clocked in i 20150402 13:00:00 some account o 20150402 14:00:00 o 20150402 15:00:00 another:account ```

generates these transactions:

```cli $ hledger -f t.timeclock print 2015-03-30 * optional description after 2 spaces ; optional comment, tags: (some account) 0.33h

2015-03-31 * 22:21-23:59 (another:account) 1.64h

2015-04-01 * 00:00-02:00 (another:account) 2.01h

2015-04-02 * 12:00-15:00 ; this demonstrates multiple sessions being clocked in (another:account) 3.00h

2015-04-02 * 13:00-14:00 (some account) 1.00h

```