From 1ebf1fec28e964be697a320692a72a84b1ff1e81 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 21 Aug 2017 17:28:57 -0700 Subject: [PATCH] timedot: also provide syntax for seconds, days, weeks, months & years --- hledger-lib/Hledger/Read/TimedotReader.hs | 50 +++++++++++++-------- hledger-lib/doc/hledger_timedot.5 | 44 ++++++++++-------- hledger-lib/doc/hledger_timedot.5.info | 45 ++++++++++--------- hledger-lib/doc/hledger_timedot.5.m4.md | 29 +++++++----- hledger-lib/doc/hledger_timedot.5.txt | 55 ++++++++++++----------- 5 files changed, 125 insertions(+), 98 deletions(-) diff --git a/hledger-lib/Hledger/Read/TimedotReader.hs b/hledger-lib/Hledger/Read/TimedotReader.hs index 0f29a8458..677d8cd2f 100644 --- a/hledger-lib/Hledger/Read/TimedotReader.hs +++ b/hledger-lib/Hledger/Read/TimedotReader.hs @@ -128,29 +128,41 @@ timedotentryp = do return t timedotdurationp :: JournalParser m Quantity -timedotdurationp = try timedotminutesp <|> try timedothoursp <|> timedotdotsp +timedotdurationp = try timedotnumericp <|> timedotdotsp --- | Parse a duration written as a decimal number of minutes followed by the letter m. --- @ --- 5m --- @ -timedotminutesp :: JournalParser m Quantity -timedotminutesp = do - (q, _, _, _) <- lift numberp - char 'm' - lift (many spacenonewline) - return $ q / 60 - --- | Parse a duration written as a decimal number of hours optionally followed by the letter h. +-- | Parse a duration of seconds, minutes, hours, days, weeks, months or years, +-- written as a decimal number followed by s, m, h, d, w, mo or y, assuming h +-- if there is no unit. Returns the duration as hours, assuming +-- 1m = 60s, 1h = 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. -- @ +-- 1.5 -- 1.5h +-- 90m -- @ -timedothoursp :: JournalParser m Quantity -timedothoursp = do - (q, _, _, _) <- lift numberp - optional $ char 'h' - lift (many spacenonewline) - return q +timedotnumericp :: JournalParser m Quantity +timedotnumericp = do + (q, _, _, _) <- lift numberp + msymbol <- optional $ choice $ map (string . fst) timeUnits + lift (many spacenonewline) + let q' = + case msymbol of + Nothing -> q + Just sym -> + case lookup sym timeUnits of + Just mult -> q * mult + Nothing -> q -- shouldn't happen.. ignore + return q' + +-- (symbol, equivalent in hours). +timeUnits = + [("s",2.777777777777778e-4) + ,("m",1.6666666666666666e-2) + ,("h",1) + ,("d",24) + ,("w",168) + ,("mo",5040) + ,("y",61320) + ] -- | Parse a quantity written as a line of dots, each representing 0.25. -- @ diff --git a/hledger-lib/doc/hledger_timedot.5 b/hledger-lib/doc/hledger_timedot.5 index dda4f7785..70bf2746e 100644 --- a/hledger-lib/doc/hledger_timedot.5 +++ b/hledger-lib/doc/hledger_timedot.5 @@ -9,17 +9,17 @@ Timedot \- hledger\[aq]s human\-friendly time logging format .SH DESCRIPTION .PP Timedot is a plain text format for logging dated, categorised quantities -(eg time), supported by hledger. +(of time, usually), supported by hledger. It is convenient for approximate and retroactive time logging, eg when the real\-time clock\-in/out required with a timeclock file is too precise or too interruptive. It can be formatted like a bar chart, making clear at a glance where time was spent. .PP -Though called "timedot", the format does not specify the commodity being -logged, so could represent other dated, quantifiable things. -Eg you could record a single\-entry journal of financial transactions, -perhaps slightly more conveniently than with hledger_journal(5) format. +Though called "timedot", this format is read by hledger as commodityless +quantities, so it could be used to represent dated quantities other than +time. +In the docs below we\[aq]ll assume it\[aq]s time. .SH FILE FORMAT .PP A timedot file contains a series of day entries. @@ -27,20 +27,26 @@ A day entry begins with a date, and is followed by category/quantity pairs, one per line. Dates are hledger\-style simple dates (see hledger_journal(5)). Categories are hledger\-style account names, optionally indented. -There must be at least two spaces between the category and the quantity. -Quantities can be written in several ways: -.IP "1." 3 -a series of dots (.). -Each dot represents one quarter unit \- eg, a quarter hour. -Spaces may optionally be used to group dots, for easier counting. -.IP "2." 3 -an integral or decimal number optionally followed by the letter h -represents whole units \- eg, hours. -Numbers may be more convenient for large quantities (and can also record -negative quantities). -.IP "3." 3 -an integral or decimal number followed by the letter m represents 1/60th -units \- eg, minutes. +As in a hledger journal, there must be at least two spaces between the +category (account name) and the quantity. +.PP +Quantities can be written as: +.IP \[bu] 2 +a sequence of dots (.) representing quarter hours. +Spaces may optionally be used for grouping and readability. +Eg: .... +\&.. +.IP \[bu] 2 +an integral or decimal number, representing hours. +Eg: 1.5 +.IP \[bu] 2 +an integral or decimal number immediately followed by a unit symbol +\f[C]s\f[], \f[C]m\f[], \f[C]h\f[], \f[C]d\f[], \f[C]w\f[], \f[C]mo\f[], +or \f[C]y\f[], representing seconds, minutes, hours, days weeks, months +or years respectively. +Eg: 90m. +The following equivalencies are assumed, currently: 1m = 60s, 1h = 60m, +1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. .PP Blank lines and lines beginning with #, ; or * are ignored. An example: diff --git a/hledger-lib/doc/hledger_timedot.5.info b/hledger-lib/doc/hledger_timedot.5.info index e9e515405..5fcc0c4cd 100644 --- a/hledger-lib/doc/hledger_timedot.5.info +++ b/hledger-lib/doc/hledger_timedot.5.info @@ -8,16 +8,15 @@ hledger_timedot(5) hledger 1.3.99 ********************************* Timedot is a plain text format for logging dated, categorised quantities -(eg time), supported by hledger. It is convenient for approximate and -retroactive time logging, eg when the real-time clock-in/out required -with a timeclock file is too precise or too interruptive. It can be -formatted like a bar chart, making clear at a glance where time was -spent. +(of time, usually), supported by hledger. It is convenient for +approximate and retroactive time logging, eg when the real-time +clock-in/out required with a timeclock file is too precise or too +interruptive. It can be formatted like a bar chart, making clear at a +glance where time was spent. - Though called "timedot", the format does not specify the commodity -being logged, so could represent other dated, quantifiable things. Eg -you could record a single-entry journal of financial transactions, -perhaps slightly more conveniently than with hledger_journal(5) format. + Though called "timedot", this format is read by hledger as +commodityless quantities, so it could be used to represent dated +quantities other than time. In the docs below we'll assume it's time. * Menu: * FILE FORMAT:: @@ -31,20 +30,22 @@ File: hledger_timedot.5.info, Node: FILE FORMAT, Prev: Top, Up: Top A timedot file contains a series of day entries. A day entry begins with a date, and is followed by category/quantity pairs, one per line. Dates are hledger-style simple dates (see hledger_journal(5)). -Categories are hledger-style account names, optionally indented. There -must be at least two spaces between the category and the quantity. -Quantities can be written in several ways: +Categories are hledger-style account names, optionally indented. As in +a hledger journal, there must be at least two spaces between the +category (account name) and the quantity. - 1. a series of dots (.). Each dot represents one quarter unit - eg, a - quarter hour. Spaces may optionally be used to group dots, for - easier counting. + Quantities can be written as: - 2. an integral or decimal number optionally followed by the letter h - represents whole units - eg, hours. Numbers may be more convenient - for large quantities (and can also record negative quantities). + * a sequence of dots (.) representing quarter hours. Spaces may + optionally be used for grouping and readability. Eg: .... .. - 3. an integral or decimal number followed by the letter m represents - 1/60th units - eg, minutes. + * an integral or decimal number, representing hours. Eg: 1.5 + + * an integral or decimal number immediately followed by a unit symbol + 's', 'm', 'h', 'd', 'w', 'mo', or 'y', representing seconds, + minutes, hours, days weeks, months or years respectively. Eg: 90m. + The following equivalencies are assumed, currently: 1m = 60s, 1h = + 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. Blank lines and lines beginning with #, ; or * are ignored. An example: @@ -109,7 +110,7 @@ $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4  Tag Table: Node: Top78 -Node: FILE FORMAT888 -Ref: #file-format991 +Node: FILE FORMAT815 +Ref: #file-format918  End Tag Table diff --git a/hledger-lib/doc/hledger_timedot.5.m4.md b/hledger-lib/doc/hledger_timedot.5.m4.md index 926b9ad40..b973d1765 100644 --- a/hledger-lib/doc/hledger_timedot.5.m4.md +++ b/hledger-lib/doc/hledger_timedot.5.m4.md @@ -16,13 +16,14 @@ Timedot - hledger's human-friendly time logging format }}) -Timedot is a plain text format for logging dated, categorised quantities (eg time), supported by hledger. +Timedot is a plain text format for logging dated, categorised quantities (of time, usually), supported by hledger. It is convenient for approximate and retroactive time logging, eg when the real-time clock-in/out required with a timeclock file is too precise or too interruptive. It can be formatted like a bar chart, making clear at a glance where time was spent. -Though called "timedot", the format does not specify the commodity being logged, so could represent other dated, quantifiable things. -Eg you could record a single-entry journal of financial transactions, perhaps slightly more conveniently than with hledger_journal(5) format. +Though called "timedot", this format is read by hledger as commodityless quantities, +so it could be used to represent dated quantities other than time. +In the docs below we'll assume it's time. # FILE FORMAT @@ -30,17 +31,23 @@ A timedot file contains a series of day entries. A day entry begins with a date, and is followed by category/quantity pairs, one per line. Dates are hledger-style [simple dates](#simple-dates) (see hledger_journal(5)). Categories are hledger-style account names, optionally indented. -There must be at least two spaces between the category and the quantity. -Quantities can be written in several ways: +As in a hledger journal, there must be at least two spaces between the category (account name) and the quantity. -1. a series of dots (.). - Each dot represents one quarter unit - eg, a quarter hour. - Spaces may optionally be used to group dots, for easier counting. +Quantities can be written as: -2. an integral or decimal number optionally followed by the letter h represents whole units - eg, hours. - Numbers may be more convenient for large quantities (and can also record negative quantities). +- a sequence of dots (.) representing quarter hours. + Spaces may optionally be used for grouping and readability. + Eg: .... .. -3. an integral or decimal number followed by the letter m represents 1/60th units - eg, minutes. +- an integral or decimal number, representing hours. + Eg: 1.5 + +- an integral or decimal number immediately followed by a unit symbol + `s`, `m`, `h`, `d`, `w`, `mo`, or `y`, representing seconds, minutes, hours, days + weeks, months or years respectively. + Eg: 90m. + The following equivalencies are assumed, currently: + 1m = 60s, 1h = 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. Blank lines and lines beginning with #, ; or * are ignored. An example: diff --git a/hledger-lib/doc/hledger_timedot.5.txt b/hledger-lib/doc/hledger_timedot.5.txt index 1c86dba37..8dcf2a55d 100644 --- a/hledger-lib/doc/hledger_timedot.5.txt +++ b/hledger-lib/doc/hledger_timedot.5.txt @@ -8,37 +8,38 @@ NAME DESCRIPTION Timedot is a plain text format for logging dated, categorised quanti- - ties (eg time), supported by hledger. It is convenient for approximate - and retroactive time logging, eg when the real-time clock-in/out - required with a timeclock file is too precise or too interruptive. It - can be formatted like a bar chart, making clear at a glance where time - was spent. + ties (of time, usually), supported by hledger. It is convenient for + approximate and retroactive time logging, eg when the real-time + clock-in/out required with a timeclock file is too precise or too + interruptive. It can be formatted like a bar chart, making clear at a + glance where time was spent. - Though called "timedot", the format does not specify the commodity - being logged, so could represent other dated, quantifiable things. Eg - you could record a single-entry journal of financial transactions, per- - haps slightly more conveniently than with hledger_journal(5) format. + Though called "timedot", this format is read by hledger as commodity- + less quantities, so it could be used to represent dated quantities + other than time. In the docs below we'll assume it's time. FILE FORMAT - A timedot file contains a series of day entries. A day entry begins - with a date, and is followed by category/quantity pairs, one per line. - Dates are hledger-style simple dates (see hledger_journal(5)). Cate- - gories are hledger-style account names, optionally indented. There - must be at least two spaces between the category and the quantity. - Quantities can be written in several ways: + A timedot file contains a series of day entries. A day entry begins + with a date, and is followed by category/quantity pairs, one per line. + Dates are hledger-style simple dates (see hledger_journal(5)). Cate- + gories are hledger-style account names, optionally indented. As in a + hledger journal, there must be at least two spaces between the category + (account name) and the quantity. - 1. a series of dots (.). Each dot represents one quarter unit - eg, a - quarter hour. Spaces may optionally be used to group dots, for eas- - ier counting. + Quantities can be written as: - 2. an integral or decimal number optionally followed by the letter h - represents whole units - eg, hours. Numbers may be more convenient - for large quantities (and can also record negative quantities). + o a sequence of dots (.) representing quarter hours. Spaces may + optionally be used for grouping and readability. Eg: .... .. - 3. an integral or decimal number followed by the letter m represents - 1/60th units - eg, minutes. + o an integral or decimal number, representing hours. Eg: 1.5 - Blank lines and lines beginning with #, ; or * are ignored. An exam- + o an integral or decimal number immediately followed by a unit symbol + s, m, h, d, w, mo, or y, representing seconds, minutes, hours, days + weeks, months or years respectively. Eg: 90m. The following equiva- + lencies are assumed, currently: 1m = 60s, 1h = 60m, 1d = 24h, 1w = + 7d, 1mo = 30d, 1y=365d. + + Blank lines and lines beginning with #, ; or * are ignored. An exam- ple: # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. @@ -82,7 +83,7 @@ FILE FORMAT ------------++---------------------------------------- || 7.75 2.25 8.00 - I prefer to use period for separating account components. We can make + I prefer to use period for separating account components. We can make this work with an account alias: 2016/2/4 @@ -101,7 +102,7 @@ FILE FORMAT REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -115,7 +116,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1)