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

;doc: csv: rewrite, eliminate fifth-level headings (#1584)

Browse Source 
The hledger manuals shall now use at most four levels of headings,
avoiding loss of structure when viewed in Info format.

CSV fields list, field assignemt, and field names section have
been expanded.

The individual field headings have been renamed ("X field") to avoid
clashing with "Transactions"'s subheadings. They can now be opened
directly in info mode, eg: hledger help 'amount field'
This commit is contained in:
Simon Michael 2021-06-25 23:35:43 -10:00
parent fc364cd8cf
commit 6a1bfe47ba
1 changed files with 124 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

205
hledger/hledger.m4.md
View File

@ -1668,6 +1668,13 @@ With this scheme, you would use
`-U` to see things which will probably hit your bank soon (like uncashed checks), `-U` to see things which will probably hit your bank soon (like uncashed checks),
and no flags to see the most up-to-date state of your finances. and no flags to see the most up-to-date state of your finances.
## Code
After the status mark, but before the description, you can optionally
write a transaction "code", enclosed in parentheses. This is a good
place to record a check number, or some other important transaction id
or reference number.
## Description ## Description
A transaction's description is the rest of the line following the date and status mark (or until a comment begins). A transaction's description is the rest of the line following the date and status mark (or until a comment begins).
@ -3187,20 +3194,21 @@ conditional rules for categorising transactions based on their
descriptions. Here's an overview of the CSV rules; descriptions. Here's an overview of the CSV rules;
these are described more fully below, after the examples: these are described more fully below, after the examples:
| | | | | |
|-------------------------------------------|---------------------------------------------------------| |-------------------------------------------|-----------------------------------------------------------------------|
| [**`skip`**](#skip) | skip one or more header lines or matched CSV records | | [**`skip`**](#skip) | skip one or more header lines or matched CSV records |
| [**`fields`**](#fields) | name CSV fields, assign them to hledger fields | | [**`fields` list**](#fields-list) | name CSV fields, assign them to hledger fields |
| [**field assignment**](#field-assignment) | assign a value to one hledger field, with interpolation | | [**field assignment**](#field-assignment) | assign a value to one hledger field, with interpolation |
| [**`separator`**](#separator) | a custom field separator | | [**Field names**](#field-names) | hledger field names, used in the fields list and field assignments |
| [**`if` block**](#if-block) | apply some rules to CSV records matched by patterns | | [**`separator`**](#separator) | a custom field separator |
| [**`if` block**](#if-block) | apply some rules to CSV records matched by patterns |
| [**`if` table**](#if-table) | apply some rules to CSV records matched by patterns, alternate syntax | | [**`if` table**](#if-table) | apply some rules to CSV records matched by patterns, alternate syntax |
| [**`end`**](#end) | skip the remaining CSV records | | [**`end`**](#end) | skip the remaining CSV records |
| [**`date-format`**](#date-format) | how to parse dates in CSV records | | [**`date-format`**](#date-format) | how to parse dates in CSV records |
| [**`decimal-mark`**](#decimal-mark) | the decimal mark used in CSV amounts, if ambiguous | | [**`decimal-mark`**](#decimal-mark) | the decimal mark used in CSV amounts, if ambiguous |
| [**`newest-first`**](#newest-first) | disambiguate record order when there's only one date | | [**`newest-first`**](#newest-first) | disambiguate record order when there's only one date |
| [**`include`**](#include) | inline another CSV rules file | | [**`include`**](#include) | inline another CSV rules file |
| [**`balance-type`**](#balance-type) | choose which type of balance assignments to use | | [**`balance-type`**](#balance-type) | choose which type of balance assignments to use |
Note, for best error messages when reading CSV files, use a `.csv`, `.tsv` or `.ssv` Note, for best error messages when reading CSV files, use a `.csv`, `.tsv` or `.ssv`
file extension or file prefix - see [File Extension](#file-extension) below. file extension or file prefix - see [File Extension](#file-extension) below.
@ -3530,20 +3538,21 @@ It also has a second purpose: it can be used inside [if blocks](#if-block)
to ignore certain CSV records (described below). to ignore certain CSV records (described below).
### `fields` ### `fields` list
```rules ```rules
fields FIELDNAME1, FIELDNAME2, ... fields FIELDNAME1, FIELDNAME2, ...
``` ```
A fields list (the word "fields" followed by comma-separated field A fields list (the word "fields" followed by comma-separated field
names) is the quick way to assign CSV field values to hledger fields. names) is the quick way to assign CSV field values to hledger fields.
It does two things: (The other way is [field assignments](#field-assignment), see below.)
A fields list does does two things:
1. it names the CSV fields. 1. It names the CSV fields.
This is optional, but can be convenient later for interpolating them. This is optional, but can be convenient later for interpolating them.
2. when you use a standard hledger field name, 2. Whenever you use a standard hledger field name (defined below),
it assigns the CSV value to that part of the hledger transaction. the CSV value is assigned to that part of the hledger transaction.
Here's an example that says Here's an example that says
"use the 1st, 2nd and 4th fields as the transaction's date, description and amount; "use the 1st, 2nd and 4th fields as the transaction's date, description and amount;
@ -3552,27 +3561,89 @@ name the last two fields for later reference; and ignore the others":
fields date, description, , amount, , , somefield, anotherfield fields date, description, , amount, , , somefield, anotherfield
``` ```
Field names may not contain whitespace. Tips:
Fields you don't care about can be left unnamed.
Currently there must be least two items (there must be at least one comma).
Note, always use comma in the fields list, even if your CSV uses - The fields list always use commas, even if your CSV data uses [another separator character](#separator).
[another separator character](#separator). - Currently there must be least two items in the list (at least one comma).
- Field names may not contain spaces. Spaces before/after field names are optional.
- If the CSV contains column headings, it's a good idea to use these, suitably modified, as the basis for your field names (eg lower-cased, with underscores instead of spaces).
- If some heading names match standard hledger fields, but you don't want to set the hledger fields directly, alter those names, eg by appending an underscore.
- Fields you don't care about can be given a dummy name (eg: `_` ), or no name.
Here are the standard hledger field/pseudo-field names. ### field assignment
For more about the transaction parts they refer to, see the manual for hledger's journal format.
#### Transaction field names ```rules
HLEDGERFIELDNAME FIELDVALUE
```
`date`, `date2`, `status`, `code`, `description`, `comment` can be used to form the Field assignments are the more flexible way to assign CSV values to hledger fields.
[transaction's](#transactions) first line. They can be used instead of or in addition to a [fields list](#fields-list) (see above).
#### Posting field names To assign a value to a hledger field, write the field name
(any of the standard hledger field/pseudo-field names, defined below),
a space, followed by a text value on the same line.
This text value may interpolate CSV fields,
referenced by their 1-based position in the CSV record (`%N`),
or by the name they were given in the [fields list](#fields-list) (`%CSVFIELDNAME`).
##### account Some examples:
`accountN`, where N is 1 to 99, causes a [posting](#postings) to be generated, ```rules
with that account name. # set the amount to the 4th CSV field, with " USD" appended
amount %4 USD
# combine three fields to make a comment, containing note: and date: tags
comment note: %somefield - %anotherfield, date: %1
```
Tips:
- Interpolation strips outer whitespace (so a CSV value like `" 1 "`
becomes `1` when interpolated)
([#1051](https://github.com/simonmichael/hledger/issues/1051)).
- See also [Tips](#tips) below.
### Field names
Here are the standard hledger field (and pseudo-field) names, which
you can use in a [fields list](#fields-list) and in [field assignments](#field-assignment).
For more about the transaction parts they refer to, see [Transactions](#transactions).
#### date field
Assigning to `date` sets the [transaction date](#simple-dates).
#### date2 field
`date2` sets the transaction's [secondary date](#secondary-dates), if any.
#### status field
`status` sets the transaction's [status](#status), if any.
#### code field
`code` sets the transaction's [code](#code), if any.
#### description field
`description` sets the transaction's [description](#description), if any.
#### comment field
`comment` sets the transaction's [comment](#comments), if any.
`commentN`, where N is a number, sets the Nth posting's comment.
Tips:
- Only single-line comments can be assigned.
- Comments can contain [tags](#tags), as usual.
#### account field
Assigning to `accountN`, where N is 1 to 99,
sets the account name of the Nth [posting](#postings),
and causes that posting to be generated.
Most often there are two postings, so you'll want to set `account1` and `account2`. Most often there are two postings, so you'll want to set `account1` and `account2`.
Typically `account1` is associated with the CSV file, and is set once with a top-level assignment, Typically `account1` is associated with the CSV file, and is set once with a top-level assignment,
@ -3581,20 +3652,23 @@ while `account2` is set based on each transaction's description, and in conditio
If a posting's account name is left unset but its amount is set (see below), If a posting's account name is left unset but its amount is set (see below),
a default account name will be chosen (like "expenses:unknown" or "income:unknown"). a default account name will be chosen (like "expenses:unknown" or "income:unknown").
##### amount #### amount field
`amountN` sets the Nth posting's amount. `amountN` sets the amount of the Nth posting,
and causes that posting to be generated.
By assigning to `amount1`, `amount2`, ... etc. you can generate up to 99 postings. By assigning to `amount1`, `amount2`, ... etc. you can generate up to 99 postings.
If the CSV uses separate fields for debits and credits (inflows and outflows), you can `amountN-in` and `amountN-out` can be used instead,
use `amountN-in` and `amountN-out` instead. if the CSV uses separate fields for debits and credits (inflows and outflows).
Note hledger assumes both of these fields are unsigned, and will automatically negate the "-out" value. hledger assumes both of these CSV fields are unsigned, and will automatically negate the "-out" value.
If the fields are signed, see ["Setting amounts"](#setting-amounts) below. If they are signed, see ["Setting amounts"](#setting-amounts) below.
There is also an unnumbered form of these names: `amount`, or `amount-in` and `amount-out`. `amount`, or `amount-in` and `amount-out` are a legacy mode,
This is supported to keep pre-hledger-1.17 CSV rules files working (and for occasional convenience). to keep pre-hledger-1.17 CSV rules files working (and for occasional convenience).
It is suitable only for two-posting transactions; it sets both posting 1's and posting 2's amount. They are suitable only for two-posting transactions;
Posting 2's amount will be negated, and also converted to cost if there's a [transaction price](#transaction-prices). they set both posting 1's and posting 2's amount.
Posting 2's amount will be negated, and also converted to cost
if there's a [transaction price](#transaction-prices).
If you have an existing rules file using the unnumbered form, you If you have an existing rules file using the unnumbered form, you
might want to use the numbered form in certain conditional blocks, might want to use the numbered form in certain conditional blocks,
@ -3604,58 +3678,27 @@ posting 1 ignores `amount`/`amount-in`/`amount-out` if any of `amount1`/`amount1
and posting 2 ignores them if any of `amount2`/`amount2-in`/`amount2-out` are assigned, and posting 2 ignores them if any of `amount2`/`amount2-in`/`amount2-out` are assigned,
avoiding conflicts. avoiding conflicts.
#### currency field
##### currency `currency` sets a currency symbol, to be prepended to all postings' amounts.
You can use this if the CSV amounts do not have a currency symbol, eg if it is in a separate column.
If the CSV has the currency symbol in a separate field (ie, not part `currencyN` prepends a currency symbol to just the Nth posting's amount.
of the amount field), you can use `currencyN` to prepend it to posting
N's amount. Or, `currency` with no number affects all postings.
##### balance #### balance field
`balanceN` sets a [balance assertion](#balance-assertions) amount `balanceN` sets a [balance assertion](#balance-assertions) amount
(or if the posting amount is left empty, a [balance assignment](#balance-assignments)) (or if the posting amount is left empty, a [balance assignment](#balance-assignments))
on posting N. on posting N.
Also, for compatibility with hledger <1.17: `balance` is a compatibility spelling for hledger <1.17;
`balance` with no number is equivalent to `balance1`. it is equivalent to `balance1`.
You can adjust the type of assertion/assignment with the You can adjust the type of assertion/assignment with the
[`balance-type` rule](#balance-type) (see below). [`balance-type` rule](#balance-type) (see below).
##### comment See [Tips](#tips) below for more about setting amounts and currency.
Finally, `commentN` sets a [comment](#comments) on the Nth posting.
Comments can also contain [tags](#tags), as usual.
See TIPS below for more about setting amounts and currency.
### field assignment
```rules
HLEDGERFIELDNAME FIELDVALUE
```
Instead of or in addition to a [fields list](#fields), you can use a
"field assignment" rule to set the value of a single hledger field, by
writing its name (any of the standard hledger field names above)
followed by a text value.
The value may contain interpolated CSV fields,
referenced by their 1-based position in the CSV record (`%N`),
or by the name they were given in the fields list (`%CSVFIELDNAME`).
Some examples:
```rules
# set the amount to the 4th CSV field, with " USD" appended
amount %4 USD
# combine three fields to make a comment, containing note: and date: tags
comment note: %somefield - %anotherfield, date: %1
```
Interpolation strips outer whitespace (so a CSV value like `" 1 "`
becomes `1` when interpolated)
([#1051](https://github.com/simonmichael/hledger/issues/1051)).
See TIPS below for more about referencing other fields.
### `separator` ### `separator`