diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index b4fbdc663..7febe0205 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -635,6 +635,7 @@ Conditional blocks (\[dq]if blocks\[dq]) are a block of rules that are applied only to CSV records which match certain patterns. They are often used for customising account names based on transaction descriptions. +.SS Matching the whole record .PP Each MATCHER can be a record matcher, which looks like this: .IP @@ -659,6 +660,7 @@ field containing a comma will appear like two fields). Eg, if the original record is \f[C]2020-01-01; \[dq]Acme, Inc.\[dq]; 1,000\f[R], the REGEX will actually see \f[C]2020-01-01,Acme, Inc., 1,000\f[R]). +.SS Matching individual fields .PP Or, MATCHER can be a field matcher, like this: .IP @@ -671,6 +673,7 @@ Or, MATCHER can be a field matcher, like this: which matches just the content of a particular CSV field. CSVFIELD is a percent sign followed by the field\[aq]s name or column number, like \f[C]%date\f[R] or \f[C]%1\f[R]. +.SS Combining matchers .PP A single matcher can be written on the same line as the \[dq]if\[dq]; or multiple matchers can be written on the following lines, non-indented. @@ -686,6 +689,7 @@ MATCHER RULE \f[R] .fi +.SS Rules applied on successful match .PP After the patterns there should be one or more rules to apply, all indented by at least one space. diff --git a/hledger-lib/hledger_csv.info b/hledger-lib/hledger_csv.info index 9a3e6605f..e6c61cd61 100644 --- a/hledger-lib/hledger_csv.info +++ b/hledger-lib/hledger_csv.info @@ -615,7 +615,20 @@ applied only to CSV records which match certain patterns. They are often used for customising account names based on transaction descriptions. - Each MATCHER can be a record matcher, which looks like this: +* Menu: + +* Matching the whole record:: +* Matching individual fields:: +* Combining matchers:: +* Rules applied on successful match:: + + +File: hledger_csv.info, Node: Matching the whole record, Next: Matching individual fields, Up: if block + +2.5.1 Matching the whole record +------------------------------- + +Each MATCHER can be a record matcher, which looks like this: REGEX @@ -632,7 +645,13 @@ that a field containing a comma will appear like two fields). Eg, if the original record is '2020-01-01; "Acme, Inc."; 1,000', the REGEX will actually see '2020-01-01,Acme, Inc., 1,000'). - Or, MATCHER can be a field matcher, like this: + +File: hledger_csv.info, Node: Matching individual fields, Next: Combining matchers, Prev: Matching the whole record, Up: if block + +2.5.2 Matching individual fields +-------------------------------- + +Or, MATCHER can be a field matcher, like this: %CSVFIELD REGEX @@ -640,7 +659,13 @@ actually see '2020-01-01,Acme, Inc., 1,000'). is a percent sign followed by the field's name or column number, like '%date' or '%1'. - A single matcher can be written on the same line as the "if"; or + +File: hledger_csv.info, Node: Combining matchers, Next: Rules applied on successful match, Prev: Matching individual fields, Up: if block + +2.5.3 Combining matchers +------------------------ + +A single matcher can be written on the same line as the "if"; or multiple matchers can be written on the following lines, non-indented. Multiple matchers are OR'd (any one of them can match), unless one begins with an '&' symbol, in which case it is AND'ed with the previous @@ -651,7 +676,13 @@ MATCHER & MATCHER RULE - After the patterns there should be one or more rules to apply, all + +File: hledger_csv.info, Node: Rules applied on successful match, Prev: Combining matchers, Up: if block + +2.5.4 Rules applied on successful match +--------------------------------------- + +After the patterns there should be one or more rules to apply, all indented by at least one space. Three kinds of rule are allowed in conditional blocks: @@ -1148,40 +1179,48 @@ Node: separator21340 Ref: #separator21475 Node: if block21886 Ref: #if-block22011 -Node: if table24287 -Ref: #if-table24406 -Node: end26144 -Ref: #end26256 -Node: date-format26480 -Ref: #date-format26612 -Node: newest-first27361 -Ref: #newest-first27499 -Node: include28182 -Ref: #include28313 -Node: balance-type28757 -Ref: #balance-type28877 -Node: TIPS29577 -Ref: #tips29659 -Node: Rapid feedback29915 -Ref: #rapid-feedback30032 -Node: Valid CSV30492 -Ref: #valid-csv30622 -Node: File Extension30814 -Ref: #file-extension30966 -Node: Reading multiple CSV files31376 -Ref: #reading-multiple-csv-files31561 -Node: Valid transactions31802 -Ref: #valid-transactions31980 -Node: Deduplicating importing32608 -Ref: #deduplicating-importing32787 -Node: Setting amounts33820 -Ref: #setting-amounts33989 -Node: Setting currency/commodity34976 -Ref: #setting-currencycommodity35168 -Node: Referencing other fields35971 -Ref: #referencing-other-fields36171 -Node: How CSV rules are evaluated37068 -Ref: #how-csv-rules-are-evaluated37241 +Node: Matching the whole record22412 +Ref: #matching-the-whole-record22587 +Node: Matching individual fields23391 +Ref: #matching-individual-fields23595 +Node: Combining matchers23819 +Ref: #combining-matchers24015 +Node: Rules applied on successful match24328 +Ref: #rules-applied-on-successful-match24519 +Node: if table25173 +Ref: #if-table25292 +Node: end27030 +Ref: #end27142 +Node: date-format27366 +Ref: #date-format27498 +Node: newest-first28247 +Ref: #newest-first28385 +Node: include29068 +Ref: #include29199 +Node: balance-type29643 +Ref: #balance-type29763 +Node: TIPS30463 +Ref: #tips30545 +Node: Rapid feedback30801 +Ref: #rapid-feedback30918 +Node: Valid CSV31378 +Ref: #valid-csv31508 +Node: File Extension31700 +Ref: #file-extension31852 +Node: Reading multiple CSV files32262 +Ref: #reading-multiple-csv-files32447 +Node: Valid transactions32688 +Ref: #valid-transactions32866 +Node: Deduplicating importing33494 +Ref: #deduplicating-importing33673 +Node: Setting amounts34706 +Ref: #setting-amounts34875 +Node: Setting currency/commodity35862 +Ref: #setting-currencycommodity36054 +Node: Referencing other fields36857 +Ref: #referencing-other-fields37057 +Node: How CSV rules are evaluated37954 +Ref: #how-csv-rules-are-evaluated38127  End Tag Table diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index 06b663d05..a25e3f354 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -479,6 +479,7 @@ CSV RULES only to CSV records which match certain patterns. They are often used for customising account names based on transaction descriptions. + Matching the whole record Each MATCHER can be a record matcher, which looks like this: REGEX @@ -496,6 +497,7 @@ CSV RULES original record is 2020-01-01; "Acme, Inc."; 1,000, the REGEX will ac- tually see 2020-01-01,Acme, Inc., 1,000). + Matching individual fields Or, MATCHER can be a field matcher, like this: %CSVFIELD REGEX @@ -504,6 +506,7 @@ CSV RULES a percent sign followed by the field's name or column number, like %date or %1. + Combining matchers A single matcher can be written on the same line as the "if"; or multi- ple matchers can be written on the following lines, non-indented. Mul- tiple matchers are OR'd (any one of them can match), unless one begins @@ -514,6 +517,7 @@ CSV RULES & MATCHER RULE + Rules applied on successful match After the patterns there should be one or more rules to apply, all in- dented by at least one space. Three kinds of rule are allowed in con- ditional blocks: diff --git a/hledger/Hledger/Cli/Commands/Aregister.txt b/hledger/Hledger/Cli/Commands/Aregister.txt index 602c793cd..c61fef79d 100644 --- a/hledger/Hledger/Cli/Commands/Aregister.txt +++ b/hledger/Hledger/Cli/Commands/Aregister.txt @@ -13,11 +13,11 @@ subaccounts), from the point of view of that account. Each line shows: - the account's historical running balance (including balance from transactions before the report start date). -This is different from register, which shows individual postings. With -aregister, each line represents a whole transaction - as in hledger-ui, -hledger-web, and your bank statement. You might prefer aregister for -reconciling with real-world asset/liability accounts, and register for -reviewing detailed revenues/expenses. +With aregister, each line represents a whole transaction - as in +hledger-ui, hledger-web, and your bank statement. By contrast, the +register command shows individual postings, across all accounts. You +might prefer aregister for reconciling with real-world asset/liability +accounts, and register for reviewing detailed revenues/expenses. An account must be specified as the first argument, which should be the full account name or an account pattern (regular expression). aregister diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index aabd85925..3708a0f28 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -292,10 +292,6 @@ Balance changes in 2008: (Average is rounded to the dollar here since all journal amounts are) -A limitation of multicolumn balance reports: eliding of boring parent -accounts in tree mode, as in the classic balance report, is not yet -supported. - The --transpose flag can be used to exchange the rows and columns of a multicolumn report. diff --git a/hledger/Hledger/Cli/Commands/Tags.txt b/hledger/Hledger/Cli/Commands/Tags.txt index 9fabb9828..c229907fd 100644 --- a/hledger/Hledger/Cli/Commands/Tags.txt +++ b/hledger/Hledger/Cli/Commands/Tags.txt @@ -1,8 +1,15 @@ tags -List all the tag names used in the journal. With a TAGREGEX argument, +List the unique tag names used in the journal. With a TAGREGEX argument, only tag names matching the regular expression (case insensitive) are shown. With QUERY arguments, only transactions matching the query are -considered. With --values flag, the tags' unique values are listed -instead. +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 +parsed from the input data, including duplicates. + +With -E/--empty, any blank/empty values will also be shown, otherwise +they are omitted. _FLAGS diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 466cbff45..18059ae35 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -2510,6 +2510,84 @@ Date [2015/05/22]: $ .PP On Microsoft Windows, the add command makes sure that no part of the file path ends with a period, as that would cause problems (#1056). +.SS aregister +.PP +aregister, areg +.PD 0 +.P +.PD +Show transactions affecting a particular account, and the account\[aq]s +running balance. +.PP +\f[C]aregister\f[R] shows the transactions affecting a particular +account (and its subaccounts), from the point of view of that account. +Each line shows: +.IP \[bu] 2 +the transaction\[aq]s (or posting\[aq]s, see below) date +.IP \[bu] 2 +the names of the other account(s) involved +.IP \[bu] 2 +the net change to this account\[aq]s balance +.IP \[bu] 2 +the account\[aq]s historical running balance (including balance from +transactions before the report start date). +.PP +With \f[C]aregister\f[R], each line represents a whole transaction - as +in hledger-ui, hledger-web, and your bank statement. +By contrast, the \f[C]register\f[R] command shows individual postings, +across all accounts. +You might prefer \f[C]aregister\f[R] for reconciling with real-world +asset/liability accounts, and \f[C]register\f[R] for reviewing detailed +revenues/expenses. +.PP +An account must be specified as the first argument, which should be the +full account name or an account pattern (regular expression). +aregister will show transactions in this account (the first one matched) +and any of its subaccounts. +.PP +Any additional arguments form a query which will filter the transactions +shown. +.PP +Transactions making a net change of zero are not shown by default; add +the \f[C]-E/--empty\f[R] flag to show them. +.SS aregister and custom posting dates +.PP +Transactions whose date is outside the report period can still be shown, +if they have a posting to this account dated inside the report period. +(And in this case it\[aq]s the posting date that is shown.) This ensures +that \f[C]aregister\f[R] can show an accurate historical running +balance, matching the one shown by \f[C]register -H\f[R] with the same +arguments. +.PP +To filter strictly by transaction date instead, add the +\f[C]--txn-dates\f[R] flag. +If you use this flag and some of your postings have custom dates, +it\[aq]s probably best to assume the running balance is wrong. +.SS Output format +.PP +This command also supports the output destination and output format +options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R], +and \f[C]json\f[R]. +.PP +Examples: +.PP +Show all transactions and historical running balance in the first +account whose name contains \[dq]checking\[dq]: +.IP +.nf +\f[C] +$ hledger areg checking +\f[R] +.fi +.PP +Show transactions and historical running balance in all asset accounts +during july: +.IP +.nf +\f[C] +$ hledger areg assets date:jul +\f[R] +.fi .SS balance .PP balance, bal, b @@ -2876,10 +2954,6 @@ Balance changes in 2008: \f[R] .fi .PP -A limitation of multicolumn balance reports: eliding of boring parent -accounts in tree mode, as in the classic balance report, is not yet -supported. -.PP The \f[C]--transpose\f[R] flag can be used to exchange the rows and columns of a multicolumn report. .PP @@ -4334,12 +4408,19 @@ tags .PD 0 .P .PD -List all the tag names used in the journal. +List the unique tag names used in the journal. With a TAGREGEX argument, only tag names matching the regular expression (case insensitive) are shown. With QUERY arguments, only transactions matching the query are considered. -With --values flag, the tags\[aq] unique values are listed instead. +.PP +With the --values flag, the tags\[aq] unique values are listed instead. +.PP +With --parsed flag, all tags or values are shown in the order they are +parsed from the input data, including duplicates. +.PP +With -E/--empty, any blank/empty values will also be shown, otherwise +they are omitted. .SS test .PP test diff --git a/hledger/hledger.info b/hledger/hledger.info index 3fcbb1d8a..486b04dd0 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -1896,6 +1896,8 @@ detailed command help. * accounts:: * activity:: * add:: +* aregister:: +* aregister and custom posting dates:: * balance:: * balancesheet:: * balancesheetequity:: @@ -1977,7 +1979,7 @@ $ hledger activity --quarterly 2008-10-01 **  -File: hledger.info, Node: add, Next: balance, Prev: activity, Up: COMMANDS +File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: COMMANDS 3.3 add ======= @@ -2048,9 +2050,84 @@ Date [2015/05/22]: $ file path ends with a period, as that would cause problems (#1056).  -File: hledger.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMANDS +File: hledger.info, Node: aregister, Next: aregister and custom posting dates, Prev: add, Up: COMMANDS -3.4 balance +3.4 aregister +============= + +aregister, areg +Show transactions affecting a particular account, and the account's +running balance. + + 'aregister' shows the transactions affecting a particular account +(and its subaccounts), from the point of view of that account. Each +line shows: + + * the transaction's (or posting's, see below) date + * the names of the other account(s) involved + * the net change to this account's balance + * the account's historical running balance (including balance from + transactions before the report start date). + + With 'aregister', each line represents a whole transaction - as in +hledger-ui, hledger-web, and your bank statement. By contrast, the +'register' command shows individual postings, across all accounts. You +might prefer 'aregister' for reconciling with real-world asset/liability +accounts, and 'register' for reviewing detailed revenues/expenses. + + An account must be specified as the first argument, which should be +the full account name or an account pattern (regular expression). +aregister will show transactions in this account (the first one matched) +and any of its subaccounts. + + Any additional arguments form a query which will filter the +transactions shown. + + Transactions making a net change of zero are not shown by default; +add the '-E/--empty' flag to show them. + + +File: hledger.info, Node: aregister and custom posting dates, Next: balance, Prev: aregister, Up: COMMANDS + +3.5 aregister and custom posting dates +====================================== + +Transactions whose date is outside the report period can still be shown, +if they have a posting to this account dated inside the report period. +(And in this case it's the posting date that is shown.) This ensures +that 'aregister' can show an accurate historical running balance, +matching the one shown by 'register -H' with the same arguments. + + To filter strictly by transaction date instead, add the '--txn-dates' +flag. If you use this flag and some of your postings have custom dates, +it's probably best to assume the running balance is wrong. + +* Menu: + +* Output format:: + +3.5.1 Output format +------------------- + +This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', and 'json'. + + Examples: + + Show all transactions and historical running balance in the first +account whose name contains "checking": + +$ hledger areg checking + + Show transactions and historical running balance in all asset +accounts during july: + +$ hledger areg assets date:jul + + +File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister and custom posting dates, Up: COMMANDS + +3.6 balance =========== balance, bal, b @@ -2093,7 +2170,7 @@ is used to ensure this (more below).  File: hledger.info, Node: Classic balance report, Next: Customising the classic balance report, Up: balance -3.4.1 Classic balance report +3.6.1 Classic balance report ---------------------------- This is the original balance report, as found in Ledger. It usually @@ -2141,7 +2218,7 @@ $ hledger balance -p 2008/6 expenses --no-total  File: hledger.info, Node: Customising the classic balance report, Next: Colour support, Prev: Classic balance report, Up: balance -3.4.2 Customising the classic balance report +3.6.2 Customising the classic balance report -------------------------------------------- You can customise the layout of classic balance reports with '--format @@ -2203,7 +2280,7 @@ may be needed to get pleasing results.  File: hledger.info, Node: Colour support, Next: Flat mode, Prev: Customising the classic balance report, Up: balance -3.4.3 Colour support +3.6.3 Colour support -------------------- The balance command shows negative amounts in red, if: @@ -2214,7 +2291,7 @@ The balance command shows negative amounts in red, if:  File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Prev: Colour support, Up: balance -3.4.4 Flat mode +3.6.4 Flat mode --------------- To see a flat list instead of the default hierarchical display, use @@ -2230,7 +2307,7 @@ $ hledger balance -p 2008/6 expenses -N --flat --drop 1  File: hledger.info, Node: Depth limited balance reports, Next: Percentages, Prev: Flat mode, Up: balance -3.4.5 Depth limited balance reports +3.6.5 Depth limited balance reports ----------------------------------- With '--depth N' or 'depth:N' or just '-N', balance reports show @@ -2249,7 +2326,7 @@ show inclusive balances at the depth limit.  File: hledger.info, Node: Percentages, Next: Multicolumn balance report, Prev: Depth limited balance reports, Up: balance -3.4.6 Percentages +3.6.6 Percentages ----------------- With '-%' or '--percent', balance reports show each account's value @@ -2281,7 +2358,7 @@ to use '-V' or '-B' to coerce the report into using a single commodity.  File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Percentages, Up: balance -3.4.7 Multicolumn balance report +3.6.7 Multicolumn balance report -------------------------------- Multicolumn or tabular balance reports are a very useful hledger @@ -2386,10 +2463,6 @@ Balance changes in 2008: (Average is rounded to the dollar here since all journal amounts are) - A limitation of multicolumn balance reports: eliding of boring parent -accounts in tree mode, as in the classic balance report, is not yet -supported. - The '--transpose' flag can be used to exchange the rows and columns of a multicolumn report. @@ -2406,7 +2479,7 @@ bal -D | less -RS'.  File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance -3.4.8 Budget report +3.6.8 Budget report ------------------- With '--budget', extra columns are displayed showing budget goals for @@ -2529,7 +2602,7 @@ Budget performance in 2017/11/01-2017/12/31:  File: hledger.info, Node: Nested budgets, Up: Budget report -3.4.8.1 Nested budgets +3.6.8.1 Nested budgets ...................... You can add budgets to any account in your account hierarchy. If you @@ -2614,7 +2687,7 @@ Budget performance in 2019/01: ----------------------------------------++------------------------------- || 0 [ 0] -3.4.9 Output format +3.6.9 Output format ------------------- This command also supports the output destination and output format @@ -2624,7 +2697,7 @@ non-budget reports only) 'html', and (experimental) 'json'.  File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS -3.5 balancesheet +3.7 balancesheet ================ balancesheet, bs @@ -2674,7 +2747,7 @@ options The output formats supported are 'txt', 'csv', 'html', and  File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS -3.6 balancesheetequity +3.8 balancesheetequity ====================== balancesheetequity, bse @@ -2714,7 +2787,7 @@ options The output formats supported are 'txt', 'csv', 'html', and  File: hledger.info, Node: cashflow, Next: check-dates, Prev: balancesheetequity, Up: COMMANDS -3.7 cashflow +3.9 cashflow ============ cashflow, cf @@ -2754,8 +2827,8 @@ options The output formats supported are 'txt', 'csv', 'html', and  File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS -3.8 check-dates -=============== +3.10 check-dates +================ check-dates Check that transactions are sorted by increasing date. With -date2, @@ -2766,8 +2839,8 @@ Reads the default journal file, or another specified with -f.  File: hledger.info, Node: check-dupes, Next: close, Prev: check-dates, Up: COMMANDS -3.9 check-dupes -=============== +3.11 check-dupes +================ check-dupes Reports account names having the same leaf but different prefixes. In @@ -2779,7 +2852,7 @@ the default journal file, or another specified as an argument.  File: hledger.info, Node: close, Next: codes, Prev: check-dupes, Up: COMMANDS -3.10 close +3.12 close ========== close, equity @@ -2819,7 +2892,7 @@ you have many foreign currency or investment transactions.  File: hledger.info, Node: close usage, Up: close -3.10.1 close usage +3.12.1 close usage ------------------ If you split your journal files by time (eg yearly), you will typically @@ -2890,7 +2963,7 @@ breaking balance assertions:  File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: COMMANDS -3.11 codes +3.13 codes ========== codes @@ -2936,7 +3009,7 @@ $ hledger codes -E  File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: COMMANDS -3.12 commodities +3.14 commodities ================ commodities @@ -2945,7 +3018,7 @@ List all commodity/currency symbols used or declared in the journal.  File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS -3.13 descriptions +3.15 descriptions ================= descriptions @@ -2965,7 +3038,7 @@ Person A  File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: COMMANDS -3.14 diff +3.16 diff ========= diff @@ -3000,7 +3073,7 @@ These transactions are in the second file only:  File: hledger.info, Node: files, Next: help, Prev: diff, Up: COMMANDS -3.15 files +3.17 files ========== files @@ -3010,7 +3083,7 @@ file names matching the regular expression (case sensitive) are shown.  File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS -3.16 help +3.18 help ========= help @@ -3050,7 +3123,7 @@ DESCRIPTION  File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS -3.17 import +3.19 import =========== import @@ -3079,7 +3152,7 @@ $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions  File: hledger.info, Node: Importing balance assignments, Up: import -3.17.1 Importing balance assignments +3.19.1 Importing balance assignments ------------------------------------ Entries added by import will have their posting amounts made explicit @@ -3098,7 +3171,7 @@ please test it and send a pull request.)  File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: COMMANDS -3.18 incomestatement +3.20 incomestatement ==================== incomestatement, is @@ -3147,7 +3220,7 @@ options The output formats supported are 'txt', 'csv', 'html', and  File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: COMMANDS -3.19 notes +3.21 notes ========== notes @@ -3167,7 +3240,7 @@ Snacks  File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: COMMANDS -3.20 payees +3.22 payees =========== payees @@ -3189,7 +3262,7 @@ Person A  File: hledger.info, Node: prices, Next: print, Prev: payees, Up: COMMANDS -3.21 prices +3.23 prices =========== prices @@ -3202,7 +3275,7 @@ Price amounts are always displayed with their full precision.  File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS -3.22 print +3.24 print ========== print, txns, p @@ -3311,7 +3384,7 @@ $ hledger print -Ocsv  File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS -3.23 print-unique +3.25 print-unique ================= print-unique @@ -3332,7 +3405,7 @@ $ LEDGER_FILE=unique.journal hledger print-unique  File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS -3.24 register +3.26 register ============= register, reg, r @@ -3422,7 +3495,7 @@ length and comparable to the others in the report.  File: hledger.info, Node: Custom register output, Up: register -3.24.1 Custom register output +3.26.1 Custom register output ----------------------------- register uses the full terminal width by default, except on windows. @@ -3454,7 +3527,7 @@ options The output formats supported are 'txt', 'csv', and  File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS -3.25 register-match +3.27 register-match =================== register-match @@ -3467,7 +3540,7 @@ ledger-autosync detect already-seen transactions when importing.  File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS -3.26 rewrite +3.28 rewrite ============ rewrite @@ -3519,7 +3592,7 @@ commodity.  File: hledger.info, Node: Re-write rules in a file, Up: rewrite -3.26.1 Re-write rules in a file +3.28.1 Re-write rules in a file ------------------------------- During the run this tool will execute so called "Automated Transactions" @@ -3562,7 +3635,7 @@ postings.  File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Up: Re-write rules in a file -3.26.1.1 Diff output format +3.28.1.1 Diff output format ........................... To use this tool for batch modification of your journal files you may @@ -3603,7 +3676,7 @@ output from 'hledger print'.  File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: Re-write rules in a file -3.26.1.2 rewrite vs. print -auto +3.28.1.2 rewrite vs. print -auto ................................ This command predates print -auto, and currently does much the same @@ -3623,7 +3696,7 @@ thing, but with these differences:  File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS -3.27 roi +3.29 roi ======== roi @@ -3651,7 +3724,7 @@ regardless of the length of reporting interval.  File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS -3.28 stats +3.30 stats ========== stats @@ -3682,20 +3755,27 @@ selection.  File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS -3.29 tags +3.31 tags ========= tags -List all the tag names used in the journal. With a TAGREGEX argument, -only tag names matching the regular expression (case insensitive) are -shown. With QUERY arguments, only transactions matching the query are -considered. With -values flag, the tags' unique values are listed -instead. +List the unique tag names used in the journal. With a TAGREGEX +argument, only tag names matching the regular expression (case +insensitive) 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 +parsed from the input data, including duplicates. + + With -E/-empty, any blank/empty values will also be shown, otherwise +they are omitted.  File: hledger.info, Node: test, Next: Add-on commands, Prev: tags, Up: COMMANDS -3.30 test +3.32 test ========= test @@ -3722,7 +3802,7 @@ $ hledger test -- -pData.Amount --color=never  File: hledger.info, Node: Add-on commands, Prev: test, Up: COMMANDS -3.31 Add-on commands +3.33 Add-on commands ==================== hledger also searches for external add-on commands, and will include @@ -3763,7 +3843,7 @@ interfaces. These are maintained and released along with hledger:  File: hledger.info, Node: ui, Next: web, Up: Add-on commands -3.31.1 ui +3.33.1 ui --------- hledger-ui provides an efficient terminal interface. @@ -3771,7 +3851,7 @@ hledger-ui provides an efficient terminal interface.  File: hledger.info, Node: web, Next: iadd, Prev: ui, Up: Add-on commands -3.31.2 web +3.33.2 web ---------- hledger-web provides a simple web interface. @@ -3781,7 +3861,7 @@ hledger-web provides a simple web interface.  File: hledger.info, Node: iadd, Next: interest, Prev: web, Up: Add-on commands -3.31.3 iadd +3.33.3 iadd ----------- hledger-iadd is a more interactive, terminal UI replacement for the add @@ -3790,7 +3870,7 @@ command.  File: hledger.info, Node: interest, Prev: iadd, Up: Add-on commands -3.31.4 interest +3.33.4 interest --------------- hledger-interest generates interest transactions for an account @@ -4027,115 +4107,120 @@ Node: Effect of valuation on reports58740 Ref: #effect-of-valuation-on-reports58928 Node: COMMANDS64449 Ref: #commands64557 -Node: accounts65651 -Ref: #accounts65749 -Node: activity66448 -Ref: #activity66558 -Node: add66941 -Ref: #add67040 -Node: balance69833 -Ref: #balance69944 -Node: Classic balance report71402 -Ref: #classic-balance-report71575 -Node: Customising the classic balance report73009 -Ref: #customising-the-classic-balance-report73237 -Node: Colour support75313 -Ref: #colour-support75480 -Node: Flat mode75653 -Ref: #flat-mode75801 -Node: Depth limited balance reports76214 -Ref: #depth-limited-balance-reports76399 -Node: Percentages76855 -Ref: #percentages77021 -Node: Multicolumn balance report78158 -Ref: #multicolumn-balance-report78338 -Node: Budget report84076 -Ref: #budget-report84219 -Node: Nested budgets89485 -Ref: #nested-budgets89597 -Ref: #output-format-193078 -Node: balancesheet93275 -Ref: #balancesheet93411 -Node: balancesheetequity94877 -Ref: #balancesheetequity95026 -Node: cashflow95749 -Ref: #cashflow95877 -Node: check-dates97056 -Ref: #check-dates97183 -Node: check-dupes97462 -Ref: #check-dupes97586 -Node: close97879 -Ref: #close97987 -Node: close usage99509 -Ref: #close-usage99602 -Node: codes102415 -Ref: #codes102523 -Node: commodities103235 -Ref: #commodities103362 -Node: descriptions103444 -Ref: #descriptions103572 -Node: diff103876 -Ref: #diff103982 -Node: files105029 -Ref: #files105129 -Node: help105276 -Ref: #help105376 -Node: import106457 -Ref: #import106571 -Node: Importing balance assignments107464 -Ref: #importing-balance-assignments107612 -Node: incomestatement108261 -Ref: #incomestatement108394 -Node: notes109881 -Ref: #notes109994 -Node: payees110362 -Ref: #payees110468 -Node: prices110888 -Ref: #prices110994 -Node: print111335 -Ref: #print111445 -Node: print-unique116241 -Ref: #print-unique116367 -Node: register116652 -Ref: #register116779 -Node: Custom register output120951 -Ref: #custom-register-output121080 -Node: register-match122417 -Ref: #register-match122551 -Node: rewrite122902 -Ref: #rewrite123017 -Node: Re-write rules in a file124872 -Ref: #re-write-rules-in-a-file125006 -Node: Diff output format126216 -Ref: #diff-output-format126385 -Node: rewrite vs print --auto127477 -Ref: #rewrite-vs.-print---auto127656 -Node: roi128212 -Ref: #roi128310 -Node: stats129322 -Ref: #stats129421 -Node: tags130209 -Ref: #tags130307 -Node: test130601 -Ref: #test130709 -Node: Add-on commands131456 -Ref: #add-on-commands131573 -Node: ui132916 -Ref: #ui133004 -Node: web133058 -Ref: #web133161 -Node: iadd133277 -Ref: #iadd133388 -Node: interest133470 -Ref: #interest133577 -Node: ENVIRONMENT133817 -Ref: #environment133929 -Node: FILES134758 -Ref: #files-1134861 -Node: LIMITATIONS135074 -Ref: #limitations135193 -Node: TROUBLESHOOTING135935 -Ref: #troubleshooting136048 +Node: accounts65704 +Ref: #accounts65802 +Node: activity66501 +Ref: #activity66611 +Node: add66994 +Ref: #add67095 +Node: aregister69888 +Ref: #aregister70027 +Node: aregister and custom posting dates71333 +Ref: #aregister-and-custom-posting-dates71526 +Ref: #output-format-172147 +Node: balance72552 +Ref: #balance72694 +Node: Classic balance report74152 +Ref: #classic-balance-report74325 +Node: Customising the classic balance report75759 +Ref: #customising-the-classic-balance-report75987 +Node: Colour support78063 +Ref: #colour-support78230 +Node: Flat mode78403 +Ref: #flat-mode78551 +Node: Depth limited balance reports78964 +Ref: #depth-limited-balance-reports79149 +Node: Percentages79605 +Ref: #percentages79771 +Node: Multicolumn balance report80908 +Ref: #multicolumn-balance-report81088 +Node: Budget report86673 +Ref: #budget-report86816 +Node: Nested budgets92082 +Ref: #nested-budgets92194 +Ref: #output-format-295675 +Node: balancesheet95872 +Ref: #balancesheet96008 +Node: balancesheetequity97474 +Ref: #balancesheetequity97623 +Node: cashflow98346 +Ref: #cashflow98474 +Node: check-dates99653 +Ref: #check-dates99782 +Node: check-dupes100061 +Ref: #check-dupes100187 +Node: close100480 +Ref: #close100588 +Node: close usage102110 +Ref: #close-usage102203 +Node: codes105016 +Ref: #codes105124 +Node: commodities105836 +Ref: #commodities105963 +Node: descriptions106045 +Ref: #descriptions106173 +Node: diff106477 +Ref: #diff106583 +Node: files107630 +Ref: #files107730 +Node: help107877 +Ref: #help107977 +Node: import109058 +Ref: #import109172 +Node: Importing balance assignments110065 +Ref: #importing-balance-assignments110213 +Node: incomestatement110862 +Ref: #incomestatement110995 +Node: notes112482 +Ref: #notes112595 +Node: payees112963 +Ref: #payees113069 +Node: prices113489 +Ref: #prices113595 +Node: print113936 +Ref: #print114046 +Node: print-unique118842 +Ref: #print-unique118968 +Node: register119253 +Ref: #register119380 +Node: Custom register output123552 +Ref: #custom-register-output123681 +Node: register-match125018 +Ref: #register-match125152 +Node: rewrite125503 +Ref: #rewrite125618 +Node: Re-write rules in a file127473 +Ref: #re-write-rules-in-a-file127607 +Node: Diff output format128817 +Ref: #diff-output-format128986 +Node: rewrite vs print --auto130078 +Ref: #rewrite-vs.-print---auto130257 +Node: roi130813 +Ref: #roi130911 +Node: stats131923 +Ref: #stats132022 +Node: tags132810 +Ref: #tags132908 +Node: test133427 +Ref: #test133535 +Node: Add-on commands134282 +Ref: #add-on-commands134399 +Node: ui135742 +Ref: #ui135830 +Node: web135884 +Ref: #web135987 +Node: iadd136103 +Ref: #iadd136214 +Node: interest136296 +Ref: #interest136403 +Node: ENVIRONMENT136643 +Ref: #environment136755 +Node: FILES137584 +Ref: #files-1137687 +Node: LIMITATIONS137900 +Ref: #limitations138019 +Node: TROUBLESHOOTING138761 +Ref: #troubleshooting138874  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 7e6415f7d..1701f6c65 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -1739,6 +1739,68 @@ COMMANDS On Microsoft Windows, the add command makes sure that no part of the file path ends with a period, as that would cause problems (#1056). + aregister + aregister, areg + Show transactions affecting a particular account, and the account's + running balance. + + aregister shows the transactions affecting a particular account (and + its subaccounts), from the point of view of that account. Each line + shows: + + o the transaction's (or posting's, see below) date + + o the names of the other account(s) involved + + o the net change to this account's balance + + o the account's historical running balance (including balance from + transactions before the report start date). + + With aregister, each line represents a whole transaction - as in + hledger-ui, hledger-web, and your bank statement. By contrast, the + register command shows individual postings, across all accounts. You + might prefer aregister for reconciling with real-world asset/liability + accounts, and register for reviewing detailed revenues/expenses. + + An account must be specified as the first argument, which should be the + full account name or an account pattern (regular expression). aregis- + ter will show transactions in this account (the first one matched) and + any of its subaccounts. + + Any additional arguments form a query which will filter the transac- + tions shown. + + Transactions making a net change of zero are not shown by default; add + the -E/--empty flag to show them. + + aregister and custom posting dates + Transactions whose date is outside the report period can still be + shown, if they have a posting to this account dated inside the report + period. (And in this case it's the posting date that is shown.) This + ensures that aregister can show an accurate historical running balance, + matching the one shown by register -H with the same arguments. + + To filter strictly by transaction date instead, add the --txn-dates + flag. If you use this flag and some of your postings have custom + dates, it's probably best to assume the running balance is wrong. + + Output format + This command also supports the output destination and output format op- + tions The output formats supported are txt, csv, and json. + + Examples: + + Show all transactions and historical running balance in the first ac- + count whose name contains "checking": + + $ hledger areg checking + + Show transactions and historical running balance in all asset accounts + during july: + + $ hledger areg assets date:jul + balance balance, bal, b Show accounts and their balances. @@ -2034,10 +2096,6 @@ COMMANDS (Average is rounded to the dollar here since all journal amounts are) - A limitation of multicolumn balance reports: eliding of boring parent - accounts in tree mode, as in the classic balance report, is not yet - supported. - The --transpose flag can be used to exchange the rows and columns of a multicolumn report. @@ -3139,23 +3197,30 @@ COMMANDS tags tags - List all the tag names used in the journal. With a TAGREGEX argument, - only tag names matching the regular expression (case insensitive) are - shown. With QUERY arguments, only transactions matching the query are - considered. With --values flag, the tags' unique values are listed in- - stead. + 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 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 + parsed from the input data, including duplicates. + + 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 -- @@ -3164,35 +3229,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 @@ -3211,23 +3276,23 @@ 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 - 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. 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 @@ -3238,13 +3303,13 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. 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 @@ -3260,36 +3325,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: @@ -3304,8 +3369,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 @@ -3325,8 +3390,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 @@ -3336,7 +3401,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) @@ -3350,7 +3415,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)