From 86fac4236d7da0bfb60b3e17c1fbb23313adf095 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 9 Nov 2020 17:13:57 -0800 Subject: [PATCH] ;update manuals --- hledger-lib/hledger_journal.5 | 14 +- hledger-lib/hledger_journal.info | 202 ++++++++++----------- hledger-lib/hledger_journal.txt | 14 +- hledger/hledger.1 | 4 + hledger/hledger.info | 122 +++++++------ hledger/hledger.txt | 296 ++++++++++++++++--------------- 6 files changed, 336 insertions(+), 316 deletions(-) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 9406f389e..1b4a795ce 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -584,7 +584,8 @@ commodity INR 9,99,99,999.00 commodity 1 000 000.9455 \f[R] .fi -.SS Amount display style +.PP +.SS Commodity display style .PP For each commodity, hledger chooses a consistent format to use when displaying amounts. @@ -613,11 +614,10 @@ journal, with the max observed number of decimal places. If you want to see fewer decimal places in reports, use a commodity directive to override that. .PP -hledger uses banker\[aq]s rounding: it rounds to the nearest even +Note, hledger uses banker\[aq]s rounding: it rounds to the nearest even number, eg 0.5 displayed with zero decimal places is \[dq]0\[dq]). -(Note, prior to hledger 1.17.1 this could vary if hledger happened to be -built with an old version of Decimal (<0.5.1); since 1.17.1 it\[aq]s -guaranteed.) +(Guaranteed since hledger 1.17.1; in older versions this could vary if +hledger was built with Decimal < 0.5.1.) .SS Transaction prices .PP Within a transaction, you can note an amount\[aq]s price in another @@ -1198,7 +1198,7 @@ your data. (Without this, hledger will parse both \f[C]1,000\f[R] and \f[C]1.000\f[R] as 1). .IP "3." 3 -It declares the amount display style to use in output - decimal and +It declares a commodity\[aq]s display style in output - decimal and digit group marks, number of decimal places, symbol placement etc. .PP You are likely to run into one of the problems solved by commodity @@ -1244,7 +1244,7 @@ followed by 0 or more decimal digits. .PP Note hledger normally uses banker\[aq]s rounding, so 0.5 displayed with zero decimal digits is \[dq]0\[dq]. -(More at Amount display style.) +(More at Commodity display style.) .SS Default commodity .PP The \f[C]D\f[R] directive sets a default commodity, to be used for diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 9ecc086f0..cd7481dc2 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -487,10 +487,10 @@ EUR 1E3 * Menu: * Digit group marks:: -* Amount display style:: +* Commodity display style::  -File: hledger_journal.info, Node: Digit group marks, Next: Amount display style, Up: Amounts +File: hledger_journal.info, Node: Digit group marks, Next: Commodity display style, Up: Amounts 1.8.1 Digit group marks ----------------------- @@ -523,10 +523,10 @@ commodity INR 9,99,99,999.00 commodity 1 000 000.9455  -File: hledger_journal.info, Node: Amount display style, Prev: Digit group marks, Up: Amounts +File: hledger_journal.info, Node: Commodity display style, Prev: Digit group marks, Up: Amounts -1.8.2 Amount display style --------------------------- +1.8.2 Commodity display style +----------------------------- For each commodity, hledger chooses a consistent format to use when displaying amounts. (Except price amounts, which are always displayed @@ -553,10 +553,10 @@ journal, with the max observed number of decimal places. If you want to see fewer decimal places in reports, use a commodity directive to override that. - hledger uses banker's rounding: it rounds to the nearest even number, -eg 0.5 displayed with zero decimal places is "0"). (Note, prior to -hledger 1.17.1 this could vary if hledger happened to be built with an -old version of Decimal (<0.5.1); since 1.17.1 it's guaranteed.) + Note, hledger uses banker's rounding: it rounds to the nearest even +number, eg 0.5 displayed with zero decimal places is "0"). (Guaranteed +since hledger 1.17.1; in older versions this could vary if hledger was +built with Decimal < 0.5.1.)  File: hledger_journal.info, Node: Transaction prices, Next: Lot prices and lot dates, Prev: Amounts, Up: Transactions @@ -1079,7 +1079,7 @@ The 'commodity' directive has several functions: formats in your data. (Without this, hledger will parse both '1,000' and '1.000' as 1). - 3. It declares the amount display style to use in output - decimal and + 3. It declares a commodity's display style in output - decimal and digit group marks, number of decimal places, symbol placement etc. You are likely to run into one of the problems solved by commodity @@ -1114,7 +1114,7 @@ significant. The number must include a decimal mark: either a period or a comma, followed by 0 or more decimal digits. Note hledger normally uses banker's rounding, so 0.5 displayed with -zero decimal digits is "0". (More at Amount display style.) +zero decimal digits is "0". (More at Commodity display style.)  File: hledger_journal.info, Node: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: Directives @@ -1889,96 +1889,96 @@ Node: Account names15177 Ref: #account-names15318 Node: Amounts15805 Ref: #amounts15944 -Node: Digit group marks17052 -Ref: #digit-group-marks17200 -Node: Amount display style18138 -Ref: #amount-display-style18292 -Node: Transaction prices19729 -Ref: #transaction-prices19901 -Node: Lot prices and lot dates22332 -Ref: #lot-prices-and-lot-dates22529 -Node: Balance assertions23017 -Ref: #balance-assertions23203 -Node: Assertions and ordering24236 -Ref: #assertions-and-ordering24424 -Node: Assertions and included files25124 -Ref: #assertions-and-included-files25367 -Node: Assertions and multiple -f options25700 -Ref: #assertions-and-multiple--f-options25956 -Node: Assertions and commodities26088 -Ref: #assertions-and-commodities26320 -Node: Assertions and prices27477 -Ref: #assertions-and-prices27691 -Node: Assertions and subaccounts28131 -Ref: #assertions-and-subaccounts28360 -Node: Assertions and virtual postings28684 -Ref: #assertions-and-virtual-postings28926 -Node: Assertions and precision29068 -Ref: #assertions-and-precision29261 -Node: Balance assignments29528 -Ref: #balance-assignments29702 -Node: Balance assignments and prices30866 -Ref: #balance-assignments-and-prices31038 -Node: Directives31262 -Ref: #directives31421 -Node: Directives and multiple files36919 -Ref: #directives-and-multiple-files37102 -Node: Comment blocks37766 -Ref: #comment-blocks37949 -Node: Including other files38125 -Ref: #including-other-files38305 -Node: Default year39229 -Ref: #default-year39398 -Node: Declaring commodities39805 -Ref: #declaring-commodities39988 -Node: Default commodity41794 -Ref: #default-commodity41980 -Node: Declaring market prices42869 -Ref: #declaring-market-prices43064 -Node: Declaring accounts43921 -Ref: #declaring-accounts44107 -Node: Account comments45032 -Ref: #account-comments45195 -Node: Account subdirectives45619 -Ref: #account-subdirectives45814 -Node: Account types46127 -Ref: #account-types46311 -Node: Account display order49357 -Ref: #account-display-order49527 -Node: Rewriting accounts50678 -Ref: #rewriting-accounts50863 -Node: Basic aliases51620 -Ref: #basic-aliases51766 -Node: Regex aliases52470 -Ref: #regex-aliases52642 -Node: Combining aliases53361 -Ref: #combining-aliases53554 -Node: Aliases and multiple files54830 -Ref: #aliases-and-multiple-files55039 -Node: end aliases55618 -Ref: #end-aliases55775 -Node: Default parent account55876 -Ref: #default-parent-account56044 -Node: Periodic transactions56928 -Ref: #periodic-transactions57103 -Node: Periodic rule syntax58975 -Ref: #periodic-rule-syntax59181 -Node: Two spaces between period expression and description!59885 -Ref: #two-spaces-between-period-expression-and-description60204 -Node: Forecasting with periodic transactions60888 -Ref: #forecasting-with-periodic-transactions61193 -Node: Budgeting with periodic transactions63248 -Ref: #budgeting-with-periodic-transactions63487 -Node: Auto postings63896 -Ref: #auto-postings64036 -Node: Auto postings and multiple files66215 -Ref: #auto-postings-and-multiple-files66419 -Node: Auto postings and dates66628 -Ref: #auto-postings-and-dates66902 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions67077 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions67428 -Node: Auto posting tags67770 -Ref: #auto-posting-tags67985 +Node: Digit group marks17055 +Ref: #digit-group-marks17206 +Node: Commodity display style18144 +Ref: #commodity-display-style18307 +Node: Transaction prices19711 +Ref: #transaction-prices19883 +Node: Lot prices and lot dates22314 +Ref: #lot-prices-and-lot-dates22511 +Node: Balance assertions22999 +Ref: #balance-assertions23185 +Node: Assertions and ordering24218 +Ref: #assertions-and-ordering24406 +Node: Assertions and included files25106 +Ref: #assertions-and-included-files25349 +Node: Assertions and multiple -f options25682 +Ref: #assertions-and-multiple--f-options25938 +Node: Assertions and commodities26070 +Ref: #assertions-and-commodities26302 +Node: Assertions and prices27459 +Ref: #assertions-and-prices27673 +Node: Assertions and subaccounts28113 +Ref: #assertions-and-subaccounts28342 +Node: Assertions and virtual postings28666 +Ref: #assertions-and-virtual-postings28908 +Node: Assertions and precision29050 +Ref: #assertions-and-precision29243 +Node: Balance assignments29510 +Ref: #balance-assignments29684 +Node: Balance assignments and prices30848 +Ref: #balance-assignments-and-prices31020 +Node: Directives31244 +Ref: #directives31403 +Node: Directives and multiple files36901 +Ref: #directives-and-multiple-files37084 +Node: Comment blocks37748 +Ref: #comment-blocks37931 +Node: Including other files38107 +Ref: #including-other-files38287 +Node: Default year39211 +Ref: #default-year39380 +Node: Declaring commodities39787 +Ref: #declaring-commodities39970 +Node: Default commodity41775 +Ref: #default-commodity41961 +Node: Declaring market prices42850 +Ref: #declaring-market-prices43045 +Node: Declaring accounts43902 +Ref: #declaring-accounts44088 +Node: Account comments45013 +Ref: #account-comments45176 +Node: Account subdirectives45600 +Ref: #account-subdirectives45795 +Node: Account types46108 +Ref: #account-types46292 +Node: Account display order49338 +Ref: #account-display-order49508 +Node: Rewriting accounts50659 +Ref: #rewriting-accounts50844 +Node: Basic aliases51601 +Ref: #basic-aliases51747 +Node: Regex aliases52451 +Ref: #regex-aliases52623 +Node: Combining aliases53342 +Ref: #combining-aliases53535 +Node: Aliases and multiple files54811 +Ref: #aliases-and-multiple-files55020 +Node: end aliases55599 +Ref: #end-aliases55756 +Node: Default parent account55857 +Ref: #default-parent-account56025 +Node: Periodic transactions56909 +Ref: #periodic-transactions57084 +Node: Periodic rule syntax58956 +Ref: #periodic-rule-syntax59162 +Node: Two spaces between period expression and description!59866 +Ref: #two-spaces-between-period-expression-and-description60185 +Node: Forecasting with periodic transactions60869 +Ref: #forecasting-with-periodic-transactions61174 +Node: Budgeting with periodic transactions63229 +Ref: #budgeting-with-periodic-transactions63468 +Node: Auto postings63877 +Ref: #auto-postings64017 +Node: Auto postings and multiple files66196 +Ref: #auto-postings-and-multiple-files66400 +Node: Auto postings and dates66609 +Ref: #auto-postings-and-dates66883 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions67058 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions67409 +Node: Auto posting tags67751 +Ref: #auto-posting-tags67966  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 322c2c751..4648b77b6 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -411,7 +411,7 @@ FILE FORMAT commodity INR 9,99,99,999.00 commodity 1 000 000.9455 - Amount display style + Commodity display style For each commodity, hledger chooses a consistent format to use when displaying amounts. (Except price amounts, which are always displayed as written). The display style is chosen as follows: @@ -437,10 +437,10 @@ FILE FORMAT see fewer decimal places in reports, use a commodity directive to over- ride that. - hledger uses banker's rounding: it rounds to the nearest even number, - eg 0.5 displayed with zero decimal places is "0"). (Note, prior to - hledger 1.17.1 this could vary if hledger happened to be built with an - old version of Decimal (<0.5.1); since 1.17.1 it's guaranteed.) + Note, hledger uses banker's rounding: it rounds to the nearest even + number, eg 0.5 displayed with zero decimal places is "0"). (Guaranteed + since hledger 1.17.1; in older versions this could vary if hledger was + built with Decimal < 0.5.1.) Transaction prices Within a transaction, you can note an amount's price in another commod- @@ -838,7 +838,7 @@ FILE FORMAT formats in your data. (Without this, hledger will parse both 1,000 and 1.000 as 1). - 3. It declares the amount display style to use in output - decimal and + 3. It declares a commodity's display style in output - decimal and digit group marks, number of decimal places, symbol placement etc. You are likely to run into one of the problems solved by commodity di- @@ -873,7 +873,7 @@ FILE FORMAT comma, followed by 0 or more decimal digits. Note hledger normally uses banker's rounding, so 0.5 displayed with - zero decimal digits is "0". (More at Amount display style.) + zero decimal digits is "0". (More at Commodity display style.) Default commodity The D directive sets a default commodity, to be used for amounts with- diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 743e06fe7..9a3d83549 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -3805,6 +3805,10 @@ $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE .PP (If you think import should leave amounts implicit like print does, please test it and send a pull request.) +.SS Commodity display styles +.PP +Imported amounts will be formatted according to the canonical commodity +styles (declared or inferred) in the main journal file. .SS incomestatement .PP incomestatement, is diff --git a/hledger/hledger.info b/hledger/hledger.info index 175cb5aed..094515f8f 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -3218,9 +3218,10 @@ $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions * Menu: * Importing balance assignments:: +* Commodity display styles::  -File: hledger.info, Node: Importing balance assignments, Up: import +File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Up: import 3.18.1 Importing balance assignments ------------------------------------ @@ -3238,6 +3239,15 @@ $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE (If you think import should leave amounts implicit like print does, please test it and send a pull request.) + +File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import + +3.18.2 Commodity display styles +------------------------------- + +Imported amounts will be formatted according to the canonical commodity +styles (declared or inferred) in the main journal file. +  File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: COMMANDS @@ -4252,60 +4262,62 @@ Node: help111433 Ref: #help111533 Node: import112614 Ref: #import112728 -Node: Importing balance assignments113621 -Ref: #importing-balance-assignments113769 -Node: incomestatement114418 -Ref: #incomestatement114551 -Node: notes115896 -Ref: #notes116009 -Node: payees116377 -Ref: #payees116483 -Node: prices116903 -Ref: #prices117009 -Node: print117350 -Ref: #print117460 -Node: print-unique122256 -Ref: #print-unique122382 -Node: register122667 -Ref: #register122794 -Node: Custom register output127243 -Ref: #custom-register-output127372 -Node: register-match128709 -Ref: #register-match128843 -Node: rewrite129194 -Ref: #rewrite129309 -Node: Re-write rules in a file131164 -Ref: #re-write-rules-in-a-file131298 -Node: Diff output format132508 -Ref: #diff-output-format132677 -Node: rewrite vs print --auto133769 -Ref: #rewrite-vs.-print---auto133948 -Node: roi134504 -Ref: #roi134602 -Node: stats135614 -Ref: #stats135713 -Node: tags136501 -Ref: #tags136599 -Node: test137118 -Ref: #test137226 -Node: Add-on commands137973 -Ref: #add-on-commands138090 -Node: ui139433 -Ref: #ui139521 -Node: web139575 -Ref: #web139678 -Node: iadd139794 -Ref: #iadd139905 -Node: interest139987 -Ref: #interest140094 -Node: ENVIRONMENT140334 -Ref: #environment140446 -Node: FILES141431 -Ref: #files-1141534 -Node: LIMITATIONS141747 -Ref: #limitations141866 -Node: TROUBLESHOOTING142608 -Ref: #troubleshooting142721 +Node: Importing balance assignments113650 +Ref: #importing-balance-assignments113831 +Node: Commodity display styles114480 +Ref: #commodity-display-styles114651 +Node: incomestatement114780 +Ref: #incomestatement114913 +Node: notes116258 +Ref: #notes116371 +Node: payees116739 +Ref: #payees116845 +Node: prices117265 +Ref: #prices117371 +Node: print117712 +Ref: #print117822 +Node: print-unique122618 +Ref: #print-unique122744 +Node: register123029 +Ref: #register123156 +Node: Custom register output127605 +Ref: #custom-register-output127734 +Node: register-match129071 +Ref: #register-match129205 +Node: rewrite129556 +Ref: #rewrite129671 +Node: Re-write rules in a file131526 +Ref: #re-write-rules-in-a-file131660 +Node: Diff output format132870 +Ref: #diff-output-format133039 +Node: rewrite vs print --auto134131 +Ref: #rewrite-vs.-print---auto134310 +Node: roi134866 +Ref: #roi134964 +Node: stats135976 +Ref: #stats136075 +Node: tags136863 +Ref: #tags136961 +Node: test137480 +Ref: #test137588 +Node: Add-on commands138335 +Ref: #add-on-commands138452 +Node: ui139795 +Ref: #ui139883 +Node: web139937 +Ref: #web140040 +Node: iadd140156 +Ref: #iadd140267 +Node: interest140349 +Ref: #interest140456 +Node: ENVIRONMENT140696 +Ref: #environment140808 +Node: FILES141793 +Ref: #files-1141896 +Node: LIMITATIONS142109 +Ref: #limitations142228 +Node: TROUBLESHOOTING142970 +Ref: #troubleshooting143083  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 13be44740..506fb3afe 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -2777,15 +2777,19 @@ COMMANDS (If you think import should leave amounts implicit like print does, please test it and send a pull request.) + Commodity display styles + Imported amounts will be formatted according to the canonical commodity + styles (declared or inferred) in the main journal file. + incomestatement incomestatement, is - This command displays an income statement, showing revenues and ex- + This command displays an income statement, showing revenues and ex- penses during one or more periods. Amounts are shown with normal posi- tive sign, as in conventional financial statements. The revenue and expense accounts shown are those accounts declared with - the Revenue or Expense type, or otherwise all accounts under a top- - level revenue or income or expense account (case insensitive, plurals + the Revenue or Expense type, or otherwise all accounts under a top- + level revenue or income or expense account (case insensitive, plurals allowed). Example: @@ -2812,13 +2816,13 @@ COMMANDS 0 With a reporting interval, multiple columns will be shown, one for each - report period. Normally incomestatement shows revenues/expenses per - period, though as with multicolumn balance reports you can alter the - report mode with --change/--cumulative/--historical. Instead of abso- + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the + report mode with --change/--cumulative/--historical. Instead of abso- lute values percentages can be displayed with -%. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, html, and (experimen- + tions The output formats supported are txt, csv, html, and (experimen- tal) json. notes @@ -2826,8 +2830,8 @@ COMMANDS List the unique notes that appear in transactions. This command lists the unique notes that appear in transactions, in al- - phabetic order. You can add a query to select a subset of transac- - tions. The note is the part of the transaction description after a | + phabetic order. You can add a query to select a subset of transac- + tions. The note is the part of the transaction description after a | character (or if there is no |, the whole description). Example: @@ -2841,8 +2845,8 @@ COMMANDS List the unique payee/payer names that appear in transactions. This command lists the unique payee/payer names that appear in transac- - tions, in alphabetic order. You can add a query to select a subset of - transactions. The payee/payer is the part of the transaction descrip- + tions, in alphabetic order. You can add a query to select a subset of + transactions. The payee/payer is the part of the transaction descrip- tion before a | character (or if there is no |, the whole description). Example: @@ -2854,10 +2858,10 @@ COMMANDS prices prices - Print market price directives from the journal. With --costs, also - print synthetic market prices based on transaction prices. With --in- - verted-costs, also print inverse prices based on transaction prices. - Prices (and postings providing prices) can be filtered by a query. + Print market price directives from the journal. With --costs, also + print synthetic market prices based on transaction prices. With --in- + verted-costs, also print inverse prices based on transaction prices. + Prices (and postings providing prices) can be filtered by a query. Price amounts are always displayed with their full precision. print @@ -2865,11 +2869,11 @@ COMMANDS Show transaction journal entries, sorted by date. The print command displays full journal entries (transactions) from the - journal file in date order, tidily formatted. With --date2, transac- + journal file in date order, tidily formatted. With --date2, transac- tions are sorted by secondary date instead. print's output is always a valid hledger journal. - It preserves all transaction information, but it does not preserve di- + It preserves all transaction information, but it does not preserve di- rectives or inter-transaction comments $ hledger print @@ -2896,43 +2900,43 @@ COMMANDS Normally, the journal entry's explicit or implicit amount style is pre- served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, when a transaction price is im- - plied but not written, it will not appear in the output. You can use - the -x/--explicit flag to make all amounts and transaction prices ex- - plicit, which can be useful for troubleshooting or for making your + not appear in the output. Similarly, when a transaction price is im- + plied but not written, it will not appear in the output. You can use + the -x/--explicit flag to make all amounts and transaction prices ex- + plicit, which can be useful for troubleshooting or for making your journal more readable and robust against data entry errors. -x is also implied by using any of -B,-V,-X,--value. - Note, -x/--explicit will cause postings with a multi-commodity amount - (these can arise when a multi-commodity transaction has an implicit - amount) to be split into multiple single-commodity postings, keeping + Note, -x/--explicit will cause postings with a multi-commodity amount + (these can arise when a multi-commodity transaction has an implicit + amount) to be split into multiple single-commodity postings, keeping the output parseable. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost using that price. This can be used for troubleshooting. - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is no similar-enough match, no transaction will be shown. With --new, for each FILE being read, hledger reads (and writes) a spe- - cial state file (.latest.FILE in the same directory), containing the - latest transaction date(s) that were seen last time FILE was read. - When this file is found, only transactions with newer dates (and new - transactions on the latest date) are printed. This is useful for ig- - noring already-seen entries in import data, such as downloaded CSV + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for ig- + noring already-seen entries in import data, such as downloaded CSV files. Eg: $ hledger -f bank1.csv print --new (shows transactions added since last print --new on this file) - This assumes that transactions added to FILE always have same or in- - creasing dates, and that transactions on the same day do not get re- + This assumes that transactions added to FILE always have same or in- + creasing dates, and that transactions on the same day do not get re- ordered. See also the import command. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, and (experimental) + tions The output formats supported are txt, csv, and (experimental) json and sql. Here's an example of print's CSV output: @@ -2951,20 +2955,20 @@ COMMANDS "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) print-unique @@ -2988,14 +2992,14 @@ COMMANDS Show postings and their running total. The register command displays matched postings, across all accounts, in - date order, with their running total or running historical balance. - (See also the aregister command, which shows matched transactions in a + date order, with their running total or running historical balance. + (See also the aregister command, which shows matched transactions in a specific account.) register normally shows line per posting, but note that multi-commodity amounts will occupy multiple lines (one line per commodity). - It is typically used with a query selecting a particular account, to + It is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -3006,8 +3010,8 @@ COMMANDS With --date2, it shows and sorts by secondary date instead. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -3017,18 +3021,18 @@ COMMANDS The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one ac- + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- count and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account to- + bers. It's also useful to show postings on the checking account to- gether with the related account: $ hledger register --related --invert assets:checking @@ -3040,7 +3044,7 @@ COMMANDS 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -3057,7 +3061,7 @@ COMMANDS 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth op- + Often, you'll want to see just one line per interval. The --depth op- tion helps with this, causing subaccounts to be aggregated: $ hledger register --monthly assets --depth 1h @@ -3065,17 +3069,17 @@ COMMANDS 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of in- - tervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of in- + tervals. This ensures that the first and last intervals are full length and comparable to the others in the report. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not a bash shell variable) or by using the --width/-w option. - The description and account columns normally share the space equally + The description and account columns normally share the space equally (about half of (width - 40) each). You can adjust this by adding a de- scription width as part of --width's argument, comma-separated: --width W,D . Here's a diagram (won't display correctly in --help): @@ -3094,27 +3098,27 @@ COMMANDS $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, and (experimental) + tions The output formats supported are txt, csv, and (experimental) json. register-match register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. If there are multiple equally - good matches, it shows the most recent. Query options (options, not - arguments) can be used to restrict the search space. Helps ledger-au- + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps ledger-au- tosync detect already-seen transactions when importing. rewrite rewrite Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print + For now the only rewrite available is adding new postings, like print --auto. This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds + the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- + posting amounts can be fixed, or a multiplier of the existing transac- tion's first posting amount. Examples: @@ -3130,7 +3134,7 @@ COMMANDS (reserve:grocery) *0.25 ; reserve 25% for grocery (reserve:) *0.25 ; reserve 25% for grocery - Note the single quotes to protect the dollar sign from bash, and the + Note the single quotes to protect the dollar sign from bash, and the two spaces between account and amount. More: @@ -3140,16 +3144,16 @@ COMMANDS $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - Argument for --add-posting option is a usual posting of transaction - with an exception for amount specification. More precisely, you can + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can use '*' (star symbol) before the amount to indicate that that this is a - factor for an amount of original matched posting. If the amount in- + factor for an amount of original matched posting. If the amount in- cludes a commodity name, the new posting amount will be in the new com- - modity; otherwise, it will be in the matched posting amount's commod- + modity; otherwise, it will be in the matched posting amount's commod- ity. Re-write rules in a file - During the run this tool will execute so called "Automated Transac- + During the run this tool will execute so called "Automated Transac- tions" found in any journal it process. I.e instead of specifying this operations in command line you can put them in a journal file. @@ -3164,7 +3168,7 @@ COMMANDS budget:gifts *-1 assets:budget *1 - Note that '=' (equality symbol) that is used instead of date in trans- + Note that '=' (equality symbol) that is used instead of date in trans- actions you usually write. It indicates the query by which you want to match the posting to add new ones. @@ -3177,12 +3181,12 @@ COMMANDS --add-posting 'assets:budget *1' \ > rewritten-tidy-output.journal - It is important to understand that relative order of such entries in - journal is important. You can re-use result of previously added post- + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- ings. Diff output format - To use this tool for batch modification of your journal files you may + To use this tool for batch modification of your journal files you may find useful output in form of unified diff. $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' @@ -3206,10 +3210,10 @@ COMMANDS If you'll pass this through patch tool you'll get transactions contain- ing the posting that matches your query be updated. Note that multiple - files might be update according to list of input files specified via + files might be update according to list of input files specified via --file options and include directives inside of these files. - Be careful. Whole transaction being re-formatted in a style of output + Be careful. Whole transaction being re-formatted in a style of output from hledger print. See also: @@ -3217,48 +3221,48 @@ COMMANDS https://github.com/simonmichael/hledger/issues/99 rewrite vs. print --auto - This command predates print --auto, and currently does much the same + This command predates print --auto, and currently does much the same thing, but with these differences: - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect only child files. - o rewrite's query limits which transactions can be rewritten; all are + o rewrite's query limits which transactions can be rewritten; all are printed. print --auto's query limits which transactions are printed. - o rewrite applies rules specified on command line or in the journal. + o rewrite applies rules specified on command line or in the journal. print --auto applies rules specified in the journal. roi roi - Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. - This command assumes that you have account(s) that hold nothing but + This command assumes that you have account(s) that hold nothing but your investments and whenever you record current appraisal/valuation of these investments you offset unrealized profit and loss into account(s) that, again, hold nothing but unrealized profit and loss. - Any transactions affecting balance of investment account(s) and not - originating from unrealized profit and loss account(s) are assumed to + Any transactions affecting balance of investment account(s) and not + originating from unrealized profit and loss account(s) are assumed to be your investments or withdrawals. - At a minimum, you need to supply a query (which could be just an ac- + At a minimum, you need to supply a query (which could be just an ac- count name) to select your investments with --inv, and another query to identify your profit and loss transactions with --pnl. - It will compute and display the internalized rate of return (IRR) and - time-weighted rate of return (TWR) for your investments for the time - period requested. Both rates of return are annualized before display, + It will compute and display the internalized rate of return (IRR) and + time-weighted rate of return (TWR) for your investments for the time + period requested. Both rates of return are annualized before display, regardless of the length of reporting interval. stats stats Show some journal statistics. - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report for each report period. Example: @@ -3276,35 +3280,35 @@ COMMANDS Commodities : 1 ($) Market prices : 12 ($) - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. tags tags - List the unique tag names used in the journal. With a TAGREGEX argu- + List the unique tag names used in the journal. With a TAGREGEX argu- ment, only tag names matching the regular expression (case insensitive) - are shown. With QUERY arguments, only transactions matching the query + are shown. With QUERY arguments, only transactions matching the query are considered. With the --values flag, the tags' unique values are listed instead. - With --parsed flag, all tags or values are shown in the order they are + With --parsed flag, all tags or values are shown in the order they are parsed from the input data, including duplicates. - With -E/--empty, any blank/empty values will also be shown, otherwise + With -E/--empty, any blank/empty values will also be shown, otherwise they are omitted. test test Run built-in unit tests. - This command runs the unit tests built in to hledger and hledger-lib, - printing the results on stdout. If any test fails, the exit code will + This command runs the unit tests built in to hledger and hledger-lib, + printing the results on stdout. If any test fails, the exit code will be non-zero. - This is mainly used by hledger developers, but you can also use it to - sanity-check the installed hledger executable on your platform. All - tests are expected to pass - if you ever see a failure, please report + This is mainly used by hledger developers, but you can also use it to + sanity-check the installed hledger executable on your platform. All + tests are expected to pass - if you ever see a failure, please report as a bug! This command also accepts tasty test runner options, written after a -- @@ -3313,35 +3317,35 @@ COMMANDS $ hledger test -- -pData.Amount --color=never - For help on these, see https://github.com/feuerbach/tasty#options (-- + For help on these, see https://github.com/feuerbach/tasty#options (-- --help currently doesn't show them). Add-on commands - hledger also searches for external add-on commands, and will include + hledger also searches for external add-on commands, and will include these in the commands list. These are programs or scripts in your PATH - whose name starts with hledger- and ends with a recognised file exten- + whose name starts with hledger- and ends with a recognised file exten- sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). - Add-ons can be invoked like any hledger command, but there are a few + Add-ons can be invoked like any hledger command, but there are a few things to be aware of. Eg if the hledger-web add-on is installed, - o hledger -h web shows hledger's help, while hledger web -h shows + o hledger -h web shows hledger's help, while hledger web -h shows hledger-web's help. - o Flags specific to the add-on must have a preceding -- to hide them - from hledger. So hledger web --serve --port 9000 will be rejected; + o Flags specific to the add-on must have a preceding -- to hide them + from hledger. So hledger web --serve --port 9000 will be rejected; you must use hledger web -- --serve --port 9000. o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger (and - haskell) library functions that built-in commands do, for command-line + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger (and + haskell) library functions that built-in commands do, for command-line options, journal parsing, reporting, etc. - Two important add-ons are the hledger-ui and hledger-web user inter- + Two important add-ons are the hledger-ui and hledger-web user inter- faces. These are maintained and released along with hledger: ui @@ -3360,20 +3364,20 @@ COMMANDS hledger-interest generates interest transactions for an account accord- ing to various schemes. - A few more experimental or old add-ons can be found in hledger's bin/ + A few more experimental or old add-ons can be found in hledger's bin/ directory. These are typically prototypes and not guaranteed to work. ENVIRONMENT LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). - A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- - trolled finance directory and YYYY is the current year. Or ~/DIR/cur- + A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- + trolled finance directory and YYYY is the current year. Or ~/DIR/cur- rent.journal, where current.journal is a symbolic link to YYYY.journal. On Mac computers, you can set this and other environment variables in a - more thorough way that also affects applications started from the GUI + more thorough way that also affects applications started from the GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en- vironment.plist file containing @@ -3383,21 +3387,21 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. - COLUMNS The screen width used by the register command. Default: the + COLUMNS The screen width used by the register command. Default: the full terminal width. - NO_COLOR If this variable exists with any value, hledger will not use - ANSI color codes in terminal output. This overrides the + NO_COLOR If this variable exists with any value, hledger will not use + ANSI color codes in terminal output. This overrides the --color/--colour option. FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). LIMITATIONS - The need to precede addon command options with -- when invoked from + The need to precede addon command options with -- when invoked from hledger is awkward. When input data contains non-ascii characters, a suitable system locale @@ -3413,36 +3417,36 @@ LIMITATIONS In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. - Not all of Ledger's journal file syntax is supported. See file format + Not all of Ledger's journal file syntax is supported. See file format differences. - On large data files, hledger is slower and uses more memory than + On large data files, hledger is slower and uses more memory than Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and re- - member you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and re- + member you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command 'hledger' found" stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, + be added to your PATH environment variable. Eg on unix-like systems, that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - Getting errors like "Illegal byte sequence" or "Invalid or incomplete - multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- + Getting errors like "Illegal byte sequence" or "Invalid or incomplete + multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- ment (invalid character)" Programs compiled with GHC (hledger, haskell build tools, etc.) need to have a UTF-8-aware locale configured in the environment, otherwise they - will fail with these kinds of errors when they encounter non-ascii + will fail with these kinds of errors when they encounter non-ascii characters. - To fix it, set the LANG environment variable to some locale which sup- + To fix it, set the LANG environment variable to some locale which sup- ports UTF-8. The locale you choose must be installed on your system. Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux: @@ -3457,8 +3461,8 @@ TROUBLESHOOTING POSIX $ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command - If available, C.UTF-8 will also work. If your preferred locale isn't - listed by locale -a, you might need to install it. Eg on Ubuntu/De- + If available, C.UTF-8 will also work. If your preferred locale isn't + listed by locale -a, you might need to install it. Eg on Ubuntu/De- bian: $ apt-get install language-pack-fr @@ -3478,8 +3482,8 @@ TROUBLESHOOTING $ echo "export LANG=en_US.utf8" >>~/.bash_profile $ bash --login - Exact spelling and capitalisation may be important. Note the differ- - ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow + Exact spelling and capitalisation may be important. Note the differ- + ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow variant spellings, but others (eg macos) require it to be exact: $ locale -a | grep -iE en_us.*utf @@ -3489,7 +3493,7 @@ TROUBLESHOOTING 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) @@ -3503,7 +3507,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)