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

;doc:journal: document alias application order more clearly (#1055)

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-06-21 12:12:35 -07:00
parent 8c7b23e25f
commit d15f775695
1 changed files with 24 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1085,15 +1085,32 @@ alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
Also note that REPLACEMENT continues to the end of line (or on command line,
to end of option argument), so it can contain trailing whitespace.
#### Multiple aliases
#### Combining aliases
You can define as many aliases as you like using directives or command-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 following order:
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)
2. `--alias` options, in the order they appear on the command line (left to right).
Recursive aliases are allowed; each alias sees the result of applying previous ones.
(This is different from Ledger.)
Note how alias directives are applied: "most recently parsed first.. bottom to top".
This means that for 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 next alias above that will be be applied next, and so on.
This gives nearby aliases precedence over distant ones, and helps
provide semantic stability - so that aliases will keep working the
same way 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.)
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`