From bc9375e4e567c1a1ddc8edd96397c16217cd9c0e Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 20 Jun 2018 19:41:28 -0700 Subject: [PATCH] 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. --- hledger-lib/hledger_journal.m4.md | 79 ++++++++++++++++---- hledger-lib/hledger_journal_directives.m4.md | 55 ++++++++++++++ 2 files changed, 118 insertions(+), 16 deletions(-) create mode 100644 hledger-lib/hledger_journal_directives.m4.md diff --git a/hledger-lib/hledger_journal.m4.md b/hledger-lib/hledger_journal.m4.md index c5fc9cd02..b555a2fca 100644 --- a/hledger-lib/hledger_journal.m4.md +++ b/hledger-lib/hledger_journal.m4.md @@ -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, 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: + + + + -- some form a begin/end pair, and affect the enclosed journal entries (and included files):\ - `alias` & `end aliases`; `comment` & `end comment` -- some affect the subsequent journal entries (and included files) in the current file:\ - `alias` or `comment` without an end directive, `Y` -- some affect all journal entries (and included files) anywhere in the current file:\ - `account`, `commodity`, `D`, `P`. +| 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) +| [`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;
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;
number notation: following commodityless entries and entries in that commodity in all files;
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 -child (included) files, but not sibling or parent (including) files. -This is by design, for simplicity and predictability of reports, but -it can be surprising at times. Eg, in: +[`account`]: #declaring-accounts +[`alias`]: #rewriting-accounts +[`apply account`]: #default-parent-account +[`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 + + + + + + + + + + + +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. + ### Comment blocks diff --git a/hledger-lib/hledger_journal_directives.m4.md b/hledger-lib/hledger_journal_directives.m4.md new file mode 100644 index 000000000..58dea957f --- /dev/null +++ b/hledger-lib/hledger_journal_directives.m4.md @@ -0,0 +1,55 @@ + + + + + +### 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) +| [`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;
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;
number notation: following commodityless entries and entries in that commodity in all files;
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 + + + + + + + + + + +