doc: csv tweaks
This commit is contained in:
Simon Michael
parent
05f569f438
commit
2ac77338f8
@ -18,7 +18,7 @@ hledger will create it if necessary, with some default rules which
|
||||
you\[aq]ll need to adjust.
|
||||
At minimum, the rules file must specify the \f[C]date\f[] and
|
||||
\f[C]amount\f[] fields.
|
||||
For an example, see How to read CSV files.
|
||||
For an example, see Cookbook: convert CSV files.
|
||||
.PP
|
||||
To learn about \f[I]exporting\f[] CSV, see CSV output.
|
||||
.SH CSV RULES
|
||||
@ -90,7 +90,7 @@ to journal entry fields if you use any of these standard field names:
|
||||
\f[C]date\f[], \f[C]date2\f[], \f[C]status\f[], \f[C]code\f[],
|
||||
\f[C]description\f[], \f[C]comment\f[], \f[C]account1\f[],
|
||||
\f[C]account2\f[], \f[C]amount\f[], \f[C]amount\-in\f[],
|
||||
\f[C]amount\-out\f[], \f[C]currency\f[].
|
||||
\f[C]amount\-out\f[], \f[C]currency\f[], \f[C]balance\f[].
|
||||
Eg:
|
||||
.IP
|
||||
.nf
|
||||
@ -195,7 +195,7 @@ Eg:
|
||||
include\ common.rules
|
||||
\f[]
|
||||
.fi
|
||||
.SH TIPS
|
||||
.SH CSV TIPS
|
||||
.PP
|
||||
Each generated journal entry will have two postings, to
|
||||
\f[C]account1\f[] and \f[C]account2\f[] respectively.
|
||||
@ -211,6 +211,11 @@ If the CSV has the currency in a separate field, assign that to the
|
||||
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.
|
||||
.PP
|
||||
|
||||
@ -13,16 +13,16 @@ file". This file should be named like the CSV file with an additional
|
||||
with '--rules-file PATH'. hledger will create it if necessary, with
|
||||
some default rules which you'll need to adjust. At minimum, the rules
|
||||
file must specify the 'date' and 'amount' fields. For an example, see
|
||||
How to read CSV files.
|
||||
Cookbook: convert CSV files.
|
||||
|
||||
To learn about _exporting_ CSV, see CSV output.
|
||||
* Menu:
|
||||
|
||||
* CSV RULES::
|
||||
* TIPS::
|
||||
* CSV TIPS::
|
||||
|
||||
|
||||
File: hledger_csv.5.info, Node: CSV RULES, Next: TIPS, Prev: Top, Up: Top
|
||||
File: hledger_csv.5.info, Node: CSV RULES, Next: CSV TIPS, Prev: Top, Up: Top
|
||||
|
||||
1 CSV RULES
|
||||
***********
|
||||
@ -89,7 +89,8 @@ File: hledger_csv.5.info, Node: field list, Next: field assignment, Prev: dat
|
||||
whitespace; uninteresting names may be left blank), and (b) assigns them
|
||||
to journal entry fields if you use any of these standard field names:
|
||||
'date', 'date2', 'status', 'code', 'description', 'comment', 'account1',
|
||||
'account2', 'amount', 'amount-in', 'amount-out', 'currency'. Eg:
|
||||
'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance'.
|
||||
Eg:
|
||||
|
||||
# use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount,
|
||||
# and give the 7th and 8th fields meaningful names for later reference:
|
||||
@ -170,10 +171,10 @@ Eg:
|
||||
include common.rules
|
||||
|
||||
|
||||
File: hledger_csv.5.info, Node: TIPS, Prev: CSV RULES, Up: Top
|
||||
File: hledger_csv.5.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top
|
||||
|
||||
2 TIPS
|
||||
******
|
||||
2 CSV TIPS
|
||||
**********
|
||||
|
||||
Each generated journal entry will have two postings, to 'account1' and
|
||||
'account2' respectively. Currently it's not possible to generate
|
||||
@ -186,6 +187,11 @@ entries with more than two postings.
|
||||
'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.)
|
||||
|
||||
If an amount value is parenthesised, it will be de-parenthesised and
|
||||
sign-flipped automatically.
|
||||
|
||||
@ -195,21 +201,21 @@ order of same-day entries will be preserved, usually.
|
||||
|
||||
Tag Table:
|
||||
Node: Top74
|
||||
Node: CSV RULES800
|
||||
Ref: #csv-rules906
|
||||
Node: skip1149
|
||||
Ref: #skip1245
|
||||
Node: date-format1417
|
||||
Ref: #date-format1546
|
||||
Node: field list2052
|
||||
Ref: #field-list2191
|
||||
Node: field assignment2886
|
||||
Ref: #field-assignment3043
|
||||
Node: conditional block3547
|
||||
Ref: #conditional-block3703
|
||||
Node: include4599
|
||||
Ref: #include4710
|
||||
Node: TIPS4941
|
||||
Ref: #tips5025
|
||||
Node: CSV RULES810
|
||||
Ref: #csv-rules920
|
||||
Node: skip1163
|
||||
Ref: #skip1259
|
||||
Node: date-format1431
|
||||
Ref: #date-format1560
|
||||
Node: field list2066
|
||||
Ref: #field-list2205
|
||||
Node: field assignment2910
|
||||
Ref: #field-assignment3067
|
||||
Node: conditional block3571
|
||||
Ref: #conditional-block3727
|
||||
Node: include4623
|
||||
Ref: #include4734
|
||||
Node: CSV TIPS4965
|
||||
Ref: #csv-tips5061
|
||||
|
||||
End Tag Table
|
||||
|
||||
@ -24,7 +24,7 @@ This file should be named like the CSV file with an additional `.rules` suffix (
|
||||
or, you can specify the file with `--rules-file PATH`.
|
||||
hledger will create it if necessary, with some default rules which you'll need to adjust.
|
||||
At minimum, the rules file must specify the `date` and `amount` fields.
|
||||
For an example, see [How to read CSV files](how-to-read-csv-files.html).
|
||||
For an example, see [Cookbook: convert CSV files](csv-import.html).
|
||||
|
||||
To learn about *exporting* CSV, see [CSV output](hledger.html#csv-output).
|
||||
|
||||
@ -157,7 +157,7 @@ a path relative to the current file's directory. Eg:
|
||||
include common.rules
|
||||
```
|
||||
|
||||
# TIPS
|
||||
# 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.
|
||||
@ -167,10 +167,14 @@ If the CSV has debit/credit amounts in separate fields, assign to the `amount-in
|
||||
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](/journal.html#balance-assertoins) on `account1`
|
||||
whenever the balance field is non-empty.
|
||||
(Eg to double-check your bank's balance calculation.)
|
||||
|
||||
If an amount value is parenthesised, it will be de-parenthesised and sign-flipped automatically.
|
||||
|
||||
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). -->
|
||||
|
||||
If you assign anything to the `balance` pseudo field, it would become an assertion of the balance of `account1`. If you assign empty string to it, no assertion will be generated (this can be used to omit balance assertions on some transactions).
|
||||
|
||||
@ -13,8 +13,8 @@ DESCRIPTION
|
||||
.rules suffix (eg: mybank.csv.rules); or, you can specify the file with
|
||||
--rules-file PATH. hledger will create it if necessary, with some
|
||||
default rules which you'll need to adjust. At minimum, the rules file
|
||||
must specify the date and amount fields. For an example, see How to
|
||||
read CSV files.
|
||||
must specify the date and amount fields. For an example, see Cookbook:
|
||||
convert CSV files.
|
||||
|
||||
To learn about exporting CSV, see CSV output.
|
||||
|
||||
@ -58,7 +58,7 @@ CSV RULES
|
||||
space; uninteresting names may be left blank), and (b) assigns them to
|
||||
journal entry fields if you use any of these standard field names:
|
||||
date, date2, status, code, description, comment, account1, account2,
|
||||
amount, amount-in, amount-out, currency. Eg:
|
||||
amount, amount-in, amount-out, currency, balance. Eg:
|
||||
|
||||
# use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount,
|
||||
# and give the 7th and 8th fields meaningful names for later reference:
|
||||
@ -123,7 +123,7 @@ CSV RULES
|
||||
# rules reused with several CSV files
|
||||
include common.rules
|
||||
|
||||
TIPS
|
||||
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.
|
||||
@ -135,16 +135,21 @@ TIPS
|
||||
currency pseudo field which will be automatically prepended to the
|
||||
amount. (Or you can do the same thing with a field assignment.)
|
||||
|
||||
If an amount value is parenthesised, it will be de-parenthesised and
|
||||
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 an amount value is parenthesised, it will be de-parenthesised and
|
||||
sign-flipped automatically.
|
||||
|
||||
The generated journal entries will be sorted by date. The original
|
||||
The generated journal entries will be sorted by date. The original
|
||||
order of same-day entries will be preserved, usually.
|
||||
|
||||
|
||||
|
||||
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)
|
||||
|
||||
|
||||
@ -158,7 +163,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)
|
||||
|
||||
|
||||
@ -739,8 +739,7 @@ alias\ checking\ =\ assets:bank:wells\ fargo:checking
|
||||
.SS Regex aliases
|
||||
.PP
|
||||
There is also a more powerful variant that uses a regular expression,
|
||||
indicated by the forward slashes.
|
||||
(This was the default behaviour in hledger 0.24\-0.25):
|
||||
indicated by the forward slashes:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
|
||||
@ -736,8 +736,7 @@ File: hledger_journal.5.info, Node: Regex aliases, Next: Multiple aliases, Pr
|
||||
......................
|
||||
|
||||
There is also a more powerful variant that uses a regular expression,
|
||||
indicated by the forward slashes. (This was the default behaviour in
|
||||
hledger 0.24-0.25):
|
||||
indicated by the forward slashes:
|
||||
|
||||
alias /REGEX/ = REPLACEMENT
|
||||
|
||||
@ -1018,25 +1017,25 @@ Node: Basic aliases25540
|
||||
Ref: #basic-aliases25685
|
||||
Node: Regex aliases26375
|
||||
Ref: #regex-aliases26545
|
||||
Node: Multiple aliases27316
|
||||
Ref: #multiple-aliases27490
|
||||
Node: end aliases27988
|
||||
Ref: #end-aliases28130
|
||||
Node: account directive28231
|
||||
Ref: #account-directive28413
|
||||
Node: apply account directive28709
|
||||
Ref: #apply-account-directive28907
|
||||
Node: Multi-line comments29566
|
||||
Ref: #multi-line-comments29758
|
||||
Node: commodity directive29886
|
||||
Ref: #commodity-directive30072
|
||||
Node: Default commodity30944
|
||||
Ref: #default-commodity31119
|
||||
Node: Default year31656
|
||||
Ref: #default-year31823
|
||||
Node: Including other files32246
|
||||
Ref: #including-other-files32405
|
||||
Node: EDITOR SUPPORT32802
|
||||
Ref: #editor-support32922
|
||||
Node: Multiple aliases27260
|
||||
Ref: #multiple-aliases27434
|
||||
Node: end aliases27932
|
||||
Ref: #end-aliases28074
|
||||
Node: account directive28175
|
||||
Ref: #account-directive28357
|
||||
Node: apply account directive28653
|
||||
Ref: #apply-account-directive28851
|
||||
Node: Multi-line comments29510
|
||||
Ref: #multi-line-comments29702
|
||||
Node: commodity directive29830
|
||||
Ref: #commodity-directive30016
|
||||
Node: Default commodity30888
|
||||
Ref: #default-commodity31063
|
||||
Node: Default year31600
|
||||
Ref: #default-year31767
|
||||
Node: Including other files32190
|
||||
Ref: #including-other-files32349
|
||||
Node: EDITOR SUPPORT32746
|
||||
Ref: #editor-support32866
|
||||
|
||||
End Tag Table
|
||||
|
||||
@ -559,44 +559,43 @@ FILE FORMAT
|
||||
|
||||
Regex aliases
|
||||
There is also a more powerful variant that uses a regular expression,
|
||||
indicated by the forward slashes. (This was the default behaviour in
|
||||
hledger 0.24-0.25):
|
||||
indicated by the forward slashes:
|
||||
|
||||
alias /REGEX/ = REPLACEMENT
|
||||
|
||||
or --alias '/REGEX/=REPLACEMENT'.
|
||||
|
||||
REGEX is a case-insensitive regular expression. Anywhere it matches
|
||||
inside an account name, the matched part will be replaced by REPLACE-
|
||||
MENT. If REGEX contains parenthesised match groups, these can be ref-
|
||||
REGEX is a case-insensitive regular expression. Anywhere it matches
|
||||
inside an account name, the matched part will be replaced by REPLACE-
|
||||
MENT. If REGEX contains parenthesised match groups, these can be ref-
|
||||
erenced by the usual numeric backreferences in REPLACEMENT. Note, cur-
|
||||
rently regular expression aliases may cause noticeable slow-downs.
|
||||
rently regular expression aliases may cause noticeable slow-downs.
|
||||
(And if you use Ledger on your hledger file, they will be ignored.) Eg:
|
||||
|
||||
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
|
||||
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
|
||||
|
||||
Multiple aliases
|
||||
You can define as many aliases as you like using directives or com-
|
||||
mand-line options. Aliases are recursive - each alias sees the result
|
||||
of applying previous ones. (This is different from Ledger, where
|
||||
You can define as many aliases as you like using directives or com-
|
||||
mand-line options. Aliases are recursive - each alias sees the result
|
||||
of applying previous ones. (This is different from Ledger, where
|
||||
aliases are non-recursive by default). Aliases are applied in the fol-
|
||||
lowing order:
|
||||
|
||||
1. alias directives, most recently seen first (recent directives take
|
||||
1. alias directives, most recently seen first (recent directives take
|
||||
precedence over earlier ones; directives not yet seen are ignored)
|
||||
|
||||
2. alias options, in the order they appear on the command line
|
||||
|
||||
end aliases
|
||||
You can clear (forget) all currently defined aliases with the
|
||||
You can clear (forget) all currently defined aliases with the
|
||||
end aliases directive:
|
||||
|
||||
end aliases
|
||||
|
||||
account directive
|
||||
The account directive predefines account names, as in Ledger and Bean-
|
||||
count. This may be useful for your own documentation; hledger doesn't
|
||||
The account directive predefines account names, as in Ledger and Bean-
|
||||
count. This may be useful for your own documentation; hledger doesn't
|
||||
make use of it yet.
|
||||
|
||||
; account ACCT
|
||||
@ -611,8 +610,8 @@ FILE FORMAT
|
||||
; etc.
|
||||
|
||||
apply account directive
|
||||
You can specify a parent account which will be prepended to all
|
||||
accounts within a section of the journal. Use the apply account and
|
||||
You can specify a parent account which will be prepended to all
|
||||
accounts within a section of the journal. Use the apply account and
|
||||
end apply account directives like so:
|
||||
|
||||
apply account home
|
||||
@ -629,7 +628,7 @@ FILE FORMAT
|
||||
home:food $10
|
||||
home:cash $-10
|
||||
|
||||
If end apply account is omitted, the effect lasts to the end of the
|
||||
If end apply account is omitted, the effect lasts to the end of the
|
||||
file. Included files are also affected, eg:
|
||||
|
||||
apply account business
|
||||
@ -638,16 +637,16 @@ FILE FORMAT
|
||||
apply account personal
|
||||
include personal.journal
|
||||
|
||||
Prior to hledger 1.0, legacy account and end spellings were also sup-
|
||||
Prior to hledger 1.0, legacy account and end spellings were also sup-
|
||||
ported.
|
||||
|
||||
Multi-line comments
|
||||
A line containing just comment starts a multi-line comment, and a line
|
||||
A line containing just comment starts a multi-line comment, and a line
|
||||
containing just end comment ends it. See comments.
|
||||
|
||||
commodity directive
|
||||
The commodity directive predefines commodities (currently this is just
|
||||
informational), and also it may define the display format for amounts
|
||||
The commodity directive predefines commodities (currently this is just
|
||||
informational), and also it may define the display format for amounts
|
||||
in this commodity (overriding the automatically inferred format).
|
||||
|
||||
It may be written on a single line, like this:
|
||||
@ -659,8 +658,8 @@ FILE FORMAT
|
||||
; separating thousands with comma.
|
||||
commodity 1,000.0000 AAAA
|
||||
|
||||
or on multiple lines, using the "format" subdirective. In this case
|
||||
the commodity symbol appears twice and should be the same in both
|
||||
or on multiple lines, using the "format" subdirective. In this case
|
||||
the commodity symbol appears twice and should be the same in both
|
||||
places:
|
||||
|
||||
; commodity SYMBOL
|
||||
@ -673,10 +672,10 @@ FILE FORMAT
|
||||
format INR 9,99,99,999.00
|
||||
|
||||
Default commodity
|
||||
The D directive sets a default commodity (and display format), to be
|
||||
The D directive sets a default commodity (and display format), to be
|
||||
used for amounts without a commodity symbol (ie, plain numbers). (Note
|
||||
this differs from Ledger's default commodity directive.) The commodity
|
||||
and display format will be applied to all subsequent commodity-less
|
||||
this differs from Ledger's default commodity directive.) The commodity
|
||||
and display format will be applied to all subsequent commodity-less
|
||||
amounts, or until the next D directive.
|
||||
|
||||
# commodity-less amounts should be treated as dollars
|
||||
@ -688,8 +687,8 @@ FILE FORMAT
|
||||
b
|
||||
|
||||
Default year
|
||||
You can set a default year to be used for subsequent dates which don't
|
||||
specify a year. This is a line beginning with Y followed by the year.
|
||||
You can set a default year to be used for subsequent dates which don't
|
||||
specify a year. This is a line beginning with Y followed by the year.
|
||||
Eg:
|
||||
|
||||
Y2009 ; set default year to 2009
|
||||
@ -709,24 +708,24 @@ FILE FORMAT
|
||||
assets
|
||||
|
||||
Including other files
|
||||
You can pull in the content of additional journal files by writing an
|
||||
You can pull in the content of additional journal files by writing an
|
||||
include directive, like this:
|
||||
|
||||
include path/to/file.journal
|
||||
|
||||
If the path does not begin with a slash, it is relative to the current
|
||||
If the path does not begin with a slash, it is relative to the current
|
||||
file. Glob patterns (*) are not currently supported.
|
||||
|
||||
The include directive can only be used in journal files. It can
|
||||
The include directive can only be used in journal files. It can
|
||||
include journal, timeclock or timedot files, but not CSV files.
|
||||
|
||||
EDITOR SUPPORT
|
||||
Add-on modes exist for various text editors, to make working with jour-
|
||||
nal files easier. They add colour, navigation aids and helpful com-
|
||||
mands. For hledger users who edit the journal file directly (the
|
||||
nal files easier. They add colour, navigation aids and helpful com-
|
||||
mands. For hledger users who edit the journal file directly (the
|
||||
majority), using one of these modes is quite recommended.
|
||||
|
||||
These were written with Ledger in mind, but also work with hledger
|
||||
These were written with Ledger in mind, but also work with hledger
|
||||
files:
|
||||
|
||||
|
||||
@ -743,7 +742,7 @@ EDITOR SUPPORT
|
||||
|
||||
|
||||
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)
|
||||
|
||||
|
||||
@ -757,7 +756,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)
|
||||
|
||||
|
||||
@ -55,3 +55,5 @@ using conversion rules file checking.csv.rules
|
||||
--------------------
|
||||
0
|
||||
```
|
||||
|
||||
Here are more [CSV rules examples](http://code.hledger.org/tree/master/examples/csv).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user