slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc:Tags: improve the Special tags list, and the tags doc generally

Browse Source
This commit is contained in:
Simon Michael 2024-02-17 12:44:55 -10:00
parent baca5f8b54
commit 6103d74b4b
1 changed files with 50 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
hledger/hledger.m4.md
View File

@ -1581,17 +1581,19 @@ except they may contain [tags](#tags), which are not ignored.
<!-- same section name as Commands > tags, if reordering these update all #tags[-1] links --> <!-- same section name as Commands > tags, if reordering these update all #tags[-1] links -->
Tags are a way to add extra labels or labelled data to transactions, postings, or accounts, Tags are a way to add extra labels or data fields to transactions, postings, or accounts,
which you can then [search](#queries) or [pivot](#pivoting) on. which you can then [search](#queries) or [pivot](#pivoting) on.
They are written as a word (optionally hyphenated) immediately followed by a full colon, A tag is a word, optionally hyphenated, immediately followed by a full colon,
in a transaction or posting or account directive's [comment](#account-comments). in the [comment](#account-comments) of a transaction, a posting, or an account directive.
(This is an exception to the usual rule that things in comments are ignored.) Eg: `2024-01-01 a transaction ; foo:`
You can write multiple tags separated by comma, and/or you can add more comment lines Note this is an exception to the usual rule that things in comments are ignored.
and write more tags there.
Here five different tags are recorded: one on the checking account, You can write multiple tags on one line, separated by comma.
two on the transaction, and two on the expenses posting: Or you can write each tag on its own comment line (no comma needed in this case).
For example, here are five different tags:
one on the `assets:checking` account, two on the transaction, and two on the `expenses:food` posting:
```journal ```journal
account assets:checking ; accounttag: account assets:checking ; accounttag:
@ -1602,11 +1604,6 @@ account assets:checking ; accounttag:
expenses:food $1 ; postingtag:, another-posting-tag: expenses:food $1 ; postingtag:, another-posting-tag:
``` ```
You can list tag names with `hledger tags [NAMEREGEX]`,
or match by tag name with a `tag:NAMEREGEX` query.
### Tag inheritance
Postings also inherit tags from their transaction and their account. Postings also inherit tags from their transaction and their account.
And transactions also acquire tags from their postings (and postings' accounts). And transactions also acquire tags from their postings (and postings' accounts).
So in the example above, the expenses posting effectively has all five tags So in the example above, the expenses posting effectively has all five tags
@ -1615,46 +1612,60 @@ and the transaction also has all five tags (by acquiring from the expenses posti
### Tag names ### Tag names
Tag names are currently not very clearly specified; any sequence of non-whitespace characters Most non-whitespace characters are allowed in tag names. Eg `😀:` is a valid tag.
followed by a colon may work.
The following tag names are generated by hledger or have special significance to hledger, You can list the tag names used in your journal with the [tags](#tags) command:\
so you may want to avoid using them yourself: `hledger tags [NAMEREGEX]`
- `balances` -- a balance assertions transaction generated by close In commands which use a [query](#queries), you can match by tag name. Eg:\
- `retain` -- a retain earnings transaction generated by close `hledger print tag:NAMEREGEX`
- `start` -- a opening balances, closing balances or balance assignment transaction generated by close
- `generated-transaction` -- a transaction generated by --forecast
- `generated-posting` -- a posting generated by --auto
- `modified` -- a transaction which has had postings added by --auto
- `type` -- declares an account's type in an account declaration
- `t` -- stores the (user defined, single letter) type of a 15m unit of time parsed from timedot format
Some additional tag names with an underscore prefix are used internally and not displayed You can declare valid tag names with the [tag directive](#tag-directive) and then check them with the [check](#check) command.
in reports (but can be matched by queries):
- `_generated-transaction` ### Special tags
- `_generated-posting`
- `_modified`
- `_conversion-matched`
Some tag names have special significance to hledger,
and could produce an error message if you use them wrongly (the `date:` tag in particular).
They are explained elsewhere, but here is a list for reference:
<!-- keep synced with JournalChecks.hs -->
```
date -- overrides a posting's date
date2 -- overrides a posting's secondary date
type -- declares an account's type
t -- appears on postings generated by timedot letters
assert -- appears on txns generated by close --assert
retain -- appears on txns generated by close --retain
start -- appears on txns generated by close --migrate/--close/--open/--assign
generated-transaction -- with --verbose-tags, appears on generated periodic txns
generated-posting -- with --verbose-tags, appears on generated auto postings
modified -- with --verbose-tags, appears on txns which have had auto postings added
Hidden tags used internally (and queryable):
_generated-transaction -- always exists on generated periodic txns
_generated-posting -- always exists on generated auto postings
_modified -- always exists on txns which have had auto postings added
_conversion-matched -- exists on postings which have been matched with a nearby @/@@ cost notation
```
### Tag values ### Tag values
Tags can have a value, which is any text after the colon up until a comma or end of line Tags can have a value, which is any text after the colon up until a comma or end of line, with surrounding whitespace removed.
(with surrounding whitespace removed). Ending at comma allows us to write multiple tags on one line, but also means that tag values can not contain commas.
Note this means that hledger tag values can not contain commas.
Eg in the following posting, the three tags' values are "value 1", "value 2", and "" (empty) respectively: Eg in the following posting, the three tags' values are "value 1", "value 2", and "" (empty) respectively:
```journal ```journal
expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz
``` ```
Note that tags can be repeated, and are additive rather than overriding: Multiple tags with the same name are additive rather than overriding:
when the same tag name is seen again with a new value, the new name:value pair is added to the tags. when the same tag name is seen again with a new value, the new name:value pair is added to the tags.
(It is not possible to override a tag's value or remove a tag.) It is not possible to override a previous tag's value or remove a tag.
You can list a tag's values with `hledger tags TAGNAME --values`, You can list all the values used for a particular tag in the journal with\
or match by tag value with a `tag:NAMEREGEX=VALUEREGEX` query. `hledger tags TAGNAME --values`
You can match on tag values with a query like `tag:NAMEREGEX=VALUEREGEX`
## Directives ## Directives
@ -2299,7 +2310,7 @@ tag item-id
Any indented subdirectives are currently ignored. Any indented subdirectives are currently ignored.
The ["tags" check](#check) will report an error if any undeclared tag name is used. The ["tags" check](#check) will report an error if any undeclared tag name is used.
It is quite easy to accidentally create a tag through normal use of colons in [comments](#comments]; It is quite easy to accidentally create a tag through normal use of colons in [comments](#comments);
if you want to prevent this, you can declare and check your tags . if you want to prevent this, you can declare and check your tags .
## Periodic transactions ## Periodic transactions