simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-09-20 02:37:12 +03:00
Code Issues 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
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.
-- @

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

@ -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:

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

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,
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:

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

@ -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)