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
transaction\[aq]s first line.
.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
\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
\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
default account name will be chosen (like expenses:unknown or
income:unknown).
.PP
If a posting\[aq]s account name is left unset but its amount is set (see
below), a default account name will be chosen (like
\[dq]expenses:unknown\[dq] or \[dq]income:unknown\[dq]).
.SS amount
.PP
\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
For convenience and backwards compatibility, if you set the amount of
posting 1 only, a second posting with the negative amount will be
generated automatically.
Or if the CSV has debits and credits in two separate fields, use
\f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] instead.
.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
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
If the CSV has the currency symbol in a separate field, you can use
\f[C]currencyN\f[R] to prepend it to posting N\[aq]s amount.
\f[C]currency\f[R] with no N affects ALL postings.
This can occasionally get in the way.
For example, currently it\[aq]s possible to generate a transaction with
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
\f[C]balanceN\f[R] sets a balance assertion amount (or if the posting
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
Finally, \f[C]commentN\f[R] sets a comment on the Nth posting.
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
-------------------------
'accountN', where N is 1 to 9, generates a posting, with that account
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).
* Menu:
'amountN' sets posting N's amount. Or, 'amount' with no N sets
posting 1's. If the CSV has debits and credits in separate fields, use
'amountN-in' and 'amountN-out' instead. Or 'amount-in' and 'amount-out'
with no N for posting 1.
* account::
* amount::
* currency::
* 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
generated automatically. (Unless the account name is parenthesised
indicating an unbalanced posting.)

File: hledger_csv.info, Node: account, Next: amount, Up: Posting field names
If the CSV has the currency symbol in a separate field, you can use
'currencyN' to prepend it to posting N's amount. 'currency' with no N
affects ALL postings.
2.2.2.1 account
...............
'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.
'accountN', where N is 1 to 9, causes a posting to be generated, with
that account name.
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.
See TIPS below for more about setting amounts and currency.
@ -991,44 +1042,54 @@ Node: Transaction field names16367
Ref: #transaction-field-names16527
Node: Posting field names16638
Ref: #posting-field-names16790
Node: field assignment18081
Ref: #field-assignment18224
Node: separator19042
Ref: #separator19171
Node: if19582
Ref: #if19684
Node: end21603
Ref: #end21709
Node: date-format21933
Ref: #date-format22065
Node: newest-first22814
Ref: #newest-first22952
Node: include23635
Ref: #include23764
Node: balance-type24208
Ref: #balance-type24328
Node: TIPS25028
Ref: #tips25110
Node: Rapid feedback25366
Ref: #rapid-feedback25483
Node: Valid CSV25943
Ref: #valid-csv26073
Node: File Extension26265
Ref: #file-extension26417
Node: Reading multiple CSV files26827
Ref: #reading-multiple-csv-files27012
Node: Valid transactions27253
Ref: #valid-transactions27431
Node: Deduplicating importing28059
Ref: #deduplicating-importing28238
Node: Setting amounts29271
Ref: #setting-amounts29440
Node: Setting currency/commodity30426
Ref: #setting-currencycommodity30618
Node: Referencing other fields31421
Ref: #referencing-other-fields31621
Node: How CSV rules are evaluated32518
Ref: #how-csv-rules-are-evaluated32691
Node: account16860
Ref: #account16976
Node: amount17320
Ref: #amount17451
Node: currency18195
Ref: #currency18330
Node: balance18521
Ref: #balance18655
Node: comment18834
Ref: #comment18951
Node: field assignment19114
Ref: #field-assignment19257
Node: separator20075
Ref: #separator20204
Node: if20615
Ref: #if20717
Node: end22636
Ref: #end22742
Node: date-format22966
Ref: #date-format23098
Node: newest-first23847
Ref: #newest-first23985
Node: include24668
Ref: #include24797
Node: balance-type25241
Ref: #balance-type25361
Node: TIPS26061
Ref: #tips26143
Node: Rapid feedback26399
Ref: #rapid-feedback26516
Node: Valid CSV26976
Ref: #valid-csv27106
Node: File Extension27298
Ref: #file-extension27450
Node: Reading multiple CSV files27860
Ref: #reading-multiple-csv-files28045
Node: Valid transactions28286
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

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
`accountN`, where N is 1 to 9, generates a
[posting](journal.html#postings), with that account name.
#### account
`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`.
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
1's. If the CSV has debits and credits in separate fields, use
`amountN-in` and `amountN-out` instead. Or `amount-in` and
`amount-out` with no N for posting 1.
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").
For convenience and backwards compatibility, if you set the amount of
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).)
#### amount
If the CSV has the currency symbol in a separate field, you can use
`currencyN` to prepend it to posting N's amount. `currency` with no N
affects ALL postings.
`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](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
(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.
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.
Posting field names
accountN, where N is 1 to 9, generates a posting, with that account
name. Most often there are two postings, so you'll want to set ac-
count1 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:un-
known or income:unknown).
account
accountN, where N is 1 to 9, causes a posting to be generated, with
that account name.
amountN sets posting N's amount. Or, amount with no N sets posting
1's. If the CSV has debits and credits in separate fields, use
amountN-in and amountN-out instead. Or amount-in and amount-out with
no N for posting 1.
Most often there are two postings, so you'll want to set account1 and
account2.
For convenience and backwards compatibility, if you set the amount of
posting 1 only, a second posting with the negative amount will be gen-
erated automatically. (Unless the account name is parenthesised indi-
cating an unbalanced posting.)
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").
If the CSV has the currency symbol in a separate field, you can use
currencyN to prepend it to posting N's amount. currency with no N af-
fects ALL postings.
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):
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
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
contain tags, as usual.