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 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 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 model this, eg for more accurate balances, you can specify individual
an equals sign. The *primary date*, on the left, is used by default; the [#posting-dates](posting dates), which I recommend. Or, you can use the
*secondary date*, on the right, is used when the `--date2` flag is specified secondary dates (aka auxiliary/effective dates) feature, supported for compatibility
(For Ledger compatibility, `--aux-date` or `--effective` also work.) with Ledger.
Their meaning is up to you, but it's best to follow a consistent rule. A secondary date can be written after the primary date, separated by
Eg write the bank's clearing date as primary, and when needed, the an equals sign. The primary date, on the left, is used by default; the
date the transaction was initiated as secondary. 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 Here's an example. Note that a secondary date will use the year of the
primary date if unspecified. primary date if unspecified.
@ -123,10 +128,11 @@ $ hledger register checking --date2
2010/02/19 movie ticket assets:checking $-10 $-10 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 your journal entries and remember whether to use or not use the
`--date2` flag for your reports. Arguably they are now obsolete, `--date2` flag for your reports. They are included in hledger for
superseded by... Ledger compatibility, but posting dates are a more powerful and less
confusing alternative.
### Posting dates ### 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` `-p --period=PERIODEXP`
: set start date, end date, and/or reporting interval all at once (overrides the flags above) : set start date, end date, and/or reporting interval all at once (overrides the flags above)
`--date2 --aux-date` `--date2`
: use postings/txns' secondary dates instead : show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared` `-C --cleared`
: include only cleared postings/txns : 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` `-p --period=PERIODEXP`
: set start date, end date, and/or reporting interval all at once (overrides the flags above) : set start date, end date, and/or reporting interval all at once (overrides the flags above)
`--date2 --aux-date` `--date2`
: use postings/txns' secondary dates instead : show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared` `-C --cleared`
: include only cleared postings/txns : 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 ["quarterly","Q"] (setboolopt "quarterly") "multiperiod/multicolumn report by quarter"
,flagNone ["yearly","Y"] (setboolopt "yearly") "multiperiod/multicolumn report by year" ,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)" ,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 ["cleared","C"] (setboolopt "cleared") "include only cleared postings/txns"
,flagNone ["pending"] (setboolopt "pending") "include only pending 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 ` `-p --period=PERIODEXP `
: set start date, end date, and/or reporting interval all at once (overrides the flags above) : set start date, end date, and/or reporting interval all at once (overrides the flags above)
`--date2 --aux-date` `--date2`
: use postings/txns' secondary dates instead : show, and match with -b/-e/-p/date:, secondary dates instead
`-C --cleared ` `-C --cleared `
: include only cleared postings/txns : include only cleared postings/txns

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

@ -56,11 +56,13 @@ or `hledger print cur:\\$`.
: match transaction descriptions : match transaction descriptions
**`date:PERIODEXPR`** **`date:PERIODEXPR`**
: match dates within the specified period (which should not include a : match dates within the specified period.
reporting interval 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`** **`date2:PERIODEXPR`**
: as above, but match secondary dates : match secondary dates within the specified period.
PERIODEXPR should not include a reporting interval.
**`depth:N`** **`depth:N`**
: match (or display, depending on command) accounts at or above this depth : 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. # 1. print shows both primary and secondary dates. The second's year defaults to the first's.
hledger -f - print --date2 hledger -f - print
<<< <<<
2009/1/1=1/2 x 2000/1/1=3/3
a 1 (a) 1
b
2000/1/2=2/2
(b) 1
>>> >>>
2009/01/01=2009/01/02 x 2000/01/01=2000/03/03
a 1 (a) 1
b -1
2000/01/02=2000/02/02
(b) 1
>>>2 >>>2
>>>= 0 >>>= 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 hledger -f - print --date2
<<< <<<
2001/2/27=2000/2/29 x 2000/1/1=3/3
a 1 (a) 1
b
2000/1/2=2/2
(b) 1
>>> >>>
2001/02/27=2000/02/29 x 2000/01/02=2000/02/02
a 1 (b) 1
b -1
2000/01/01=2000/03/03
(a) 1
>>>2 >>>2
>>>= 0 >>>= 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 hledger -f - register --date2
<<< <<<
2009/1/1=2010/1/1 x 2009/1/1=2010/1/1 x
@ -9,7 +16,7 @@ hledger -f - register --date2
b -1 0 b -1 0
>>>=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 hledger -f- register -p 2014/1/2 --date2
<<< <<<
2014/1/1=1/2 2014/1/1=1/2
@ -21,7 +28,7 @@ hledger -f- register -p 2014/1/2 --date2
2014/01/02 (a) 1 1 2014/01/02 (a) 1 1
>>>=0 >>>=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 hledger -f- register date:2014/1/2 --date2
<<< <<<
2014/1/1=1/2 2014/1/1=1/2
@ -33,7 +40,7 @@ hledger -f- register date:2014/1/2 --date2
2014/01/02 (a) 1 1 2014/01/02 (a) 1 1
>>>=0 >>>=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 hledger -f- register date2:2014/1/2
<<< <<<
2014/1/1=1/2 2014/1/1=1/2
@ -45,7 +52,7 @@ hledger -f- register date2:2014/1/2
2014/01/01 (a) 1 1 2014/01/01 (a) 1 1
>>>=0 >>>=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 hledger -f- register date2:2014/1/2 --date2
<<< <<<
2014/1/1=1/2 2014/1/1=1/2
@ -57,7 +64,7 @@ hledger -f- register date2:2014/1/2 --date2
2014/01/02 (a) 1 1 2014/01/02 (a) 1 1
>>>=0 >>>=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 hledger -f- register date2:2014/1/1 --date2
<<< <<<
2014/1/1=1/2 2014/1/1=1/2
@ -68,3 +75,15 @@ hledger -f- register date2:2014/1/1 --date2
>>> >>>
>>>=0 >>>=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