slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: proofreading csv parser docs

Browse Source
This commit is contained in:
Dmitry Astapov 2019-10-15 22:53:01 +01:00
parent 1ab8631264
commit cb6a5fc4a1
1 changed files with 28 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
hledger-lib/hledger_csv.m4.md
View File

@ -38,7 +38,7 @@ At minimum, the rules file must identify the date and amount fields.
It's often necessary to specify the date format, and the number of header lines to skip, also. It's often necessary to specify the date format, and the number of header lines to skip, also.
Eg: Eg:
``` ```
fields date, _, _, amount fields date, _, _, amount1
date-format %d/%m/%Y date-format %d/%m/%Y
skip 1 skip 1
``` ```
@ -55,7 +55,7 @@ A more complete example:
skip 1 skip 1
# name the csv fields (and assign the transaction's date, amount and code) # name the csv fields (and assign the transaction's date, amount and code)
fields date, _, toorfrom, name, amzstatus, amount, fees, code fields date, _, toorfrom, name, amzstatus, amount1, fees, code
# how to parse the date # how to parse the date
date-format %b %-d, %Y date-format %b %-d, %Y
@ -64,7 +64,7 @@ date-format %b %-d, %Y
description %toorfrom %name description %toorfrom %name
# save these fields as tags # save these fields as tags
comment status:%amzstatus, fees:%fees comment status:%amzstatus
# set the base account for all transactions # set the base account for all transactions
account1 assets:amazon account1 assets:amazon
@ -72,6 +72,9 @@ account1 assets:amazon
# flip the sign on the amount # flip the sign on the amount
amount -%amount amount -%amount
# Put fees in a separate posting
amount3 %fees
comment3 fees
``` ```
For more examples, see [Convert CSV files](https://github.com/simonmichael/hledger/wiki/Convert-CSV-files). For more examples, see [Convert CSV files](https://github.com/simonmichael/hledger/wiki/Convert-CSV-files).
@ -140,7 +143,7 @@ An assignment to any of `accountN`, `amountN`, `amountN-in`, `amountN-out`, `bal
Fields `amount`, `amount-in`, `amount-out`, `currency`, `balance` and `comment` are treated as aliases for `amount1`, and so on. If your rules file leads to both aliased fields having different values, `hledger` will raise an error. Fields `amount`, `amount-in`, `amount-out`, `currency`, `balance` and `comment` are treated as aliases for `amount1`, and so on. If your rules file leads to both aliased fields having different values, `hledger` will raise an error.
You need to provide enough information to create at least two postings. You need to provide enough information to create at least one posting.
Eg: Eg:
```rules ```rules
@ -150,7 +153,7 @@ Eg:
# CSV field: # CSV field:
# 1 2 3 4 5 6 7 8 # 1 2 3 4 5 6 7 8
# entry field: # entry field:
fields date, description, , amount, , , somefield, anotherfield fields date, description, , amount1, , , somefield, anotherfield
``` ```
## field assignment ## field assignment
@ -178,12 +181,20 @@ Note, interpolation strips any outer whitespace, so a CSV value like
## conditional block ## conditional block
`if` *`PATTERN`*\ `if` *`PATTERN`*\
    *`FIELDASSIGNMENTS` or `skip N` or `skip end`*...     *`FIELDASSIGNMENTS`*...
`if`\ `if`\
*`PATTERN`*\ *`PATTERN`*\
*`PATTERN`*...\ *`PATTERN`*...\
    *`FIELDASSIGNMENTS` or `skip N` or `skip end`*...     *`FIELDASSIGNMENTS`*...
`if` *`PATTERN`*\
*`PATTERN`*...\
    *`skip N`*...
`if` *`PATTERN`*\
*`PATTERN`*...\
    *`skip end`*...
This applies one or more field assignments, only to those CSV records matched by one of the PATTERNs. This applies one or more field assignments, only to those CSV records matched by one of the PATTERNs.
The patterns are case-insensitive regular expressions which match anywhere The patterns are case-insensitive regular expressions which match anywhere
@ -192,7 +203,7 @@ specific field). When there are multiple patterns they can be written
on separate lines, unindented. on separate lines, unindented.
The field assignments are on separate lines indented by at least one space. The field assignments are on separate lines indented by at least one space.
Instead of field assignments you can specify `skip N` to skip the next N records (including the one that matchied). Special form `skip end` will cause the rest of the file to be skipped. Instead of field assignments you can specify `skip N` to skip the next N records (including the one that matchied) or `skip end` to skip the rest of the file.
Examples: Examples:
```rules ```rules
@ -242,22 +253,21 @@ The order of same-day entries will be preserved
## CSV accounts ## CSV accounts
Each journal entry will have two [postings](journal.html#postings), to `account1` and `account2` respectively. Each journal entry will have at least two [postings](journal.html#postings), to `account1` and some other account (usually `account2`).
It's not yet possible to generate entries with more than two postings.
It's conventional and recommended to use `account1` for the account whose CSV we are reading. It's conventional and recommended to use `account1` for the account whose CSV we are reading.
## CSV amounts ## CSV amounts
A transaction [amount](journal.html#amounts) must be set, in one of these ways: A posting [amount](journal.html#amounts) could be set in one of these ways:
- with an `amount` or `amount1` field assignment, which sets the first posting's amount - with an `amountN` field assignment, which sets the Nth posting's amount
- (When the CSV has debit and credit amounts in separate fields:)\ - (When the CSV has debit and credit amounts in separate fields:)\
with field assignments for the `amount-in` and `amount-out` (or `amount1-in` and `amount1-out`) pseudo with field assignments for the `amountN-in` and `amountN-out` pseudo
fields (both of them). Whichever one has a value will be used, with fields (both of them). Whichever one has a value will be used, with
appropriate sign. If both contain a value, it might not work so well. appropriate sign. If both contain a value, it might not work so well.
- or implicitly by means of a [balance assignment](journal.html#balance-assignments) (see below). - with `balanceN` field assignment that creates a [balance assignment](journal.html#balance-assignments) (see below).
There is some special handling for sign in amounts: There is some special handling for sign in amounts:
@ -265,13 +275,13 @@ There is some special handling for sign in amounts:
- If an amount value begins with a double minus sign, those will cancel out and be removed. - If an amount value begins with a double minus sign, those will cancel out and be removed.
If the currency/commodity symbol is provided as a separate CSV field, If the currency/commodity symbol is provided as a separate CSV field,
assign it to the `currency` pseudo field; the symbol will be prepended assign it to the `currency` pseudo field (applicable to the whole transaction) or `currencyN` (applicable to Nth posting only); the symbol will be prepended
to the amount to the amount
(TODO: <s>when there is an amount</s>). (TODO: <s>when there is an amount</s>).
Or, you can use an `amount` [field assignment](#field-assignment) for more control, eg: Or, you can use an `amountN` [field assignment](#field-assignment) for more control, eg:
``` ```
fields date,description,currency,amount fields date,description,currency,amount_
amount %amount %currency amount1 %amount_ %currency
``` ```
## CSV balance assertions/assignments ## CSV balance assertions/assignments