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

;journal: document directives/alias multi-file limitation clearly

Browse Source
This commit is contained in:
Simon Michael 2020-03-16 09:00:38 -07:00
parent 888e278afc
commit 2aab02f4e8
4 changed files with 341 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
hledger-lib/hledger_journal.5
View File

@ -1066,13 +1066,21 @@ As you can see, directives vary in which journal entries and files they
affect, and whether they are focussed on input (parsing) or output affect, and whether they are focussed on input (parsing) or output
(reports). (reports).
Some directives have multiple effects. Some directives have multiple effects.
.SS Directives and multiple files
.PP .PP
If you have a journal made up of multiple files, or pass multiple -f If you use multiple \f[C]-f\f[R]/\f[C]--file\f[R] options, or the
options on the command line, note that directives which affect input \f[C]include\f[R] directive, hledger will process multiple input files.
typically last only until the end of their defining file. But note that directives which affect input (see above) typically last
This provides more simplicity and predictability, eg reports are not only until the end of the file in which they occur.
changed by writing file options in a different order. .PP
It can be surprising at times though. This may seem inconvenient, but it\[aq]s intentional; it makes reports
stable and deterministic, independent of the order of input.
Otherwise you could see different numbers if you happened to write -f
options in a different order, or if you moved includes around while
cleaning up your files.
.PP
It can be surprising though; for example, it means that \f[C]alias\f[R]
directives do not affect parent or sibling files (see below).
.SS Comment blocks .SS Comment blocks
.PP .PP
A line containing just \f[C]comment\f[R] starts a commented region of A line containing just \f[C]comment\f[R] starts a commented region of
@ -1543,6 +1551,46 @@ independent of which files are being read and in which order.
.PP .PP
In case of trouble, adding \f[C]--debug=6\f[R] to the command line will In case of trouble, adding \f[C]--debug=6\f[R] to the command line will
show which aliases are being applied when. show which aliases are being applied when.
.SS Aliases and multiple files
.PP
As explained at Directives and multiple files, \f[C]alias\f[R]
directives do not affect parent or sibling files.
Eg in this command,
.IP
.nf
\f[C]
hledger -f a.aliases -f b.journal
\f[R]
.fi
.PP
account aliases defined in a.aliases will not affect b.journal.
Including the aliases doesn\[aq]t work either:
.IP
.nf
\f[C]
include a.aliases
2020-01-01 ; not affected by a.aliases
foo 1
bar
\f[R]
.fi
.PP
This means that account aliases should usually be declared at the start
of your top-most file, like this:
.IP
.nf
\f[C]
alias foo=Foo
alias bar=Bar
2020-01-01 ; affected by aliases above
foo 1
bar
include c.journal ; also affected
\f[R]
.fi
.SS \f[C]end aliases\f[R] .SS \f[C]end aliases\f[R]
.PP .PP
You can clear (forget) all currently defined aliases with the You can clear (forget) all currently defined aliases with the

211
hledger-lib/hledger_journal.info
View File

@ -929,15 +929,9 @@ scope are affected by a directive
they affect, and whether they are focussed on input (parsing) or output they affect, and whether they are focussed on input (parsing) or output
(reports). Some directives have multiple effects. (reports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This provides
more simplicity and predictability, eg reports are not changed by
writing file options in a different order. It can be surprising at
times though.
* Menu: * Menu:
* Directives and multiple files::
* Comment blocks:: * Comment blocks::
* Including other files:: * Including other files::
* Default year:: * Default year::
@ -949,9 +943,29 @@ times though.
* Default parent account:: * Default parent account::
 
File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Up: Directives File: hledger_journal.info, Node: Directives and multiple files, Next: Comment blocks, Up: Directives
1.12.1 Comment blocks 1.12.1 Directives and multiple files
------------------------------------
If you use multiple '-f'/'--file' options, or the 'include' directive,
hledger will process multiple input files. But note that directives
which affect input (see above) typically last only until the end of the
file in which they occur.
This may seem inconvenient, but it's intentional; it makes reports
stable and deterministic, independent of the order of input. Otherwise
you could see different numbers if you happened to write -f options in a
different order, or if you moved includes around while cleaning up your
files.
It can be surprising though; for example, it means that 'alias'
directives do not affect parent or sibling files (see below).

File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Prev: Directives and multiple files, Up: Directives
1.12.2 Comment blocks
--------------------- ---------------------
A line containing just 'comment' starts a commented region of the file, A line containing just 'comment' starts a commented region of the file,
@ -961,7 +975,7 @@ file) ends it. See also comments.
 
File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives
1.12.2 Including other files 1.12.3 Including other files
---------------------------- ----------------------------
You can pull in the content of additional files by writing an include You can pull in the content of additional files by writing an include
@ -979,7 +993,7 @@ include journal, timeclock or timedot files, but not CSV files.
 
File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives
1.12.3 Default year 1.12.4 Default year
------------------- -------------------
You can set a default year to be used for subsequent dates which don't You can set a default year to be used for subsequent dates which don't
@ -1005,7 +1019,7 @@ Y2010 ; change default year to 2010
 
File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives
1.12.4 Declaring commodities 1.12.5 Declaring commodities
---------------------------- ----------------------------
The 'commodity' directive has several functions: The 'commodity' directive has several functions:
@ -1055,7 +1069,7 @@ a comma, followed by 0 or more decimal digits.
 
File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives
1.12.5 Default commodity 1.12.6 Default commodity
------------------------ ------------------------
The 'D' directive sets a default commodity, to be used for amounts The 'D' directive sets a default commodity, to be used for amounts
@ -1082,7 +1096,7 @@ D $1,000.00
 
File: hledger_journal.info, Node: Market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives File: hledger_journal.info, Node: Market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives
1.12.6 Market prices 1.12.7 Market prices
-------------------- --------------------
The 'P' directive declares a market price, which is an exchange rate The 'P' directive declares a market price, which is an exchange rate
@ -1112,7 +1126,7 @@ another commodity using these prices.
 
File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Market prices, Up: Directives File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Market prices, Up: Directives
1.12.7 Declaring accounts 1.12.8 Declaring accounts
------------------------- -------------------------
'account' directives can be used to pre-declare accounts. Though not 'account' directives can be used to pre-declare accounts. Though not
@ -1145,7 +1159,7 @@ account assets:bank:checking
 
File: hledger_journal.info, Node: Account comments, Next: Account subdirectives, Up: Declaring accounts File: hledger_journal.info, Node: Account comments, Next: Account subdirectives, Up: Declaring accounts
1.12.7.1 Account comments 1.12.8.1 Account comments
......................... .........................
Comments, beginning with a semicolon, can be added: Comments, beginning with a semicolon, can be added:
@ -1165,7 +1179,7 @@ account assets:bank:checking ; same-line comment, note 2+ spaces before ;
 
File: hledger_journal.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts File: hledger_journal.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts
1.12.7.2 Account subdirectives 1.12.8.2 Account subdirectives
.............................. ..............................
We also allow (and ignore) Ledger-style indented subdirectives, just for We also allow (and ignore) Ledger-style indented subdirectives, just for
@ -1183,7 +1197,7 @@ account ACCTNAME [ACCTTYPE] [;COMMENT]
 
File: hledger_journal.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts File: hledger_journal.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts
1.12.7.3 Account types 1.12.8.3 Account types
...................... ......................
hledger recognises five types (or classes) of account: Asset, Liability, hledger recognises five types (or classes) of account: Asset, Liability,
@ -1228,7 +1242,7 @@ account - ; type:L
 
File: hledger_journal.info, Node: Account display order, Prev: Account types, Up: Declaring accounts File: hledger_journal.info, Node: Account display order, Prev: Account types, Up: Declaring accounts
1.12.7.4 Account display order 1.12.8.4 Account display order
.............................. ..............................
Account directives also set the order in which accounts are displayed, Account directives also set the order in which accounts are displayed,
@ -1274,7 +1288,7 @@ means:
 
File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives
1.12.8 Rewriting accounts 1.12.9 Rewriting accounts
------------------------- -------------------------
You can define account alias rules which rewrite your account names, or You can define account alias rules which rewrite your account names, or
@ -1298,12 +1312,13 @@ hledger-web.
* Basic aliases:: * Basic aliases::
* Regex aliases:: * Regex aliases::
* Combining aliases:: * Combining aliases::
* Aliases and multiple files::
* end aliases:: * end aliases::
 
File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts
1.12.8.1 Basic aliases 1.12.9.1 Basic aliases
...................... ......................
To set an account alias, use the 'alias' directive in your journal file. To set an account alias, use the 'alias' directive in your journal file.
@ -1326,7 +1341,7 @@ alias checking = assets:bank:wells fargo:checking
 
File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts
1.12.8.2 Regex aliases 1.12.9.2 Regex aliases
...................... ......................
There is also a more powerful variant that uses a regular expression, There is also a more powerful variant that uses a regular expression,
@ -1349,9 +1364,9 @@ command line, to end of option argument), so it can contain trailing
whitespace. whitespace.
 
File: hledger_journal.info, Node: Combining aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts File: hledger_journal.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: Rewriting accounts
1.12.8.3 Combining aliases 1.12.9.3 Combining aliases
.......................... ..........................
You can define as many aliases as you like, using journal directives You can define as many aliases as you like, using journal directives
@ -1386,9 +1401,41 @@ independent of which files are being read and in which order.
which aliases are being applied when. which aliases are being applied when.
 
File: hledger_journal.info, Node: end aliases, Prev: Combining aliases, Up: Rewriting accounts File: hledger_journal.info, Node: Aliases and multiple files, Next: end aliases, Prev: Combining aliases, Up: Rewriting accounts
1.12.8.4 'end aliases' 1.12.9.4 Aliases and multiple files
...................................
As explained at Directives and multiple files, 'alias' directives do not
affect parent or sibling files. Eg in this command,
hledger -f a.aliases -f b.journal
account aliases defined in a.aliases will not affect b.journal.
Including the aliases doesn't work either:
include a.aliases
2020-01-01 ; not affected by a.aliases
foo 1
bar
This means that account aliases should usually be declared at the
start of your top-most file, like this:
alias foo=Foo
alias bar=Bar
2020-01-01 ; affected by aliases above
foo 1
bar
include c.journal ; also affected

File: hledger_journal.info, Node: end aliases, Prev: Aliases and multiple files, Up: Rewriting accounts
1.12.9.5 'end aliases'
...................... ......................
You can clear (forget) all currently defined aliases with the 'end You can clear (forget) all currently defined aliases with the 'end
@ -1399,8 +1446,8 @@ end aliases
 
File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives
1.12.9 Default parent account 1.12.10 Default parent account
----------------------------- ------------------------------
You can specify a parent account which will be prepended to all accounts 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 within a section of the journal. Use the 'apply account' and 'end apply
@ -1793,58 +1840,62 @@ Node: Balance assignments and prices29457
Ref: #balance-assignments-and-prices29629 Ref: #balance-assignments-and-prices29629
Node: Directives29853 Node: Directives29853
Ref: #directives30012 Ref: #directives30012
Node: Comment blocks35660 Node: Directives and multiple files35331
Ref: #comment-blocks35805 Ref: #directives-and-multiple-files35514
Node: Including other files35981 Node: Comment blocks36178
Ref: #including-other-files36161 Ref: #comment-blocks36361
Node: Default year36569 Node: Including other files36537
Ref: #default-year36738 Ref: #including-other-files36717
Node: Declaring commodities37145 Node: Default year37125
Ref: #declaring-commodities37328 Ref: #default-year37294
Node: Default commodity39001 Node: Declaring commodities37701
Ref: #default-commodity39177 Ref: #declaring-commodities37884
Node: Market prices40066 Node: Default commodity39557
Ref: #market-prices40231 Ref: #default-commodity39733
Node: Declaring accounts41072 Node: Market prices40622
Ref: #declaring-accounts41248 Ref: #market-prices40787
Node: Account comments42173 Node: Declaring accounts41628
Ref: #account-comments42336 Ref: #declaring-accounts41804
Node: Account subdirectives42760 Node: Account comments42729
Ref: #account-subdirectives42955 Ref: #account-comments42892
Node: Account types43268 Node: Account subdirectives43316
Ref: #account-types43452 Ref: #account-subdirectives43511
Node: Account display order45091 Node: Account types43824
Ref: #account-display-order45261 Ref: #account-types44008
Node: Rewriting accounts46412 Node: Account display order45647
Ref: #rewriting-accounts46597 Ref: #account-display-order45817
Node: Basic aliases47323 Node: Rewriting accounts46968
Ref: #basic-aliases47469 Ref: #rewriting-accounts47153
Node: Regex aliases48173 Node: Basic aliases47910
Ref: #regex-aliases48345 Ref: #basic-aliases48056
Node: Combining aliases49063 Node: Regex aliases48760
Ref: #combining-aliases49241 Ref: #regex-aliases48932
Node: end aliases50517 Node: Combining aliases49650
Ref: #end-aliases50665 Ref: #combining-aliases49843
Node: Default parent account50766 Node: Aliases and multiple files51119
Ref: #default-parent-account50932 Ref: #aliases-and-multiple-files51328
Node: Periodic transactions51816 Node: end aliases51907
Ref: #periodic-transactions52015 Ref: #end-aliases52064
Node: Periodic rule syntax53887 Node: Default parent account52165
Ref: #periodic-rule-syntax54093 Ref: #default-parent-account52333
Node: Two spaces between period expression and description!54797 Node: Periodic transactions53217
Ref: #two-spaces-between-period-expression-and-description55116 Ref: #periodic-transactions53416
Node: Forecasting with periodic transactions55800 Node: Periodic rule syntax55288
Ref: #forecasting-with-periodic-transactions56105 Ref: #periodic-rule-syntax55494
Node: Budgeting with periodic transactions58131 Node: Two spaces between period expression and description!56198
Ref: #budgeting-with-periodic-transactions58370 Ref: #two-spaces-between-period-expression-and-description56517
Node: Auto postings / transaction modifiers58819 Node: Forecasting with periodic transactions57201
Ref: #auto-postings-transaction-modifiers59031 Ref: #forecasting-with-periodic-transactions57506
Node: Auto postings and dates61527 Node: Budgeting with periodic transactions59532
Ref: #auto-postings-and-dates61784 Ref: #budgeting-with-periodic-transactions59771
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61959 Node: Auto postings / transaction modifiers60220
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62334 Ref: #auto-postings-transaction-modifiers60432
Node: Auto posting tags62712 Node: Auto postings and dates62928
Ref: #auto-posting-tags62951 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
 
End Tag Table End Tag Table

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

@ -819,18 +819,22 @@ As you can see, directives vary in which journal entries and files they affect,
and whether they are focussed on input (parsing) or output (reports). and whether they are focussed on input (parsing) or output (reports).
Some directives have multiple effects. Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f options on the command line, ### Directives and multiple files
note that directives which affect input typically last only until the end of their defining file.
This provides more simplicity and predictability, eg reports are not changed by writing file options in a different order.
It can be surprising at times though.
<!-- TODO: retest
For example, in:
hledger -f a.aliases -f b.journal If you use multiple `-f`/`--file` options, or the `include` directive,
hledger will process multiple input files. But note that directives
which affect input (see above) typically last only until the end of
the file in which they occur.
you might expect account aliases defined in a.aliases to affect b.journal, but they will not, This may seem inconvenient, but it's intentional; it makes reports
unless you `include a.aliases` in b.journal, or vice versa. stable and deterministic, independent of the order of input. Otherwise
--> you could see different numbers if you happened to write -f options in
a different order, or if you moved includes around while cleaning up
your files.
It can be surprising though; for example, it means that
[`alias` directives do not affect parent or sibling files](#aliases-and-multiple-files)
(see below).
### Comment blocks ### Comment blocks
@ -1215,9 +1219,39 @@ independent of which files are being read and in which order.
In case of trouble, adding `--debug=6` to the command line will show which aliases are being applied when. In case of trouble, adding `--debug=6` to the command line will show which aliases are being applied when.
#### Aliases and multiple files
As explained at [Directives and multiple files](#directives-and-multiple-files),
`alias` directives do not affect parent or sibling files. Eg in this command,
```shell
hledger -f a.aliases -f b.journal
```
account aliases defined in a.aliases will not affect b.journal.
Including the aliases doesn't work either:
```journal
include a.aliases
2020-01-01 ; not affected by a.aliases
foo 1
bar
```
This means that account aliases should usually be declared at the
start of your top-most file, like this:
```journal
alias foo=Foo
alias bar=Bar
2020-01-01 ; affected by aliases above
foo 1
bar
include c.journal ; also affected
```
#### `end aliases` #### `end aliases`
You can clear (forget) all currently defined aliases with the `end aliases` directive: You can clear (forget) all currently defined aliases with the `end
aliases` directive:
```journal ```journal
end aliases end aliases

47
hledger-lib/hledger_journal.txt
View File

@ -732,12 +732,20 @@ FILE FORMAT
affect, and whether they are focussed on input (parsing) or output (re- affect, and whether they are focussed on input (parsing) or output (re-
ports). Some directives have multiple effects. ports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f Directives and multiple files
options on the command line, note that directives which affect input If you use multiple -f/--file options, or the include directive,
typically last only until the end of their defining file. This pro- hledger will process multiple input files. But note that directives
vides more simplicity and predictability, eg reports are not changed by which affect input (see above) typically last only until the end of the
writing file options in a different order. It can be surprising at file in which they occur.
times though.
This may seem inconvenient, but it's intentional; it makes reports sta-
ble and deterministic, independent of the order of input. Otherwise
you could see different numbers if you happened to write -f options in
a different order, or if you moved includes around while cleaning up
your files.
It can be surprising though; for example, it means that alias direc-
tives do not affect parent or sibling files (see below).
Comment blocks Comment blocks
A line containing just comment starts a commented region of the file, A line containing just comment starts a commented region of the file,
@ -1099,6 +1107,33 @@ FILE FORMAT
In case of trouble, adding --debug=6 to the command line will show In case of trouble, adding --debug=6 to the command line will show
which aliases are being applied when. which aliases are being applied when.
Aliases and multiple files
As explained at Directives and multiple files, alias directives do not
affect parent or sibling files. Eg in this command,
hledger -f a.aliases -f b.journal
account aliases defined in a.aliases will not affect b.journal. In-
cluding the aliases doesn't work either:
include a.aliases
2020-01-01 ; not affected by a.aliases
foo 1
bar
This means that account aliases should usually be declared at the start
of your top-most file, like this:
alias foo=Foo
alias bar=Bar
2020-01-01 ; affected by aliases above
foo 1
bar
include c.journal ; also affected
end aliases end aliases
You can clear (forget) all currently defined aliases with the end You can clear (forget) all currently defined aliases with the end
aliases directive: aliases directive: