From 58edc161c9c9c2779073c03d5dd3bdb5bbd31a8f Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Sat, 15 Dec 2012 21:11:33 +0000
Subject: [PATCH] docs: draft v2 conversion rules

---
 RULES.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 RULES.md

diff --git a/RULES.md b/RULES.md
new file mode 100644
index 000000000..b97315c7a
--- /dev/null
+++ b/RULES.md
@@ -0,0 +1,78 @@
+# 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.
+