lib: doc: journal: describe current directive semantics, finally
It's amazing how you can build, document, support and fix a thing for years and not know what exactly it does. Directives are tricky. Here is a pretty accurate description of their current behaviour, determined by testing.
This commit is contained in:
Simon Michael
parent
26489765ef
commit
bc9375e4e5
@ -613,28 +613,75 @@ feature, except hledger's tag values are simple strings.
|
|||||||
|
|
||||||
A directive is a line in the journal beginning with a special keyword,
|
A directive is a line in the journal beginning with a special keyword,
|
||||||
that influences how the journal is processed.
|
that influences how the journal is processed.
|
||||||
Some directives may also have indented sub-directives on the following lines (`commodity`).
|
hledger's directives are based on a subset of Ledger's, but there are many differences
|
||||||
|
(and also some differences between hledger versions).
|
||||||
|
|
||||||
### Directive scope, multiple files
|
Directives' behaviour and interactions can get a little bit [complex](https://github.com/simonmichael/hledger/issues/793),
|
||||||
|
so here is a table summarising the directives and their effects, with links to more detailed docs.
|
||||||
|
|
||||||
Directives vary in which journal entries they affect:
|
<!-- <style> -->
|
||||||
|
<!-- table a code { white-space:nowrap; } -->
|
||||||
|
<!-- h1,h2,h3,h4,h5,h6 { color:red; } -->
|
||||||
|
<!-- </style> -->
|
||||||
|
|
||||||
- some form a begin/end pair, and affect the enclosed journal entries (and included files):\
|
| directive | end directive | subdirectives | purpose | can affect (as of 2018/06)
|
||||||
`alias` & `end aliases`; `comment` & `end comment`
|
|:------------------|:--------------------|:----------------|:-------------------------------------------------------------------|:---------------------------------------------
|
||||||
- some affect the subsequent journal entries (and included files) in the current file:\
|
| [`account`] | | any text | declare an account name & optional account code | account code: balance reports (except `balance` single-column mode) <!-- all entries in all files -->
|
||||||
`alias` or `comment` without an end directive, `Y`
|
| [`alias`] | `end aliases` | | rewrite account names | following inline/included entries until end of current file or end directive
|
||||||
- some affect all journal entries (and included files) anywhere in the current file:\
|
| [`apply account`] | `end apply account` | | prepend a common parent to account names | following inline/included entries until end of current file or end directive
|
||||||
`account`, `commodity`, `D`, `P`.
|
| [`comment`] | `end comment` | | ignore part of journal | following inline/included entries until end of current file or end directive
|
||||||
|
| [`commodity`] | | `format` | declare a commodity and its number notation & display style | number notation: following entries in that commodity in all files; <br>display style: amounts of that commodity in reports
|
||||||
|
| [`D`] | | | declare a commodity, number notation & display style for commodityless amounts | commodity: all commodityless entries in all files; <br>number notation: following commodityless entries and entries in that commodity in all files; <br>display style: amounts of that commodity in reports
|
||||||
|
| [`include`] | | | include entries/directives from another file | what the included directives affect
|
||||||
|
| [`P`] | | | declare a market price for a commodity | amounts of that commodity in reports, when -V is used
|
||||||
|
| [`Y`] | | | declare a year for yearless dates | following inline/included entries until end of current file
|
||||||
|
|
||||||
It's important to note that directives can affect the current file and
|
[`account`]: #declaring-accounts
|
||||||
child (included) files, but not sibling or parent (including) files.
|
[`alias`]: #rewriting-accounts
|
||||||
This is by design, for simplicity and predictability of reports, but
|
[`apply account`]: #default-parent-account
|
||||||
it can be surprising at times. Eg, in:
|
[`comment`]: #comment-blocks
|
||||||
|
[`commodity`]: #declaring-commodities
|
||||||
|
[`D`]: #default-commodity
|
||||||
|
[`include`]: #including-other-files
|
||||||
|
[`P`]: #market-prices
|
||||||
|
[`Y`]: #default-year
|
||||||
|
|
||||||
hledger -f a.prices -f b.journal
|
And some definitions:
|
||||||
|
|
||||||
the prices defined in a.prices will not be effective in b.journal (a sibling file).
|
|||
|
||||||
Instead, you have to include (or inline) a.prices in b.journal, or vice versa.
|
|:----------------|:--------------------------------------------------------------------------------------------------------------------
|
||||||
|
| subdirective | optional indented directive or unparsed text lines immediately following a parent directive
|
||||||
|
| account code | numeric code influencing account display order in most balance reports
|
||||||
|
| number notation | how to interpret numbers when parsing journal entries (the identity of the decimal separator character). (Currently each commodity can have its own notation, even in the same file.)
|
||||||
|
| display style | how to display amounts of a commodity in reports (symbol side and spacing, digit groups, decimal separator, decimal places)
|
||||||
|
| directive scope | which entries and (when there are multiple files) which files are affected by a directive
|
||||||
|
|
||||||
|
<!-- | **entries affected:** | -->
|
||||||
|
<!-- | following | subsequent entries in the file/parse stream -->
|
||||||
|
<!-- | delimited | subsequent entries, until an optional end directive -->
|
||||||
|
<!-- | all | all preceding and following entries -->
|
||||||
|
<!-- | **files affected:** | -->
|
||||||
|
<!-- | current | affects current file only -->
|
||||||
|
<!-- | children | affects current file and files included by it -->
|
||||||
|
<!-- | siblings | affects current file, included files, and other same-level files, but not higher-level files -->
|
||||||
|
<!-- | all | affects all files -->
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
hledger -f a.aliases -f b.journal
|
||||||
|
|
||||||
|
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.
|
||||||
|
-->
|
||||||
|
|
||||||
### Comment blocks
|
### Comment blocks
|
||||||
|
|
||||||
|
|||||||
55
hledger-lib/hledger_journal_directives.m4.md
Normal file
55
hledger-lib/hledger_journal_directives.m4.md
Normal file
@ -0,0 +1,55 @@
|
|||||||
|
<!-- <style> -->
|
||||||
|
<!-- table a code { white-space:nowrap; } -->
|
||||||
|
<!-- h1,h2,h3,h4,h5,h6 { color:red; } -->
|
||||||
|
<!-- </style> -->
|
||||||
|
|
||||||
|
### Summary of directives
|
||||||
|
|
||||||
|
hledger's directives are based on Ledger's, but there are many differences (and also some between hledger versions).
|
||||||
|
Directives' behaviour and interactions can get a little bit [complex](https://github.com/simonmichael/hledger/issues/793),
|
||||||
|
especially with multiple files,
|
||||||
|
so here is a table summarising them and their effects.
|
||||||
|
|
||||||
|
|
||||||
|
| directive | end directive | subdirectives | purpose | can affect (as of 2018/06)
|
||||||
|
|:------------------|:--------------------|:----------------|:-------------------------------------------------------------------|:---------------------------------------------
|
||||||
|
| [`account`] | | any text | declare an account name & optional account code | account code: balance reports (except `balance` single-column mode) <!-- all entries in all files -->
|
||||||
|
| [`alias`] | `end aliases` | | rewrite account names | following inline/included entries until end of current file or end directive
|
||||||
|
| [`apply account`] | `end apply account` | | prepend a common parent to account names | following inline/included entries until end of current file or end directive
|
||||||
|
| [`comment`] | `end comment` | | ignore part of journal | following inline/included entries until end of current file or end directive
|
||||||
|
| [`commodity`] | | `format` | declare a commodity and its number notation & display style | number notation: following entries in that commodity in all files; <br>display style: amounts of that commodity in reports
|
||||||
|
| [`D`] | | | declare a commodity, number notation & display style for commodityless amounts | commodity: all commodityless entries in all files; <br>number notation: following commodityless entries and entries in that commodity in all files; <br>display style: amounts of that commodity in reports
|
||||||
|
| [`include`] | | | include entries/directives from another file | what the included directives affect
|
||||||
|
| [`P`] | | | declare a market price for a commodity | amounts of that commodity in reports, when -V is used
|
||||||
|
| [`Y`] | | | declare a year for yearless dates | following inline/included entries until end of current file
|
||||||
|
|
||||||
|
[`account`]: http://hledger.org/journal.html#declaring-accounts
|
||||||
|
[`alias`]: http://hledger.org/journal.html#rewriting-accounts
|
||||||
|
[`apply account`]: http://hledger.org/journal.html#default-parent-account
|
||||||
|
[`comment`]: http://hledger.org/journal.html#comment-blocks
|
||||||
|
[`commodity`]: http://hledger.org/journal.html#declaring-commodities
|
||||||
|
[`D`]: http://hledger.org/journal.html#default-commodity
|
||||||
|
[`include`]: http://hledger.org/journal.html#including-other-files
|
||||||
|
[`P`]: http://hledger.org/journal.html#market-prices
|
||||||
|
[`Y`]: http://hledger.org/journal.html#default-year
|
||||||
|
|
||||||
|
#### Definitions:
|
||||||
|
|
||||||
|
|||
|
||||||
|
|:----------------|:--------------------------------------------------------------------------------------------------------------------
|
||||||
|
| subdirective | optional indented directive or unparsed text lines immediately following a parent directive
|
||||||
|
| account code | numeric code influencing account display order in most balance reports
|
||||||
|
| number notation | how to interpret numbers when parsing journal entries (the identity of the decimal separator character). Currently each commodity can have its own notation, even in the same file.
|
||||||
|
| display style | how to display amounts of a commodity in reports (symbol side and spacing, digit groups, decimal separator, decimal places)
|
||||||
|
| directive scope | which entries and (when there are multiple files) which files are affected by a directive
|
||||||
|
|
||||||
|
<!-- | **entries affected:** | -->
|
||||||
|
<!-- | following | subsequent entries in the file/parse stream -->
|
||||||
|
<!-- | delimited | subsequent entries, until an optional end directive -->
|
||||||
|
<!-- | all | all preceding and following entries -->
|
||||||
|
<!-- | **files affected:** | -->
|
||||||
|
<!-- | current | affects current file only -->
|
||||||
|
<!-- | children | affects current file and files included by it -->
|
||||||
|
<!-- | siblings | affects current file, included files, and other same-level files, but not higher-level files -->
|
||||||
|
<!-- | all | affects all files -->
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user