hledger/RULES.md

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