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

187
hledger-lib/hledger_journal.txt
View File

@ -732,34 +732,42 @@ 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,
and a line containing just end comment (or the end of the current file) and a line containing just end comment (or the end of the current file)
ends it. See also comments. ends it. See also comments.
Including other files 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: directive, like this:
include path/to/file.journal 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. The include file path may contain common glob patterns (e.g. 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. clude journal, timeclock or timedot files, but not CSV files.
Default year 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
specify a year. This is a line beginning with Y followed by the year. specify a year. This is a line beginning with Y followed by the year.
Eg: Eg:
Y2009 ; set default year to 2009 Y2009 ; set default year to 2009
@ -781,19 +789,19 @@ FILE FORMAT
Declaring commodities Declaring commodities
The commodity directive has several functions: 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. currently not enforced, but can serve as documentation.
2. It declares what decimal mark character (period or comma) to expect 2. It declares what decimal mark character (period or comma) to expect
when parsing input - useful to disambiguate international number when parsing input - useful to disambiguate international number
formats in your data. (Without this, hledger will parse both 1,000 formats in your data. (Without this, hledger will parse both 1,000
and 1.000 as 1). 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. digit group marks, number of decimal places, symbol placement etc.
You are likely to run into one of the problems solved by commodity di- 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 rectives, sooner or later, so it's a good idea to just always use them
to declare your commodities. to declare your commodities.
A commodity directive is just the word commodity followed by an amount. A commodity directive is just the word commodity followed by an amount.
@ -806,8 +814,8 @@ FILE FORMAT
; separating thousands with comma. ; separating thousands with comma.
commodity 1,000.0000 AAAA commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. (In this case or on multiple lines, using the "format" subdirective. (In this case
the commodity symbol appears twice and should be the same in both the commodity symbol appears twice and should be the same in both
places.): places.):
; commodity SYMBOL ; commodity SYMBOL
@ -820,19 +828,19 @@ FILE FORMAT
format INR 1,00,00,000.00 format INR 1,00,00,000.00
The quantity of the amount does not matter; only the format is signifi- 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. comma, followed by 0 or more decimal digits.
Default commodity 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- 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- plied to all subsequent commodity-less amounts, or until the next D di-
rective. (Note, this is different from Ledger's D.) 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 rective, setting the commodity's display style (for output) and decimal
mark (for parsing input). As with commodity, the amount must always be 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. used, commodity's style takes precedence.
The syntax is D AMOUNT. Eg: The syntax is D AMOUNT. Eg:
@ -846,9 +854,9 @@ FILE FORMAT
b b
Market prices Market prices
The P directive declares a market price, which is an exchange rate be- 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 tween two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange, "historical prices".) These are often obtained from a stock exchange,
cryptocurrency exchange, or the foreign exchange market. cryptocurrency exchange, or the foreign exchange market.
Here is the format: Here is the format:
@ -859,16 +867,16 @@ FILE FORMAT
o COMMODITYA is the symbol of the commodity being priced 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. 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: dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 EUR $1.35 P 2009/1/1 EUR $1.35
P 2010/1/1 EUR $1.40 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. commodity using these prices.
Declaring accounts Declaring accounts
@ -878,20 +886,20 @@ FILE FORMAT
o They can document your intended chart of accounts, providing a refer- o They can document your intended chart of accounts, providing a refer-
ence. ence.
o They can store extra information about accounts (account numbers, o They can store extra information about accounts (account numbers,
notes, etc.) notes, etc.)
o They can help hledger know your accounts' types (asset, liability, o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and equity, revenue, expense), useful for reports like balancesheet and
incomestatement. 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). 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. 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 name, eg:
account assets:bank:checking account assets:bank:checking
@ -899,7 +907,7 @@ FILE FORMAT
Account comments Account comments
Comments, beginning with a semicolon, can be added: 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) account names)
o on the next lines, indented o on the next lines, indented
@ -913,7 +921,7 @@ FILE FORMAT
Same-line comments are not supported by Ledger, or hledger <1.13. Same-line comments are not supported by Ledger, or hledger <1.13.
Account subdirectives Account subdirectives
We also allow (and ignore) Ledger-style indented subdirectives, just We also allow (and ignore) Ledger-style indented subdirectives, just
for compatibility.: for compatibility.:
account assets:bank:checking account assets:bank:checking
@ -926,18 +934,18 @@ FILE FORMAT
[LEDGER-STYLE SUBDIRECTIVES, IGNORED] [LEDGER-STYLE SUBDIRECTIVES, IGNORED]
Account types Account types
hledger recognises five types (or classes) of account: Asset, Liabil- hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware ity, Equity, Revenue, Expense. This is used by a few accounting-aware
reports such as balancesheet, incomestatement and cashflow. reports such as balancesheet, incomestatement and cashflow.
Auto-detected account types Auto-detected account types
If you name your top-level accounts with some variation of assets, lia- 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. detected automatically.
Account types declared with tags Account types declared with tags
More generally, you can declare an account's type with an account di- 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 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 words Asset, Liability, Equity, Revenue, Expense, or one of the letters
ALERX (case insensitive): ALERX (case insensitive):
@ -948,8 +956,8 @@ FILE FORMAT
account expenses ; type:Expense account expenses ; type:Expense
Account types declared with account type codes Account types declared with account type codes
Or, you can write one of those letters separated from the account name 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- by two or more spaces, but this should probably be considered depre-
cated as of hledger 1.13: cated as of hledger 1.13:
account assets A account assets A
@ -959,7 +967,7 @@ FILE FORMAT
account expenses X account expenses X
Overriding auto-detected types 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: names mentioned above, you might need to help the reports a bit. Eg:
; make "liabilities" not have the liability type - who knows why ; make "liabilities" not have the liability type - who knows why
@ -970,8 +978,8 @@ FILE FORMAT
account - ; type:L account - ; type:L
Account display order 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,
eg in reports, the hledger-ui accounts screen, and the hledger-web eg in reports, the hledger-ui accounts screen, and the hledger-web
sidebar. By default accounts are listed in alphabetical order. But if sidebar. By default accounts are listed in alphabetical order. But if
you have these account directives in the journal: you have these account directives in the journal:
@ -993,20 +1001,20 @@ FILE FORMAT
Undeclared accounts, if any, are displayed last, in alphabetical order. Undeclared accounts, if any, are displayed last, in alphabetical order.
Note that sorting is done at each level of the account tree (within Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently, each group of sibling accounts under the same parent). And currently,
this directive: this directive:
account other:zoo 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: 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- that you don't intend to post to, just to customize their display or-
der 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). a:b and a:c).
Rewriting accounts Rewriting accounts
@ -1024,14 +1032,14 @@ FILE FORMAT
o customising reports o customising reports
Account aliases also rewrite account names in account directives. They 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. web.
See also Rewrite account names. See also Rewrite account names.
Basic aliases 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.
This affects all subsequent journal entries in the current file or its This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional: included files. The spaces around the = are optional:
alias OLD = NEW alias OLD = NEW
@ -1039,49 +1047,49 @@ FILE FORMAT
Or, you can use the --alias 'OLD=NEW' option on the command line. This 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. affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are case sensitive full account names. hledger will re- 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- place any occurrence of the old account name with the new one. Subac-
counts are also affected. Eg: counts are also affected. Eg:
alias checking = assets:bank:wells fargo:checking 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" ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
Regex aliases 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: indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'. or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE- inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref- MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Eg: erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" ; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Also note that REPLACEMENT continues to the end of line (or on command 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- line, to end of option argument), so it can contain trailing white-
space. space.
Combining aliases 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. and/or command line options.
Recursive aliases - where an account name is rewritten by one alias, Recursive aliases - where an account name is rewritten by one alias,
then by another alias, and so on - are allowed. Each alias sees the then by another alias, and so on - are allowed. Each alias sees the
effect of previously applied aliases. effect of previously applied aliases.
In such cases it can be important to understand which aliases will be 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 applied and in which order. For (each account name in) each journal
entry, we apply: 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) 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). (left to right).
In other words, for (an account name in) a given journal entry: 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. o aliases defined after/below the entry do not affect it.
This gives nearby aliases precedence over distant ones, and helps pro- This gives nearby aliases precedence over distant ones, and helps pro-
vide semantic stability - aliases will keep working the same way inde- vide semantic stability - aliases will keep working the same way inde-
pendent of which files are being read and in which order. 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. 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: