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 .SS Setting currency/commodity
.PP .PP
If the currency/commodity symbol is included in the CSV\[aq]s amount If the currency/commodity symbol is included in the CSV\[aq]s amount
field(s), you don\[aq]t have to do anything special. field(s):
.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
.IP .IP
.nf .nf
\f[C] \f[C]
fields date,description,currency,quantity 2020-01-01,foo,$123.00
# add currency symbol on the right:
amount %quantity %currency
\f[R] \f[R]
.fi .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 .SS Referencing other fields
.PP .PP
In field assignments, you can interpolate only CSV fields, not hledger 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 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. you don't have to do anything special for the commodity symbol, it
The symbol will prepended to the amount quantity (on the left will be assigned as part of the amount. Eg:
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).
* or assign it to 'currencyN' which adds it to posting N's amount fields date,description,amount
only.
* or for more control, construct the amount from symbol and quantity 2020-01-01 foo
using field assignment, eg: expenses:unknown $123.00
income:unknown $-123.00
fields date,description,currency,quantity If the currency is provided as a separate CSV field:
# add currency symbol on the right:
amount %quantity %currency 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 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 Ref: #setting-amounts35064
Node: Setting currency/commodity36051 Node: Setting currency/commodity36051
Ref: #setting-currencycommodity36243 Ref: #setting-currencycommodity36243
Node: Referencing other fields37046 Node: Referencing other fields37423
Ref: #referencing-other-fields37246 Ref: #referencing-other-fields37623
Node: How CSV rules are evaluated38143 Node: How CSV rules are evaluated38520
Ref: #how-csv-rules-are-evaluated38316 Ref: #how-csv-rules-are-evaluated38693
 
End Tag Table End Tag Table

88
hledger-lib/hledger_csv.txt
View File

@ -804,29 +804,51 @@ TIPS
Setting currency/commodity Setting currency/commodity
If the currency/commodity symbol is included in the CSV's amount 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 you don't have to do anything special for the commodity symbol, it will
symbol will prepended to the amount quantity (on the left side). If be assigned as part of the amount. Eg:
you write a trailing space after the symbol, there will be a space
between symbol and amount (an exception to the usual whitespace
stripping).
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 2020-01-01 foo
using field assignment, eg: expenses:unknown $123.00
income:unknown $-123.00
fields date,description,currency,quantity If the currency is provided as a separate CSV field:
# add currency symbol on the right:
amount %quantity %currency 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 Referencing other fields
In field assignments, you can interpolate only CSV fields, not hledger 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 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 field named amount1, but %amount1 always means the CSV field, not the
hledger field: hledger field:
# Name the third CSV field "amount1" # Name the third CSV field "amount1"
@ -838,7 +860,7 @@ TIPS
# Set comment to the CSV amount1 (not the amount1 assigned above) # Set comment to the CSV amount1 (not the amount1 assigned above)
comment %amount1 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": eral "amount1":
fields date,description,csvamount fields date,description,csvamount
@ -846,7 +868,7 @@ TIPS
# Can't interpolate amount1 here # Can't interpolate amount1 here
comment %amount1 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 only the last one takes effect. Here, comment's value will be be B, or
C if "something" is matched, but never A: C if "something" is matched, but never A:
@ -856,14 +878,14 @@ TIPS
comment C comment C
How CSV rules are evaluated 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, to). First,
o include - all includes are inlined, from top to bottom, depth 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 (At each include point the file is inlined and scanned for further
includes, recursively, before proceeding.) 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: peated, the last one wins:
o skip (at top level) o skip (at top level)
@ -877,30 +899,30 @@ TIPS
Then for each CSV record in turn: Then for each CSV record in turn:
o test all if blocks. If any of them contain a end rule, skip all re- 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, maining CSV records. Otherwise if any of them contain a skip rule,
skip that many CSV records. If there are multiple matched skip skip that many CSV records. If there are multiple matched skip
rules, the first one wins. rules, the first one wins.
o collect all field assignments at top level and in matched if blocks. 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 When there are multiple assignments for a field, keep only the last
one. 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- signed to it (and interpolate the %CSVFIELDNAME references), or a de-
fault fault
o generate a synthetic hledger transaction from these values. o generate a synthetic hledger transaction from these values.
This is all part of the CSV reader, one of several readers hledger can 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, use to parse input files. When all files have been read successfully,
the transactions are passed as input to whichever hledger command the the transactions are passed as input to whichever hledger command the
user specified. user specified.
REPORTING BUGS 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) or hledger mail list)
@ -914,7 +936,7 @@ COPYRIGHT
SEE ALSO 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- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) dot(5), ledger(1)