hledger-lib-1.0: doc/hledger_csv.5.info

This is hledger-lib/doc/hledger_csv.5.info, produced by makeinfo
version 4.8 from stdin.


File: hledger_csv.5.info,  Node: Top,  Up: (dir)

hledger_csv(5) hledger 1.0
**************************

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
`.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.

   To learn about _exporting_ CSV, see CSV output.

* Menu:

* CSV RULES::
* TIPS::


File: hledger_csv.5.info,  Node: CSV RULES,  Next: TIPS,  Prev: Top,  Up: Top

1 CSV RULES
***********

The following six kinds of rule can appear in the rules file, in any
order. Blank lines and lines beginning with `#' or `;' are ignored.

* Menu:

* skip::
* date-format::
* field list::
* field assignment::
* conditional block::
* include::


File: hledger_csv.5.info,  Node: skip,  Next: date-format,  Up: CSV RULES

1.1 skip
========

`skip'_`N'_

   Skip this number of CSV records at the beginning. You'll need this
whenever your CSV data contains header lines. Eg:


# ignore the first CSV line
skip 1


File: hledger_csv.5.info,  Node: date-format,  Next: field list,  Prev: skip,  Up: CSV RULES

1.2 date-format
===============

`date-format'_`DATEFMT'_

   When your CSV date fields are not formatted like `YYYY/MM/DD' (or
`YYYY-MM-DD' or `YYYY.MM.DD'), you'll need to specify the format.
DATEFMT is a strptime-like date parsing pattern, which must parse the
date field values completely. Examples:


# for dates like "6/11/2013":
date-format %-d/%-m/%Y


# for dates like "11/06/2013":
date-format %m/%d/%Y


# for dates like "2013-Nov-06":
date-format %Y-%h-%d


# for dates like "11/6/2013 11:32 PM":
date-format %-m/%-d/%Y %l:%M %p


File: hledger_csv.5.info,  Node: field list,  Next: field assignment,  Prev: date-format,  Up: CSV RULES

1.3 field list
==============

`fields'_`FIELDNAME1'_, _`FIELDNAME2'_...

   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:
`date', `date2', `status', `code', `description', `comment',
`account1', `account2', `amount', `amount-in', `amount-out',
`currency'. 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:
#
# CSV field:
#      1     2            3 4       5 6 7          8
# entry field:
fields date, description, , amount, , , somefield, anotherfield


File: hledger_csv.5.info,  Node: field assignment,  Next: conditional block,  Prev: field list,  Up: CSV RULES

1.4 field assignment
====================

_`ENTRYFIELDNAME'_ _`FIELDVALUE'_

   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 (`%CSVFIELDNAME') or 1-based position (`%N'). Eg:


# set the amount to the 4th CSV field with "USD " prepended
amount USD %4


# combine three fields to make a comment (containing two tags)
comment note: %somefield - %anotherfield, date: %1

   Field assignments can be used instead of or in addition to a field
list.


File: hledger_csv.5.info,  Node: conditional block,  Next: include,  Prev: field assignment,  Up: CSV RULES

1.5 conditional block
=====================

`if' _`PATTERN'_
_`FIELDASSIGNMENTS'_...

   `if'
_`PATTERN'_
_`PATTERN'_...
_`FIELDASSIGNMENTS'_...

   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'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:


# if the CSV record contains "groceries", set account2 to "expenses:groceries"
if groceries
 account2 expenses:groceries


# 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


File: hledger_csv.5.info,  Node: include,  Prev: conditional block,  Up: CSV RULES

1.6 include
===========

`include'_`RULESFILE'_

   Include another rules file at this point. `RULESFILE' is either an
absolute file path or a path relative to the current file's directory.
Eg:


# rules reused with several CSV files
include common.rules


File: hledger_csv.5.info,  Node: TIPS,  Prev: CSV RULES,  Up: Top

2 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.

   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 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.



Tag Table:
Node: Top90
Node: CSV RULES795
Ref: #csv-rules901
Node: skip1144
Ref: #skip1240
Node: date-format1411
Ref: #date-format1540
Node: field list2049
Ref: #field-list2188
Node: field assignment2883
Ref: #field-assignment3040
Node: conditional block3545
Ref: #conditional-block3701
Node: include4588
Ref: #include4699
Node: TIPS4930
Ref: #tips5014

End Tag Table