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

;doc:journal: rewrite the Tags section

Browse Source
This commit is contained in:
Simon Michael 2024-11-09 13:10:27 -10:00
parent 1ad9fbb4a8
commit 21d8044bcf
1 changed files with 56 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
hledger/hledger.m4.md
View File

@ -1826,99 +1826,93 @@ the directives' placement might be important - see [`commodity` directive](#comm
## Tags ## Tags
<!-- same section name as Commands > tags, if reordering these update all #tags[-1] links --> <!-- Note: same section name as Commands > tags; that one will have anchor #tags-1. If reordering these, update all #tags[-1] links. -->
Tags are a way to add extra labels or data fields 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. They are usually a word or hyphenated word, immediately followed by a full colon,
written within the [comment](#account-comments) of a transaction, a posting, or an `account` directive.
(Yes, storing data in comments is slightly weird!)
A tag is a word, optionally hyphenated, immediately followed by a full colon, You can write each tag on its own comment line, or multiple tags on one line, separated by commas.
in the [comment](#account-comments) of a transaction, a posting, or an account directive. Tags can also have a value, which is any text after the colon until the next comma or end of line, excluding surrounding whitespace.
Eg: `2024-01-01 a transaction ; foo:` (hledger tag values can't contain commas.)
Note this is an exception to the usual rule that things in comments are ignored. If the same tag name appears multiple times in a comment, each name:value pair is preserved.
You can write multiple tags on one line, separated by comma. An example: in this journal there are six tags, one of them with a value:
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:
account expenses:food
2017/1/16 bought groceries ; transactiontag-1: 2017/1/16 bought groceries ; transactiontag:
; transactiontag-2: ; transactiontag2:
assets:checking $-1 assets:checking $-1
expenses:food $1 ; postingtag:, another-posting-tag: ; posting-tag-1:, (belongs to the posting above)
expenses:food $1 ; posting-tag-2:, posting-tag-3: with a value
``` ```
Postings also inherit tags from their transaction and their account. ### Querying with tags
And transactions also acquire tags from their postings (and postings' accounts).
So in the example above, the expenses posting effectively has all five tags Tags are most often used to select a subset of data; you can match tagged things with `tag:` [queries](#queries) (discussed below).
(by inheriting from the account and transaction),
and the transaction also has all five tags (by acquiring from the expenses posting). When querying for tag names or values, note that postings inherit tags from their transaction and from their account,
and transactions acquire tags from their postings. So in the example above,
- the assets:checking posting effectively has four tags (one of its own, one from the account, two from the transaction)
- the expenses:food posting effectively has four tags (two of its own, two from the transaction)
- the transaction effectively has all six tags (two of its own, and two from each posting)
### Displaying tags
You can use the [`tags` command](#tags-1) to list tag names or values.
The [`print` command](#print) also shows tags.
You can use [--pivot](#pivoting) to display tag values in other reports, in various ways (eg appended to account names, like pseudo subaccounts).
### When to use tags ?
Tags provide more dimensions of categorisation, complementing accounts and transaction descriptions.
When to use each of these is somewhat a matter of taste.
Accounts have the most built-in support, and regex queries on descriptions are also quite powerful. So you may not need tags at all.
But if you want to track multiple cross-cutting categories, they can be a good fit.
For example, you could tag trip-related transactions with `trip: YEAR:PLACE`, without disturbing your usual account categories.
### Tag names ### Tag names
Most non-whitespace characters are allowed in tag names. Eg `😀:` is a valid tag. What is allowed in a tag name ? Currently, most non-whitespace characters. Eg `😀:` is a valid tag.
You can list the tag names used in your journal with the [tags](#tags) command:\ For extra error checking, you can declare valid tag names with the [`tag` directive](#tag-directive),
`hledger tags [NAMEREGEX]` and then enforce these with the [`check` command](#check).
In commands which use a [query](#queries), you can match by tag name. Eg:\ But note that tags are detected quite loosely at present, sometimes where you didn't intend them.
`hledger print tag:NAMEREGEX` Eg `; see https://foo.com` contains a `https` tag with value `//foo.com`.
You can declare valid tag names with the [tag directive](#tag-directive) and then check them with the [check](#check) command.
### Special tags ### Special tags
Some tag names have special significance to hledger. Some tag names have special significance to hledger. They are explained elsewhere, but here's a quick reference:
There's not much harm in using them yourself, but some could produce an error message, particularly the `date:` and `type:` tags.
They are explained elsewhere, but here is a quick list for reference:
<!-- keep synced with JournalChecks.hs --> <!-- keep synced with JournalChecks.hs -->
Tags you can set to influence hledger's behaviour:
``` ```
type -- declares an account's type
date -- overrides a posting's date date -- overrides a posting's date
date2 -- overrides a posting's secondary date date2 -- overrides a posting's secondary date
type -- declares an account's type
```
Tags hledger adds to indicate generated data (either always, or when `--verbose-tags` is used):
```
t -- appears on postings generated by timedot letters
assert -- appears on txns generated by close --assert assert -- appears on txns generated by close --assert
retain -- appears on txns generated by close --retain retain -- appears on txns generated by close --retain
start -- appears on txns generated by close --migrate/--close/--open/--assign start -- appears on txns generated by close --migrate/--close/--open/--assign
t -- appears on postings generated from timedot letters
generated-transaction -- appears on txns generated by a periodic rule generated-transaction -- appears on txns generated by a periodic rule
modified-transaction -- appears on txns which have had auto postings added modified-transaction -- appears on txns which have had auto postings added
generated-posting -- appears on generated postings generated-posting -- appears on generated postings
cost-posting -- marks postings which have a cost, or could have a cost, cost-posting -- appears on postings which have (or could have) a cost,
that's equivalent to nearby conversion postings and which have equivalent conversion postings in the transaction
conversion-posting -- marks postings which are to a V/Conversion account conversion-posting -- appears on postings which are to a V/Conversion account
and whose amount is equivalent to a nearby cost posting and which have an equivalent cost posting in the transaction
``` ```
The `*-transaction` and `*-posting` tags above are also added as hidden tags (with a `_` prefix). The second group above (generated-transaction, etc.) are normally hidden, with a `_` prefix added.
Hidden tags are not displayed, but can be relied on for querying. This means `print` doesn't show them by default; but you can still use them in queries.
You can add the `--verbose-tags` flag to make them visible, which can be useful for troubleshooting.
### Tag values
Tags can have a value, which is any text after the colon up until a comma or end of line, 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.
Eg in the following posting, the three tags' values are "value 1", "value 2", and "" (empty) respectively:
```journal
expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz
```
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.
It is not possible to override a previous tag's value or remove a tag.
You can list all the values used for a particular tag in the journal with\
`hledger tags TAGNAME --values`
You can match on tag values with a query like `tag:NAMEREGEX=VALUEREGEX`
## Directives ## Directives