From b945147246b48f4e53d8155aa740a0bd1b92a440 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Tue, 27 Dec 2022 13:12:49 -1000 Subject: [PATCH] ;doc: journal: directives tweak --- hledger/hledger.m4.md | 65 +++++++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 30 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 2db7c37c1..6146eb25d 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1703,22 +1703,23 @@ And here is what each directive does, and which files and journal entries (trans -| directive | what it does | ends at file end? | -|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------| -| **[`account`]** | Declares an account, for [checking](#check) all entries in all files;
and its [display order](#account-display-order) and [type](#declaring-account-types).
Subdirectives: any text, ignored. | N | -| **[`alias`]** | Rewrites account names, in following entries until end of current file or [`end aliases`].
Command line equivalent: [`--alias`] | Y | -| **[`comment`]** | Ignores part of the journal file, until end of current file or `end comment`. | Y | -| **[`commodity`]** | Declares up to four things:
1. a commodity symbol, for checking all amounts in all files
2. the decimal mark for parsing amounts of this commodity, in the following entries until end of current file (if there is no `decimal-mark` directive)
3. and the display style for amounts of this commodity
4. which is also the precision to use for balanced-transaction checking in this commodity.
Takes precedence over `D`.
Subdirectives: `format` (Ledger-compatible syntax).
Command line equivalent: [`-c/--commodity-style`](#commodity-styles) | N,
Y,
N,
N | -| **[`decimal-mark`]** | Declares the decimal mark, for parsing amounts of all commodities in following entries until next `decimal-mark` or end of current file. Included files can override. Takes precedence over `commodity` and `D`. | Y | -| **[`include`]** | Includes entries and directives from another file, as if they were written inline.
Command line alternative: multiple [`-f/--file`](#multiple-files) | N | -| **[`payee`]** | Declares a payee name, for checking all entries in all files. | N | -| **[`P`]** | Declares the market price of a commodity on some date, for [value reports](#valuation). | N | -| **[`~`]** (tilde) | Declares a periodic transaction rule that generates future transactions with `--forecast` and budget goals with `balance --budget`. | N | -| **[`=`]** (equals) | Declares an auto posting rule that generates extra postings on matched transactions with `--auto`, in current, parent, and child files (but not sibling files, see [#1212](https://github.com/simonmichael/hledger/issues/1212)). | partly | -| Other syntax: | | | -| **[`apply account`]** | Prepends a common parent account to all account names, in following entries until end of current file or `end apply account`. | Y | -| **[`D`]** | Sets a default commodity to use for no-symbol amounts;
and, if there is no `commodity` directive for this commodity: its decimal mark, balancing precision, and display style, as above. | Y,
Y,
N,
N | -| **[`Y`]** | Sets a default year to use for any yearless dates, in following entries until end of current file. | Y | +| directive | what it does | ends at file end? | +|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------| +| **[`account`]** | Declares an account, for [checking](#check) all entries in all files;
and its [display order](#account-display-order) and [type](#declaring-account-types).
Subdirectives: any text, ignored. | N | +| **[`alias`]** | Rewrites account names, in following entries until end of current file or [`end aliases`].
Command line equivalent: [`--alias`] | Y | +| **[`comment`]** | Ignores part of the journal file, until end of current file or `end comment`. | Y | +| **[`commodity`]** | Declares up to four things:
1. a commodity symbol, for checking all amounts in all files
2. the decimal mark for parsing amounts of this commodity, in the following entries until end of current file (if there is no `decimal-mark` directive)
3. and the display style for amounts of this commodity
4. which is also the precision to use for balanced-transaction checking in this commodity.
Takes precedence over `D`.
Subdirectives: `format` (Ledger-compatible syntax).
Command line equivalent: [`-c/--commodity-style`](#commodity-styles) | N,
Y,
N,
N | +| **[`decimal-mark`]** | Declares the decimal mark, for parsing amounts of all commodities in following entries until next `decimal-mark` or end of current file. Included files can override. Takes precedence over `commodity` and `D`. | Y | +| **[`include`]** | Includes entries and directives from another file, as if they were written inline.
Command line alternative: multiple [`-f/--file`](#multiple-files) | N | +| **[`payee`]** | Declares a payee name, for checking all entries in all files. | N | +| **[`P`]** | Declares the market price of a commodity on some date, for [value reports](#valuation). | N | +| **[`~`]** (tilde) | Declares a periodic transaction rule that generates future transactions with `--forecast` and budget goals with `balance --budget`. | N | +| Other syntax: | | | +| **[`apply account`]** | Prepends a common parent account to all account names, in following entries until end of current file or `end apply account`. | Y | +| **[`D`]** | Sets a default commodity to use for no-symbol amounts;
and, if there is no `commodity` directive for this commodity: its decimal mark, balancing precision, and display style, as above. | Y,
Y,
N,
N | +| **[`Y`]** | Sets a default year to use for any yearless dates, in following entries until end of current file. | Y | +| **[`=`]** (equals) | Declares an auto posting rule that generates extra postings on matched transactions with `--auto`, in current, parent, and child files (but not sibling files, see [#1212](https://github.com/simonmichael/hledger/issues/1212)). | partly | +| **[Other Ledger directives]** | Other directives from Ledger's file format are accepted but ignored. | | [`=`]: #auto-postings [`D`]: #default-commodity @@ -1734,6 +1735,7 @@ And here is what each directive does, and which files and journal entries (trans [`include`]: #including-files [`payee`]: #payees [`~`]: #periodic-transactions +[Other Ledger directives]: #other-ledger-directives ### Directives and multiple files @@ -2184,7 +2186,7 @@ commodity INR format INR 1,00,00,000.00 ``` -Any indented subdirectives other than `format` are currently ignored. +Other indented subdirectives are currently ignored. Remember that if the commodity symbol contains spaces, numbers, or punctuation, it must be enclosed in double quotes (cf [Commodity](#commodity)). @@ -2740,29 +2742,32 @@ makes your financial data less portable and less trustworthy in an audit. ### Other Ledger directives -These other Ledger directives are currently ignored: +These other Ledger directives are currently accepted but ignored. +This allows hledger to read more Ledger files, +but be aware that hledger's reports may differ from Ledger's if you use these. ```journal apply fixed COMM AMT -apply tag TAG -assert EXPR -A ACCT -bucket ACCT -capture ACCT REGEX -check EXPR -define VAR=EXPR +apply tag TAG +assert EXPR +bucket / A ACCT +capture ACCT REGEX +check EXPR +define VAR=EXPR end apply fixed end apply tag end apply year end tag -expr EXPR -tag NAME -value EXPR +eval / expr EXPR python -eval EXPR ---command-line-flag + PYTHONCODE +tag NAME +value EXPR +--command-line-flags ``` +See also for a detailed hledger/Ledger syntax comparison. + # CSV hledger can read [CSV](http://en.wikipedia.org/wiki/Comma-separated_values) files