mirror of
https://github.com/simonmichael/hledger.git
synced 2024-09-20 02:37:12 +03:00
79 lines
3.3 KiB
Markdown
79 lines
3.3 KiB
Markdown
|
# hledger conversion rules v2 (draft)
|
||
|
|
||
|
When hledger reads CSV files, it looks for conversion rules that help
|
||
|
it transform the CSV records into meaningful journal entries. These
|
||
|
usually come from a file, named like the csv file with a `.rules`
|
||
|
suffix added.
|
||
|
|
||
|
The version 2 rules format aims to be more powerful and more
|
||
|
understandable than version 1. This design document describes the
|
||
|
proposed rules and syntax for discussion and refinement.
|
||
|
|
||
|
## Rules syntax
|
||
|
|
||
|
Several kinds of rule may be used. In order of increasing complexity:
|
||
|
|
||
|
1. A **FIELD LIST** is an easy way to name CSV fields, and also to
|
||
|
assign them to entry fields. It is a comma-separated list of names
|
||
|
on one line, as is often found at the start of a CSV file. When
|
||
|
standard journal entry field names are used (`date`, `date2`,
|
||
|
`status`, `code`, `description`, `account`, `account2`, `amount`,
|
||
|
`comment`, `tag`), the csv values in that position are used for
|
||
|
those entry fields. Eg:
|
||
|
|
||
|
date, desc, amount, notes, some other field
|
||
|
|
||
|
2. **FIELD ASSIGNMENTS** are a slightly more flexible way to define
|
||
|
entry fields. They consist of an entry field name, then a colon
|
||
|
(optional), then a string containing 0 or more CSV field
|
||
|
references. Eg, here the entry description is built from three CSV
|
||
|
fields:
|
||
|
|
||
|
description: %desc (%notes) %"some other field"
|
||
|
|
||
|
3. **ENTRY TEMPLATES** give most flexibility, defining the entire
|
||
|
journal entry at once. They look like a standard journal entry, but
|
||
|
with CSV field references instead of values, beginning with `%date`
|
||
|
on the first line. Eg, this builds an entry with an extra virtual
|
||
|
posting:
|
||
|
|
||
|
%date %description
|
||
|
%account %amount
|
||
|
%default-account
|
||
|
(some special account) %amount
|
||
|
|
||
|
4. **CONDITIONAL BLOCKS** enable field assignments or an entry
|
||
|
template, when a CSV field matches a certain pattern. They consist
|
||
|
of the word `if` (optional), then a CSV field name, then either `~`
|
||
|
(for case-insensitive infix regular expression matching) or `=`
|
||
|
(for case-insensitive exact matching), then the regular expression
|
||
|
or value to match, then one or more field assignments or one entry
|
||
|
template, and finally a blank line. Eg, here if description
|
||
|
contains "groc" then the entry's account and comment are set as
|
||
|
shown:
|
||
|
|
||
|
description ~ groc
|
||
|
account: expenses:groceries
|
||
|
comment: household
|
||
|
|
||
|
5. **DIRECTIVES** influence the overall conversion process. They are:
|
||
|
|
||
|
skip-lines 1 # skips this number of CSV header lines
|
||
|
date-format %d/%m/%y # parses the CSV date field in this way
|
||
|
default-currency $ # adds this currency symbol to amounts without one
|
||
|
default-account assets:checking # uses this value as the default for account2
|
||
|
|
||
|
## Other rules syntax features:
|
||
|
|
||
|
- **COMMENTS** beginning with `#` or `;` are ignored, as are (except
|
||
|
as noted above) blank lines.
|
||
|
|
||
|
- **FIELD NAMES** are either a word containing no whitespace and no
|
||
|
comment character (`;` or `#`), or a phrase enclosed by double quotes.
|
||
|
|
||
|
- **FIELD REFERENCES** look like `%name` or `%1`. They are replaced by
|
||
|
the content of the CSV field with that name or position. A reference
|
||
|
to a field containing an amount may be written `%-name`, in which
|
||
|
case the amount's sign will be reversed.
|
||
|
|