From e2ce7c48028e5631db42f3c8e9464b268697ca2c Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 6 May 2016 16:56:43 -0700 Subject: [PATCH] doc, tests: clarify what --date2 does --- hledger-lib/doc/hledger_journal.5.m4.md | 26 +++++++++------- hledger-ui/doc/hledger-ui.1.m4.md | 4 +-- hledger-web/doc/hledger-web.1.m4.md | 4 +-- hledger/Hledger/Cli/CliOptions.hs | 2 +- hledger/doc/options.m4.md | 4 +-- hledger/doc/queries.m4.md | 8 +++-- tests/print/date2.test | 40 +++++++++++++++---------- tests/register/date2.test | 31 +++++++++++++++---- 8 files changed, 78 insertions(+), 41 deletions(-) diff --git a/hledger-lib/doc/hledger_journal.5.m4.md b/hledger-lib/doc/hledger_journal.5.m4.md index 7c0e03c99..8758002ab 100644 --- a/hledger-lib/doc/hledger_journal.5.m4.md +++ b/hledger-lib/doc/hledger_journal.5.m4.md @@ -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 diff --git a/hledger-ui/doc/hledger-ui.1.m4.md b/hledger-ui/doc/hledger-ui.1.m4.md index b43e8413f..05c1a985f 100644 --- a/hledger-ui/doc/hledger-ui.1.m4.md +++ b/hledger-ui/doc/hledger-ui.1.m4.md @@ -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 diff --git a/hledger-web/doc/hledger-web.1.m4.md b/hledger-web/doc/hledger-web.1.m4.md index 8e6af02ef..95973589f 100644 --- a/hledger-web/doc/hledger-web.1.m4.md +++ b/hledger-web/doc/hledger-web.1.m4.md @@ -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 diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs index 8881a3d5c..acb9c4c79 100644 --- a/hledger/Hledger/Cli/CliOptions.hs +++ b/hledger/Hledger/Cli/CliOptions.hs @@ -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" diff --git a/hledger/doc/options.m4.md b/hledger/doc/options.m4.md index f4eb6f2ba..9251f012e 100644 --- a/hledger/doc/options.m4.md +++ b/hledger/doc/options.m4.md @@ -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 diff --git a/hledger/doc/queries.m4.md b/hledger/doc/queries.m4.md index 1aadb35de..111bb85d2 100644 --- a/hledger/doc/queries.m4.md +++ b/hledger/doc/queries.m4.md @@ -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 diff --git a/tests/print/date2.test b/tests/print/date2.test index ef77f0fd9..55799ffd5 100644 --- a/tests/print/date2.test +++ b/tests/print/date2.test @@ -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 diff --git a/tests/register/date2.test b/tests/register/date2.test index ccabddff1..dc61c37fd 100644 --- a/tests/register/date2.test +++ b/tests/register/date2.test @@ -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