slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

timedot: also provide syntax for seconds, days, weeks, months & years

Browse Source
This commit is contained in:
Simon Michael 2017-08-21 17:28:57 -07:00
parent d8696c5ea0
commit 1ebf1fec28
5 changed files with 125 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
hledger-lib/Hledger/Read/TimedotReader.hs
View File

@ -128,29 +128,41 @@ timedotentryp = do
return t return t
timedotdurationp :: JournalParser m Quantity 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. -- | 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
-- 5m -- if there is no unit. Returns the duration as hours, assuming
-- @ -- 1m = 60s, 1h = 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d.
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.
-- @ -- @
-- 1.5
-- 1.5h -- 1.5h
-- 90m
-- @ -- @
timedothoursp :: JournalParser m Quantity timedotnumericp :: JournalParser m Quantity
timedothoursp = do timedotnumericp = do
(q, _, _, _) <- lift numberp (q, _, _, _) <- lift numberp
optional $ char 'h' msymbol <- optional $ choice $ map (string . fst) timeUnits
lift (many spacenonewline) lift (many spacenonewline)
return q 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. -- | Parse a quantity written as a line of dots, each representing 0.25.
-- @ -- @

44
hledger-lib/doc/hledger_timedot.5
View File

@ -9,17 +9,17 @@ Timedot \- hledger\[aq]s human\-friendly time logging format
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
Timedot is a plain text format for logging dated, categorised quantities 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 It is convenient for approximate and retroactive time logging, eg when
the real\-time clock\-in/out required with a timeclock file is too the real\-time clock\-in/out required with a timeclock file is too
precise or too interruptive. precise or too interruptive.
It can be formatted like a bar chart, making clear at a glance where It can be formatted like a bar chart, making clear at a glance where
time was spent. time was spent.
.PP .PP
Though called "timedot", the format does not specify the commodity being Though called "timedot", this format is read by hledger as commodityless
logged, so could represent other dated, quantifiable things. quantities, so it could be used to represent dated quantities other than
Eg you could record a single\-entry journal of financial transactions, time.
perhaps slightly more conveniently than with hledger_journal(5) format. In the docs below we\[aq]ll assume it\[aq]s time.
.SH FILE FORMAT .SH FILE FORMAT
.PP .PP
A timedot file contains a series of day entries. 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. pairs, one per line.
Dates are hledger\-style simple dates (see hledger_journal(5)). Dates are hledger\-style simple dates (see hledger_journal(5)).
Categories are hledger\-style account names, optionally indented. Categories are hledger\-style account names, optionally indented.
There must be at least two spaces between the category and the quantity. As in a hledger journal, there must be at least two spaces between the
Quantities can be written in several ways: category (account name) and the quantity.
.IP "1." 3 .PP
a series of dots (.). Quantities can be written as:
Each dot represents one quarter unit \- eg, a quarter hour. .IP \[bu] 2
Spaces may optionally be used to group dots, for easier counting. a sequence of dots (.) representing quarter hours.
.IP "2." 3 Spaces may optionally be used for grouping and readability.
an integral or decimal number optionally followed by the letter h Eg: ....
represents whole units \- eg, hours. \&..
Numbers may be more convenient for large quantities (and can also record .IP \[bu] 2
negative quantities). an integral or decimal number, representing hours.
.IP "3." 3 Eg: 1.5
an integral or decimal number followed by the letter m represents 1/60th .IP \[bu] 2
units \- eg, minutes. 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 .PP
Blank lines and lines beginning with #, ; or * are ignored. Blank lines and lines beginning with #, ; or * are ignored.
An example: An example:

45
hledger-lib/doc/hledger_timedot.5.info
View File

@ -8,16 +8,15 @@ hledger_timedot(5) hledger 1.3.99
********************************* *********************************
Timedot is a plain text format for logging dated, categorised quantities Timedot is a plain text format for logging dated, categorised quantities
(eg time), supported by hledger. It is convenient for approximate and (of time, usually), supported by hledger. It is convenient for
retroactive time logging, eg when the real-time clock-in/out required approximate and retroactive time logging, eg when the real-time
with a timeclock file is too precise or too interruptive. It can be clock-in/out required with a timeclock file is too precise or too
formatted like a bar chart, making clear at a glance where time was interruptive. It can be formatted like a bar chart, making clear at a
spent. glance where time was spent.
Though called "timedot", the format does not specify the commodity Though called "timedot", this format is read by hledger as
being logged, so could represent other dated, quantifiable things. Eg commodityless quantities, so it could be used to represent dated
you could record a single-entry journal of financial transactions, quantities other than time. In the docs below we'll assume it's time.
perhaps slightly more conveniently than with hledger_journal(5) format.
* Menu: * Menu:
* FILE FORMAT:: * 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 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. with a date, and is followed by category/quantity pairs, one per line.
Dates are hledger-style simple dates (see hledger_journal(5)). Dates are hledger-style simple dates (see hledger_journal(5)).
Categories are hledger-style account names, optionally indented. There Categories are hledger-style account names, optionally indented. As in
must be at least two spaces between the category and the quantity. a hledger journal, there must be at least two spaces between the
Quantities can be written in several ways: category (account name) and the quantity.
1. a series of dots (.). Each dot represents one quarter unit - eg, a Quantities can be written as:
quarter hour. Spaces may optionally be used to group dots, for
easier counting.
2. an integral or decimal number optionally followed by the letter h * a sequence of dots (.) representing quarter hours. Spaces may
represents whole units - eg, hours. Numbers may be more convenient optionally be used for grouping and readability. Eg: .... ..
for large quantities (and can also record negative quantities).
3. an integral or decimal number followed by the letter m represents * an integral or decimal number, representing hours. Eg: 1.5
1/60th units - eg, minutes.
* 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 Blank lines and lines beginning with #, ; or * are ignored. An
example: example:
@ -109,7 +110,7 @@ $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4
 
Tag Table: Tag Table:
Node: Top78 Node: Top78
Node: FILE FORMAT888 Node: FILE FORMAT815
Ref: #file-format991 Ref: #file-format918
 
End Tag Table End Tag Table

29
hledger-lib/doc/hledger_timedot.5.m4.md
View File

@ -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, 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. 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. 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. Though called "timedot", this format is read by hledger as commodityless quantities,
Eg you could record a single-entry journal of financial transactions, perhaps slightly more conveniently than with hledger_journal(5) format. so it could be used to represent dated quantities other than time.
In the docs below we'll assume it's time.
# FILE FORMAT # 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. 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)). Dates are hledger-style [simple dates](#simple-dates) (see hledger_journal(5)).
Categories are hledger-style account names, optionally indented. Categories are hledger-style account names, optionally indented.
There must be at least two spaces between the category and the quantity. As in a hledger journal, there must be at least two spaces between the category (account name) and the quantity.
Quantities can be written in several ways:
1. a series of dots (.). Quantities can be written as:
Each dot represents one quarter unit - eg, a quarter hour.
Spaces may optionally be used to group dots, for easier counting.
2. an integral or decimal number optionally followed by the letter h represents whole units - eg, hours. - a sequence of dots (.) representing quarter hours.
Numbers may be more convenient for large quantities (and can also record negative quantities). 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. Blank lines and lines beginning with #, ; or * are ignored.
An example: An example:

55
hledger-lib/doc/hledger_timedot.5.txt
View File

@ -8,37 +8,38 @@ NAME
DESCRIPTION DESCRIPTION
Timedot is a plain text format for logging dated, categorised quanti- Timedot is a plain text format for logging dated, categorised quanti-
ties (eg time), supported by hledger. It is convenient for approximate ties (of time, usually), supported by hledger. It is convenient for
and retroactive time logging, eg when the real-time clock-in/out approximate and retroactive time logging, eg when the real-time
required with a timeclock file is too precise or too interruptive. It clock-in/out required with a timeclock file is too precise or too
can be formatted like a bar chart, making clear at a glance where time interruptive. It can be formatted like a bar chart, making clear at a
was spent. glance where time was spent.
Though called "timedot", the format does not specify the commodity Though called "timedot", this format is read by hledger as commodity-
being logged, so could represent other dated, quantifiable things. Eg less quantities, so it could be used to represent dated quantities
you could record a single-entry journal of financial transactions, per- other than time. In the docs below we'll assume it's time.
haps slightly more conveniently than with hledger_journal(5) format.
FILE FORMAT FILE FORMAT
A timedot file contains a series of day entries. A day entry begins 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. with a date, and is followed by category/quantity pairs, one per line.
Dates are hledger-style simple dates (see hledger_journal(5)). Cate- Dates are hledger-style simple dates (see hledger_journal(5)). Cate-
gories are hledger-style account names, optionally indented. There gories are hledger-style account names, optionally indented. As in a
must be at least two spaces between the category and the quantity. hledger journal, there must be at least two spaces between the category
Quantities can be written in several ways: (account name) and the quantity.
1. a series of dots (.). Each dot represents one quarter unit - eg, a Quantities can be written as:
quarter hour. Spaces may optionally be used to group dots, for eas-
ier counting.
2. an integral or decimal number optionally followed by the letter h o a sequence of dots (.) representing quarter hours. Spaces may
represents whole units - eg, hours. Numbers may be more convenient optionally be used for grouping and readability. Eg: .... ..
for large quantities (and can also record negative quantities).
3. an integral or decimal number followed by the letter m represents o an integral or decimal number, representing hours. Eg: 1.5
1/60th units - eg, minutes.
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: ple:
# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. # 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 || 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: this work with an account alias:
2016/2/4 2016/2/4
@ -101,7 +102,7 @@ FILE FORMAT
REPORTING BUGS 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) or hledger mail list)
@ -115,7 +116,7 @@ COPYRIGHT
SEE ALSO 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- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) dot(5), ledger(1)