slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: journal: clarify alias docs (#1055)

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-06-23 15:56:29 -07:00
parent 016808fd06
commit 2e4f047fed
1 changed files with 13 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
hledger-lib/hledger_journal.m4.md
View File

@ -1088,29 +1088,27 @@ to end of option argument), so it can contain trailing whitespace.
#### Combining aliases #### Combining aliases
You can define as many aliases as you like, using journal directives and/or command line options. You can define as many aliases as you like, using journal directives and/or command line options.
As each journal entry is parsed, the aliases currently in effect are applied in the following order:
1. `alias` directives, most recently parsed first (reading upward from the journal entry, bottom to top) Recursive aliases - where an account name is rewritten by one alias, then by another alias, and so on - are allowed.
2. `--alias` options, in the order they appear on the command line (left to right). Each alias sees the effect of previously applied aliases.
Recursive aliases are allowed; each alias sees the result of applying previous ones. In such cases it can be important to understand which aliases will be applied and in which order.
(This is different from Ledger.) For (each account name in) each journal entry, we apply:
Note how alias directives are applied: "most recently parsed first.. bottom to top". 1. `alias` directives preceding the journal entry, most recently parsed first (ie, reading upward from the journal entry, bottom to top)
This means that for a given journal entry: 2. `--alias` options, in the order they appeared on the command line (left to right).
In other words, for (an account name in) a given journal entry:
- aliases defined after/below the entry do not affect it
- the nearest alias declaration before/above the entry is applied first - the nearest alias declaration before/above the entry is applied first
- the next alias above that will be be applied next, and so on. - the next alias before/above that will be be applied next, and so on
- aliases defined after/below the entry do not affect it.
This gives nearby aliases precedence over distant ones, and helps This gives nearby aliases precedence over distant ones, and helps
provide semantic stability - so that aliases will keep working the provide semantic stability - aliases will keep working the same way
same way independent of which files are being read and in which order. independent of which files are being read and in which order.
(If you forget this, recursive aliases will not work as you expect.
Tip: you can always add `--debug=6` to see which aliases are applied
in which order.)
In case of trouble, adding `--debug=6` to the command line will show which aliases are being applied when.
#### `end aliases` #### `end aliases`