doc: csv: improve CSV conversion tips
[ci skip]
This commit is contained in:
Simon Michael
parent
ce5724fee1
commit
cd589a5e4e
@ -199,39 +199,54 @@ include\ common.rules
|
||||
.PP
|
||||
\f[C]newest\-first\f[]
|
||||
.PP
|
||||
Consider adding this rule if: your CSV records are in reverse
|
||||
Consider adding this rule if all of the following are true: you might be
|
||||
processing just one day of data, your CSV records are in reverse
|
||||
chronological order (newest first), and you care about preserving the
|
||||
order of same\-day transactions, and you might be processing just one
|
||||
day of data.
|
||||
order of same\-day transactions.
|
||||
It usually isn\[aq]t needed, because hledger autodetects the CSV order,
|
||||
but if all the CSV records have the same date it assumes they are oldest
|
||||
first.
|
||||
but when all CSV records have the same date it will assume they are
|
||||
oldest first.
|
||||
.SH CSV TIPS
|
||||
.PP
|
||||
Each generated journal entry will have two postings, to
|
||||
\f[C]account1\f[] and \f[C]account2\f[] respectively.
|
||||
Currently it\[aq]s not possible to generate entries with more than two
|
||||
postings.
|
||||
.PP
|
||||
If the CSV has debit/credit amounts in separate fields, assign to the
|
||||
\f[C]amount\-in\f[] and \f[C]amount\-out\f[] pseudo fields instead of
|
||||
\f[C]amount\f[].
|
||||
.PP
|
||||
If the CSV has the currency in a separate field, assign that to the
|
||||
\f[C]currency\f[] pseudo field which will be automatically prepended to
|
||||
the amount.
|
||||
(Or you can do the same thing with a field assignment.)
|
||||
.PP
|
||||
If the CSV includes a running balance, you can assign that to the
|
||||
\f[C]balance\f[] pseudo field to generate a balance assertion on
|
||||
\f[C]account1\f[] whenever the balance field is non\-empty.
|
||||
(Eg to double\-check your bank\[aq]s balance calculation.)
|
||||
.PP
|
||||
If an amount value is parenthesised, it will be de\-parenthesised and
|
||||
sign\-flipped automatically.
|
||||
.SS CSV ordering
|
||||
.PP
|
||||
The generated journal entries will be sorted by date.
|
||||
The original order of same\-day entries will be preserved, usually.
|
||||
The order of same\-day entries will be preserved (except in the special
|
||||
case where you might need \f[C]newest\-first\f[], see above).
|
||||
.SS CSV accounts
|
||||
.PP
|
||||
Each journal entry will have two postings, to \f[C]account1\f[] and
|
||||
\f[C]account2\f[] respectively.
|
||||
It\[aq]s not yet possible to generate entries with more than two
|
||||
postings.
|
||||
It\[aq]s conventional and recommended to use \f[C]account1\f[] for the
|
||||
account whose CSV we are reading.
|
||||
.SS CSV amounts
|
||||
.PP
|
||||
The \f[C]amount\f[] field sets the amount of the \f[C]account1\f[]
|
||||
posting.
|
||||
.PP
|
||||
If the CSV has debit/credit amounts in separate fields, assign to the
|
||||
\f[C]amount\-in\f[] and \f[C]amount\-out\f[] pseudo fields instead.
|
||||
(Whichever one has a value will be used, with appropriate sign.
|
||||
If both contain a value, it may not work so well.)
|
||||
.PP
|
||||
If an amount value is parenthesised, it will be de\-parenthesised and
|
||||
sign\-flipped.
|
||||
.PP
|
||||
If an amount value begins with a double minus sign, those will cancel
|
||||
out and be removed.
|
||||
.PP
|
||||
If the CSV has the currency symbol in a separate field, assign that to
|
||||
the \f[C]currency\f[] pseudo field to have it prepended to the amount.
|
||||
Or, you can use a field assignment to \f[C]amount\f[] that interpolates
|
||||
both CSV fields (giving more control, eg to put the currency symbol on
|
||||
the right).
|
||||
.SS CSV balance assertions
|
||||
.PP
|
||||
If the CSV includes a running balance, you can assign that to the
|
||||
\f[C]balance\f[] pseudo field; whenever the running balance value is
|
||||
non\-empty, it will be asserted as the balance after the
|
||||
\f[C]account1\f[] posting.
|
||||
|
||||
|
||||
.SH "REPORTING BUGS"
|
||||
|
||||
@ -179,12 +179,12 @@ File: hledger_csv.5.info, Node: newest-first, Prev: include, Up: CSV RULES
|
||||
|
||||
'newest-first'
|
||||
|
||||
Consider adding this rule if: your CSV records are in reverse
|
||||
Consider adding this rule if all of the following are true: you might
|
||||
be processing just one day of data, your CSV records are in reverse
|
||||
chronological order (newest first), and you care about preserving the
|
||||
order of same-day transactions, and you might be processing just one day
|
||||
of data. It usually isn't needed, because hledger autodetects the CSV
|
||||
order, but if all the CSV records have the same date it assumes they are
|
||||
oldest first.
|
||||
order of same-day transactions. It usually isn't needed, because
|
||||
hledger autodetects the CSV order, but when all CSV records have the
|
||||
same date it will assume they are oldest first.
|
||||
|
||||
|
||||
File: hledger_csv.5.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top
|
||||
@ -192,27 +192,68 @@ File: hledger_csv.5.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top
|
||||
2 CSV TIPS
|
||||
**********
|
||||
|
||||
Each generated journal entry will have two postings, to 'account1' and
|
||||
'account2' respectively. Currently it's not possible to generate
|
||||
entries with more than two postings.
|
||||
* Menu:
|
||||
|
||||
* CSV ordering::
|
||||
* CSV accounts::
|
||||
* CSV amounts::
|
||||
* CSV balance assertions::
|
||||
|
||||
|
||||
File: hledger_csv.5.info, Node: CSV ordering, Next: CSV accounts, Up: CSV TIPS
|
||||
|
||||
2.1 CSV ordering
|
||||
================
|
||||
|
||||
The generated journal entries will be sorted by date. The order of
|
||||
same-day entries will be preserved (except in the special case where you
|
||||
might need 'newest-first', see above).
|
||||
|
||||
|
||||
File: hledger_csv.5.info, Node: CSV accounts, Next: CSV amounts, Prev: CSV ordering, Up: CSV TIPS
|
||||
|
||||
2.2 CSV accounts
|
||||
================
|
||||
|
||||
Each journal entry will have two postings, to 'account1' and 'account2'
|
||||
respectively. It's not yet possible to generate entries with more than
|
||||
two postings. It's conventional and recommended to use 'account1' for
|
||||
the account whose CSV we are reading.
|
||||
|
||||
|
||||
File: hledger_csv.5.info, Node: CSV amounts, Next: CSV balance assertions, Prev: CSV accounts, Up: CSV TIPS
|
||||
|
||||
2.3 CSV amounts
|
||||
===============
|
||||
|
||||
The 'amount' field sets the amount of the 'account1' posting.
|
||||
|
||||
If the CSV has debit/credit amounts in separate fields, assign to the
|
||||
'amount-in' and 'amount-out' pseudo fields instead of 'amount'.
|
||||
|
||||
If the CSV has the currency in a separate field, assign that to the
|
||||
'currency' pseudo field which will be automatically prepended to the
|
||||
amount. (Or you can do the same thing with a field assignment.)
|
||||
|
||||
If the CSV includes a running balance, you can assign that to the
|
||||
'balance' pseudo field to generate a balance assertion on 'account1'
|
||||
whenever the balance field is non-empty. (Eg to double-check your
|
||||
bank's balance calculation.)
|
||||
'amount-in' and 'amount-out' pseudo fields instead. (Whichever one has
|
||||
a value will be used, with appropriate sign. If both contain a value,
|
||||
it may not work so well.)
|
||||
|
||||
If an amount value is parenthesised, it will be de-parenthesised and
|
||||
sign-flipped automatically.
|
||||
sign-flipped.
|
||||
|
||||
The generated journal entries will be sorted by date. The original
|
||||
order of same-day entries will be preserved, usually.
|
||||
If an amount value begins with a double minus sign, those will cancel
|
||||
out and be removed.
|
||||
|
||||
If the CSV has the currency symbol in a separate field, assign that
|
||||
to the 'currency' pseudo field to have it prepended to the amount. Or,
|
||||
you can use a field assignment to 'amount' that interpolates both CSV
|
||||
fields (giving more control, eg to put the currency symbol on the
|
||||
right).
|
||||
|
||||
|
||||
File: hledger_csv.5.info, Node: CSV balance assertions, Prev: CSV amounts, Up: CSV TIPS
|
||||
|
||||
2.4 CSV balance assertions
|
||||
==========================
|
||||
|
||||
If the CSV includes a running balance, you can assign that to the
|
||||
'balance' pseudo field; whenever the running balance value is non-empty,
|
||||
it will be asserted as the balance after the 'account1' posting.
|
||||
|
||||
|
||||
Tag Table:
|
||||
@ -233,7 +274,15 @@ Node: include4648
|
||||
Ref: #include4780
|
||||
Node: newest-first5011
|
||||
Ref: #newest-first5127
|
||||
Node: CSV TIPS5510
|
||||
Ref: #csv-tips5606
|
||||
Node: CSV TIPS5538
|
||||
Ref: #csv-tips5634
|
||||
Node: CSV ordering5721
|
||||
Ref: #csv-ordering5841
|
||||
Node: CSV accounts6022
|
||||
Ref: #csv-accounts6162
|
||||
Node: CSV amounts6416
|
||||
Ref: #csv-amounts6564
|
||||
Node: CSV balance assertions7339
|
||||
Ref: #csv-balance-assertions7488
|
||||
|
||||
End Tag Table
|
||||
|
||||
@ -161,31 +161,45 @@ include common.rules
|
||||
|
||||
`newest-first`
|
||||
|
||||
Consider adding this rule if:
|
||||
Consider adding this rule if all of the following are true:
|
||||
you might be processing just one day of data,
|
||||
your CSV records are in reverse chronological order (newest first),
|
||||
and you care about preserving the order of same-day transactions,
|
||||
and you might be processing just one day of data.
|
||||
and you care about preserving the order of same-day transactions.
|
||||
It usually isn't needed, because hledger autodetects the CSV order,
|
||||
but if all the CSV records have the same date it assumes they are oldest first.
|
||||
but when all CSV records have the same date it will assume they are oldest first.
|
||||
|
||||
# CSV TIPS
|
||||
|
||||
Each generated journal entry will have two postings, to `account1` and `account2` respectively.
|
||||
Currently it's not possible to generate entries with more than two postings.
|
||||
## CSV ordering
|
||||
|
||||
If the CSV has debit/credit amounts in separate fields, assign to the `amount-in` and `amount-out` pseudo fields instead of `amount`.
|
||||
The generated [journal entries](/journal.html#transactions) will be sorted by date.
|
||||
The order of same-day entries will be preserved
|
||||
(except in the special case where you might need [`newest-first`](#newest-first), see above).
|
||||
|
||||
If the CSV has the currency in a separate field, assign that to the `currency` pseudo field which will be automatically prepended to the amount.
|
||||
(Or you can do the same thing with a field assignment.)
|
||||
## CSV accounts
|
||||
|
||||
If the CSV includes a running balance, you can assign that to the `balance` pseudo field
|
||||
to generate a [balance assertion](/journal.html#balance-assertions) on `account1`
|
||||
whenever the balance field is non-empty.
|
||||
(Eg to double-check your bank's balance calculation.)
|
||||
Each journal entry will have two [postings](/journal.html#postings), to `account1` and `account2` respectively.
|
||||
It's not yet possible to generate entries with more than two postings.
|
||||
It's conventional and recommended to use `account1` for the account whose CSV we are reading.
|
||||
|
||||
If an amount value is parenthesised, it will be de-parenthesised and sign-flipped automatically.
|
||||
## CSV amounts
|
||||
|
||||
The generated journal entries will be sorted by date.
|
||||
The original order of same-day entries will be preserved, usually.
|
||||
<!-- (by reversing the CSV entries if they seem to be in reverse date order). -->
|
||||
The `amount` field sets the [amount](/journal.html#amounts) of the `account1` posting.
|
||||
|
||||
If the CSV has debit/credit amounts in separate fields, assign to the `amount-in` and `amount-out` pseudo fields instead.
|
||||
(Whichever one has a value will be used, with appropriate sign. If both contain a value, it may not work so well.)
|
||||
|
||||
If an amount value is parenthesised, it will be de-parenthesised and sign-flipped.
|
||||
|
||||
If an amount value begins with a double minus sign, those will cancel out and be removed.
|
||||
|
||||
If the CSV has the currency symbol in a separate field,
|
||||
assign that to the `currency` pseudo field to have it prepended to the amount.
|
||||
Or, you can use a [field assignment](#field-assignment) to `amount` that interpolates both CSV fields
|
||||
(giving more control, eg to put the currency symbol on the right).
|
||||
|
||||
## CSV balance assertions
|
||||
|
||||
If the CSV includes a running balance, you can assign that to the `balance` pseudo field;
|
||||
whenever the running balance value is non-empty,
|
||||
it will be [asserted](/journal.html#balance-assertions) as the balance after the `account1` posting.
|
||||
|
||||
@ -126,40 +126,53 @@ CSV RULES
|
||||
newest-first
|
||||
newest-first
|
||||
|
||||
Consider adding this rule if: your CSV records are in reverse chrono-
|
||||
logical order (newest first), and you care about preserving the order
|
||||
of same-day transactions, and you might be processing just one day of
|
||||
data. It usually isn't needed, because hledger autodetects the CSV
|
||||
order, but if all the CSV records have the same date it assumes they
|
||||
are oldest first.
|
||||
Consider adding this rule if all of the following are true: you might
|
||||
be processing just one day of data, your CSV records are in reverse
|
||||
chronological order (newest first), and you care about preserving the
|
||||
order of same-day transactions. It usually isn't needed, because
|
||||
hledger autodetects the CSV order, but when all CSV records have the
|
||||
same date it will assume they are oldest first.
|
||||
|
||||
CSV TIPS
|
||||
Each generated journal entry will have two postings, to account1 and
|
||||
account2 respectively. Currently it's not possible to generate entries
|
||||
with more than two postings.
|
||||
CSV ordering
|
||||
The generated journal entries will be sorted by date. The order of
|
||||
same-day entries will be preserved (except in the special case where
|
||||
you might need newest-first, see above).
|
||||
|
||||
If the CSV has debit/credit amounts in separate fields, assign to the
|
||||
amount-in and amount-out pseudo fields instead of amount.
|
||||
CSV accounts
|
||||
Each journal entry will have two postings, to account1 and account2
|
||||
respectively. It's not yet possible to generate entries with more than
|
||||
two postings. It's conventional and recommended to use account1 for
|
||||
the account whose CSV we are reading.
|
||||
|
||||
If the CSV has the currency in a separate field, assign that to the
|
||||
currency pseudo field which will be automatically prepended to the
|
||||
amount. (Or you can do the same thing with a field assignment.)
|
||||
CSV amounts
|
||||
The amount field sets the amount of the account1 posting.
|
||||
|
||||
If the CSV includes a running balance, you can assign that to the bal-
|
||||
ance pseudo field to generate a balance assertion on account1 whenever
|
||||
the balance field is non-empty. (Eg to double-check your bank's bal-
|
||||
ance calculation.)
|
||||
If the CSV has debit/credit amounts in separate fields, assign to the
|
||||
amount-in and amount-out pseudo fields instead. (Whichever one has a
|
||||
value will be used, with appropriate sign. If both contain a value, it
|
||||
may not work so well.)
|
||||
|
||||
If an amount value is parenthesised, it will be de-parenthesised and
|
||||
sign-flipped automatically.
|
||||
sign-flipped.
|
||||
|
||||
The generated journal entries will be sorted by date. The original
|
||||
order of same-day entries will be preserved, usually.
|
||||
If an amount value begins with a double minus sign, those will cancel
|
||||
out and be removed.
|
||||
|
||||
If the CSV has the currency symbol in a separate field, assign that to
|
||||
the currency pseudo field to have it prepended to the amount. Or, you
|
||||
can use a field assignment to amount that interpolates both CSV fields
|
||||
(giving more control, eg to put the currency symbol on the right).
|
||||
|
||||
CSV balance assertions
|
||||
If the CSV includes a running balance, you can assign that to the bal-
|
||||
ance pseudo field; whenever the running balance value is non-empty, it
|
||||
will be asserted as the balance after the account1 posting.
|
||||
|
||||
|
||||
|
||||
REPORTING BUGS
|
||||
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
||||
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
||||
or hledger mail list)
|
||||
|
||||
|
||||
@ -173,7 +186,7 @@ COPYRIGHT
|
||||
|
||||
|
||||
SEE ALSO
|
||||
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
|
||||
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
|
||||
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
|
||||
dot(5), ledger(1)
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user