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

;csv: doc: cleanups

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-11-06 18:42:39 -08:00
parent 7ecc42f142
commit 6e951962f9
1 changed files with 24 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -124,7 +124,7 @@ HLEDGERFIELDNAME FIELDVALUE
Instead of or in addition to a [fields list](#fields), you can Instead of or in addition to a [fields list](#fields), you can
assign a value to a hledger field by writing its name assign a value to a hledger field by writing its name
(any of the standard names above) followed by a text value. (any of the standard names above) followed by a text value.
The value may contain interpolated CSV fields, The value may contain interpolated CSV fields ([only](#referencing-other-fields)),
referenced by their 1-based position in the CSV record (`%N`), referenced by their 1-based position in the CSV record (`%N`),
or by the name they were given in the fields list (`%CSVFIELDNAME`). or by the name they were given in the fields list (`%CSVFIELDNAME`).
Eg: Eg:
@ -139,8 +139,6 @@ comment note: %somefield - %anotherfield, date: %1
Interpolation strips any outer whitespace, so a CSV value like `" 1 "` Interpolation strips any outer whitespace, so a CSV value like `" 1 "`
becomes `1` when interpolated becomes `1` when interpolated
([#1051](https://github.com/simonmichael/hledger/issues/1051)). ([#1051](https://github.com/simonmichael/hledger/issues/1051)).
Note you can only interpolate CSV fields, not the hledger fields being assigned to;
for more on this, see [TIPS](#tips).
## `date-format` ## `date-format`
@ -376,10 +374,11 @@ A posting amount can be set in one of these ways:
setting the amount indirectly via a setting the amount indirectly via a
[balance assignment](journal.html#balance-assignments). [balance assignment](journal.html#balance-assignments).
There is some special handling for sign in amounts: There is some special handling for an amount's sign:
- If an amount value is parenthesised, it will be de-parenthesised and sign-flipped. - If an amount value is parenthesised, it will be de-parenthesised and sign-flipped.
- If an amount value begins with a double minus sign, those cancel out and are removed. - If an amount value begins with a double minus sign, those cancel out and are removed.
- If an amount value begins with a plus sign, that will 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,
you can assign it to `currency` (affects all posting amounts) or `currencyN` (affects just posting N's amount). you can assign it to `currency` (affects all posting amounts) or `currencyN` (affects just posting N's amount).
@ -429,28 +428,36 @@ if something
## How CSV rules are evaluated ## How CSV rules are evaluated
Here's how to think of CSV rules being evaluated (if you really need to). First, Here's how to think of CSV rules being evaluated (if you really need to).
First,
- include - all includes are inlined, from top to bottom, depth first. (At each include point the file is inlined and scanned for further includes, before proceeding.) - `include` - all includes are inlined, from top to bottom, depth
first. (At each include point the file is inlined and scanned for
further includes, recursively, before proceeding.)
Then "global" rules are evaluated, top to bottom. If a rule is repeated, the last one wins: Then "global" rules are evaluated, top to bottom. If a rule is
repeated, the last one wins:
- skip (at top level) - `skip` (at top level)
- date-format - `date-format`
- newest-first - `newest-first`
- fields - names the CSV fields, optionally sets up initial assignments to hledger fields - `fields` - names the CSV fields, optionally sets up initial assignments to hledger fields
Then for each CSV record in turn: Then for each CSV record in turn:
- test all `if` blocks. If any of them contain a `end` rule, skip all remaining CSV records. - test all `if` blocks. If any of them contain a `end` rule, skip all remaining CSV records.
Otherwise if any of them contain a `skip` rule, skip that many CSV records. Otherwise if any of them contain a `skip` rule, skip that many CSV records.
If there are multiple matched skip rules, the first one wins. If there are multiple matched `skip` rules, the first one wins.
- collect all field assignments at top level and in matched if blocks. - collect all field assignments at top level and in matched `if` blocks.
When there are multiple assignments for a field, keep only the last one. When there are multiple assignments for a field, keep only the last one.
- compute a value for each hledger field - either the one that was assigned to it - compute a value for each hledger field - either the one that was assigned to it
(and interpolate the %CSVFIELDNAME references), or a default (and interpolate the %CSVFIELDNAME references), or a default
- generate a synthetic hledger transaction from these values, - generate a synthetic hledger transaction from these values.
which becomes part of the input to the hledger command that has been selected
This is all part of the CSV reader, one of several readers hledger can
use to parse input files. When all files have been read successfully,
the transactions are passed as input to whichever hledger command the
user specified.
## Valid transactions ## Valid transactions
@ -461,9 +468,8 @@ transactions. Or, amounts may not be displayed with a canonical
display style. display style.
So when setting up or adjusting CSV rules, you should check your So when setting up or adjusting CSV rules, you should check your
results visually with the print command. You can pipe print's output results visually with the print command. You can also pipe the output
through hledger once more to validate and canonicalise fully. through hledger once more to fully validate and canonicalise it:
Eg:
```shell ```shell
$ hledger -f some.csv print | hledger -f- print -I $ hledger -f some.csv print | hledger -f- print -I