;journal: document directives/alias multi-file limitation clearly
This commit is contained in:
Simon Michael
parent
888e278afc
commit
2aab02f4e8
@ -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
|
||||
(reports).
|
||||
Some directives have multiple effects.
|
||||
.SS Directives and multiple files
|
||||
.PP
|
||||
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.
|
||||
If you use multiple \f[C]-f\f[R]/\f[C]--file\f[R] options, or the
|
||||
\f[C]include\f[R] 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.
|
||||
.PP
|
||||
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
|
||||
.PP
|
||||
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
|
||||
In case of trouble, adding \f[C]--debug=6\f[R] to the command line will
|
||||
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]
|
||||
.PP
|
||||
You can clear (forget) all currently defined aliases with the
|
||||
|
||||
@ -929,15 +929,9 @@ scope are affected by a directive
|
||||
they affect, and whether they are focussed on input (parsing) or output
|
||||
(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:
|
||||
|
||||
* Directives and multiple files::
|
||||
* Comment blocks::
|
||||
* Including other files::
|
||||
* Default year::
|
||||
@ -949,9 +943,29 @@ times though.
|
||||
* 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,
|
||||
@ -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
|
||||
|
||||
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
|
||||
@ -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
|
||||
|
||||
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
|
||||
@ -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
|
||||
|
||||
1.12.4 Declaring commodities
|
||||
1.12.5 Declaring commodities
|
||||
----------------------------
|
||||
|
||||
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
|
||||
|
||||
1.12.5 Default commodity
|
||||
1.12.6 Default commodity
|
||||
------------------------
|
||||
|
||||
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
|
||||
|
||||
1.12.6 Market prices
|
||||
1.12.7 Market prices
|
||||
--------------------
|
||||
|
||||
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
|
||||
|
||||
1.12.7 Declaring accounts
|
||||
1.12.8 Declaring accounts
|
||||
-------------------------
|
||||
|
||||
'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
|
||||
|
||||
1.12.7.1 Account comments
|
||||
1.12.8.1 Account comments
|
||||
.........................
|
||||
|
||||
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
|
||||
|
||||
1.12.7.2 Account subdirectives
|
||||
1.12.8.2 Account subdirectives
|
||||
..............................
|
||||
|
||||
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
|
||||
|
||||
1.12.7.3 Account types
|
||||
1.12.8.3 Account types
|
||||
......................
|
||||
|
||||
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
|
||||
|
||||
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,
|
||||
@ -1274,7 +1288,7 @@ means:
|
||||
|
||||
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
|
||||
@ -1298,12 +1312,13 @@ hledger-web.
|
||||
* Basic aliases::
|
||||
* Regex aliases::
|
||||
* Combining aliases::
|
||||
* Aliases and multiple files::
|
||||
* end aliases::
|
||||
|
||||
|
||||
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.
|
||||
@ -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
|
||||
|
||||
1.12.8.2 Regex aliases
|
||||
1.12.9.2 Regex aliases
|
||||
......................
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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
|
||||
@ -1386,9 +1401,41 @@ independent of which files are being read and in which order.
|
||||
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
|
||||
@ -1399,8 +1446,8 @@ end aliases
|
||||
|
||||
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
|
||||
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
|
||||
Node: Directives29853
|
||||
Ref: #directives30012
|
||||
Node: Comment blocks35660
|
||||
Ref: #comment-blocks35805
|
||||
Node: Including other files35981
|
||||
Ref: #including-other-files36161
|
||||
Node: Default year36569
|
||||
Ref: #default-year36738
|
||||
Node: Declaring commodities37145
|
||||
Ref: #declaring-commodities37328
|
||||
Node: Default commodity39001
|
||||
Ref: #default-commodity39177
|
||||
Node: Market prices40066
|
||||
Ref: #market-prices40231
|
||||
Node: Declaring accounts41072
|
||||
Ref: #declaring-accounts41248
|
||||
Node: Account comments42173
|
||||
Ref: #account-comments42336
|
||||
Node: Account subdirectives42760
|
||||
Ref: #account-subdirectives42955
|
||||
Node: Account types43268
|
||||
Ref: #account-types43452
|
||||
Node: Account display order45091
|
||||
Ref: #account-display-order45261
|
||||
Node: Rewriting accounts46412
|
||||
Ref: #rewriting-accounts46597
|
||||
Node: Basic aliases47323
|
||||
Ref: #basic-aliases47469
|
||||
Node: Regex aliases48173
|
||||
Ref: #regex-aliases48345
|
||||
Node: Combining aliases49063
|
||||
Ref: #combining-aliases49241
|
||||
Node: end aliases50517
|
||||
Ref: #end-aliases50665
|
||||
Node: Default parent account50766
|
||||
Ref: #default-parent-account50932
|
||||
Node: Periodic transactions51816
|
||||
Ref: #periodic-transactions52015
|
||||
Node: Periodic rule syntax53887
|
||||
Ref: #periodic-rule-syntax54093
|
||||
Node: Two spaces between period expression and description!54797
|
||||
Ref: #two-spaces-between-period-expression-and-description55116
|
||||
Node: Forecasting with periodic transactions55800
|
||||
Ref: #forecasting-with-periodic-transactions56105
|
||||
Node: Budgeting with periodic transactions58131
|
||||
Ref: #budgeting-with-periodic-transactions58370
|
||||
Node: Auto postings / transaction modifiers58819
|
||||
Ref: #auto-postings-transaction-modifiers59031
|
||||
Node: Auto postings and dates61527
|
||||
Ref: #auto-postings-and-dates61784
|
||||
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61959
|
||||
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62334
|
||||
Node: Auto posting tags62712
|
||||
Ref: #auto-posting-tags62951
|
||||
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
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
||||
@ -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).
|
||||
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.
|
||||
<!-- TODO: retest
|
||||
For example, in:
|
||||
### Directives and multiple files
|
||||
|
||||
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,
|
||||
unless you `include a.aliases` in b.journal, or vice versa.
|
||||
-->
|
||||
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](#aliases-and-multiple-files)
|
||||
(see below).
|
||||
|
||||
### 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.
|
||||
|
||||
#### 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`
|
||||
|
||||
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
|
||||
end aliases
|
||||
|
||||
@ -732,34 +732,42 @@ FILE FORMAT
|
||||
affect, and whether they are focussed on input (parsing) or output (re-
|
||||
ports). 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 pro-
|
||||
vides more simplicity and predictability, eg reports are not changed by
|
||||
writing file options in a different order. It can be surprising at
|
||||
times though.
|
||||
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 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
|
||||
A line containing just comment starts a commented region of the file,
|
||||
A line containing just comment starts a commented region of the file,
|
||||
and a line containing just end comment (or the end of the current file)
|
||||
ends it. See also comments.
|
||||
|
||||
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
|
||||
directive, like this:
|
||||
|
||||
include path/to/file.journal
|
||||
|
||||
If the path does not begin with a slash, it is relative to the current
|
||||
file. The include file path may contain common glob patterns (e.g.
|
||||
If the path does not begin with a slash, it is relative to the current
|
||||
file. The include file path may contain common glob patterns (e.g.
|
||||
*).
|
||||
|
||||
The include directive can only be used in journal files. It can in-
|
||||
The include directive can only be used in journal files. It can in-
|
||||
clude journal, timeclock or timedot files, but not CSV files.
|
||||
|
||||
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
|
||||
@ -781,19 +789,19 @@ FILE FORMAT
|
||||
Declaring commodities
|
||||
The commodity directive has several functions:
|
||||
|
||||
1. It declares commodities which may be used in the journal. This is
|
||||
1. It declares commodities which may be used in the journal. This is
|
||||
currently not enforced, but can serve as documentation.
|
||||
|
||||
2. It declares what decimal mark character (period or comma) to expect
|
||||
when parsing input - useful to disambiguate international number
|
||||
formats in your data. (Without this, hledger will parse both 1,000
|
||||
2. It declares what decimal mark character (period or comma) to expect
|
||||
when parsing input - useful to disambiguate international number
|
||||
formats in your data. (Without this, hledger will parse both 1,000
|
||||
and 1.000 as 1).
|
||||
|
||||
3. It declares the amount display style to use in output - decimal and
|
||||
3. It declares the amount display style to use in output - decimal and
|
||||
digit group marks, number of decimal places, symbol placement etc.
|
||||
|
||||
You are likely to run into one of the problems solved by commodity di-
|
||||
rectives, sooner or later, so it's a good idea to just always use them
|
||||
You are likely to run into one of the problems solved by commodity di-
|
||||
rectives, sooner or later, so it's a good idea to just always use them
|
||||
to declare your commodities.
|
||||
|
||||
A commodity directive is just the word commodity followed by an amount.
|
||||
@ -806,8 +814,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
|
||||
@ -820,19 +828,19 @@ FILE FORMAT
|
||||
format INR 1,00,00,000.00
|
||||
|
||||
The quantity of the amount does not matter; only the format is signifi-
|
||||
cant. The number must include a decimal mark: either a period or a
|
||||
cant. The number must include a decimal mark: either a period or a
|
||||
comma, followed by 0 or more decimal digits.
|
||||
|
||||
Default commodity
|
||||
The D directive sets a default commodity, to be used for amounts with-
|
||||
The D directive sets a default commodity, to be used for amounts with-
|
||||
out a commodity symbol (ie, plain numbers). This commodity will be ap-
|
||||
plied to all subsequent commodity-less amounts, or until the next D di-
|
||||
rective. (Note, this is different from Ledger's D.)
|
||||
|
||||
For compatibility/historical reasons, D also acts like a commodity di-
|
||||
For compatibility/historical reasons, D also acts like a commodity di-
|
||||
rective, setting the commodity's display style (for output) and decimal
|
||||
mark (for parsing input). As with commodity, the amount must always be
|
||||
written with a decimal mark (period or comma). If both directives are
|
||||
written with a decimal mark (period or comma). If both directives are
|
||||
used, commodity's style takes precedence.
|
||||
|
||||
The syntax is D AMOUNT. Eg:
|
||||
@ -846,9 +854,9 @@ FILE FORMAT
|
||||
b
|
||||
|
||||
Market prices
|
||||
The P directive declares a market price, which is an exchange rate be-
|
||||
tween two commodities on a certain date. (In Ledger, they are called
|
||||
"historical prices".) These are often obtained from a stock exchange,
|
||||
The P directive declares a market price, which is an exchange rate be-
|
||||
tween two commodities on a certain date. (In Ledger, they are called
|
||||
"historical prices".) These are often obtained from a stock exchange,
|
||||
cryptocurrency exchange, or the foreign exchange market.
|
||||
|
||||
Here is the format:
|
||||
@ -859,16 +867,16 @@ FILE FORMAT
|
||||
|
||||
o COMMODITYA is the symbol of the commodity being priced
|
||||
|
||||
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
|
||||
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
|
||||
modity, giving the price in commodity B of one unit of commodity A.
|
||||
|
||||
These two market price directives say that one euro was worth 1.35 US
|
||||
These two market price directives say that one euro was worth 1.35 US
|
||||
dollars during 2009, and $1.40 from 2010 onward:
|
||||
|
||||
P 2009/1/1 EUR $1.35
|
||||
P 2010/1/1 EUR $1.40
|
||||
|
||||
The -V/--value flag can be used to convert reported amounts to another
|
||||
The -V/--value flag can be used to convert reported amounts to another
|
||||
commodity using these prices.
|
||||
|
||||
Declaring accounts
|
||||
@ -878,20 +886,20 @@ FILE FORMAT
|
||||
o They can document your intended chart of accounts, providing a refer-
|
||||
ence.
|
||||
|
||||
o They can store extra information about accounts (account numbers,
|
||||
o They can store extra information about accounts (account numbers,
|
||||
notes, etc.)
|
||||
|
||||
o They can help hledger know your accounts' types (asset, liability,
|
||||
equity, revenue, expense), useful for reports like balancesheet and
|
||||
o They can help hledger know your accounts' types (asset, liability,
|
||||
equity, revenue, expense), useful for reports like balancesheet and
|
||||
incomestatement.
|
||||
|
||||
o They control account display order in reports, allowing non-alpha-
|
||||
o They control account display order in reports, allowing non-alpha-
|
||||
betic sorting (eg Revenues to appear above Expenses).
|
||||
|
||||
o They help with account name completion in the add command, hledger-
|
||||
o They help with account name completion in the add command, hledger-
|
||||
iadd, hledger-web, ledger-mode etc.
|
||||
|
||||
The simplest form is just the word account followed by a hledger-style
|
||||
The simplest form is just the word account followed by a hledger-style
|
||||
account name, eg:
|
||||
|
||||
account assets:bank:checking
|
||||
@ -899,7 +907,7 @@ FILE FORMAT
|
||||
Account comments
|
||||
Comments, beginning with a semicolon, can be added:
|
||||
|
||||
o on the same line, after two or more spaces (because ; is allowed in
|
||||
o on the same line, after two or more spaces (because ; is allowed in
|
||||
account names)
|
||||
|
||||
o on the next lines, indented
|
||||
@ -913,7 +921,7 @@ FILE FORMAT
|
||||
Same-line comments are not supported by Ledger, or hledger <1.13.
|
||||
|
||||
Account subdirectives
|
||||
We also allow (and ignore) Ledger-style indented subdirectives, just
|
||||
We also allow (and ignore) Ledger-style indented subdirectives, just
|
||||
for compatibility.:
|
||||
|
||||
account assets:bank:checking
|
||||
@ -926,18 +934,18 @@ FILE FORMAT
|
||||
[LEDGER-STYLE SUBDIRECTIVES, IGNORED]
|
||||
|
||||
Account types
|
||||
hledger recognises five types (or classes) of account: Asset, Liabil-
|
||||
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
|
||||
hledger recognises five types (or classes) of account: Asset, Liabil-
|
||||
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
|
||||
reports such as balancesheet, incomestatement and cashflow.
|
||||
|
||||
Auto-detected account types
|
||||
If you name your top-level accounts with some variation of assets, lia-
|
||||
bilities/debts, equity, revenues/income, or expenses, their types are
|
||||
bilities/debts, equity, revenues/income, or expenses, their types are
|
||||
detected automatically.
|
||||
|
||||
Account types declared with tags
|
||||
More generally, you can declare an account's type with an account di-
|
||||
rective, by writing a type: tag in a comment, followed by one of the
|
||||
More generally, you can declare an account's type with an account di-
|
||||
rective, by writing a type: tag in a comment, followed by one of the
|
||||
words Asset, Liability, Equity, Revenue, Expense, or one of the letters
|
||||
ALERX (case insensitive):
|
||||
|
||||
@ -948,8 +956,8 @@ FILE FORMAT
|
||||
account expenses ; type:Expense
|
||||
|
||||
Account types declared with account type codes
|
||||
Or, you can write one of those letters separated from the account name
|
||||
by two or more spaces, but this should probably be considered depre-
|
||||
Or, you can write one of those letters separated from the account name
|
||||
by two or more spaces, but this should probably be considered depre-
|
||||
cated as of hledger 1.13:
|
||||
|
||||
account assets A
|
||||
@ -959,7 +967,7 @@ FILE FORMAT
|
||||
account expenses X
|
||||
|
||||
Overriding auto-detected types
|
||||
If you ever override the types of those auto-detected english account
|
||||
If you ever override the types of those auto-detected english account
|
||||
names mentioned above, you might need to help the reports a bit. Eg:
|
||||
|
||||
; make "liabilities" not have the liability type - who knows why
|
||||
@ -970,8 +978,8 @@ FILE FORMAT
|
||||
account - ; type:L
|
||||
|
||||
Account display order
|
||||
Account directives also set the order in which accounts are displayed,
|
||||
eg in reports, the hledger-ui accounts screen, and the hledger-web
|
||||
Account directives also set the order in which accounts are displayed,
|
||||
eg in reports, the hledger-ui accounts screen, and the hledger-web
|
||||
sidebar. By default accounts are listed in alphabetical order. But if
|
||||
you have these account directives in the journal:
|
||||
|
||||
@ -993,20 +1001,20 @@ FILE FORMAT
|
||||
|
||||
Undeclared accounts, if any, are displayed last, in alphabetical order.
|
||||
|
||||
Note that sorting is done at each level of the account tree (within
|
||||
each group of sibling accounts under the same parent). And currently,
|
||||
Note that sorting is done at each level of the account tree (within
|
||||
each group of sibling accounts under the same parent). And currently,
|
||||
this directive:
|
||||
|
||||
account other:zoo
|
||||
|
||||
would influence the position of zoo among other's subaccounts, but not
|
||||
would influence the position of zoo among other's subaccounts, but not
|
||||
the position of other among the top-level accounts. This means:
|
||||
|
||||
o you will sometimes declare parent accounts (eg account other above)
|
||||
o you will sometimes declare parent accounts (eg account other above)
|
||||
that you don't intend to post to, just to customize their display or-
|
||||
der
|
||||
|
||||
o sibling accounts stay together (you couldn't display x:y in between
|
||||
o sibling accounts stay together (you couldn't display x:y in between
|
||||
a:b and a:c).
|
||||
|
||||
Rewriting accounts
|
||||
@ -1024,14 +1032,14 @@ FILE FORMAT
|
||||
o customising reports
|
||||
|
||||
Account aliases also rewrite account names in account directives. They
|
||||
do not affect account names being entered via hledger add or hledger-
|
||||
do not affect account names being entered via hledger add or hledger-
|
||||
web.
|
||||
|
||||
See also Rewrite account names.
|
||||
|
||||
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
|
||||
@ -1039,49 +1047,49 @@ 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 case sensitive full account names. hledger will re-
|
||||
place any occurrence of the old account name with the new one. Subac-
|
||||
OLD and NEW are case sensitive full account names. hledger will re-
|
||||
place any occurrence of the old account name with the new one. Subac-
|
||||
counts 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,
|
||||
There is also a more powerful variant that uses a regular expression,
|
||||
indicated by the forward slashes:
|
||||
|
||||
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. Eg:
|
||||
|
||||
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
|
||||
; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
|
||||
|
||||
Also note that REPLACEMENT continues to the end of line (or on command
|
||||
line, to end of option argument), so it can contain trailing white-
|
||||
Also note that REPLACEMENT continues to the end of line (or on command
|
||||
line, to end of option argument), so it can contain trailing white-
|
||||
space.
|
||||
|
||||
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
|
||||
and/or command line options.
|
||||
|
||||
Recursive aliases - where an account name is rewritten by one alias,
|
||||
then by another alias, and so on - are allowed. Each alias sees the
|
||||
Recursive aliases - where an account name is rewritten by one alias,
|
||||
then by another alias, and so on - are allowed. Each alias sees the
|
||||
effect of previously applied aliases.
|
||||
|
||||
In such cases it can be important to understand which aliases will be
|
||||
applied and in which order. For (each account name in) each journal
|
||||
In such cases it can be important to understand which aliases will be
|
||||
applied and in which order. For (each account name in) each journal
|
||||
entry, we apply:
|
||||
|
||||
1. alias directives preceding the journal entry, most recently parsed
|
||||
1. alias directives preceding the journal entry, most recently parsed
|
||||
first (ie, reading upward from the journal entry, bottom to top)
|
||||
|
||||
2. --alias options, in the order they appeared on the command line
|
||||
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:
|
||||
@ -1092,13 +1100,40 @@ FILE FORMAT
|
||||
|
||||
o aliases defined after/below the entry do not affect it.
|
||||
|
||||
This gives nearby aliases precedence over distant ones, and helps pro-
|
||||
vide semantic stability - aliases will keep working the same way inde-
|
||||
This gives nearby aliases precedence over distant ones, and helps pro-
|
||||
vide semantic stability - aliases will keep working the same way inde-
|
||||
pendent of which files are being read and in which order.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
You can clear (forget) all currently defined aliases with the end
|
||||
aliases directive:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user