From 47ca1965b25f38f4325231b26f1a19bf9d66c681 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 10 Dec 2016 07:56:57 -0800 Subject: [PATCH] doc: document balance assignments (#438) --- hledger-lib/doc/hledger_journal.5 | 40 ++++- hledger-lib/doc/hledger_journal.5.info | 210 ++++++++++++++---------- hledger-lib/doc/hledger_journal.5.m4.md | 34 +++- hledger-lib/doc/hledger_journal.5.txt | 174 ++++++++++++-------- 4 files changed, 296 insertions(+), 162 deletions(-) diff --git a/hledger-lib/doc/hledger_journal.5 b/hledger-lib/doc/hledger_journal.5 index 963fbe2dd..87692ff5f 100644 --- a/hledger-lib/doc/hledger_journal.5 +++ b/hledger-lib/doc/hledger_journal.5 @@ -327,7 +327,7 @@ You can usually find an equivalent journal entry using real postings, which is more correct and provides better error checking. .SS Balance Assertions .PP -hledger supports ledger\-style balance assertions in journal files. +hledger supports Ledger\-style balance assertions in journal files. These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s amount. Eg in this example we assert the expected dollar balance in accounts a @@ -423,6 +423,44 @@ Balance assertions are checked against all postings, both real and virtual. They are not affected by the \f[C]\-\-real/\-R\f[] flag or \f[C]real:\f[] query. +.SS Balance Assignments +.PP +Ledger\-style balance assignments are also supported. +These are like balance assertions, but with no posting amount on the +left side of the equals sign; instead it is calculated automatically so +as to satisfy the assertion. +This can be a convenience during data entry, eg when setting opening +balances: +.IP +.nf +\f[C] +;\ starting\ a\ new\ journal,\ set\ asset\ account\ balances\ +2016/1/1\ opening\ balances +\ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ =\ $409.32 +\ \ assets:savings\ \ \ \ \ \ \ \ \ \ \ \ \ =\ $735.24 +\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ =\ $42 +\ \ equity:opening\ balances +\f[] +.fi +.PP +or when adjusting a balance to reality: +.IP +.nf +\f[C] +;\ no\ cash\ left;\ update\ balance,\ record\ any\ untracked\ spending\ as\ a\ generic\ expense +2016/1/15 +\ \ assets:cash\ \ \ \ =\ $0 +\ \ expenses:misc +\f[] +.fi +.PP +The calculated amount depends on the account\[aq]s balance in the +commodity at that point (which depends on the previously\-dated postings +of the commodity to that account since the last balance assertion or +assignment). +Note that using balance assignments makes your journal a little less +explicit; to know the exact amount posted, you have to run hledger or do +the calculations yourself, instead of just reading it. .SS Prices .SS Transaction prices .PP diff --git a/hledger-lib/doc/hledger_journal.5.info b/hledger-lib/doc/hledger_journal.5.info index 363eec497..f78263c0c 100644 --- a/hledger-lib/doc/hledger_journal.5.info +++ b/hledger-lib/doc/hledger_journal.5.info @@ -70,6 +70,7 @@ File: hledger_journal.5.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: * Amounts:: * Virtual Postings:: * Balance Assertions:: +* Balance Assignments:: * Prices:: * Comments:: * Tags:: @@ -331,12 +332,12 @@ can usually find an equivalent journal entry using real postings, which is more correct and provides better error checking.  -File: hledger_journal.5.info, Node: Balance Assertions, Next: Prices, Prev: Virtual Postings, Up: FILE FORMAT +File: hledger_journal.5.info, Node: Balance Assertions, Next: Balance Assignments, Prev: Virtual Postings, Up: FILE FORMAT 1.6 Balance Assertions ====================== -hledger supports ledger-style balance assertions in journal files. These +hledger supports Ledger-style balance assertions in journal files. These look like `=EXPECTEDBALANCE' following a posting's amount. Eg in this example we assert the expected dollar balance in accounts a and b after each posting: @@ -442,9 +443,44 @@ Balance assertions are checked against all postings, both real and virtual. They are not affected by the `--real/-R' flag or `real:' query.  -File: hledger_journal.5.info, Node: Prices, Next: Comments, Prev: Balance Assertions, Up: FILE FORMAT +File: hledger_journal.5.info, Node: Balance Assignments, Next: Prices, Prev: Balance Assertions, Up: FILE FORMAT -1.7 Prices +1.7 Balance Assignments +======================= + +Ledger-style balance assignments are also supported. These are like +balance assertions, but with no posting amount on the left side of the +equals sign; instead it is calculated automatically so as to satisfy the +assertion. This can be a convenience during data entry, eg when setting +opening balances: + + +; starting a new journal, set asset account balances +2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + + +; no cash left; update balance, record any untracked spending as a generic expense +2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the +commodity at that point (which depends on the previously-dated postings +of the commodity to that account since the last balance assertion or +assignment). Note that using balance assignments makes your journal a +little less explicit; to know the exact amount posted, you have to run +hledger or do the calculations yourself, instead of just reading it. + + +File: hledger_journal.5.info, Node: Prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT + +1.8 Prices ========== * Menu: @@ -455,7 +491,7 @@ File: hledger_journal.5.info, Node: Prices, Next: Comments, Prev: Balance Ass  File: hledger_journal.5.info, Node: Transaction prices, Next: Market prices, Up: Prices -1.7.1 Transaction prices +1.8.1 Transaction prices ------------------------ When recording a transaction, you can also record an amount's price in @@ -509,7 +545,7 @@ conversion rate of purchases made in a foreign currency.  File: hledger_journal.5.info, Node: Market prices, Prev: Transaction prices, Up: Prices -1.7.2 Market prices +1.8.2 Market prices ------------------- Market prices are not tied to a particular transaction; they represent @@ -540,7 +576,7 @@ P 2010/1/1 € $1.40  File: hledger_journal.5.info, Node: Comments, Next: Tags, Prev: Prices, Up: FILE FORMAT -1.8 Comments +1.9 Comments ============ Lines in the journal beginning with a semicolon (`;') or hash (`#') or @@ -581,8 +617,8 @@ end comment  File: hledger_journal.5.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT -1.9 Tags -======== +1.10 Tags +========= A _tag_ is a word followed by a full colon inside a transaction or posting comment. You can write multiple tags, comma separated. Eg: `; a @@ -609,7 +645,7 @@ are simple strings.  File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT -1.10 Directives +1.11 Directives =============== * Menu: @@ -626,7 +662,7 @@ File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT  File: hledger_journal.5.info, Node: Account aliases, Next: account directive, Up: Directives -1.10.1 Account aliases +1.11.1 Account aliases ---------------------- You can define aliases which rewrite your account names (after reading @@ -655,7 +691,7 @@ be useful for:  File: hledger_journal.5.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases -1.10.1.1 Basic aliases +1.11.1.1 Basic aliases ...................... To set an account alias, use the `alias' directive in your journal @@ -680,7 +716,7 @@ alias checking = assets:bank:wells fargo:checking  File: hledger_journal.5.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Account aliases -1.10.1.2 Regex aliases +1.11.1.2 Regex aliases ...................... There is also a more powerful variant that uses a regular expression, @@ -706,7 +742,7 @@ alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3  File: hledger_journal.5.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases -1.10.1.3 Multiple aliases +1.11.1.3 Multiple aliases ......................... You can define as many aliases as you like using directives or @@ -723,7 +759,7 @@ order:  File: hledger_journal.5.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases -1.10.1.4 end aliases +1.11.1.4 end aliases .................... You can clear (forget) all currently defined aliases with the `end @@ -735,7 +771,7 @@ end aliases  File: hledger_journal.5.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives -1.10.2 account directive +1.11.2 account directive ------------------------ The `account' directive predefines account names, as in Ledger and @@ -757,7 +793,7 @@ account expenses:food  File: hledger_journal.5.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives -1.10.3 apply account directive +1.11.3 apply account directive ------------------------------ You can specify a parent account which will be prepended to all accounts @@ -796,7 +832,7 @@ supported.  File: hledger_journal.5.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives -1.10.4 Multi-line comments +1.11.4 Multi-line comments -------------------------- A line containing just `comment' starts a multi-line comment, and a @@ -805,7 +841,7 @@ line containing just `end comment' ends it. See comments.  File: hledger_journal.5.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives -1.10.5 commodity directive +1.11.5 commodity directive -------------------------- The `commodity' directive predefines commodities (currently this is @@ -840,7 +876,7 @@ commodity INR  File: hledger_journal.5.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives -1.10.6 Default commodity +1.11.6 Default commodity ------------------------ The D directive sets a default commodity (and display format), to be @@ -861,7 +897,7 @@ D $1,000.00  File: hledger_journal.5.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives -1.10.7 Default year +1.11.7 Default year ------------------- You can set a default year to be used for subsequent dates which don't @@ -888,7 +924,7 @@ Y2010 ; change default year to 2010  File: hledger_journal.5.info, Node: Including other files, Prev: Default year, Up: Directives -1.10.8 Including other files +1.11.8 Including other files ---------------------------- You can pull in the content of additional journal files by writing an @@ -929,69 +965,71 @@ Tag Table: Node: Top94 Node: FILE FORMAT2284 Ref: #file-format2410 -Node: Transactions2569 -Ref: #transactions2689 -Node: Dates3632 -Ref: #dates3760 -Node: Simple dates3825 -Ref: #simple-dates3953 -Node: Secondary dates4317 -Ref: #secondary-dates4473 -Node: Posting dates6033 -Ref: #posting-dates6164 -Node: Account names7535 -Ref: #account-names7674 -Node: Amounts8159 -Ref: #amounts8297 -Node: Virtual Postings10396 -Ref: #virtual-postings10557 -Node: Balance Assertions11777 -Ref: #balance-assertions11941 -Node: Assertions and ordering12763 -Ref: #assertions-and-ordering12948 -Node: Assertions and commodities13979 -Ref: #assertions-and-commodities14205 -Node: Assertions and subaccounts14897 -Ref: #assertions-and-subaccounts15131 -Node: Assertions and virtual postings15653 -Ref: #assertions-and-virtual-postings15862 -Node: Prices16003 -Ref: #prices16135 -Node: Transaction prices16186 -Ref: #transaction-prices16331 -Node: Market prices17938 -Ref: #market-prices18073 -Node: Comments18961 -Ref: #comments19083 -Node: Tags20195 -Ref: #tags20313 -Node: Directives21236 -Ref: #directives21351 -Node: Account aliases21544 -Ref: #account-aliases21690 -Node: Basic aliases22292 -Ref: #basic-aliases22437 -Node: Regex aliases23125 -Ref: #regex-aliases23295 -Node: Multiple aliases24065 -Ref: #multiple-aliases24239 -Node: end aliases24735 -Ref: #end-aliases24877 -Node: account directive24979 -Ref: #account-directive25161 -Node: apply account directive25457 -Ref: #apply-account-directive25655 -Node: Multi-line comments26315 -Ref: #multi-line-comments26507 -Node: commodity directive26634 -Ref: #commodity-directive26820 -Node: Default commodity27693 -Ref: #default-commodity27868 -Node: Default year28404 -Ref: #default-year28571 -Node: Including other files28994 -Ref: #including-other-files29153 -Node: EDITOR SUPPORT29549 -Ref: #editor-support29669 +Node: Transactions2593 +Ref: #transactions2713 +Node: Dates3656 +Ref: #dates3784 +Node: Simple dates3849 +Ref: #simple-dates3977 +Node: Secondary dates4341 +Ref: #secondary-dates4497 +Node: Posting dates6057 +Ref: #posting-dates6188 +Node: Account names7559 +Ref: #account-names7698 +Node: Amounts8183 +Ref: #amounts8321 +Node: Virtual Postings10420 +Ref: #virtual-postings10581 +Node: Balance Assertions11801 +Ref: #balance-assertions11978 +Node: Assertions and ordering12800 +Ref: #assertions-and-ordering12985 +Node: Assertions and commodities14016 +Ref: #assertions-and-commodities14242 +Node: Assertions and subaccounts14934 +Ref: #assertions-and-subaccounts15168 +Node: Assertions and virtual postings15690 +Ref: #assertions-and-virtual-postings15899 +Node: Balance Assignments16040 +Ref: #balance-assignments16209 +Node: Prices17327 +Ref: #prices17460 +Node: Transaction prices17511 +Ref: #transaction-prices17656 +Node: Market prices19263 +Ref: #market-prices19398 +Node: Comments20286 +Ref: #comments20408 +Node: Tags21520 +Ref: #tags21640 +Node: Directives22563 +Ref: #directives22678 +Node: Account aliases22871 +Ref: #account-aliases23017 +Node: Basic aliases23619 +Ref: #basic-aliases23764 +Node: Regex aliases24452 +Ref: #regex-aliases24622 +Node: Multiple aliases25392 +Ref: #multiple-aliases25566 +Node: end aliases26062 +Ref: #end-aliases26204 +Node: account directive26306 +Ref: #account-directive26488 +Node: apply account directive26784 +Ref: #apply-account-directive26982 +Node: Multi-line comments27642 +Ref: #multi-line-comments27834 +Node: commodity directive27961 +Ref: #commodity-directive28147 +Node: Default commodity29020 +Ref: #default-commodity29195 +Node: Default year29731 +Ref: #default-year29898 +Node: Including other files30321 +Ref: #including-other-files30480 +Node: EDITOR SUPPORT30876 +Ref: #editor-support30996  End Tag Table diff --git a/hledger-lib/doc/hledger_journal.5.m4.md b/hledger-lib/doc/hledger_journal.5.m4.md index bb79805c0..54e20db6a 100644 --- a/hledger-lib/doc/hledger_journal.5.m4.md +++ b/hledger-lib/doc/hledger_journal.5.m4.md @@ -251,8 +251,8 @@ Virtual postings have some legitimate uses, but those are few. You can usually f ## Balance Assertions -hledger supports ledger-style -[balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions) +hledger supports +[Ledger-style balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions) in journal files. These look like `=EXPECTEDBALANCE` following a posting's amount. Eg in this example we assert the expected dollar balance in accounts a and b after @@ -339,6 +339,36 @@ Balance assertions are checked against all postings, both real and flag or `real:` query. +## Balance Assignments + +[Ledger-style balance assignments](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assignments) are also supported. +These are like [balance assertions](#balance-assertions), but with no posting amount on the left side of the equals sign; +instead it is calculated automatically so as to satisfy the assertion. +This can be a convenience during data entry, eg when setting opening balances: +```journal +; starting a new journal, set asset account balances +2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances +``` +or when adjusting a balance to reality: +```journal +; no cash left; update balance, record any untracked spending as a generic expense +2016/1/15 + assets:cash = $0 + expenses:misc +``` + +The calculated amount depends on the account's balance in the commodity at that point +(which depends on the previously-dated postings of the commodity to that account +since the last balance assertion or assignment). +Note that using balance assignments makes your journal a little less explicit; +to know the exact amount posted, you have to run hledger or do the calculations yourself, +instead of just reading it. + + ## Prices ### Transaction prices diff --git a/hledger-lib/doc/hledger_journal.5.txt b/hledger-lib/doc/hledger_journal.5.txt index a2fe5df0a..312d93e5e 100644 --- a/hledger-lib/doc/hledger_journal.5.txt +++ b/hledger-lib/doc/hledger_journal.5.txt @@ -253,7 +253,7 @@ FILE FORMAT more correct and provides better error checking. Balance Assertions - hledger supports ledger-style balance assertions in journal files. + hledger supports Ledger-style balance assertions in journal files. These look like =EXPECTEDBALANCE following a posting's amount. Eg in this example we assert the expected dollar balance in accounts a and b after each posting: @@ -329,21 +329,49 @@ FILE FORMAT Balance assertions are checked against all postings, both real and vir- tual. They are not affected by the --real/-R flag or real: query. + Balance Assignments + Ledger-style balance assignments are also supported. These are like + balance assertions, but with no posting amount on the left side of the + equals sign; instead it is calculated automatically so as to satisfy + the assertion. This can be a convenience during data entry, eg when + setting opening balances: + + ; starting a new journal, set asset account balances + 2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + + ; no cash left; update balance, record any untracked spending as a generic expense + 2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the commodity + at that point (which depends on the previously-dated postings of the + commodity to that account since the last balance assertion or assign- + ment). Note that using balance assignments makes your journal a little + less explicit; to know the exact amount posted, you have to run hledger + or do the calculations yourself, instead of just reading it. + Prices Transaction prices - When recording a transaction, you can also record an amount's price in - another commodity. This documents the exchange rate, cost (of a pur- - chase), or selling price (of a sale) that was in effect within this - particular transaction (or more precisely, within the particular post- + When recording a transaction, you can also record an amount's price in + another commodity. This documents the exchange rate, cost (of a pur- + chase), or selling price (of a sale) that was in effect within this + particular transaction (or more precisely, within the particular post- ing). These transaction prices are fixed, and do not change. - Such priced amounts can be displayed in their transaction price's com- - modity, by using the --cost/-B flag (B for "cost Basis"), supported by + Such priced amounts can be displayed in their transaction price's com- + modity, by using the --cost/-B flag (B for "cost Basis"), supported by most hledger commands. There are three ways to specify a transaction price: - 1. Write the unit price (aka exchange rate), as @ UNITPRICE after the + 1. Write the unit price (aka exchange rate), as @ UNITPRICE after the amount: 2009/1/1 @@ -357,7 +385,7 @@ FILE FORMAT assets:cash 3. Or let hledger infer the price so as to balance the transaction. To - permit this, you must fully specify all posting amounts, and their + permit this, you must fully specify all posting amounts, and their sum must have a non-zero amount in exactly two commodities: 2009/1/1 @@ -371,17 +399,17 @@ FILE FORMAT assets:foreign currency $135.00 assets:cash $-135.00 - Example use for transaction prices: recording the effective conversion + Example use for transaction prices: recording the effective conversion rate of purchases made in a foreign currency. Market prices - Market prices are not tied to a particular transaction; they represent - historical exchange rates between two commodities, usually from some + Market prices are not tied to a particular transaction; they represent + historical exchange rates between two commodities, usually from some public market which publishes such rates. - When market prices are known, the -V/--value option will use them to - convert reported amounts to their market value as of the report end - date. This option is currently available only with the balance com- + When market prices are known, the -V/--value option will use them to + convert reported amounts to their market value as of the report end + date. This option is currently available only with the balance com- mand. You record market prices (Ledger calls them historical prices) with a P @@ -391,7 +419,7 @@ FILE FORMAT P DATE COMMODITYSYMBOL UNITPRICE For example, the following directives say that the euro's exchange rate - was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and + was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and unknown before 2009). P 2009/1/1 $1.35 @@ -400,17 +428,17 @@ FILE FORMAT Example use for market prices: tracking the value of stocks. Comments - Lines in the journal beginning with a semicolon (;) or hash (#) or - asterisk (*) are comments, and will be ignored. (Asterisk comments - make it easy to treat your journal like an org-mode outline in emacs.) + Lines in the journal beginning with a semicolon (;) or hash (#) or + asterisk (*) are comments, and will be ignored. (Asterisk comments + make it easy to treat your journal like an org-mode outline in emacs.) - Also, anything between comment and end comment directives is a - (multi-line) comment. If there is no end comment, the comment extends + Also, anything between comment and end comment directives is a + (multi-line) comment. If there is no end comment, the comment extends to the end of the file. - You can attach comments to a transaction by writing them after the - description and/or indented on the following lines (before the post- - ings). Similarly, you can attach comments to an individual posting by + You can attach comments to a transaction by writing them after the + description and/or indented on the following lines (before the post- + ings). Similarly, you can attach comments to an individual posting by writing them after the amount and/or indented on the following lines. Some examples: @@ -435,30 +463,30 @@ FILE FORMAT ; a journal comment (because not indented) Tags - A tag is a word followed by a full colon inside a transaction or post- - ing comment. You can write multiple tags, comma separated. Eg: - ; a comment containing sometag:, anothertag:. You can search for tags + A tag is a word followed by a full colon inside a transaction or post- + ing comment. You can write multiple tags, comma separated. Eg: + ; a comment containing sometag:, anothertag:. You can search for tags with the tag: query. - A tag can also have a value, which is any text between the colon and - the next comma or newline, excluding leading/trailing whitespace. (So + A tag can also have a value, which is any text between the colon and + the next comma or newline, excluding leading/trailing whitespace. (So hledger tag values can not contain commas or newlines). - Tags in a transaction comment affect the transaction and all of its - postings, while tags in a posting comment affect only that posting. - For example, the following transaction has three tags (A, TAG2, + Tags in a transaction comment affect the transaction and all of its + postings, while tags in a posting comment affect only that posting. + For example, the following transaction has three tags (A, TAG2, third-tag) and the posting has four (A, TAG2, third-tag, posting-tag): 1/1 a transaction ; A:, TAG2: ; third-tag: a third transaction tag, this time with a value (a) $1 ; posting-tag: - Tags are like Ledger's metadata feature, except hledger's tag values + Tags are like Ledger's metadata feature, except hledger's tag values are simple strings. Directives Account aliases - You can define aliases which rewrite your account names (after reading + You can define aliases which rewrite your account names (after reading the journal, before generating reports). hledger's account aliases can be useful for: @@ -475,8 +503,8 @@ FILE FORMAT See also How to use account aliases. Basic aliases - To set an account alias, use the alias directive in your journal file. - This affects all subsequent journal entries in the current file or its + To set an account alias, use the alias directive in your journal file. + This affects all subsequent journal entries in the current file or its included files. The spaces around the = are optional: alias OLD = NEW @@ -484,53 +512,53 @@ FILE FORMAT Or, you can use the --alias 'OLD=NEW' option on the command line. This affects all entries. It's useful for trying out aliases interactively. - OLD and NEW are full account names. hledger will replace any occur- - rence of the old account name with the new one. Subaccounts are also + OLD and NEW are full account names. hledger will replace any occur- + rence of the old account name with the new one. Subaccounts are also affected. Eg: alias checking = assets:bank:wells fargo:checking # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" Regex aliases - There is also a more powerful variant that uses a regular expression, - indicated by the forward slashes. (This was the default behaviour in + There is also a more powerful variant that uses a regular expression, + indicated by the forward slashes. (This was the default behaviour in hledger 0.24-0.25): alias /REGEX/ = REPLACEMENT or --alias '/REGEX/=REPLACEMENT'. - REGEX is a case-insensitive regular expression. Anywhere it matches - inside an account name, the matched part will be replaced by REPLACE- - MENT. If REGEX contains parenthesised match groups, these can be ref- + REGEX is a case-insensitive regular expression. Anywhere it matches + inside an account name, the matched part will be replaced by REPLACE- + MENT. If REGEX contains parenthesised match groups, these can be ref- erenced by the usual numeric backreferences in REPLACEMENT. Note, cur- - rently regular expression aliases may cause noticeable slow-downs. + rently regular expression aliases may cause noticeable slow-downs. (And if you use Ledger on your hledger file, they will be ignored.) Eg: alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" Multiple aliases - You can define as many aliases as you like using directives or com- - mand-line options. Aliases are recursive - each alias sees the result - of applying previous ones. (This is different from Ledger, where + You can define as many aliases as you like using directives or com- + mand-line options. Aliases are recursive - each alias sees the result + of applying previous ones. (This is different from Ledger, where aliases are non-recursive by default). Aliases are applied in the fol- lowing order: - 1. alias directives, most recently seen first (recent directives take + 1. alias directives, most recently seen first (recent directives take precedence over earlier ones; directives not yet seen are ignored) 2. alias options, in the order they appear on the command line end aliases - You can clear (forget) all currently defined aliases with the + You can clear (forget) all currently defined aliases with the end aliases directive: end aliases account directive - The account directive predefines account names, as in Ledger and Bean- - count. This may be useful for your own documentation; hledger doesn't + The account directive predefines account names, as in Ledger and Bean- + count. This may be useful for your own documentation; hledger doesn't make use of it yet. ; account ACCT @@ -545,8 +573,8 @@ FILE FORMAT ; etc. apply account directive - You can specify a parent account which will be prepended to all - accounts within a section of the journal. Use the apply account and + You can specify a parent account which will be prepended to all + accounts within a section of the journal. Use the apply account and end apply account directives like so: apply account home @@ -563,7 +591,7 @@ FILE FORMAT home:food $10 home:cash $-10 - If end apply account is omitted, the effect lasts to the end of the + If end apply account is omitted, the effect lasts to the end of the file. Included files are also affected, eg: apply account business @@ -572,16 +600,16 @@ FILE FORMAT apply account personal include personal.journal - Prior to hledger 1.0, legacy account and end spellings were also sup- + Prior to hledger 1.0, legacy account and end spellings were also sup- ported. Multi-line comments - A line containing just comment starts a multi-line comment, and a line + A line containing just comment starts a multi-line comment, and a line containing just end comment ends it. See comments. commodity directive - The commodity directive predefines commodities (currently this is just - informational), and also it may define the display format for amounts + The commodity directive predefines commodities (currently this is just + informational), and also it may define the display format for amounts in this commodity (overriding the automatically inferred format). It may be written on a single line, like this: @@ -593,8 +621,8 @@ FILE FORMAT ; separating thousands with comma. commodity 1,000.0000 AAAA - or on multiple lines, using the "format" subdirective. In this case - the commodity symbol appears twice and should be the same in both + or on multiple lines, using the "format" subdirective. In this case + the commodity symbol appears twice and should be the same in both places: ; commodity SYMBOL @@ -607,10 +635,10 @@ FILE FORMAT format INR 9,99,99,999.00 Default commodity - The D directive sets a default commodity (and display format), to be + The D directive sets a default commodity (and display format), to be used for amounts without a commodity symbol (ie, plain numbers). (Note - this differs from Ledger's default commodity directive.) The commodity - and display format will be applied to all subsequent commodity-less + this differs from Ledger's default commodity directive.) The commodity + and display format will be applied to all subsequent commodity-less amounts, or until the next D directive. # commodity-less amounts should be treated as dollars @@ -622,8 +650,8 @@ FILE FORMAT b Default year - You can set a default year to be used for subsequent dates which don't - specify a year. This is a line beginning with Y followed by the year. + You can set a default year to be used for subsequent dates which don't + specify a year. This is a line beginning with Y followed by the year. Eg: Y2009 ; set default year to 2009 @@ -643,24 +671,24 @@ FILE FORMAT assets Including other files - You can pull in the content of additional journal files by writing an + You can pull in the content of additional journal files by writing an include directive, like this: include path/to/file.journal - If the path does not begin with a slash, it is relative to the current + If the path does not begin with a slash, it is relative to the current file. Glob patterns (*) are not currently supported. - The include directive can only be used in journal files. It can + The include directive can only be used in journal files. It can include journal, timeclock or timedot files, but not CSV files. EDITOR SUPPORT Add-on modes exist for various text editors, to make working with jour- - nal files easier. They add colour, navigation aids and helpful com- - mands. For hledger users who edit the journal file directly (the + nal files easier. They add colour, navigation aids and helpful com- + mands. For hledger users who edit the journal file directly (the majority), using one of these modes is quite recommended. - These were written with Ledger in mind, but also work with hledger + These were written with Ledger in mind, but also work with hledger files: @@ -677,7 +705,7 @@ EDITOR SUPPORT 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) @@ -691,7 +719,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)