reader package:hledger-lib

A hledger journal reader is a storage format name, a list of file extensions assumed to be in this format, and an IO action that reads data in this format, returning a Journal. The journal parser used by the latter is also stored separately for direct use by the journal reader's includedirectivep to parse included files. The type variable m is needed for this parser. Lately it requires an InputOpts, basically to support --old-timeclock.

findReader mformat mpath

Find the reader named by mformat, if provided. ("ssv" and "tsv" are recognised as alternate names for the csv reader, which also handles those formats.) Or, if a file path is provided, find the first reader that handles its file extension, if any.

Separate a file path and its reader prefix, if any.

>>> splitReaderPrefix "csv:-"
(Just csv,"-")

A reader for CSV (character-separated) data. This also reads a rules file to help interpret the CSV data.

A reader for hledger's journal file format (http://hledger.org/hledger.html#the-journal-file). hledger's journal format is a compatible subset of c++ ledger's (http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), so this reader should handle many ledger files as well. Example:

2012/3/24 gift
expenses:gifts  $10
assets:cash

Journal format supports the include directive which can read files in other formats, so the other file format readers need to be importable and invocable here. Some important parts of journal parsing are therefore kept in Hledger.Read.Common, to avoid import cycles.

A reader for a CSV rules file. This reads the actual data from a file specified by a source rule or from a similarly-named file in the same directory. Most of the code for reading rules files and csv files is in this module.

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 ```

A reader for the "timedot" file format. Example:

;DATE
;ACCT  DOTS  # Each dot represents 15m, spaces are ignored
;ACCT  8    # numbers with or without a following h represent hours
;ACCT  5m   # numbers followed by m represent minutes

; on 2/1, 1h was spent on FOSS haskell work, 0.25h on research, etc.
2/1
fos.haskell   .... ..
biz.research  .
inc.client1   .... .... .... .... .... ....

2/2
biz.research  .
inc.client1   .... .... ..