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

;update manuals

Browse Source
This commit is contained in:
Simon Michael 2020-10-25 18:50:17 -10:00
parent d42070ee87
commit 8b97d31db4
3 changed files with 164 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
hledger-lib/hledger_csv.5
View File

@ -1087,31 +1087,80 @@ If an amount value begins with a plus sign, that will be removed
.SS Setting currency/commodity
.PP
If the currency/commodity symbol is included in the CSV\[aq]s amount
field(s), you don\[aq]t have to do anything special.
.PP
If the currency is provided as a separate CSV field, you can either:
.IP \[bu] 2
assign that to \f[C]currency\f[R], which adds it to all posting amounts.
The symbol will prepended to the amount quantity (on the left side).
If you write a trailing space after the symbol, there will be a space
between symbol and amount (an exception to the usual whitespace
stripping).
.IP \[bu] 2
or assign it to \f[C]currencyN\f[R] which adds it to posting N\[aq]s
amount only.
.IP \[bu] 2
or for more control, construct the amount from symbol and quantity using
field assignment, eg:
.RS 2
field(s):
.IP
.nf
\f[C]
fields date,description,currency,quantity
# add currency symbol on the right:
amount %quantity %currency
2020-01-01,foo,$123.00
\f[R]
.fi
.RE
.PP
you don\[aq]t have to do anything special for the commodity symbol, it
will be assigned as part of the amount.
Eg:
.IP
.nf
\f[C]
fields date,description,amount
\f[R]
.fi
.IP
.nf
\f[C]
2020-01-01 foo
expenses:unknown $123.00
income:unknown $-123.00
\f[R]
.fi
.PP
If the currency is provided as a separate CSV field:
.IP
.nf
\f[C]
2020-01-01,foo,USD,123.00
\f[R]
.fi
.PP
You can assign that to the \f[C]currency\f[R] pseudo-field, which has
the special effect of prepending itself to every amount in the
transaction (on the left, with no separating space):
.IP
.nf
\f[C]
fields date,description,currency,amount
\f[R]
.fi
.IP
.nf
\f[C]
2020-01-01 foo
expenses:unknown USD123.00
income:unknown USD-123.00
\f[R]
.fi
.PP
Or, you can use a field assignment to construct the amount yourself,
with more control.
Eg to put the symbol on the right, and separated by a space:
.IP
.nf
\f[C]
fields date,description,cur,amt
amount %amt %cur
\f[R]
.fi
.IP
.nf
\f[C]
2020-01-01 foo
expenses:unknown 123.00 USD
income:unknown -123.00 USD
\f[R]
.fi
.PP
Note we used temporary field names \f[C]cur\f[R] (and \f[C]amt\f[R]) -
not \f[C]currency\f[R], since in this case we don\[aq]t want to trigger
that name\[aq]s special effect.
.SS Referencing other fields
.PP
In field assignments, you can interpolate only CSV fields, not hledger

58
hledger-lib/hledger_csv.info
View File

@ -1049,25 +1049,47 @@ File: hledger_csv.info, Node: Setting currency/commodity, Next: Referencing ot
==============================
If the currency/commodity symbol is included in the CSV's amount
field(s), you don't have to do anything special.
field(s):
If the currency is provided as a separate CSV field, you can either:
2020-01-01,foo,$123.00
* assign that to 'currency', which adds it to all posting amounts.
The symbol will prepended to the amount quantity (on the left
side). If you write a trailing space after the symbol, there will
be a space between symbol and amount (an exception to the usual
whitespace stripping).
you don't have to do anything special for the commodity symbol, it
will be assigned as part of the amount. Eg:
* or assign it to 'currencyN' which adds it to posting N's amount
only.
fields date,description,amount
* or for more control, construct the amount from symbol and quantity
using field assignment, eg:
2020-01-01 foo
expenses:unknown $123.00
income:unknown $-123.00
fields date,description,currency,quantity
# add currency symbol on the right:
amount %quantity %currency
If the currency is provided as a separate CSV field:
2020-01-01,foo,USD,123.00
You can assign that to the 'currency' pseudo-field, which has the
special effect of prepending itself to every amount in the transaction
(on the left, with no separating space):
fields date,description,currency,amount
2020-01-01 foo
expenses:unknown USD123.00
income:unknown USD-123.00
Or, you can use a field assignment to construct the amount yourself,
with more control. Eg to put the symbol on the right, and separated by
a space:
fields date,description,cur,amt
amount %amt %cur
2020-01-01 foo
expenses:unknown 123.00 USD
income:unknown -123.00 USD
Note we used temporary field names 'cur' (and 'amt') - not
'currency', since in this case we don't want to trigger that name's
special effect.

File: hledger_csv.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Setting currency/commodity, Up: TIPS
@ -1224,10 +1246,10 @@ Node: Setting amounts34895
Ref: #setting-amounts35064
Node: Setting currency/commodity36051
Ref: #setting-currencycommodity36243
Node: Referencing other fields37046
Ref: #referencing-other-fields37246
Node: How CSV rules are evaluated38143
Ref: #how-csv-rules-are-evaluated38316
Node: Referencing other fields37423
Ref: #referencing-other-fields37623
Node: How CSV rules are evaluated38520
Ref: #how-csv-rules-are-evaluated38693

End Tag Table

88
hledger-lib/hledger_csv.txt
View File

@ -804,29 +804,51 @@ TIPS
Setting currency/commodity
If the currency/commodity symbol is included in the CSV's amount
field(s), you don't have to do anything special.
field(s):
If the currency is provided as a separate CSV field, you can either:
2020-01-01,foo,$123.00
o assign that to currency, which adds it to all posting amounts. The
symbol will prepended to the amount quantity (on the left side). If
you write a trailing space after the symbol, there will be a space
between symbol and amount (an exception to the usual whitespace
stripping).
you don't have to do anything special for the commodity symbol, it will
be assigned as part of the amount. Eg:
o or assign it to currencyN which adds it to posting N's amount only.
fields date,description,amount
o or for more control, construct the amount from symbol and quantity
using field assignment, eg:
2020-01-01 foo
expenses:unknown $123.00
income:unknown $-123.00
fields date,description,currency,quantity
# add currency symbol on the right:
amount %quantity %currency
If the currency is provided as a separate CSV field:
2020-01-01,foo,USD,123.00
You can assign that to the currency pseudo-field, which has the special
effect of prepending itself to every amount in the transaction (on the
left, with no separating space):
fields date,description,currency,amount
2020-01-01 foo
expenses:unknown USD123.00
income:unknown USD-123.00
Or, you can use a field assignment to construct the amount yourself,
with more control. Eg to put the symbol on the right, and separated by
a space:
fields date,description,cur,amt
amount %amt %cur
2020-01-01 foo
expenses:unknown 123.00 USD
income:unknown -123.00 USD
Note we used temporary field names cur (and amt) - not currency, since
in this case we don't want to trigger that name's special effect.
Referencing other fields
In field assignments, you can interpolate only CSV fields, not hledger
fields. In the example below, there's both a CSV field and a hledger
field named amount1, but %amount1 always means the CSV field, not the
In field assignments, you can interpolate only CSV fields, not hledger
fields. In the example below, there's both a CSV field and a hledger
field named amount1, but %amount1 always means the CSV field, not the
hledger field:
# Name the third CSV field "amount1"
@ -838,7 +860,7 @@ TIPS
# Set comment to the CSV amount1 (not the amount1 assigned above)
comment %amount1
Here, since there's no CSV amount1 field, %amount1 will produce a lit-
Here, since there's no CSV amount1 field, %amount1 will produce a lit-
eral "amount1":
fields date,description,csvamount
@ -846,7 +868,7 @@ TIPS
# Can't interpolate amount1 here
comment %amount1
When there are multiple field assignments to the same hledger field,
When there are multiple field assignments to the same hledger field,
only the last one takes effect. Here, comment's value will be be B, or
C if "something" is matched, but never A:
@ -856,14 +878,14 @@ TIPS
comment C
How CSV rules are evaluated
Here's how to think of CSV rules being evaluated (if you really need
Here's how to think of CSV rules being evaluated (if you really need
to). First,
o include - all includes are inlined, from top to bottom, depth first.
(At each include point the file is inlined and scanned for further
o 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 re-
Then "global" rules are evaluated, top to bottom. If a rule is re-
peated, the last one wins:
o skip (at top level)
@ -877,30 +899,30 @@ TIPS
Then for each CSV record in turn:
o test all if blocks. If any of them contain a end rule, skip all re-
maining CSV records. Otherwise if any of them contain a skip rule,
skip that many CSV records. If there are multiple matched skip
o test all if blocks. If any of them contain a end rule, skip all re-
maining 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.
o collect all field assignments at top level and in matched if blocks.
When there are multiple assignments for a field, keep only the last
o 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.
o compute a value for each hledger field - either the one that was as-
o compute a value for each hledger field - either the one that was as-
signed to it (and interpolate the %CSVFIELDNAME references), or a de-
fault
o generate a synthetic hledger transaction from these values.
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
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.
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -914,7 +936,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)