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 2021-06-26 00:06:14 -10:00
parent 6a1bfe47ba
commit fcebdfe0cc
3 changed files with 1303 additions and 1057 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

278
hledger/hledger.1
View File

@ -5263,6 +5263,12 @@ With this scheme, you would use \f[C]-PC\f[R] to see the current balance
at your bank, \f[C]-U\f[R] to see things which will probably hit your at your bank, \f[C]-U\f[R] to see things which will probably hit your
bank soon (like uncashed checks), and no flags to see the most bank soon (like uncashed checks), and no flags to see the most
up-to-date state of your finances. up-to-date state of your finances.
.SS Code
.PP
After the status mark, but before the description, you can optionally
write a transaction \[dq]code\[dq], enclosed in parentheses.
This is a good place to record a check number, or some other important
transaction id or reference number.
.SS Description .SS Description
.PP .PP
A transaction\[aq]s description is the rest of the line following the A transaction\[aq]s description is the rest of the line following the
@ -6395,28 +6401,26 @@ rate between two commodities on a certain date.
often obtained from a stock exchange, cryptocurrency exchange, or the often obtained from a stock exchange, cryptocurrency exchange, or the
foreign exchange market. foreign exchange market.
.PP .PP
Here is the format: The format is:
.IP .IP
.nf .nf
\f[C] \f[C]
P DATE COMMODITYA COMMODITYBAMOUNT P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT
\f[R] \f[R]
.fi .fi
.IP \[bu] 2
DATE is a simple date
.IP \[bu] 2
COMMODITYA is the symbol of the commodity being priced
.IP \[bu] 2
COMMODITYBAMOUNT is an amount (symbol and quantity) in a second
commodity, giving the price in commodity B of one unit of commodity A.
.PP .PP
These two market price directives say that one euro was worth 1.35 US DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity
dollars during 2009, and $1.40 from 2010 onward: being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity)
of commodity 2 that one unit of commodity 1 is worth on this date.
Examples:
.IP .IP
.nf .nf
\f[C] \f[C]
P 2009/1/1 \[Eu] $1.35 # one euro was worth $1.35 from 2009-01-01 onward:
P 2010/1/1 \[Eu] $1.40 P 2009-01-01 \[Eu] $1.35
# and $1.40 from 2010-01-01 onward:
P 2010-01-01 \[Eu] $1.40
\f[R] \f[R]
.fi .fi
.PP .PP
@ -7212,14 +7216,14 @@ below, after the examples:
.PP .PP
.TS .TS
tab(@); tab(@);
lw(30.1n) lw(39.9n). lw(26.4n) lw(43.6n).
T{ T{
\f[B]\f[CB]skip\f[B]\f[R] \f[B]\f[CB]skip\f[B]\f[R]
T}@T{ T}@T{
skip one or more header lines or matched CSV records skip one or more header lines or matched CSV records
T} T}
T{ T{
\f[B]\f[CB]fields\f[B]\f[R] \f[B]\f[CB]fields\f[B] list\f[R]
T}@T{ T}@T{
name CSV fields, assign them to hledger fields name CSV fields, assign them to hledger fields
T} T}
@ -7229,6 +7233,11 @@ T}@T{
assign a value to one hledger field, with interpolation assign a value to one hledger field, with interpolation
T} T}
T{ T{
\f[B]Field names\f[R]
T}@T{
hledger field names, used in the fields list and field assignments
T}
T{
\f[B]\f[CB]separator\f[B]\f[R] \f[B]\f[CB]separator\f[B]\f[R]
T}@T{ T}@T{
a custom field separator a custom field separator
@ -7633,7 +7642,7 @@ whenever your CSV data contains header lines.
.PP .PP
It also has a second purpose: it can be used inside if blocks to ignore It also has a second purpose: it can be used inside if blocks to ignore
certain CSV records (described below). certain CSV records (described below).
.SS \f[C]fields\f[R] .SS \f[C]fields\f[R] list
.IP .IP
.nf .nf
\f[C] \f[C]
@ -7644,13 +7653,14 @@ fields FIELDNAME1, FIELDNAME2, ...
A fields list (the word \[dq]fields\[dq] followed by comma-separated A fields list (the word \[dq]fields\[dq] followed by comma-separated
field names) is the quick way to assign CSV field values to hledger field names) is the quick way to assign CSV field values to hledger
fields. fields.
It does two things: (The other way is field assignments, see below.) A fields list does does
two things:
.IP "1." 3 .IP "1." 3
it names the CSV fields. It names the CSV fields.
This is optional, but can be convenient later for interpolating them. This is optional, but can be convenient later for interpolating them.
.IP "2." 3 .IP "2." 3
when you use a standard hledger field name, it assigns the CSV value to Whenever you use a standard hledger field name (defined below), the CSV
that part of the hledger transaction. value is assigned to that part of the hledger transaction.
.PP .PP
Here\[aq]s an example that says \[dq]use the 1st, 2nd and 4th fields as Here\[aq]s an example that says \[dq]use the 1st, 2nd and 4th fields as
the transaction\[aq]s date, description and amount; name the last two the transaction\[aq]s date, description and amount; name the last two
@ -7662,91 +7672,27 @@ fields date, description, , amount, , , somefield, anotherfield
\f[R] \f[R]
.fi .fi
.PP .PP
Field names may not contain whitespace. Tips:
Fields you don\[aq]t care about can be left unnamed. .IP \[bu] 2
Currently there must be least two items (there must be at least one The fields list always use commas, even if your CSV data uses another
comma).
.PP
Note, always use comma in the fields list, even if your CSV uses another
separator character. separator character.
.PP .IP \[bu] 2
Here are the standard hledger field/pseudo-field names. Currently there must be least two items in the list (at least one
For more about the transaction parts they refer to, see the manual for comma).
hledger\[aq]s journal format. .IP \[bu] 2
.SS Transaction field names Field names may not contain spaces.
.PP Spaces before/after field names are optional.
\f[C]date\f[R], \f[C]date2\f[R], \f[C]status\f[R], \f[C]code\f[R], .IP \[bu] 2
\f[C]description\f[R], \f[C]comment\f[R] can be used to form the If the CSV contains column headings, it\[aq]s a good idea to use these,
transaction\[aq]s first line. suitably modified, as the basis for your field names (eg lower-cased,
.SS Posting field names with underscores instead of spaces).
.SS account .IP \[bu] 2
.PP If some heading names match standard hledger fields, but you don\[aq]t
\f[C]accountN\f[R], where N is 1 to 99, causes a posting to be want to set the hledger fields directly, alter those names, eg by
generated, with that account name. appending an underscore.
.PP .IP \[bu] 2
Most often there are two postings, so you\[aq]ll want to set Fields you don\[aq]t care about can be given a dummy name (eg:
\f[C]account1\f[R] and \f[C]account2\f[R]. \f[C]_\f[R] ), or no name.
Typically \f[C]account1\f[R] is associated with the CSV file, and is set
once with a top-level assignment, while \f[C]account2\f[R] is set based
on each transaction\[aq]s description, and in conditional blocks.
.PP
If a posting\[aq]s account name is left unset but its amount is set (see
below), a default account name will be chosen (like
\[dq]expenses:unknown\[dq] or \[dq]income:unknown\[dq]).
.SS amount
.PP
\f[C]amountN\f[R] sets the Nth posting\[aq]s amount.
By assigning to \f[C]amount1\f[R], \f[C]amount2\f[R], ...
etc.
you can generate up to 99 postings.
.PP
If the CSV uses separate fields for debits and credits (inflows and
outflows), you can use \f[C]amountN-in\f[R] and \f[C]amountN-out\f[R]
instead.
Note hledger assumes both of these fields are unsigned, and will
automatically negate the \[dq]-out\[dq] value.
If the fields are signed, see \[dq]Setting amounts\[dq] below.
.PP
There is also an unnumbered form of these names: \f[C]amount\f[R], or
\f[C]amount-in\f[R] and \f[C]amount-out\f[R].
This is supported to keep pre-hledger-1.17 CSV rules files working (and
for occasional convenience).
It is suitable only for two-posting transactions; it sets both posting
1\[aq]s and posting 2\[aq]s amount.
Posting 2\[aq]s amount will be negated, and also converted to cost if
there\[aq]s a transaction price.
.PP
If you have an existing rules file using the unnumbered form, you might
want to use the numbered form in certain conditional blocks, without
having to update and retest all the old rules.
To facilitate this, posting 1 ignores
\f[C]amount\f[R]/\f[C]amount-in\f[R]/\f[C]amount-out\f[R] if any of
\f[C]amount1\f[R]/\f[C]amount1-in\f[R]/\f[C]amount1-out\f[R] are
assigned, and posting 2 ignores them if any of
\f[C]amount2\f[R]/\f[C]amount2-in\f[R]/\f[C]amount2-out\f[R] are
assigned, avoiding conflicts.
.SS currency
.PP
If the CSV has the currency symbol in a separate field (ie, not part of
the amount field), you can use \f[C]currencyN\f[R] to prepend it to
posting N\[aq]s amount.
Or, \f[C]currency\f[R] with no number affects all postings.
.SS balance
.PP
\f[C]balanceN\f[R] sets a balance assertion amount (or if the posting
amount is left empty, a balance assignment) on posting N.
.PP
Also, for compatibility with hledger <1.17: \f[C]balance\f[R] with no
number is equivalent to \f[C]balance1\f[R].
.PP
You can adjust the type of assertion/assignment with the
\f[C]balance-type\f[R] rule (see below).
.SS comment
.PP
Finally, \f[C]commentN\f[R] sets a comment on the Nth posting.
Comments can also contain tags, as usual.
.PP
See TIPS below for more about setting amounts and currency.
.SS field assignment .SS field assignment
.IP .IP
.nf .nf
@ -7755,13 +7701,17 @@ HLEDGERFIELDNAME FIELDVALUE
\f[R] \f[R]
.fi .fi
.PP .PP
Instead of or in addition to a fields list, you can use a \[dq]field Field assignments are the more flexible way to assign CSV values to
assignment\[dq] rule to set the value of a single hledger field, by hledger fields.
writing its name (any of the standard hledger field names above) They can be used instead of or in addition to a fields list (see above).
followed by a text value. .PP
The value may contain interpolated CSV fields, referenced by their To assign a value to a hledger field, write the field name (any of the
1-based position in the CSV record (\f[C]%N\f[R]), or by the name they standard hledger field/pseudo-field names, defined below), a space,
were given in the fields list (\f[C]%CSVFIELDNAME\f[R]). followed by a text value on the same line.
This text value may interpolate CSV fields, referenced by their 1-based
position in the CSV record (\f[C]%N\f[R]), or by the name they were
given in the fields list (\f[C]%CSVFIELDNAME\f[R]).
.PP
Some examples: Some examples:
.IP .IP
.nf .nf
@ -7774,9 +7724,108 @@ comment note: %somefield - %anotherfield, date: %1
\f[R] \f[R]
.fi .fi
.PP .PP
Tips:
.IP \[bu] 2
Interpolation strips outer whitespace (so a CSV value like Interpolation strips outer whitespace (so a CSV value like
\f[C]\[dq] 1 \[dq]\f[R] becomes \f[C]1\f[R] when interpolated) (#1051). \f[C]\[dq] 1 \[dq]\f[R] becomes \f[C]1\f[R] when interpolated) (#1051).
See TIPS below for more about referencing other fields. .IP \[bu] 2
See also Tips below.
.SS Field names
.PP
Here are the standard hledger field (and pseudo-field) names, which you
can use in a fields list and in field assignments.
For more about the transaction parts they refer to, see Transactions.
.SS date field
.PP
Assigning to \f[C]date\f[R] sets the transaction date.
.SS date2 field
.PP
\f[C]date2\f[R] sets the transaction\[aq]s secondary date, if any.
.SS status field
.PP
\f[C]status\f[R] sets the transaction\[aq]s status, if any.
.SS code field
.PP
\f[C]code\f[R] sets the transaction\[aq]s code, if any.
.SS description field
.PP
\f[C]description\f[R] sets the transaction\[aq]s description, if any.
.SS comment field
.PP
\f[C]comment\f[R] sets the transaction\[aq]s comment, if any.
.PP
\f[C]commentN\f[R], where N is a number, sets the Nth posting\[aq]s
comment.
.PP
Tips: - Only single-line comments can be assigned.
- Comments can contain tags, as usual.
.SS account field
.PP
Assigning to \f[C]accountN\f[R], where N is 1 to 99, sets the account
name of the Nth posting, and causes that posting to be generated.
.PP
Most often there are two postings, so you\[aq]ll want to set
\f[C]account1\f[R] and \f[C]account2\f[R].
Typically \f[C]account1\f[R] is associated with the CSV file, and is set
once with a top-level assignment, while \f[C]account2\f[R] is set based
on each transaction\[aq]s description, and in conditional blocks.
.PP
If a posting\[aq]s account name is left unset but its amount is set (see
below), a default account name will be chosen (like
\[dq]expenses:unknown\[dq] or \[dq]income:unknown\[dq]).
.SS amount field
.PP
\f[C]amountN\f[R] sets the amount of the Nth posting, and causes that
posting to be generated.
By assigning to \f[C]amount1\f[R], \f[C]amount2\f[R], ...
etc.
you can generate up to 99 postings.
.PP
\f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] can be used instead, if
the CSV uses separate fields for debits and credits (inflows and
outflows).
hledger assumes both of these CSV fields are unsigned, and will
automatically negate the \[dq]-out\[dq] value.
If they are signed, see \[dq]Setting amounts\[dq] below.
.PP
\f[C]amount\f[R], or \f[C]amount-in\f[R] and \f[C]amount-out\f[R] are a
legacy mode, to keep pre-hledger-1.17 CSV rules files working (and for
occasional convenience).
They are suitable only for two-posting transactions; they set both
posting 1\[aq]s and posting 2\[aq]s amount.
Posting 2\[aq]s amount will be negated, and also converted to cost if
there\[aq]s a transaction price.
.PP
If you have an existing rules file using the unnumbered form, you might
want to use the numbered form in certain conditional blocks, without
having to update and retest all the old rules.
To facilitate this, posting 1 ignores
\f[C]amount\f[R]/\f[C]amount-in\f[R]/\f[C]amount-out\f[R] if any of
\f[C]amount1\f[R]/\f[C]amount1-in\f[R]/\f[C]amount1-out\f[R] are
assigned, and posting 2 ignores them if any of
\f[C]amount2\f[R]/\f[C]amount2-in\f[R]/\f[C]amount2-out\f[R] are
assigned, avoiding conflicts.
.SS currency field
.PP
\f[C]currency\f[R] sets a currency symbol, to be prepended to all
postings\[aq] amounts.
You can use this if the CSV amounts do not have a currency symbol, eg if
it is in a separate column.
.PP
\f[C]currencyN\f[R] prepends a currency symbol to just the Nth
posting\[aq]s amount.
.SS balance field
.PP
\f[C]balanceN\f[R] sets a balance assertion amount (or if the posting
amount is left empty, a balance assignment) on posting N.
.PP
\f[C]balance\f[R] is a compatibility spelling for hledger <1.17; it is
equivalent to \f[C]balance1\f[R].
.PP
You can adjust the type of assertion/assignment with the
\f[C]balance-type\f[R] rule (see below).
.PP
See Tips below for more about setting amounts and currency.
.SS \f[C]separator\f[R] .SS \f[C]separator\f[R]
.PP .PP
You can use the \f[C]separator\f[R] rule to read other kinds of You can use the \f[C]separator\f[R] rule to read other kinds of
@ -8052,6 +8101,11 @@ For the supported strptime syntax, see:
.P .P
.PD .PD
https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime
.PP
Note that although you can parse date-times which include a time zone,
that time zone is ignored; it will not change the date that is parsed.
This means when reading CSV data with times not in your local time zone,
dates can be \[dq]off by one\[dq].
.SS \f[C]decimal-mark\f[R] .SS \f[C]decimal-mark\f[R]
.IP .IP
.nf .nf

997
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

235
hledger/hledger.txt
View File

@ -3833,6 +3833,12 @@ JOURNAL FORMAT
uncashed checks), and no flags to see the most up-to-date state of your uncashed checks), and no flags to see the most up-to-date state of your
finances. finances.
Code
After the status mark, but before the description, you can optionally
write a transaction "code", enclosed in parentheses. This is a good
place to record a check number, or some other important transaction id
or reference number.
Description Description
A transaction's description is the rest of the line following the date A transaction's description is the rest of the line following the date
and status mark (or until a comment begins). Sometimes called the and status mark (or until a comment begins). Sometimes called the
@ -4644,22 +4650,20 @@ JOURNAL FORMAT
"historical prices".) These are often obtained from a stock exchange, "historical prices".) These are often obtained from a stock exchange,
cryptocurrency exchange, or the foreign exchange market. cryptocurrency exchange, or the foreign exchange market.
Here is the format: The format is:
P DATE COMMODITYA COMMODITYBAMOUNT P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT
o DATE is a simple date DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity
being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity)
of commodity 2 that one unit of commodity 1 is worth on this date.
Examples:
o COMMODITYA is the symbol of the commodity being priced # one euro was worth $1.35 from 2009-01-01 onward:
P 2009-01-01 EUR $1.35
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- # and $1.40 from 2010-01-01 onward:
modity, giving the price in commodity B of one unit of commodity A. P 2010-01-01 EUR $1.40
These two market price directives say that one euro was worth 1.35 US
dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 EUR $1.35
P 2010/1/1 EUR $1.40
The -V, -X and --value flags use these market prices to show amount The -V, -X and --value flags use these market prices to show amount
values in another commodity. See Valuation. values in another commodity. See Valuation.
@ -5291,26 +5295,28 @@ CSV FORMAT
below, after the examples: below, after the examples:
skip skip one or more header lines or matched skip skip one or more header lines or matched CSV
CSV records records
fields name CSV fields, assign them to hledger fields list name CSV fields, assign them to hledger
fields fields
field assignment assign a value to one hledger field, field assignment assign a value to one hledger field, with
with interpolation interpolation
Field names hledger field names, used in the fields list
and field assignments
separator a custom field separator separator a custom field separator
if block apply some rules to CSV records matched if block apply some rules to CSV records matched by
by patterns patterns
if table apply some rules to CSV records matched if table apply some rules to CSV records matched by
by patterns, alternate syntax patterns, alternate syntax
end skip the remaining CSV records end skip the remaining CSV records
date-format how to parse dates in CSV records date-format how to parse dates in CSV records
decimal-mark the decimal mark used in CSV amounts, if decimal-mark the decimal mark used in CSV amounts, if
ambiguous ambiguous
newest-first disambiguate record order when there's newest-first disambiguate record order when there's only
only one date one date
include inline another CSV rules file include inline another CSV rules file
balance-type choose which type of balance assignments balance-type choose which type of balance assignments to
to use use
Note, for best error messages when reading CSV files, use a .csv, .tsv Note, for best error messages when reading CSV files, use a .csv, .tsv
or .ssv file extension or file prefix - see File Extension below. or .ssv file extension or file prefix - see File Extension below.
@ -5607,18 +5613,19 @@ CSV FORMAT
It also has a second purpose: it can be used inside if blocks to ignore It also has a second purpose: it can be used inside if blocks to ignore
certain CSV records (described below). certain CSV records (described below).
fields fields list
fields FIELDNAME1, FIELDNAME2, ... fields FIELDNAME1, FIELDNAME2, ...
A fields list (the word "fields" followed by comma-separated field A fields list (the word "fields" followed by comma-separated field
names) is the quick way to assign CSV field values to hledger fields. names) is the quick way to assign CSV field values to hledger fields.
It does two things: (The other way is field assignments, see below.) A fields list does
does two things:
1. it names the CSV fields. This is optional, but can be convenient 1. It names the CSV fields. This is optional, but can be convenient
later for interpolating them. later for interpolating them.
2. when you use a standard hledger field name, it assigns the CSV value 2. Whenever you use a standard hledger field name (defined below), the
to that part of the hledger transaction. CSV value is assigned to that part of the hledger transaction.
Here's an example that says "use the 1st, 2nd and 4th fields as the Here's an example that says "use the 1st, 2nd and 4th fields as the
transaction's date, description and amount; name the last two fields transaction's date, description and amount; name the last two fields
@ -5626,25 +5633,88 @@ CSV FORMAT
fields date, description, , amount, , , somefield, anotherfield fields date, description, , amount, , , somefield, anotherfield
Field names may not contain whitespace. Fields you don't care about Tips:
can be left unnamed. Currently there must be least two items (there
must be at least one comma).
Note, always use comma in the fields list, even if your CSV uses o The fields list always use commas, even if your CSV data uses another
another separator character. separator character.
Here are the standard hledger field/pseudo-field names. For more about o Currently there must be least two items in the list (at least one
the transaction parts they refer to, see the manual for hledger's jour- comma).
nal format.
Transaction field names o Field names may not contain spaces. Spaces before/after field names
date, date2, status, code, description, comment can be used to form the are optional.
transaction's first line.
Posting field names o If the CSV contains column headings, it's a good idea to use these,
account suitably modified, as the basis for your field names (eg lower-cased,
accountN, where N is 1 to 99, causes a posting to be generated, with with underscores instead of spaces).
that account name.
o If some heading names match standard hledger fields, but you don't
want to set the hledger fields directly, alter those names, eg by
appending an underscore.
o Fields you don't care about can be given a dummy name (eg: _ ), or no
name.
field assignment
HLEDGERFIELDNAME FIELDVALUE
Field assignments are the more flexible way to assign CSV values to
hledger fields. They can be used instead of or in addition to a fields
list (see above).
To assign a value to a hledger field, write the field name (any of the
standard hledger field/pseudo-field names, defined below), a space,
followed by a text value on the same line. This text value may inter-
polate CSV fields, referenced by their 1-based position in the CSV
record (%N), or by the name they were given in the fields list (%CSV-
FIELDNAME).
Some examples:
# set the amount to the 4th CSV field, with " USD" appended
amount %4 USD
# combine three fields to make a comment, containing note: and date: tags
comment note: %somefield - %anotherfield, date: %1
Tips:
o Interpolation strips outer whitespace (so a CSV value like " 1 "
becomes 1 when interpolated) (#1051).
o See also Tips below.
Field names
Here are the standard hledger field (and pseudo-field) names, which you
can use in a fields list and in field assignments. For more about the
transaction parts they refer to, see Transactions.
date field
Assigning to date sets the transaction date.
date2 field
date2 sets the transaction's secondary date, if any.
status field
status sets the transaction's status, if any.
code field
code sets the transaction's code, if any.
description field
description sets the transaction's description, if any.
comment field
comment sets the transaction's comment, if any.
commentN, where N is a number, sets the Nth posting's comment.
Tips: - Only single-line comments can be assigned. - Comments can con-
tain tags, as usual.
account field
Assigning to accountN, where N is 1 to 99, sets the account name of the
Nth posting, and causes that posting to be generated.
Most often there are two postings, so you'll want to set account1 and Most often there are two postings, so you'll want to set account1 and
account2. Typically account1 is associated with the CSV file, and is account2. Typically account1 is associated with the CSV file, and is
@ -5655,22 +5725,22 @@ CSV FORMAT
below), a default account name will be chosen (like "expenses:unknown" below), a default account name will be chosen (like "expenses:unknown"
or "income:unknown"). or "income:unknown").
amount amount field
amountN sets the Nth posting's amount. By assigning to amount1, amountN sets the amount of the Nth posting, and causes that posting to
amount2, ... etc. you can generate up to 99 postings. be generated. By assigning to amount1, amount2, ... etc. you can
generate up to 99 postings.
If the CSV uses separate fields for debits and credits (inflows and amountN-in and amountN-out can be used instead, if the CSV uses sepa-
outflows), you can use amountN-in and amountN-out instead. Note rate fields for debits and credits (inflows and outflows). hledger
hledger assumes both of these fields are unsigned, and will automati- assumes both of these CSV fields are unsigned, and will automatically
cally negate the "-out" value. If the fields are signed, see "Setting negate the "-out" value. If they are signed, see "Setting amounts"
amounts" below. below.
There is also an unnumbered form of these names: amount, or amount-in amount, or amount-in and amount-out are a legacy mode, to keep pre-
and amount-out. This is supported to keep pre-hledger-1.17 CSV rules hledger-1.17 CSV rules files working (and for occasional convenience).
files working (and for occasional convenience). It is suitable only They are suitable only for two-posting transactions; they set both
for two-posting transactions; it sets both posting 1's and posting 2's posting 1's and posting 2's amount. Posting 2's amount will be
amount. Posting 2's amount will be negated, and also converted to cost negated, and also converted to cost if there's a transaction price.
if there's a transaction price.
If you have an existing rules file using the unnumbered form, you might If you have an existing rules file using the unnumbered form, you might
want to use the numbered form in certain conditional blocks, without want to use the numbered form in certain conditional blocks, without
@ -5680,46 +5750,24 @@ CSV FORMAT
if any of amount2/amount2-in/amount2-out are assigned, avoiding con- if any of amount2/amount2-in/amount2-out are assigned, avoiding con-
flicts. flicts.
currency currency field
If the CSV has the currency symbol in a separate field (ie, not part of currency sets a currency symbol, to be prepended to all postings'
the amount field), you can use currencyN to prepend it to posting N's amounts. You can use this if the CSV amounts do not have a currency
amount. Or, currency with no number affects all postings. symbol, eg if it is in a separate column.
balance currencyN prepends a currency symbol to just the Nth posting's amount.
balance field
balanceN sets a balance assertion amount (or if the posting amount is balanceN sets a balance assertion amount (or if the posting amount is
left empty, a balance assignment) on posting N. left empty, a balance assignment) on posting N.
Also, for compatibility with hledger <1.17: balance with no number is balance is a compatibility spelling for hledger <1.17; it is equivalent
equivalent to balance1. to balance1.
You can adjust the type of assertion/assignment with the balance-type You can adjust the type of assertion/assignment with the balance-type
rule (see below). rule (see below).
comment See Tips below for more about setting amounts and currency.
Finally, commentN sets a comment on the Nth posting. Comments can also
contain tags, as usual.
See TIPS below for more about setting amounts and currency.
field assignment
HLEDGERFIELDNAME FIELDVALUE
Instead of or in addition to a fields list, you can use a "field
assignment" rule to set the value of a single hledger field, by writing
its name (any of the standard hledger field names above) followed by a
text value. The value may contain interpolated CSV fields, referenced
by their 1-based position in the CSV record (%N), or by the name they
were given in the fields list (%CSVFIELDNAME). Some examples:
# set the amount to the 4th CSV field, with " USD" appended
amount %4 USD
# combine three fields to make a comment, containing note: and date: tags
comment note: %somefield - %anotherfield, date: %1
Interpolation strips outer whitespace (so a CSV value like " 1 "
becomes 1 when interpolated) (#1051). See TIPS below for more about
referencing other fields.
separator separator
You can use the separator rule to read other kinds of character-sepa- You can use the separator rule to read other kinds of character-sepa-
@ -5910,6 +5958,11 @@ CSV FORMAT
https://hackage.haskell.org/package/time/docs/Data-Time-For- https://hackage.haskell.org/package/time/docs/Data-Time-For-
mat.html#v:formatTime mat.html#v:formatTime
Note that although you can parse date-times which include a time zone,
that time zone is ignored; it will not change the date that is parsed.
This means when reading CSV data with times not in your local time
zone, dates can be "off by one".
decimal-mark decimal-mark
decimal-mark . decimal-mark .