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

;doc: csv: clarify posting field rules, note a limitation

Browse Source
This commit is contained in:
Simon Michael 2020-03-10 13:39:47 -07:00
parent ababccd8e0
commit 8e04bd11fe
4 changed files with 223 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
hledger-lib/hledger_csv.5
View File

@ -487,34 +487,53 @@ hledger\[aq]s journal format.
\f[C]description\f[R], \f[C]comment\f[R] can be used to form the \f[C]description\f[R], \f[C]comment\f[R] can be used to form the
transaction\[aq]s first line. transaction\[aq]s first line.
.SS Posting field names .SS Posting field names
.SS account
.PP
\f[C]accountN\f[R], where N is 1 to 9, causes a posting to be generated,
with that account name.
.PP .PP
\f[C]accountN\f[R], where N is 1 to 9, generates a posting, with that
account name.
Most often there are two postings, so you\[aq]ll want to set Most often there are two postings, so you\[aq]ll want to set
\f[C]account1\f[R] and \f[C]account2\f[R]. \f[C]account1\f[R] and \f[C]account2\f[R].
If a posting\[aq]s account name is left unset but its amount is set, a .PP
default account name will be chosen (like expenses:unknown or If a posting\[aq]s account name is left unset but its amount is set (see
income:unknown). below), a default account name will be chosen (like
\[dq]expenses:unknown\[dq] or \[dq]income:unknown\[dq]).
.SS amount
.PP .PP
\f[C]amountN\f[R] sets posting N\[aq]s amount. \f[C]amountN\f[R] sets posting N\[aq]s amount.
Or, \f[C]amount\f[R] with no N sets posting 1\[aq]s.
If the CSV has debits and credits in separate fields, use
\f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] instead.
Or \f[C]amount-in\f[R] and \f[C]amount-out\f[R] with no N for posting 1.
.PP .PP
For convenience and backwards compatibility, if you set the amount of Or if the CSV has debits and credits in two separate fields, use
posting 1 only, a second posting with the negative amount will be \f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] instead.
generated automatically. .PP
Some aliases and special behaviour exist to support older CSV rules
(before hledger 1.17):
.IP \[bu] 2
if \f[C]amount1\f[R] is the only posting amount assigned, then a second
posting with the balancing amount will be generated automatically.
(Unless the account name is parenthesised indicating an unbalanced (Unless the account name is parenthesised indicating an unbalanced
posting.) posting.)
.IP \[bu] 2
\f[C]amount\f[R] is an alias for \f[C]amount1\f[R]
.IP \[bu] 2
\f[C]amount-in\f[R]/\f[C]amount-out\f[R] are aliases for
\f[C]amount1-in\f[R]/\f[C]amount1-out\f[R]
.PP .PP
If the CSV has the currency symbol in a separate field, you can use This can occasionally get in the way.
\f[C]currencyN\f[R] to prepend it to posting N\[aq]s amount. For example, currently it\[aq]s possible to generate a transaction with
\f[C]currency\f[R] with no N affects ALL postings. a blank amount1, but not one with a blank amount2.
.SS currency
.PP
If the CSV has the currency symbol in a separate field (ie, not part of
the amount field), you can use \f[C]currencyN\f[R] to prepend it to
posting N\[aq]s amount.
Or, \f[C]currency\f[R] affects all postings.
.SS balance
.PP .PP
\f[C]balanceN\f[R] sets a balance assertion amount (or if the posting \f[C]balanceN\f[R] sets a balance assertion amount (or if the posting
amount is left empty, a balance assignment). amount is left empty, a balance assignment).
You may need to adjust this with the \f[C]balance-type\f[R] rule. You may need to adjust this with the \f[C]balance-type\f[R] rule (see
below).
.SS comment
.PP .PP
Finally, \f[C]commentN\f[R] sets a comment on the Nth posting. Finally, \f[C]commentN\f[R] sets a comment on the Nth posting.
Comments can also contain tags, as usual. Comments can also contain tags, as usual.

177
hledger-lib/hledger_csv.info
View File

@ -451,31 +451,82 @@ File: hledger_csv.info, Node: Posting field names, Prev: Transaction field nam
2.2.2 Posting field names 2.2.2 Posting field names
------------------------- -------------------------
'accountN', where N is 1 to 9, generates a posting, with that account * Menu:
name. Most often there are two postings, so you'll want to set
'account1' and 'account2'. If a posting's account name is left unset
but its amount is set, a default account name will be chosen (like
expenses:unknown or income:unknown).
'amountN' sets posting N's amount. Or, 'amount' with no N sets * account::
posting 1's. If the CSV has debits and credits in separate fields, use * amount::
'amountN-in' and 'amountN-out' instead. Or 'amount-in' and 'amount-out' * currency::
with no N for posting 1. * balance::
* comment::
For convenience and backwards compatibility, if you set the amount of 
posting 1 only, a second posting with the negative amount will be File: hledger_csv.info, Node: account, Next: amount, Up: Posting field names
generated automatically. (Unless the account name is parenthesised
indicating an unbalanced posting.)
If the CSV has the currency symbol in a separate field, you can use 2.2.2.1 account
'currencyN' to prepend it to posting N's amount. 'currency' with no N ...............
affects ALL postings.
'balanceN' sets a balance assertion amount (or if the posting amount 'accountN', where N is 1 to 9, causes a posting to be generated, with
is left empty, a balance assignment). You may need to adjust this with that account name.
the 'balance-type' rule.
Finally, 'commentN' sets a comment on the Nth posting. Comments can Most often there are two postings, so you'll want to set 'account1'
and 'account2'.
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").

File: hledger_csv.info, Node: amount, Next: currency, Prev: account, Up: Posting field names
2.2.2.2 amount
..............
'amountN' sets posting N's amount.
Or if the CSV has debits and credits in two separate fields, use
'amountN-in' and 'amountN-out' instead.
Some aliases and special behaviour exist to support older CSV rules
(before hledger 1.17):
* if 'amount1' is the only posting amount assigned, then a second
posting with the balancing amount will be generated automatically.
(Unless the account name is parenthesised indicating an unbalanced
posting.)
* 'amount' is an alias for 'amount1'
* 'amount-in'/'amount-out' are aliases for 'amount1-in'/'amount1-out'
This can occasionally get in the way. For example, currently it's
possible to generate a transaction with a blank amount1, but not one
with a blank amount2.

File: hledger_csv.info, Node: currency, Next: balance, Prev: amount, Up: Posting field names
2.2.2.3 currency
................
If the CSV has the currency symbol in a separate field (ie, not part of
the amount field), you can use 'currencyN' to prepend it to posting N's
amount. Or, 'currency' affects all postings.

File: hledger_csv.info, Node: balance, Next: comment, Prev: currency, Up: Posting field names
2.2.2.4 balance
...............
'balanceN' sets a balance assertion amount (or if the posting amount is
left empty, a balance assignment). You may need to adjust this with the
'balance-type' rule (see below).

File: hledger_csv.info, Node: comment, Prev: balance, Up: Posting field names
2.2.2.5 comment
...............
Finally, 'commentN' sets a comment on the Nth posting. Comments can
also contain tags, as usual. also contain tags, as usual.
See TIPS below for more about setting amounts and currency. See TIPS below for more about setting amounts and currency.
@ -991,44 +1042,54 @@ Node: Transaction field names16367
Ref: #transaction-field-names16527 Ref: #transaction-field-names16527
Node: Posting field names16638 Node: Posting field names16638
Ref: #posting-field-names16790 Ref: #posting-field-names16790
Node: field assignment18081 Node: account16860
Ref: #field-assignment18224 Ref: #account16976
Node: separator19042 Node: amount17320
Ref: #separator19171 Ref: #amount17451
Node: if19582 Node: currency18195
Ref: #if19684 Ref: #currency18330
Node: end21603 Node: balance18521
Ref: #end21709 Ref: #balance18655
Node: date-format21933 Node: comment18834
Ref: #date-format22065 Ref: #comment18951
Node: newest-first22814 Node: field assignment19114
Ref: #newest-first22952 Ref: #field-assignment19257
Node: include23635 Node: separator20075
Ref: #include23764 Ref: #separator20204
Node: balance-type24208 Node: if20615
Ref: #balance-type24328 Ref: #if20717
Node: TIPS25028 Node: end22636
Ref: #tips25110 Ref: #end22742
Node: Rapid feedback25366 Node: date-format22966
Ref: #rapid-feedback25483 Ref: #date-format23098
Node: Valid CSV25943 Node: newest-first23847
Ref: #valid-csv26073 Ref: #newest-first23985
Node: File Extension26265 Node: include24668
Ref: #file-extension26417 Ref: #include24797
Node: Reading multiple CSV files26827 Node: balance-type25241
Ref: #reading-multiple-csv-files27012 Ref: #balance-type25361
Node: Valid transactions27253 Node: TIPS26061
Ref: #valid-transactions27431 Ref: #tips26143
Node: Deduplicating importing28059 Node: Rapid feedback26399
Ref: #deduplicating-importing28238 Ref: #rapid-feedback26516
Node: Setting amounts29271 Node: Valid CSV26976
Ref: #setting-amounts29440 Ref: #valid-csv27106
Node: Setting currency/commodity30426 Node: File Extension27298
Ref: #setting-currencycommodity30618 Ref: #file-extension27450
Node: Referencing other fields31421 Node: Reading multiple CSV files27860
Ref: #referencing-other-fields31621 Ref: #reading-multiple-csv-files28045
Node: How CSV rules are evaluated32518 Node: Valid transactions28286
Ref: #how-csv-rules-are-evaluated32691 Ref: #valid-transactions28464
Node: Deduplicating importing29092
Ref: #deduplicating-importing29271
Node: Setting amounts30304
Ref: #setting-amounts30473
Node: Setting currency/commodity31459
Ref: #setting-currencycommodity31651
Node: Referencing other fields32454
Ref: #referencing-other-fields32654
Node: How CSV rules are evaluated33551
Ref: #how-csv-rules-are-evaluated33724
 
End Tag Table End Tag Table

50
hledger-lib/hledger_csv.m4.md
View File

@ -412,30 +412,46 @@ For more about the transaction parts they refer to, see the manual for hledger's
### Posting field names ### Posting field names
`accountN`, where N is 1 to 9, generates a #### account
[posting](journal.html#postings), with that account name.
`accountN`, where N is 1 to 9, causes a [posting](journal.html#postings) to be generated,
with that account name.
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`.
If a posting's account name is left unset but its amount is set,
a default account name will be chosen (like expenses:unknown or income:unknown).
`amountN` sets posting N's amount. Or, `amount` with no N sets posting If a posting's account name is left unset but its amount is set (see below),
1's. If the CSV has debits and credits in separate fields, use a default account name will be chosen (like "expenses:unknown" or "income:unknown").
`amountN-in` and `amountN-out` instead. Or `amount-in` and
`amount-out` with no N for posting 1.
For convenience and backwards compatibility, if you set the amount of #### amount
posting 1 only, a second posting with the negative amount will be
generated automatically.
(Unless the account name is parenthesised indicating an
[unbalanced posting](journal.html#virtual-postings).)
If the CSV has the currency symbol in a separate field, you can use `amountN` sets posting N's amount.
`currencyN` to prepend it to posting N's amount. `currency` with no N
affects ALL postings. Or if the CSV has debits and credits in two separate fields, use `amountN-in` and `amountN-out` instead.
Some aliases and special behaviour exist to support older CSV rules (before hledger 1.17):
- if `amount1` is the only posting amount assigned, then a second posting
with the balancing amount will be generated automatically.
(Unless the account name is parenthesised indicating an [unbalanced posting](journal.html#virtual-postings).)
- `amount` is an alias for `amount1`
- `amount-in`/`amount-out` are aliases for `amount1-in`/`amount1-out`
This can occasionally get in the way. For example, currently it's possible to generate
a transaction with a blank amount1, but not one with a blank amount2.
#### currency
If the CSV has the currency symbol in a separate field (ie, not part
of the amount field), you can use `currencyN` to prepend it to posting
N's amount. Or, `currency` affects all postings.
#### balance
`balanceN` sets a [balance assertion](journal.html#balance-assertions) amount `balanceN` sets a [balance assertion](journal.html#balance-assertions) amount
(or if the posting amount is left empty, a [balance assignment](journal.html#balance-assignments)). (or if the posting amount is left empty, a [balance assignment](journal.html#balance-assignments)).
You may need to adjust this with the [`balance-type` rule](#balance-type). You may need to adjust this with the [`balance-type` rule](#balance-type) (see below).
#### comment
Finally, `commentN` sets a [comment](journal.html#comments) on the Nth posting. Finally, `commentN` sets a [comment](journal.html#comments) on the Nth posting.
Comments can also contain [tags](journal.html#tags), as usual. Comments can also contain [tags](journal.html#tags), as usual.

53
hledger-lib/hledger_csv.txt
View File

@ -376,30 +376,49 @@ CSV RULES
transaction's first line. transaction's first line.
Posting field names Posting field names
accountN, where N is 1 to 9, generates a posting, with that account account
name. Most often there are two postings, so you'll want to set ac- accountN, where N is 1 to 9, causes a posting to be generated, with
count1 and account2. If a posting's account name is left unset but its that account name.
amount is set, a default account name will be chosen (like expenses:un-
known or income:unknown).
amountN sets posting N's amount. Or, amount with no N sets posting Most often there are two postings, so you'll want to set account1 and
1's. If the CSV has debits and credits in separate fields, use account2.
amountN-in and amountN-out instead. Or amount-in and amount-out with
no N for posting 1.
For convenience and backwards compatibility, if you set the amount of If a posting's account name is left unset but its amount is set (see
posting 1 only, a second posting with the negative amount will be gen- below), a default account name will be chosen (like "expenses:unknown"
erated automatically. (Unless the account name is parenthesised indi- or "income:unknown").
cating an unbalanced posting.)
If the CSV has the currency symbol in a separate field, you can use amount
currencyN to prepend it to posting N's amount. currency with no N af- amountN sets posting N's amount.
fects ALL postings.
Or if the CSV has debits and credits in two separate fields, use
amountN-in and amountN-out instead.
Some aliases and special behaviour exist to support older CSV rules
(before hledger 1.17):
o if amount1 is the only posting amount assigned, then a second posting
with the balancing amount will be generated automatically. (Unless
the account name is parenthesised indicating an unbalanced posting.)
o amount is an alias for amount1
o amount-in/amount-out are aliases for amount1-in/amount1-out
This can occasionally get in the way. For example, currently it's pos-
sible to generate a transaction with a blank amount1, but not one with
a blank amount2.
currency
If the CSV has the currency symbol in a separate field (ie, not part of
the amount field), you can use currencyN to prepend it to posting N's
amount. Or, currency affects all postings.
balance
balanceN sets a balance assertion amount (or if the posting amount is balanceN sets a balance assertion amount (or if the posting amount is
left empty, a balance assignment). You may need to adjust this with left empty, a balance assignment). You may need to adjust this with
the balance-type rule. the balance-type rule (see below).
comment
Finally, commentN sets a comment on the Nth posting. Comments can also Finally, commentN sets a comment on the Nth posting. Comments can also
contain tags, as usual. contain tags, as usual.