diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 434aca4ba..b43502d59 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -524,7 +524,7 @@ EUR 1E3 \f[R] .fi .PP -A decimal mark (decimal point) can be written with a period or a comma: +A decimal mark can be written as a period or a comma: .IP .nf \f[C] @@ -1027,6 +1027,16 @@ declare a year for yearless dates T}@T{ following inline/included entries until end of current file T} +T{ +\f[C]=\f[R] +T}@T{ +T}@T{ +T}@T{ +declare an auto posting rule, adding postings to other transactions +T}@T{ +all entries in parent/current/child files (but not sibling files, see +#1212) +T} .TE .PP And some definitions: @@ -1807,31 +1817,28 @@ Goals and actual performance can then be compared in budget reports. For more details, see: balance: Budget report and Budgeting and Forecasting. .PP -.SS Auto postings / transaction modifiers +.SS Auto postings .PP -Transaction modifier rules, AKA auto posting rules, describe changes to -be applied automatically to certain matched transactions. -Currently just one kind of change is possible - adding extra postings, -which we call \[dq]automated postings\[dq] or just \[dq]auto -postings\[dq]. -These rules become active when you use the \f[C]--auto\f[R] flag. +\[dq]Automated postings\[dq] or \[dq]auto postings\[dq] are extra +postings which get added automatically to transactions which match +certain queries, defined by \[dq]auto posting rules\[dq], when you use +the \f[C]--auto\f[R] flag. .PP -A transaction modifier rule looks much like a normal transaction except -the first line is an equals sign followed by a query that matches -certain postings (mnemonic: \f[C]=\f[R] suggests matching). -And each \[dq]posting\[dq] is actually a posting-generating rule: +An auto posting rule looks a bit like a transaction: .IP .nf \f[C] = QUERY ACCOUNT AMOUNT - ACCOUNT [AMOUNT] ... + ACCOUNT [AMOUNT] \f[R] .fi .PP -These posting-generating rules look like normal postings, except the -amount can be: +except the first line is an equals sign (mnemonic: \f[C]=\f[R] suggests +matching), followed by a query (which matches existing postings), and +each \[dq]posting\[dq] line describes a posting to be generated, and the +posting amounts can be: .IP \[bu] 2 a normal amount with a commodity symbol, eg \f[C]$2\f[R]. This will be used as-is. @@ -1849,7 +1856,7 @@ N, and symbol S). The matched posting\[aq]s amount will be multiplied by N, and its commodity symbol will be replaced with S. .PP -A query term containing spaces must be enclosed in single or double +Any query term containing spaces must be enclosed in single or double quotes, as on the command line. Eg, note the quotes around the second query term below: .IP @@ -1860,10 +1867,6 @@ Eg, note the quotes around the second query term below: \f[R] .fi .PP -These rules have global effect - a rule appearing anywhere in your data -can potentially affect any transaction, including transactions recorded -above it or in another file. -.PP Some examples: .IP .nf @@ -1902,6 +1905,12 @@ $ hledger print --auto assets:checking $20 \f[R] .fi +.SS Auto postings and multiple files +.PP +An auto posting rule can affect any transaction in the current file, or +in any parent file or child file. +Note, currently it will not affect sibling files (when multiple +\f[C]-f\f[R]/\f[C]--file\f[R] are used - see #1212). .SS Auto postings and dates .PP A posting date (or secondary date) in the matched posting, or (taking @@ -1909,7 +1918,7 @@ precedence) a posting date in the auto posting rule itself, will also be used in the generated posting. .SS Auto postings and transaction balancing / inferred amounts / balance assertions .PP -Currently, transaction modifiers are applied / auto postings are added: +Currently, auto postings are added: .IP \[bu] 2 after missing amounts are inferred, and transactions are checked for balancedness, @@ -1921,7 +1930,7 @@ after auto postings are added. This changed in hledger 1.12+; see #893 for background. .SS Auto posting tags .PP -Postings added by transaction modifiers will have some extra tags: +Automated postings will have some extra tags: .IP \[bu] 2 \f[C]generated-posting:= QUERY\f[R] - shows this was generated by an auto posting rule, and the query @@ -1931,8 +1940,8 @@ appear in hledger\[aq]s output. This can be used to match postings generated \[dq]just now\[dq], rather than generated in the past and saved to the journal. .PP -Also, any transaction that has been changed by transaction modifier -rules will have these tags added: +Also, any transaction that has been changed by auto posting rules will +have these tags added: .IP \[bu] 2 \f[C]modified:\f[R] - this transaction was modified .IP \[bu] 2 diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 65c23ce30..d59553d65 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -85,7 +85,7 @@ optional fields, separated by spaces: * Balance Assignments:: * Directives:: * Periodic transactions:: -* Auto postings / transaction modifiers:: +* Auto postings::  File: hledger_journal.info, Node: Dates, Next: Status, Up: Transactions @@ -470,8 +470,7 @@ $-1 1E-6 EUR 1E3 - A decimal mark (decimal point) can be written with a period or a -comma: + A decimal mark can be written as a period or a comma: 1.23 1,23456780000009 @@ -912,6 +911,11 @@ account' apply account names inline/included dates inline/included entries until end of current file +'=' declare an auto posting all entries in + rule, adding postings to parent/current/child + other transactions files (but not + sibling files, + see #1212) And some definitions: @@ -1485,7 +1489,7 @@ If account aliases are present, they are applied after the default parent account.  -File: hledger_journal.info, Node: Periodic transactions, Next: Auto postings / transaction modifiers, Prev: Directives, Up: Transactions +File: hledger_journal.info, Node: Periodic transactions, Next: Auto postings, Prev: Directives, Up: Transactions 1.13 Periodic transactions ========================== @@ -1647,29 +1651,26 @@ compared in budget reports. Forecasting.  -File: hledger_journal.info, Node: Auto postings / transaction modifiers, Prev: Periodic transactions, Up: Transactions +File: hledger_journal.info, Node: Auto postings, Prev: Periodic transactions, Up: Transactions -1.14 Auto postings / transaction modifiers -========================================== +1.14 Auto postings +================== -Transaction modifier rules, AKA auto posting rules, describe changes to -be applied automatically to certain matched transactions. Currently -just one kind of change is possible - adding extra postings, which we -call "automated postings" or just "auto postings". These rules become -active when you use the '--auto' flag. +"Automated postings" or "auto postings" are extra postings which get +added automatically to transactions which match certain queries, defined +by "auto posting rules", when you use the '--auto' flag. - A transaction modifier rule looks much like a normal transaction -except the first line is an equals sign followed by a query that matches -certain postings (mnemonic: '=' suggests matching). And each "posting" -is actually a posting-generating rule: + An auto posting rule looks a bit like a transaction: = QUERY ACCOUNT AMOUNT - ACCOUNT [AMOUNT] ... + ACCOUNT [AMOUNT] - These posting-generating rules look like normal postings, except the -amount can be: + except the first line is an equals sign (mnemonic: '=' suggests +matching), followed by a query (which matches existing postings), and +each "posting" line describes a posting to be generated, and the posting +amounts can be: * a normal amount with a commodity symbol, eg '$2'. This will be used as-is. @@ -1682,17 +1683,13 @@ amount can be: and symbol S). The matched posting's amount will be multiplied by N, and its commodity symbol will be replaced with S. - A query term containing spaces must be enclosed in single or double + Any query term containing spaces must be enclosed in single or double quotes, as on the command line. Eg, note the quotes around the second query term below: = expenses:groceries 'expenses:dining out' (budget:funds:dining out) *-1 - These rules have global effect - a rule appearing anywhere in your -data can potentially affect any transaction, including transactions -recorded above it or in another file. - Some examples: ; every time I buy food, schedule a dollar donation @@ -1726,14 +1723,25 @@ $ hledger print --auto * Menu: +* Auto postings and multiple files:: * Auto postings and dates:: * Auto postings and transaction balancing / inferred amounts / balance assertions:: * Auto posting tags::  -File: hledger_journal.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers +File: hledger_journal.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings -1.14.1 Auto postings and dates +1.14.1 Auto postings and multiple files +--------------------------------------- + +An auto posting rule can affect any transaction in the current file, or +in any parent file or child file. Note, currently it will not affect +sibling files (when multiple '-f'/'--file' are used - see #1212). + + +File: hledger_journal.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings + +1.14.2 Auto postings and dates ------------------------------ A posting date (or secondary date) in the matched posting, or (taking @@ -1741,13 +1749,12 @@ precedence) a posting date in the auto posting rule itself, will also be used in the generated posting.  -File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings / transaction modifiers +File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings -1.14.2 Auto postings and transaction balancing / inferred amounts / +1.14.3 Auto postings and transaction balancing / inferred amounts / ------------------------------------------------------------------- -balance assertions Currently, transaction modifiers are applied / auto -postings are added: +balance assertions Currently, auto postings are added: * after missing amounts are inferred, and transactions are checked for balancedness, @@ -1758,12 +1765,12 @@ after auto postings are added. This changed in hledger 1.12+; see #893 for background.  -File: hledger_journal.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers +File: hledger_journal.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings -1.14.3 Auto posting tags +1.14.4 Auto posting tags ------------------------ -Postings added by transaction modifiers will have some extra tags: +Automated postings will have some extra tags: * 'generated-posting:= QUERY' - shows this was generated by an auto posting rule, and the query @@ -1772,8 +1779,8 @@ Postings added by transaction modifiers will have some extra tags: "just now", rather than generated in the past and saved to the journal. - Also, any transaction that has been changed by transaction modifier -rules will have these tags added: + Also, any transaction that has been changed by auto posting rules +will have these tags added: * 'modified:' - this transaction was modified * '_modified:' - a hidden tag not appearing in the comment; this @@ -1784,118 +1791,120 @@ Tag Table: Node: Top76 Node: Transactions1875 Ref: #transactions1967 -Node: Dates3156 -Ref: #dates3255 -Node: Simple dates3320 -Ref: #simple-dates3446 -Node: Secondary dates3955 -Ref: #secondary-dates4109 -Node: Posting dates5445 -Ref: #posting-dates5574 -Node: Status6946 -Ref: #status7067 -Node: Description8775 -Ref: #description8909 -Node: Payee and note9229 -Ref: #payee-and-note9343 -Node: Comments9678 -Ref: #comments9804 -Node: Tags10998 -Ref: #tags11113 -Node: Postings12506 -Ref: #postings12634 -Node: Virtual Postings13660 -Ref: #virtual-postings13777 -Node: Account names15082 -Ref: #account-names15223 -Node: Amounts15710 -Ref: #amounts15849 -Node: Digit group marks16781 -Ref: #digit-group-marks16929 -Node: Amount display style17867 -Ref: #amount-display-style18021 -Node: Transaction prices19182 -Ref: #transaction-prices19348 -Node: Balance Assertions21614 -Ref: #balance-assertions21794 -Node: Assertions and ordering22827 -Ref: #assertions-and-ordering23015 -Node: Assertions and included files23715 -Ref: #assertions-and-included-files23958 -Node: Assertions and multiple -f options24291 -Ref: #assertions-and-multiple--f-options24547 -Node: Assertions and commodities24679 -Ref: #assertions-and-commodities24911 -Node: Assertions and prices26068 -Ref: #assertions-and-prices26282 -Node: Assertions and subaccounts26722 -Ref: #assertions-and-subaccounts26951 -Node: Assertions and virtual postings27275 -Ref: #assertions-and-virtual-postings27517 -Node: Assertions and precision27659 -Ref: #assertions-and-precision27852 -Node: Balance Assignments28119 -Ref: #balance-assignments28293 -Node: Balance assignments and prices29457 -Ref: #balance-assignments-and-prices29629 -Node: Directives29853 -Ref: #directives30012 -Node: Directives and multiple files35331 -Ref: #directives-and-multiple-files35514 -Node: Comment blocks36178 -Ref: #comment-blocks36361 -Node: Including other files36537 -Ref: #including-other-files36717 -Node: Default year37125 -Ref: #default-year37294 -Node: Declaring commodities37701 -Ref: #declaring-commodities37884 -Node: Default commodity39557 -Ref: #default-commodity39733 -Node: Market prices40622 -Ref: #market-prices40787 -Node: Declaring accounts41628 -Ref: #declaring-accounts41804 -Node: Account comments42729 -Ref: #account-comments42892 -Node: Account subdirectives43316 -Ref: #account-subdirectives43511 -Node: Account types43824 -Ref: #account-types44008 -Node: Account display order45647 -Ref: #account-display-order45817 -Node: Rewriting accounts46968 -Ref: #rewriting-accounts47153 -Node: Basic aliases47910 -Ref: #basic-aliases48056 -Node: Regex aliases48760 -Ref: #regex-aliases48932 -Node: Combining aliases49650 -Ref: #combining-aliases49843 -Node: Aliases and multiple files51119 -Ref: #aliases-and-multiple-files51328 -Node: end aliases51907 -Ref: #end-aliases52064 -Node: Default parent account52165 -Ref: #default-parent-account52333 -Node: Periodic transactions53217 -Ref: #periodic-transactions53416 -Node: Periodic rule syntax55288 -Ref: #periodic-rule-syntax55494 -Node: Two spaces between period expression and description!56198 -Ref: #two-spaces-between-period-expression-and-description56517 -Node: Forecasting with periodic transactions57201 -Ref: #forecasting-with-periodic-transactions57506 -Node: Budgeting with periodic transactions59532 -Ref: #budgeting-with-periodic-transactions59771 -Node: Auto postings / transaction modifiers60220 -Ref: #auto-postings-transaction-modifiers60432 -Node: Auto postings and dates62928 -Ref: #auto-postings-and-dates63185 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions63360 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions63735 -Node: Auto posting tags64113 -Ref: #auto-posting-tags64352 +Node: Dates3132 +Ref: #dates3231 +Node: Simple dates3296 +Ref: #simple-dates3422 +Node: Secondary dates3931 +Ref: #secondary-dates4085 +Node: Posting dates5421 +Ref: #posting-dates5550 +Node: Status6922 +Ref: #status7043 +Node: Description8751 +Ref: #description8885 +Node: Payee and note9205 +Ref: #payee-and-note9319 +Node: Comments9654 +Ref: #comments9780 +Node: Tags10974 +Ref: #tags11089 +Node: Postings12482 +Ref: #postings12610 +Node: Virtual Postings13636 +Ref: #virtual-postings13753 +Node: Account names15058 +Ref: #account-names15199 +Node: Amounts15686 +Ref: #amounts15825 +Node: Digit group marks16739 +Ref: #digit-group-marks16887 +Node: Amount display style17825 +Ref: #amount-display-style17979 +Node: Transaction prices19140 +Ref: #transaction-prices19306 +Node: Balance Assertions21572 +Ref: #balance-assertions21752 +Node: Assertions and ordering22785 +Ref: #assertions-and-ordering22973 +Node: Assertions and included files23673 +Ref: #assertions-and-included-files23916 +Node: Assertions and multiple -f options24249 +Ref: #assertions-and-multiple--f-options24505 +Node: Assertions and commodities24637 +Ref: #assertions-and-commodities24869 +Node: Assertions and prices26026 +Ref: #assertions-and-prices26240 +Node: Assertions and subaccounts26680 +Ref: #assertions-and-subaccounts26909 +Node: Assertions and virtual postings27233 +Ref: #assertions-and-virtual-postings27475 +Node: Assertions and precision27617 +Ref: #assertions-and-precision27810 +Node: Balance Assignments28077 +Ref: #balance-assignments28251 +Node: Balance assignments and prices29415 +Ref: #balance-assignments-and-prices29587 +Node: Directives29811 +Ref: #directives29970 +Node: Directives and multiple files35651 +Ref: #directives-and-multiple-files35834 +Node: Comment blocks36498 +Ref: #comment-blocks36681 +Node: Including other files36857 +Ref: #including-other-files37037 +Node: Default year37445 +Ref: #default-year37614 +Node: Declaring commodities38021 +Ref: #declaring-commodities38204 +Node: Default commodity39877 +Ref: #default-commodity40053 +Node: Market prices40942 +Ref: #market-prices41107 +Node: Declaring accounts41948 +Ref: #declaring-accounts42124 +Node: Account comments43049 +Ref: #account-comments43212 +Node: Account subdirectives43636 +Ref: #account-subdirectives43831 +Node: Account types44144 +Ref: #account-types44328 +Node: Account display order45967 +Ref: #account-display-order46137 +Node: Rewriting accounts47288 +Ref: #rewriting-accounts47473 +Node: Basic aliases48230 +Ref: #basic-aliases48376 +Node: Regex aliases49080 +Ref: #regex-aliases49252 +Node: Combining aliases49970 +Ref: #combining-aliases50163 +Node: Aliases and multiple files51439 +Ref: #aliases-and-multiple-files51648 +Node: end aliases52227 +Ref: #end-aliases52384 +Node: Default parent account52485 +Ref: #default-parent-account52653 +Node: Periodic transactions53537 +Ref: #periodic-transactions53712 +Node: Periodic rule syntax55584 +Ref: #periodic-rule-syntax55790 +Node: Two spaces between period expression and description!56494 +Ref: #two-spaces-between-period-expression-and-description56813 +Node: Forecasting with periodic transactions57497 +Ref: #forecasting-with-periodic-transactions57802 +Node: Budgeting with periodic transactions59828 +Ref: #budgeting-with-periodic-transactions60067 +Node: Auto postings60516 +Ref: #auto-postings60656 +Node: Auto postings and multiple files62835 +Ref: #auto-postings-and-multiple-files63039 +Node: Auto postings and dates63248 +Ref: #auto-postings-and-dates63522 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions63697 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions64048 +Node: Auto posting tags64390 +Ref: #auto-posting-tags64605  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index c076424a2..9d44d26b0 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -370,7 +370,7 @@ FILE FORMAT 1E-6 EUR 1E3 - A decimal mark (decimal point) can be written with a period or a comma: + A decimal mark can be written as a period or a comma: 1.23 1,23456780000009 @@ -709,6 +709,11 @@ FILE FORMAT dates line/included en- tries until end of current file + = declare an auto posting all entries in par- + rule, adding postings to ent/current/child + other transactions files (but not sib- + ling files, see + #1212) And some definitions: @@ -718,12 +723,10 @@ FILE FORMAT number how to interpret numbers when parsing journal entries (the iden- nota- tity of the decimal separator character). (Currently each com- tion modity can have its own notation, even in the same file.) + dis- how to display amounts of a commodity in reports (symbol side play and spacing, digit groups, decimal separator, decimal places) style - - - direc- which entries and (when there are multiple files) which files tive are affected by a directive scope @@ -1313,51 +1316,44 @@ FILE FORMAT For more details, see: balance: Budget report and Budgeting and Fore- casting. - Auto postings / transaction modifiers - Transaction modifier rules, AKA auto posting rules, describe changes to - be applied automatically to certain matched transactions. Currently - just one kind of change is possible - adding extra postings, which we - call "automated postings" or just "auto postings". These rules become - active when you use the --auto flag. + Auto postings + "Automated postings" or "auto postings" are extra postings which get + added automatically to transactions which match certain queries, de- + fined by "auto posting rules", when you use the --auto flag. - A transaction modifier rule looks much like a normal transaction except - the first line is an equals sign followed by a query that matches cer- - tain postings (mnemonic: = suggests matching). And each "posting" is - actually a posting-generating rule: + An auto posting rule looks a bit like a transaction: = QUERY ACCOUNT AMOUNT - ACCOUNT [AMOUNT] ... + ACCOUNT [AMOUNT] - These posting-generating rules look like normal postings, except the - amount can be: + except the first line is an equals sign (mnemonic: = suggests match- + ing), followed by a query (which matches existing postings), and each + "posting" line describes a posting to be generated, and the posting + amounts can be: - o a normal amount with a commodity symbol, eg $2. This will be used + o a normal amount with a commodity symbol, eg $2. This will be used as-is. o a number, eg 2. The commodity symbol (if any) from the matched post- ing will be added to this. - o a numeric multiplier, eg *2 (a star followed by a number N). The + o a numeric multiplier, eg *2 (a star followed by a number N). The matched posting's amount (and total price, if any) will be multiplied by N. - o a multiplier with a commodity symbol, eg *$2 (a star, number N, and + o a multiplier with a commodity symbol, eg *$2 (a star, number N, and symbol S). The matched posting's amount will be multiplied by N, and its commodity symbol will be replaced with S. - A query term containing spaces must be enclosed in single or double - quotes, as on the command line. Eg, note the quotes around the second + Any query term containing spaces must be enclosed in single or double + quotes, as on the command line. Eg, note the quotes around the second query term below: = expenses:groceries 'expenses:dining out' (budget:funds:dining out) *-1 - These rules have global effect - a rule appearing anywhere in your data - can potentially affect any transaction, including transactions recorded - above it or in another file. - Some examples: ; every time I buy food, schedule a dollar donation @@ -1389,36 +1385,41 @@ FILE FORMAT assets:checking:gifts -$20 assets:checking $20 + Auto postings and multiple files + An auto posting rule can affect any transaction in the current file, or + in any parent file or child file. Note, currently it will not affect + sibling files (when multiple -f/--file are used - see #1212). + Auto postings and dates - A posting date (or secondary date) in the matched posting, or (taking - precedence) a posting date in the auto posting rule itself, will also + A posting date (or secondary date) in the matched posting, or (taking + precedence) a posting date in the auto posting rule itself, will also be used in the generated posting. Auto postings and transaction balancing / inferred amounts / balance asser- tions - Currently, transaction modifiers are applied / auto postings are added: + Currently, auto postings are added: - o after missing amounts are inferred, and transactions are checked for + o after missing amounts are inferred, and transactions are checked for balancedness, o but before balance assertions are checked. - Note this means that journal entries must be balanced both before and + Note this means that journal entries must be balanced both before and after auto postings are added. This changed in hledger 1.12+; see #893 for background. Auto posting tags - Postings added by transaction modifiers will have some extra tags: + Automated postings will have some extra tags: o generated-posting:= QUERY - shows this was generated by an auto post- ing rule, and the query - o _generated-posting:= QUERY - a hidden tag, which does not appear in + o _generated-posting:= QUERY - a hidden tag, which does not appear in hledger's output. This can be used to match postings generated "just now", rather than generated in the past and saved to the journal. - Also, any transaction that has been changed by transaction modifier - rules will have these tags added: + Also, any transaction that has been changed by auto posting rules will + have these tags added: o modified: - this transaction was modified @@ -1428,7 +1429,7 @@ FILE FORMAT 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) @@ -1442,7 +1443,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)