branch: elpa/csv2ledger
commit ae65a1f36b94c3919d9858c8d0f0121555549533
Author: Joost Kremers <joostkrem...@fastmail.com>
Commit: Joost Kremers <joostkrem...@fastmail.com>
Update README.
---
README.md | 29 ++++++++++++++++++-----------
1 file changed, 18 insertions(+), 11 deletions(-)
diff --git a/README.md b/README.md
index d5ad9e87be..59fab0f8b9 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ The purpose of this small library is to read bank
transactions in a CSV file and
The description is optional, you can leave it out if you prefer. The format
used for the amount is also configurable. By default, `csv2ledger` just copies
the amount from the CSV file, but you can apply a conversion to it if you like.
-For ease of reference, I will use the following terms to refer to the various
parts of the entry. The account associated with the bank account for the CSV
file is called the *base* account. In the example here, it is
`Assets:Checkings`. The other account, here `Expenses:Groceries`, is the
*balancing account*, though I also refer to it as the *target account*. The
real-life entity associated with the balancing account, here "Aldi Supermarket"
is often called the payee, but since I general [...]
+For ease of reference, I will use the following terms to refer to the various
parts of the entry. The account associated with the bank account for the CSV
file is called the *base* account. In the example here, it is
`Assets:Checkings`. The other account, here `Expenses:Groceries`, is the
*balancing account*, though I also refer to it as the *target account*. The
real-life entity associated with the balancing account, here "Aldi Supermarket"
is often called the payee, but since I general [...]
Not indicated in the above example is the *effective* date (also called
*posted*). This is the date that may follow the booking date, separated by an
equal sign:
@@ -33,7 +33,10 @@ If you have this information in your CSV file, you can use
it and add it to the
## Setup ##
-At the very least, you will need to set two user options: `c2l-base-account`
and `c2l-csv-columns`. `c2l-base-account` is the account that represents your
bank account in your ledger file. By default, it is set to `Assets:Checking`.
`c2l-csv-columns` is a list of column names representing the columns in your
CSV file. The following column names are meaningful to `csv2ledger:`
+At the very least, you will need to set two user options: `c2l-base-account`
and `c2l-csv-columns`. `c2l-base-account` is the account that represents your
bank account in your ledger file. By default, it is set to the value
`"Assets:Checking"`.
+
+
+`c2l-csv-columns` is a list of column labels representing the columns in your
CSV file. Note that these column labels should **not** be set to the column
names in your CSV file. Rather, they should indicate to `csv2ledger` what type
of data each column contains. The following column names are meaningful to
`csv2ledger`:
- `date`: booking date of the transaction
- `posted`: effective date of the transaction
@@ -44,7 +47,7 @@ At the very least, you will need to set two user options:
`c2l-base-account` and
- `credit`: the amount received
- `debit`: the amount payed
-Note that the column names are symbols. In the default setup, all these fields
may be used to create the Ledger entry, though some of them are only used in
specific circumstances.
+In the default setup, all these fields may be used to create the Ledger entry,
though some of them are only used in specific circumstances.
First, `payee` and `sender` never appear both. By default, `payee` is used as
the title of the ledger entry and `sender` is ignored. If you set the option
`c2l-account-holder` however, the `sender` will be used as the title for
transactions in which you are the payee, i.e., when you receive money. If you
do not have a `sender` field in your CSV files, you may simply leave it out. In
that case, the `payee` will always be used as the title, at least in the
default setup.
@@ -58,7 +61,11 @@ Note that `c2l-csv-columns` should contain a column name for
each column in your
(setq c2l-csv-columns '(date _ type description sender payee amount _))
```
-Note that I have a `type` field in this list. In my CSV files, this field
indicates whether the transaction is a bank transfer, an ATM withdrawal, a card
payment at a store, etc. By default, `csv2ledger` itself does not do anything
with the `type` field, but with some additional configuration, you can make use
of such extra information in several ways, as discussed below.
+If you set `c2l-csv-columns` in your init file, keep in mind that the column
labels are symbols, not strings.
+
+Note that I have a `type` field in this list, which is not in the list of
"meaningful" fields just above. You can, in fact, add any field to
`c2l-csv-columns` that you like. By default, `csv2ledger` does not do anything
with such user-defined fields, but with some additional configuration, you can
make use of them in several ways, as discussed below.
+
+In my CSV files, for example, the `type` column indicates whether the
transaction is a bank transfer, an ATM withdrawal, a card payment at a store,
etc. I use this information to capture ATM withdrawals, as discussed below.
## Running the conversion ##
@@ -87,13 +94,13 @@ The matchers are simple substrings, not regular
expressions. I have not found th
("\\(?:restaurant\\)" . "Expenses:Leasure:Restaurant"))
```
-`c2l-account-regexps` is not a customisable option, because normally the
variable is set based on the contents of the account matchers file. If you set
it to a value yourself though, `csv2ledger` will not overwrite it. (Just make
sure the value is set before calling any functions from `csv2ledger`.)
+`c2l-account-regexps` is not a customisable option, because normally the
variable is set based on the contents of the account matchers file. If you set
it to a value yourself though, `csv2ledger` will not overwrite it. (Just make
sure the value is set before calling any functions from `csv2ledger`, and keep
in mind that if you have multiple regexes matching a transaction, the first
regex that matches wins out.)
-When `c2l-account-regexes` is compiled from the account matchers file, each
account has only one entry in the alist, but this is not a requirement. You can
have multiple regexes pointing to the same account. Note that if you have
multiple regexes matching a transaction the first regex that matches wins out.
+When `c2l-account-regexes` is compiled from the account matchers file, each
account has only one entry in the alist, but this is not a requirement. You can
have multiple regexes pointing to the same account.
By default, only the `payee` and `description` fields are compared against the
account matchers. This can be configured with the option
`c2l-target-match-fields`. Its default value is `(payee description)`, but you
can add other fields to it. In fact, I set it to the value `(description payee
sender type)`.
-Two things are of note here: first, the order of this list determines the
order in which the fields get checked. I prefer for the `description` field to
be checked first, because it tends to contain more information than the `payee`
field. Second, I added the `type` field to the list. As already mentioned,
`csv2ledger` does not do anything with this field, but I include it
`c2l-csv-columns` and I use it here to match the target account. Specifically,
I use it to capture ATM withdrawals a [...]
+Two things are of note here: first, the order of this list determines the
order in which the fields get checked. I prefer for the `description` field to
be checked first, because it tends to contain more information than the `payee`
field. Second, I added the `type` field to the list. As already mentioned,
`csv2ledger` does not do anything with this field, but I include it in
`c2l-csv-columns` and I use it here to match the target account. Specifically,
I use it to capture ATM withdrawal [...]
Note that there is another way to automatically recognise an account, which
involves writing your own function to do the recognition. This option is
discussed below.
@@ -156,9 +163,9 @@ And add it to `c2l-field-modify-functions` as follows:
### Modifying the transaction ###
-One potential disadvantage of the functions in `c2l-field-modify-functions` is
that they only take the value of a single field as argument. This is
insufficient if you want to modify a field value on the basis of the other
fields in the transaction. If you need to make such a change to the
transaction, you can set the option `c2l-transaction-modify-function` to a
function that takes the entire transaction as its argument and returns a
modified transaction.
+One potential disadvantage of the functions in `c2l-field-modify-functions` is
that they only take the value of a single field as argument. This is
insufficient if you want to modify a field value on the basis of the other
fields in the transaction. If you need to make such a change to the
transaction, you can set the option `c2l-transaction-modify-functions` to a
list of functions that take the entire transaction as its argument and return a
modified transaction.
-The transaction will be passed as an alist of field-value pairs. For example,
for the ledger entry shown above, the transaction would be something like this:
+The transaction is passed as an alist of field-value pairs. For example, for
the ledger entry shown above, the transaction would be as follows:
```
((date . "2022-20-17")
@@ -179,7 +186,7 @@ The default value of `c2l-transaction-modify-functions`
contains three functions
### Setting the title ###
-As explained above, by default, `cs2vledger` uses the payee for the title of
the ledger entry. (In fact, the ledger documentation tends to use the term
*payee* for what I call the title.) It will use the sender as the title if the
user option `c2l-account-holder` matches the payee, provided that option is set.
+As explained above, by default, `cs2vledger` uses the payee for the title of
the ledger entry. However, it will use the sender as the title instead if the
user option `c2l-account-holder` matches the payee, provided that option is set.
The particular function that takes care of this is `c2l-create-title` and it
is the first function in `c2l-transaction-modify-functions`. You can replace it
with a custom function if you want to construct the title differently.
@@ -200,5 +207,5 @@ The third function in `c2l-transaction-modify-functions` is
`c2l-create-account`
### Creating the entry ###
-After all modification functions have been called, the resulting transaction
is passed to the function in `c2l-entry-function` . The default value of this
option is the function `c2l-compose-entry`, which creates entries in the form
shown above. If that format does not suit your needs, you can use a custom
function instead. It should take the transaction as an alist and return a
string that can be inserted into a ledger buffer.
+After all modification functions have been called, the resulting transaction
is passed to the function pointed to by the user option `c2l-entry-function` .
The default value of this option is the function `c2l-compose-entry`, which
creates entries in the form shown above. If that format does not suit your
needs, you can use a custom function instead. It should take the transaction as
an alist and return a string that can be inserted into a ledger buffer.
