256 lines
6.7 KiB
Groff
256 lines
6.7 KiB
Groff
|
|
.TH "hledger_csv" "5" "July 2017" "hledger 1.3.99" "hledger User Manuals"
|
|
|
|
|
|
|
|
.SH NAME
|
|
.PP
|
|
CSV \- how hledger reads CSV data, and the CSV rules file format
|
|
.SH DESCRIPTION
|
|
.PP
|
|
hledger can read CSV files, converting each CSV record into a journal
|
|
entry (transaction), if you provide some conversion hints in a "rules
|
|
file".
|
|
This file should be named like the CSV file with an additional
|
|
\f[C]\&.rules\f[] suffix (eg: \f[C]mybank.csv.rules\f[]); or, you can
|
|
specify the file with \f[C]\-\-rules\-file\ PATH\f[].
|
|
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 Cookbook: convert CSV files.
|
|
.PP
|
|
To learn about \f[I]exporting\f[] CSV, see CSV output.
|
|
.SH CSV RULES
|
|
.PP
|
|
The following seven kinds of rule can appear in the rules file, in any
|
|
order.
|
|
Blank lines and lines beginning with \f[C]#\f[] or \f[C];\f[] are
|
|
ignored.
|
|
.SS skip
|
|
.PP
|
|
\f[C]skip\f[]\f[I]\f[C]N\f[]\f[]
|
|
.PP
|
|
Skip this number of CSV records at the beginning.
|
|
You\[aq]ll need this whenever your CSV data contains header lines.
|
|
Eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ ignore\ the\ first\ CSV\ line
|
|
skip\ 1
|
|
\f[]
|
|
.fi
|
|
.SS date\-format
|
|
.PP
|
|
\f[C]date\-format\f[]\f[I]\f[C]DATEFMT\f[]\f[]
|
|
.PP
|
|
When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or
|
|
\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you\[aq]ll need to
|
|
specify the format.
|
|
DATEFMT is a strptime\-like date parsing pattern, which must parse the
|
|
date field values completely.
|
|
Examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ for\ dates\ like\ "6/11/2013":
|
|
date\-format\ %\-d/%\-m/%Y
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ for\ dates\ like\ "11/06/2013":
|
|
date\-format\ %m/%d/%Y
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ for\ dates\ like\ "2013\-Nov\-06":
|
|
date\-format\ %Y\-%h\-%d
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ for\ dates\ like\ "11/6/2013\ 11:32\ PM":
|
|
date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p
|
|
\f[]
|
|
.fi
|
|
.SS field list
|
|
.PP
|
|
\f[C]fields\f[]\f[I]\f[C]FIELDNAME1\f[]\f[],
|
|
\f[I]\f[C]FIELDNAME2\f[]\f[]...
|
|
.PP
|
|
This (a) names the CSV fields, in order (names may not contain
|
|
whitespace; uninteresting names may be left blank), and (b) assigns them
|
|
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]balance\f[].
|
|
Eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ use\ the\ 1st,\ 2nd\ and\ 4th\ CSV\ fields\ as\ the\ entry\[aq]s\ date,\ description\ and\ amount,
|
|
#\ and\ give\ the\ 7th\ and\ 8th\ fields\ meaningful\ names\ for\ later\ reference:
|
|
#
|
|
#\ CSV\ field:
|
|
#\ \ \ \ \ \ 1\ \ \ \ \ 2\ \ \ \ \ \ \ \ \ \ \ \ 3\ 4\ \ \ \ \ \ \ 5\ 6\ 7\ \ \ \ \ \ \ \ \ \ 8
|
|
#\ entry\ field:
|
|
fields\ date,\ description,\ ,\ amount,\ ,\ ,\ somefield,\ anotherfield
|
|
\f[]
|
|
.fi
|
|
.SS field assignment
|
|
.PP
|
|
\f[I]\f[C]ENTRYFIELDNAME\f[]\f[] \f[I]\f[C]FIELDVALUE\f[]\f[]
|
|
.PP
|
|
This sets a journal entry field (one of the standard names above) to the
|
|
given text value, which can include CSV field values interpolated by
|
|
name (\f[C]%CSVFIELDNAME\f[]) or 1\-based position (\f[C]%N\f[]).
|
|
Eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ set\ the\ amount\ to\ the\ 4th\ CSV\ field\ with\ "USD\ "\ prepended
|
|
amount\ USD\ %4
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ combine\ three\ fields\ to\ make\ a\ comment\ (containing\ two\ tags)
|
|
comment\ note:\ %somefield\ \-\ %anotherfield,\ date:\ %1
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Field assignments can be used instead of or in addition to a field list.
|
|
.SS conditional block
|
|
.PP
|
|
\f[C]if\f[] \f[I]\f[C]PATTERN\f[]\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\ \ \ \ \f[I]\f[C]FIELDASSIGNMENTS\f[]\f[]...
|
|
.PP
|
|
\f[C]if\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[I]\f[C]PATTERN\f[]\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[I]\f[C]PATTERN\f[]\f[]...
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\ \ \ \ \f[I]\f[C]FIELDASSIGNMENTS\f[]\f[]...
|
|
.PP
|
|
This applies one or more field assignments, only to those CSV records
|
|
matched by one of the PATTERNs.
|
|
The patterns are case\-insensitive regular expressions which match
|
|
anywhere within the whole CSV record (it\[aq]s not yet possible to match
|
|
within a specific field).
|
|
When there are multiple patterns they can be written on separate lines,
|
|
unindented.
|
|
The field assignments are on separate lines indented by at least one
|
|
space.
|
|
Examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ if\ the\ CSV\ record\ contains\ "groceries",\ set\ account2\ to\ "expenses:groceries"
|
|
if\ groceries
|
|
\ account2\ expenses:groceries
|
|
\f[]
|
|
.fi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ if\ the\ CSV\ record\ contains\ any\ of\ these\ patterns,\ set\ account2\ and\ comment\ as\ shown
|
|
if
|
|
monthly\ service\ fee
|
|
atm\ transaction\ fee
|
|
banking\ thru\ software
|
|
\ account2\ expenses:business:banking
|
|
\ comment\ \ XXX\ deductible\ ?\ check\ it
|
|
\f[]
|
|
.fi
|
|
.SS include
|
|
.PP
|
|
\f[C]include\f[]\f[I]\f[C]RULESFILE\f[]\f[]
|
|
.PP
|
|
Include another rules file at this point.
|
|
\f[C]RULESFILE\f[] is either an absolute file path or a path relative to
|
|
the current file\[aq]s directory.
|
|
Eg:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ rules\ reused\ with\ several\ CSV\ files
|
|
include\ common.rules
|
|
\f[]
|
|
.fi
|
|
.SS newest\-first
|
|
.PP
|
|
\f[C]newest\-first\f[]
|
|
.PP
|
|
Consider adding this rule if: 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\[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.
|
|
.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.
|
|
.PP
|
|
The generated journal entries will be sorted by date.
|
|
The original order of same\-day entries will be preserved, usually.
|
|
|
|
|
|
.SH "REPORTING BUGS"
|
|
Report bugs at http://bugs.hledger.org
|
|
(or on the #hledger IRC channel or hledger mail list)
|
|
|
|
.SH AUTHORS
|
|
Simon Michael <simon@joyful.com> and contributors
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Copyright (C) 2007-2016 Simon Michael.
|
|
.br
|
|
Released under GNU GPL v3 or later.
|
|
|
|
.SH SEE ALSO
|
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
|
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5),
|
|
ledger(1)
|
|
|
|
http://hledger.org
|