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