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

doc, tests: clarify what --date2 does

Browse Source
This commit is contained in:
Simon Michael 2016-05-06 16:56:43 -07:00
parent 8dec8b2630
commit e2ce7c4802
8 changed files with 78 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
hledger-lib/doc/hledger_journal.5.m4.md
View File

@ -95,14 +95,19 @@ Some examples: `2010/01/31`, `1/31`, `2010-01-31`, `2010.1.31`.
Real-life transactions sometimes involve more than one date - eg the date
you write a cheque, and the date it clears in your bank. When you want to
model this, eg for more accurate balances, write both dates separated by
an equals sign. The *primary date*, on the left, is used by default; the
*secondary date*, on the right, is used when the `--date2` flag is specified
(For Ledger compatibility, `--aux-date` or `--effective` also work.)
model this, eg for more accurate balances, you can specify individual
[#posting-dates](posting dates), which I recommend. Or, you can use the
secondary dates (aka auxiliary/effective dates) feature, supported for compatibility
with Ledger.
Their meaning is up to you, but it's best to follow a consistent rule.
Eg write the bank's clearing date as primary, and when needed, the
date the transaction was initiated as secondary.
A secondary date can be written after the primary date, separated by
an equals sign. The primary date, on the left, is used by default; the
secondary date, on the right, is used when the `--date2` flag is
specified (`--aux-date` or `--effective` also work).
The meaning of secondary dates is up to you, but it's best to follow a
consistent rule. Eg write the bank's clearing date as primary, and
when needed, the date the transaction was initiated as secondary.
Here's an example. Note that a secondary date will use the year of the
primary date if unspecified.
@ -123,10 +128,11 @@ $ hledger register checking --date2
2010/02/19 movie ticket assets:checking $-10 $-10
```
Secondary dates require some effort: you must use them consistently in
Secondary dates require some effort; you must use them consistently in
your journal entries and remember whether to use or not use the
`--date2` flag for your reports. Arguably they are now obsolete,
superseded by...
`--date2` flag for your reports. They are included in hledger for
Ledger compatibility, but posting dates are a more powerful and less
confusing alternative.
### Posting dates

4
hledger-ui/doc/hledger-ui.1.m4.md
View File

@ -117,8 +117,8 @@ The following common hledger options should also work:
`-p --period=PERIODEXP`
: set start date, end date, and/or reporting interval all at once (overrides the flags above)
`--date2 --aux-date`
: use postings/txns' secondary dates instead
`--date2`
: show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared`
: include only cleared postings/txns

4
hledger-web/doc/hledger-web.1.m4.md
View File

@ -164,8 +164,8 @@ The following common hledger options should also work:
`-p --period=PERIODEXP`
: set start date, end date, and/or reporting interval all at once (overrides the flags above)
`--date2 --aux-date`
: use postings/txns' secondary dates instead
`--date2`
: show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared`
: include only cleared postings/txns

2
hledger/Hledger/Cli/CliOptions.hs
View File

@ -128,7 +128,7 @@ reportflags = [
,flagNone ["quarterly","Q"] (setboolopt "quarterly") "multiperiod/multicolumn report by quarter"
,flagNone ["yearly","Y"] (setboolopt "yearly") "multiperiod/multicolumn report by year"
,flagReq ["period","p"] (\s opts -> Right $ setopt "period" s opts) "PERIODEXP" "set start date, end date, and/or reporting interval all at once (overrides the flags above)"
,flagNone ["date2","aux-date"] (setboolopt "date2") "use postings/txns' secondary dates instead"
,flagNone ["date2"] (setboolopt "date2") "show, and make -b/-e/-p/date: match, secondary dates instead"
,flagNone ["cleared","C"] (setboolopt "cleared") "include only cleared postings/txns"
,flagNone ["pending"] (setboolopt "pending") "include only pending postings/txns"

4
hledger/doc/options.m4.md
View File

@ -80,8 +80,8 @@ Both of these must be written after the command name.
`-p --period=PERIODEXP `
: set start date, end date, and/or reporting interval all at once (overrides the flags above)
`--date2 --aux-date`
: use postings/txns' secondary dates instead
`--date2`
: show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared `
: include only cleared postings/txns

8
hledger/doc/queries.m4.md
View File

@ -56,11 +56,13 @@ or `hledger print cur:\\$`.
: match transaction descriptions
**`date:PERIODEXPR`**
: match dates within the specified period (which should not include a
reporting interval
: match dates within the specified period.
PERIODEXPR should not include a reporting interval.
The command-line `--date2` flag makes this match secondary dates instead (like the `-b`/`-e`/`-p` options).
**`date2:PERIODEXPR`**
: as above, but match secondary dates
: match secondary dates within the specified period.
PERIODEXPR should not include a reporting interval.
**`depth:N`**
: match (or display, depending on command) accounts at or above this depth

40
tests/print/date2.test
View File

@ -1,27 +1,37 @@
# print shows both dates. The second's year defaults to the first's.
hledger -f - print --date2
# 1. print shows both primary and secondary dates. The second's year defaults to the first's.
hledger -f - print
<<<
2009/1/1=1/2 x
a 1
b
2000/1/1=3/3
(a) 1
2000/1/2=2/2
(b) 1
>>>
2009/01/01=2009/01/02 x
a 1
b -1
2000/01/01=2000/03/03
(a) 1
2000/01/02=2000/02/02
(b) 1
>>>2
>>>= 0
# Secondary date of 29 Feb on leap year should be valid
# 2. With --date2, the secondary date is used for sorting.
hledger -f - print --date2
<<<
2001/2/27=2000/2/29 x
a 1
b
2000/1/1=3/3
(a) 1
2000/1/2=2/2
(b) 1
>>>
2001/02/27=2000/02/29 x
a 1
b -1
2000/01/02=2000/02/02
(b) 1
2000/01/01=2000/03/03
(a) 1
>>>2
>>>= 0

31
tests/register/date2.test
View File

@ -1,4 +1,11 @@
# 1.
# intended behaviour of secondary dates:
# print shows both dates
# register shows the primary or (with --date2) secondary date
# -b/-e/-p match the primary or (with --date2) secondary date
# date:D matches the primary or (with --date2) secondary date
# date2:D matches the secondary date
# 1. --date2 causes the secondary date to be displayed
hledger -f - register --date2
<<<
2009/1/1=2010/1/1 x
@ -9,7 +16,7 @@ hledger -f - register --date2
b -1 0
>>>=0
# 2. -b/-e/-p match the secondary date if --date2 is present (also, the secondary date is displayed)
# 2. --date2 causes -b/-e/-p to match the secondary date
hledger -f- register -p 2014/1/2 --date2
<<<
2014/1/1=1/2
@ -21,7 +28,7 @@ hledger -f- register -p 2014/1/2 --date2
2014/01/02 (a) 1 1
>>>=0
# 3. date: matches the secondary date if --date2 is present (on the command line, at least)
# 3. --date2 causes date: to match the secondary date
hledger -f- register date:2014/1/2 --date2
<<<
2014/1/1=1/2
@ -33,7 +40,7 @@ hledger -f- register date:2014/1/2 --date2
2014/01/02 (a) 1 1
>>>=0
# 4. date2: matches the secondary date
# 4. date2: matches the secondary date (but does not necessarily display it)
hledger -f- register date2:2014/1/2
<<<
2014/1/1=1/2
@ -45,7 +52,7 @@ hledger -f- register date2:2014/1/2
2014/01/01 (a) 1 1
>>>=0
# 5. you need to add --date2 if you also want the secondary date displayed
# 5. date2: plus --date2 both matches and displays the secondary date
hledger -f- register date2:2014/1/2 --date2
<<<
2014/1/1=1/2
@ -57,7 +64,7 @@ hledger -f- register date2:2014/1/2 --date2
2014/01/02 (a) 1 1
>>>=0
# 3. date2: matching is not affected by --date2
# 6. date2: matching is not affected by --date2
hledger -f- register date2:2014/1/1 --date2
<<<
2014/1/1=1/2
@ -68,3 +75,15 @@ hledger -f- register date2:2014/1/1 --date2
>>>
>>>=0
# 7. with --date2, the secondary date is used for sorting
hledger -f- register --date2
<<<
2014/1/1=2/2
(a) 1
2014/1/3=2/1
(b) 1
>>>
2014/02/01 (b) 1 1
2014/02/02 (a) 1 2
>>>=0