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

;regen manuals

Browse Source
This commit is contained in:
Simon Michael 2020-05-25 17:49:01 -07:00
parent 798a2c8674
commit 9417ee625e
22 changed files with 1963 additions and 1234 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hledger-lib/defs.m4
View File

@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion.
m4_define({{_version_}}, {{1.17.99}})m4_dnl
m4_dnl
m4_dnl Date to show in man pages. Updated by make setdate.
m4_define({{_monthyear_}}, {{March 2020}})m4_dnl
m4_define({{_monthyear_}}, {{May 2020}})m4_dnl

58
hledger-lib/hledger_csv.5
View File

@ -1,6 +1,6 @@
.\"t
.TH "hledger_csv" "5" "March 2020" "hledger 1.17.99" "hledger User Manuals"
.TH "hledger_csv" "5" "May 2020" "hledger 1.17.99" "hledger User Manuals"
@ -19,7 +19,7 @@ file\f[R].
By default this is named like the CSV file with a \f[C].rules\f[R]
extension added.
Eg when reading \f[C]FILE.csv\f[R], hledger also looks for
\f[C]FILE.csv.rules\f[R] in the same directory.
\f[C]FILE.csv.rules\f[R] in the same directory as \f[C]FILE.csv\f[R].
You can specify a different rules file with the \f[C]--rules-file\f[R]
option.
If a rules file is not found, hledger will create a sample rules file,
@ -489,8 +489,8 @@ transaction\[aq]s first line.
.SS Posting field names
.SS account
.PP
\f[C]accountN\f[R], where N is 1 to 9, causes a posting to be generated,
with that account name.
\f[C]accountN\f[R], where N is 1 to 99, causes a posting to be
generated, with that account name.
.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].
@ -504,14 +504,30 @@ below), a default account name will be chosen (like
.SS amount
.PP
\f[C]amountN\f[R] sets posting N\[aq]s amount.
If the CSV uses separate fields for debit and credit amounts, you can
use \f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] instead.
If the CSV uses separate fields for inflows and outflows, you can use
\f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] instead.
By assigning to \f[C]amount1\f[R], \f[C]amount2\f[R], ...
etc.
you can generate anywhere from 0 to 99 postings.
.PP
Also, for compatibility with hledger <1.17: \f[C]amount\f[R] or
\f[C]amount-in\f[R]/\f[C]amount-out\f[R] with no number sets the amount
for postings 1 and 2.
For posting 2 the amount is negated, and converted to cost if
there\[aq]s a transaction price.
There is also an older, unnumbered form of these names, suitable for
2-posting transactions, which sets both posting 1\[aq]s and (negated)
posting 2\[aq]s amount: \f[C]amount\f[R], or \f[C]amount-in\f[R] and
\f[C]amount-out\f[R].
This is still supported because it keeps pre-hledger-1.17 csv rules
files working, and because it can be more succinct, and because it
converts posting 2\[aq]s amount to cost if there\[aq]s a transaction
price, which can be useful.
.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
@ -620,13 +636,19 @@ REGEX
.PP
REGEX is a case-insensitive regular expression which tries to match
anywhere within the CSV record.
It is a POSIX extended regular expressions with some additions (see
Regular expressions in the hledger manual).
Note: the \[dq]CSV record\[dq] it is matched against is not the original
record, but a synthetic one, with enclosing double quotes or whitespace
removed, and always comma-separated.
(Eg, an SSV record \f[C]2020-01-01; \[dq]Acme, Inc.\[dq]; 1,000\f[R]
appears to REGEX as \f[C]2020-01-01,Acme, Inc.,1,000\f[R]).
It is a POSIX ERE (extended regular expression) that also supports GNU
word boundaries (\f[C]\[rs]b\f[R], \f[C]\[rs]B\f[R], \f[C]\[rs]<\f[R],
\f[C]\[rs]>\f[R]), and nothing else.
If you have trouble, be sure to check our
https://hledger.org/hledger.html#regular-expressions doc.
.PP
Important note: the record that is matched is not the original record,
but a synthetic one, with any enclosing double quotes (but not enclosing
whitespace) removed, and always comma-separated (which means that a
field containing a comma will appear like two fields).
Eg, if the original record is
\f[C]2020-01-01; \[dq]Acme, Inc.\[dq]; 1,000\f[R], the REGEX will
actually see \f[C]2020-01-01,Acme, Inc., 1,000\f[R]).
.PP
Or, MATCHER can be a field matcher, like this:
.IP

186
hledger-lib/hledger_csv.info
View File

@ -16,9 +16,9 @@ CSV output.)
We describe each CSV file's format with a corresponding _rules file_.
By default this is named like the CSV file with a '.rules' extension
added. Eg when reading 'FILE.csv', hledger also looks for
'FILE.csv.rules' in the same directory. You can specify a different
rules file with the '--rules-file' option. If a rules file is not
found, hledger will create a sample rules file, which you'll need to
'FILE.csv.rules' in the same directory as 'FILE.csv'. You can specify a
different rules file with the '--rules-file' option. If a rules file is
not found, hledger will create a sample rules file, which you'll need to
adjust.
This file contains rules describing the CSV data (header line, fields
@ -465,7 +465,7 @@ File: hledger_csv.info, Node: account, Next: amount, Up: Posting field names
2.2.2.1 account
...............
'accountN', where N is 1 to 9, causes a posting to be generated, with
'accountN', where N is 1 to 99, causes a posting to be generated, with
that account name.
Most often there are two postings, so you'll want to set 'account1'
@ -484,13 +484,25 @@ File: hledger_csv.info, Node: amount, Next: currency, Prev: account, Up: Pos
..............
'amountN' sets posting N's amount. If the CSV uses separate fields for
debit and credit amounts, you can use 'amountN-in' and 'amountN-out'
instead.
inflows and outflows, you can use 'amountN-in' and 'amountN-out'
instead. By assigning to 'amount1', 'amount2', ... etc. you can
generate anywhere from 0 to 99 postings.
Also, for compatibility with hledger <1.17: 'amount' or
'amount-in'/'amount-out' with no number sets the amount for postings 1
and 2. For posting 2 the amount is negated, and converted to cost if
there's a transaction price.
There is also an older, unnumbered form of these names, suitable for
2-posting transactions, which sets both posting 1's and (negated)
posting 2's amount: 'amount', or 'amount-in' and 'amount-out'. This is
still supported because it keeps pre-hledger-1.17 csv rules files
working, and because it can be more succinct, and because it converts
posting 2's amount to cost if there's a transaction price, which can be
useful.
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 'amount'/'amount-in'/'amount-out' if any of
'amount1'/'amount1-in'/'amount1-out' are assigned, and posting 2 ignores
them if any of 'amount2'/'amount2-in'/'amount2-out' are assigned,
avoiding conflicts.

File: hledger_csv.info, Node: currency, Next: balance, Prev: amount, Up: Posting field names
@ -599,13 +611,17 @@ descriptions.
REGEX
REGEX is a case-insensitive regular expression which tries to match
anywhere within the CSV record. It is a POSIX extended regular
expressions with some additions (see Regular expressions in the hledger
manual). Note: the "CSV record" it is matched against is not the
original record, but a synthetic one, with enclosing double quotes or
whitespace removed, and always comma-separated. (Eg, an SSV record
'2020-01-01; "Acme, Inc."; 1,000' appears to REGEX as '2020-01-01,Acme,
Inc.,1,000').
anywhere within the CSV record. It is a POSIX ERE (extended regular
expression) that also supports GNU word boundaries ('\b', '\B', '\<',
'\>'), and nothing else. If you have trouble, be sure to check our
https://hledger.org/hledger.html#regular-expressions doc.
Important note: the record that is matched is not the original
record, but a synthetic one, with any enclosing double quotes (but not
enclosing whitespace) removed, and always comma-separated (which means
that a field containing a comma will appear like two fields). Eg, if
the original record is '2020-01-01; "Acme, Inc."; 1,000', the REGEX will
actually see '2020-01-01,Acme, Inc., 1,000').
Or, MATCHER can be a field matcher, like this:
@ -1019,74 +1035,74 @@ command the user specified.

Tag Table:
Node: Top72
Node: EXAMPLES2099
Ref: #examples2205
Node: Basic2413
Ref: #basic2513
Node: Bank of Ireland3055
Ref: #bank-of-ireland3190
Node: Amazon4652
Ref: #amazon4770
Node: Paypal6489
Ref: #paypal6583
Node: CSV RULES14227
Ref: #csv-rules14336
Node: skip14612
Ref: #skip14705
Node: fields15080
Ref: #fields15202
Node: Transaction field names16367
Ref: #transaction-field-names16527
Node: Posting field names16638
Ref: #posting-field-names16790
Node: account16860
Ref: #account16976
Node: amount17512
Ref: #amount17643
Node: currency18024
Ref: #currency18159
Node: balance18365
Ref: #balance18499
Node: comment18816
Ref: #comment18933
Node: field assignment19096
Ref: #field-assignment19239
Node: separator20057
Ref: #separator20186
Node: if20597
Ref: #if20699
Node: end22618
Ref: #end22724
Node: date-format22948
Ref: #date-format23080
Node: newest-first23829
Ref: #newest-first23967
Node: include24650
Ref: #include24779
Node: balance-type25223
Ref: #balance-type25343
Node: TIPS26043
Ref: #tips26125
Node: Rapid feedback26381
Ref: #rapid-feedback26498
Node: Valid CSV26958
Ref: #valid-csv27088
Node: File Extension27280
Ref: #file-extension27432
Node: Reading multiple CSV files27842
Ref: #reading-multiple-csv-files28027
Node: Valid transactions28268
Ref: #valid-transactions28446
Node: Deduplicating importing29074
Ref: #deduplicating-importing29253
Node: Setting amounts30286
Ref: #setting-amounts30455
Node: Setting currency/commodity31441
Ref: #setting-currencycommodity31633
Node: Referencing other fields32436
Ref: #referencing-other-fields32636
Node: How CSV rules are evaluated33533
Ref: #how-csv-rules-are-evaluated33706
Node: EXAMPLES2113
Ref: #examples2219
Node: Basic2427
Ref: #basic2527
Node: Bank of Ireland3069
Ref: #bank-of-ireland3204
Node: Amazon4666
Ref: #amazon4784
Node: Paypal6503
Ref: #paypal6597
Node: CSV RULES14241
Ref: #csv-rules14350
Node: skip14626
Ref: #skip14719
Node: fields15094
Ref: #fields15216
Node: Transaction field names16381
Ref: #transaction-field-names16541
Node: Posting field names16652
Ref: #posting-field-names16804
Node: account16874
Ref: #account16990
Node: amount17527
Ref: #amount17658
Node: currency18765
Ref: #currency18900
Node: balance19106
Ref: #balance19240
Node: comment19557
Ref: #comment19674
Node: field assignment19837
Ref: #field-assignment19980
Node: separator20798
Ref: #separator20927
Node: if21338
Ref: #if21440
Node: end23596
Ref: #end23702
Node: date-format23926
Ref: #date-format24058
Node: newest-first24807
Ref: #newest-first24945
Node: include25628
Ref: #include25757
Node: balance-type26201
Ref: #balance-type26321
Node: TIPS27021
Ref: #tips27103
Node: Rapid feedback27359
Ref: #rapid-feedback27476
Node: Valid CSV27936
Ref: #valid-csv28066
Node: File Extension28258
Ref: #file-extension28410
Node: Reading multiple CSV files28820
Ref: #reading-multiple-csv-files29005
Node: Valid transactions29246
Ref: #valid-transactions29424
Node: Deduplicating importing30052
Ref: #deduplicating-importing30231
Node: Setting amounts31264
Ref: #setting-amounts31433
Node: Setting currency/commodity32419
Ref: #setting-currencycommodity32611
Node: Referencing other fields33414
Ref: #referencing-other-fields33614
Node: How CSV rules are evaluated34511
Ref: #how-csv-rules-are-evaluated34684

End Tag Table

50
hledger-lib/hledger_csv.txt
View File

@ -15,9 +15,9 @@ DESCRIPTION
We describe each CSV file's format with a corresponding rules file. By
default this is named like the CSV file with a .rules extension added.
Eg when reading FILE.csv, hledger also looks for FILE.csv.rules in the
same directory. You can specify a different rules file with the
--rules-file option. If a rules file is not found, hledger will create
a sample rules file, which you'll need to adjust.
same directory as FILE.csv. You can specify a different rules file
with the --rules-file option. If a rules file is not found, hledger
will create a sample rules file, which you'll need to adjust.
This file contains rules describing the CSV data (header line, fields
layout, date format etc.), and how to construct hledger journal entries
@ -377,7 +377,7 @@ CSV RULES
Posting field names
account
accountN, where N is 1 to 9, causes a posting to be generated, with
accountN, where N is 1 to 99, causes a posting to be generated, with
that account name.
Most often there are two postings, so you'll want to set account1 and
@ -391,13 +391,24 @@ CSV RULES
amount
amountN sets posting N's amount. If the CSV uses separate fields for
debit and credit amounts, you can use amountN-in and amountN-out in-
stead.
inflows and outflows, you can use amountN-in and amountN-out instead.
By assigning to amount1, amount2, ... etc. you can generate anywhere
from 0 to 99 postings.
Also, for compatibility with hledger <1.17: amount or amount-in/amount-
out with no number sets the amount for postings 1 and 2. For posting 2
the amount is negated, and converted to cost if there's a transaction
price.
There is also an older, unnumbered form of these names, suitable for
2-posting transactions, which sets both posting 1's and (negated) post-
ing 2's amount: amount, or amount-in and amount-out. This is still
supported because it keeps pre-hledger-1.17 csv rules files working,
and because it can be more succinct, and because it converts posting
2's amount to cost if there's a transaction price, which can be useful.
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 amount/amount-in/amount-out if any of
amount1/amount1-in/amount1-out are assigned, and posting 2 ignores them
if any of amount2/amount2-in/amount2-out are assigned, avoiding con-
flicts.
currency
If the CSV has the currency symbol in a separate field (ie, not part of
@ -474,12 +485,17 @@ CSV RULES
REGEX
REGEX is a case-insensitive regular expression which tries to match
anywhere within the CSV record. It is a POSIX extended regular expres-
sions with some additions (see Regular expressions in the hledger man-
ual). Note: the "CSV record" it is matched against is not the original
record, but a synthetic one, with enclosing double quotes or whitespace
removed, and always comma-separated. (Eg, an SSV record 2020-01-01;
"Acme, Inc."; 1,000 appears to REGEX as 2020-01-01,Acme, Inc.,1,000).
anywhere within the CSV record. It is a POSIX ERE (extended regular
expression) that also supports GNU word boundaries (\b, \B, \<, \>),
and nothing else. If you have trouble, be sure to check our
https://hledger.org/hledger.html#regular-expressions doc.
Important note: the record that is matched is not the original record,
but a synthetic one, with any enclosing double quotes (but not enclos-
ing whitespace) removed, and always comma-separated (which means that a
field containing a comma will appear like two fields). Eg, if the
original record is 2020-01-01; "Acme, Inc."; 1,000, the REGEX will ac-
tually see 2020-01-01,Acme, Inc., 1,000).
Or, MATCHER can be a field matcher, like this:
@ -834,4 +850,4 @@ SEE ALSO
hledger 1.17.99 March 2020 hledger_csv(5)
hledger 1.17.99 May 2020 hledger_csv(5)

54
hledger-lib/hledger_journal.5
View File

@ -1,6 +1,6 @@
.\"t
.TH "hledger_journal" "5" "March 2020" "hledger 1.17.99" "hledger User Manuals"
.TH "hledger_journal" "5" "May 2020" "hledger 1.17.99" "hledger User Manuals"
@ -63,7 +63,8 @@ a comment (any remaining text following a semicolon until end of line,
and any following indented lines beginning with a semicolon)
.IP \[bu] 2
0 or more indented \f[I]posting\f[R] lines, describing what was
transferred and the accounts involved.
transferred and the accounts involved (indented comment lines are also
allowed, but not blank lines or non-indented lines).
.PP
Here\[aq]s a simple journal file containing one transaction:
.IP
@ -409,7 +410,7 @@ amount.
This makes it easy to write account names containing spaces.
But if you accidentally leave only one space (or tab) before the amount,
the amount will be considered part of the account name.
.SS Virtual Postings
.SS Virtual postings
.PP
A posting with a parenthesised account name is called a \f[I]virtual
posting\f[R] or \f[I]unbalanced posting\f[R], which means it is exempt
@ -504,9 +505,9 @@ be enclosed in double quotes:
\f[R]
.fi
.PP
Amounts can be negative.
The minus sign can be written before or after a left-side commodity
symbol:
Amounts can be preceded by a minus sign (or a plus sign, though plus is
the default), The sign can be written before or after a left-side
commodity symbol:
.IP
.nf
\f[C]
@ -515,6 +516,16 @@ $-1
\f[R]
.fi
.PP
One or more spaces between the sign and the number are acceptable when
parsing (but they won\[aq]t be displayed in output):
.IP
.nf
\f[C]
+ $1
$- 1
\f[R]
.fi
.PP
Scientific E notation is allowed:
.IP
.nf
@ -586,7 +597,7 @@ the commodity, that format is used (see examples above).
Otherwise the format of the first posting amount in that commodity seen
in the journal is used.
But the number of decimal places (\[dq]precision\[dq]) will be the
maximum from all posting amounts in that commmodity.
maximum from all posting amounts in that commodity.
.IP \[bu] 2
Or if there are no such amounts in the journal, a default format is used
(like \f[C]$1000.00\f[R]).
@ -659,9 +670,10 @@ hledger infer the price that balances the transaction:
\f[R]
.fi
.RE
.PP
(Ledger users: Ledger uses a different syntax for fixed prices,
\f[C]{=UNITPRICE}\f[R], which hledger currently ignores).
.IP "5." 3
Like 1 and 2, but the \f[C]\[at]\f[R] or \f[C]\[at]\[at]\f[R] is
parenthesised; this is for compatibility with Ledger journals (Virtual
posting costs), and in hledger is equivalent to 1 and 2.
.PP
Use the \f[C]-B/--cost\f[R] flag to convert amounts to their transaction
price\[aq]s commodity, if any.
@ -700,7 +712,18 @@ $ hledger bal -N --flat -B
\[Eu]100 assets:euros
\f[R]
.fi
.SS Balance Assertions
.SS Lot prices and lot dates
.PP
Ledger allows another kind of price, lot price (four variants:
\f[C]{UNITPRICE}\f[R], \f[C]{{TOTALPRICE}}\f[R],
\f[C]{=FIXEDUNITPRICE}\f[R], \f[C]{{=FIXEDTOTALPRICE}}\f[R]), and/or a
lot date (\f[C][DATE]\f[R]) to be specified.
These are normally used to select a lot when selling investments.
hledger will parse these, for compatibility with Ledger journals, but
currently ignores them.
A transaction price, lot price and/or lot date may appear in any order,
after the posting amount and before the balance assertion if any.
.SS Balance assertions
.PP
hledger supports Ledger-style balance assertions in journal files.
These look like, for example, \f[C]= EXPECTEDBALANCE\f[R] following a
@ -856,7 +879,7 @@ always what is shown by reports.
Eg a commodity directive may limit the display precision, but this will
not affect balance assertions.
Balance assertion failure messages show exact amounts.
.SS Balance Assignments
.SS Balance assignments
.PP
Ledger-style balance assignments are also supported.
These are like balance assertions, but with no posting amount on the
@ -1237,7 +1260,7 @@ D $1,000.00
b
\f[R]
.fi
.SS Market prices
.SS Declaring market prices
.PP
The \f[C]P\f[R] directive declares a market price, which is an exchange
rate between two commodities on a certain date.
@ -1270,8 +1293,9 @@ P 2010/1/1 \[Eu] $1.40
\f[R]
.fi
.PP
The \f[C]-V/--value\f[R] flag can be used to convert reported amounts to
another commodity using these prices.
The \f[C]-V\f[R], \f[C]-X\f[R] and \f[C]--value\f[R] flags use these
market prices to show amount values in another commodity.
See Valuation.
.SS Declaring accounts
.PP
\f[C]account\f[R] directives can be used to pre-declare accounts.

399
hledger-lib/hledger_journal.info
View File

@ -62,7 +62,8 @@ optional fields, separated by spaces:
* a comment (any remaining text following a semicolon until end of
line, and any following indented lines beginning with a semicolon)
* 0 or more indented _posting_ lines, describing what was transferred
and the accounts involved.
and the accounts involved (indented comment lines are also allowed,
but not blank lines or non-indented lines).
Here's a simple journal file containing one transaction:
@ -81,8 +82,9 @@ optional fields, separated by spaces:
* Account names::
* Amounts::
* Transaction prices::
* Balance Assertions::
* Balance Assignments::
* Lot prices and lot dates::
* Balance assertions::
* Balance assignments::
* Directives::
* Periodic transactions::
* Auto postings::
@ -377,12 +379,12 @@ the amount, the amount will be considered part of the account name.
* Menu:
* Virtual Postings::
* Virtual postings::

File: hledger_journal.info, Node: Virtual Postings, Up: Postings
File: hledger_journal.info, Node: Virtual postings, Up: Postings
1.6.1 Virtual Postings
1.6.1 Virtual postings
----------------------
A posting with a parenthesised account name is called a _virtual
@ -459,10 +461,17 @@ must be enclosed in double quotes:
3 "no. 42 green apples"
Amounts can be negative. The minus sign can be written before or
after a left-side commodity symbol:
Amounts can be preceded by a minus sign (or a plus sign, though plus
is the default), The sign can be written before or after a left-side
commodity symbol:
-$1
$-1
One or more spaces between the sign and the number are acceptable
when parsing (but they won't be displayed in output):
+ $1
$- 1
Scientific E notation is allowed:
@ -529,7 +538,7 @@ as written). The display style is chosen as follows:
* Otherwise the format of the first posting amount in that commodity
seen in the journal is used. But the number of decimal places
("precision") will be the maximum from all posting amounts in that
commmodity.
commodity.
* Or if there are no such amounts in the journal, a default format is
used (like '$1000.00').
@ -550,7 +559,7 @@ hledger 1.17.1 this could vary if hledger happened to be built with an
old version of Decimal (<0.5.1); since 1.17.1 it's guaranteed.)

File: hledger_journal.info, Node: Transaction prices, Next: Balance Assertions, Prev: Amounts, Up: Transactions
File: hledger_journal.info, Node: Transaction prices, Next: Lot prices and lot dates, Prev: Amounts, Up: Transactions
1.9 Transaction prices
======================
@ -584,8 +593,9 @@ certain date.
assets:euros €100 ; one hundred euros purchased
assets:dollars $-135 ; for $135
(Ledger users: Ledger uses a different syntax for fixed prices,
'{=UNITPRICE}', which hledger currently ignores).
4. 5. Like 1 and 2, but the '@' or '@@' is parenthesised; this is for
compatibility with Ledger journals (Virtual posting costs), and in
hledger is equivalent to 1 and 2.
Use the '-B/--cost' flag to convert amounts to their transaction
price's commodity, if any. (mnemonic: "B" is from "cost Basis", as in
@ -613,9 +623,24 @@ $ hledger bal -N --flat -B
€100 assets:euros

File: hledger_journal.info, Node: Balance Assertions, Next: Balance Assignments, Prev: Transaction prices, Up: Transactions
File: hledger_journal.info, Node: Lot prices and lot dates, Next: Balance assertions, Prev: Transaction prices, Up: Transactions
1.10 Balance Assertions
1.10 Lot prices and lot dates
=============================
Ledger allows another kind of price, lot price (four variants:
'{UNITPRICE}', '{{TOTALPRICE}}', '{=FIXEDUNITPRICE}',
'{{=FIXEDTOTALPRICE}}'), and/or a lot date ('[DATE]') to be specified.
These are normally used to select a lot when selling investments.
hledger will parse these, for compatibility with Ledger journals, but
currently ignores them. A transaction price, lot price and/or lot date
may appear in any order, after the posting amount and before the balance
assertion if any.

File: hledger_journal.info, Node: Balance assertions, Next: Balance assignments, Prev: Lot prices and lot dates, Up: Transactions
1.11 Balance assertions
=======================
hledger supports Ledger-style balance assertions in journal files.
@ -651,9 +676,9 @@ does not disable balance assignments, below).
* Assertions and precision::

File: hledger_journal.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance Assertions
File: hledger_journal.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance assertions
1.10.1 Assertions and ordering
1.11.1 Assertions and ordering
------------------------------
hledger sorts an account's postings and assertions first by date and
@ -670,9 +695,9 @@ control over the order of postings and assertions within a day, so you
can assert intra-day balances.

File: hledger_journal.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance Assertions
File: hledger_journal.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance assertions
1.10.2 Assertions and included files
1.11.2 Assertions and included files
------------------------------------
With included files, things are a little more complicated. Including
@ -682,18 +707,18 @@ and you also want to assert the account's balance on the same day,
you'll have to put the assertion in the right file.

File: hledger_journal.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance Assertions
File: hledger_journal.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance assertions
1.10.3 Assertions and multiple -f options
1.11.3 Assertions and multiple -f options
-----------------------------------------
Balance assertions don't work well across files specified with multiple
-f options. Use include or concatenate the files instead.

File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f options, Up: Balance Assertions
File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f options, Up: Balance assertions
1.10.4 Assertions and commodities
1.11.4 Assertions and commodities
---------------------------------
The asserted balance must be a simple single-commodity amount, and in
@ -739,9 +764,9 @@ commodity into its own subaccount:
a:euro 0 == 1€

File: hledger_journal.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance Assertions
File: hledger_journal.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions
1.10.5 Assertions and prices
1.11.5 Assertions and prices
----------------------------
Balance assertions ignore transaction prices, and should normally be
@ -757,9 +782,9 @@ to generate balance assertions with prices), and because balance
_assignments_ do use them (see below).

File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance Assertions
File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions
1.10.6 Assertions and subaccounts
1.11.6 Assertions and subaccounts
---------------------------------
The balance assertions above ('=' and '==') do not count the balance
@ -774,9 +799,9 @@ eg:
checking 1 ==* 11

File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance Assertions
File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance assertions
1.10.7 Assertions and virtual postings
1.11.7 Assertions and virtual postings
--------------------------------------
Balance assertions are checked against all postings, both real and
@ -784,9 +809,9 @@ virtual. They are not affected by the '--real/-R' flag or 'real:'
query.

File: hledger_journal.info, Node: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance Assertions
File: hledger_journal.info, Node: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions
1.10.8 Assertions and precision
1.11.8 Assertions and precision
-------------------------------
Balance assertions compare the exactly calculated amounts, which are not
@ -795,9 +820,9 @@ display precision, but this will not affect balance assertions. Balance
assertion failure messages show exact amounts.

File: hledger_journal.info, Node: Balance Assignments, Next: Directives, Prev: Balance Assertions, Up: Transactions
File: hledger_journal.info, Node: Balance assignments, Next: Directives, Prev: Balance assertions, Up: Transactions
1.11 Balance Assignments
1.12 Balance assignments
========================
Ledger-style balance assignments are also supported. These are like
@ -832,9 +857,9 @@ hledger or do the calculations yourself, instead of just reading it.
* Balance assignments and prices::

File: hledger_journal.info, Node: Balance assignments and prices, Up: Balance Assignments
File: hledger_journal.info, Node: Balance assignments and prices, Up: Balance assignments
1.11.1 Balance assignments and prices
1.12.1 Balance assignments and prices
-------------------------------------
A transaction price in a balance assignment will cause the calculated
@ -848,9 +873,9 @@ $ hledger print --explicit
(a) $1 @ €2 = $1 @ €2

File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Prev: Balance Assignments, Up: Transactions
File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Prev: Balance assignments, Up: Transactions
1.12 Directives
1.13 Directives
===============
A directive is a line in the journal beginning with a special keyword,
@ -946,7 +971,7 @@ they affect, and whether they are focussed on input (parsing) or output
* Default year::
* Declaring commodities::
* Default commodity::
* Market prices::
* Declaring market prices::
* Declaring accounts::
* Rewriting accounts::
* Default parent account::
@ -954,7 +979,7 @@ they affect, and whether they are focussed on input (parsing) or output

File: hledger_journal.info, Node: Directives and multiple files, Next: Comment blocks, Up: Directives
1.12.1 Directives and multiple files
1.13.1 Directives and multiple files
------------------------------------
If you use multiple '-f'/'--file' options, or the 'include' directive,
@ -974,7 +999,7 @@ directives do not affect parent or sibling files (see below).

File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Prev: Directives and multiple files, Up: Directives
1.12.2 Comment blocks
1.13.2 Comment blocks
---------------------
A line containing just 'comment' starts a commented region of the file,
@ -984,7 +1009,7 @@ file) ends it. See also comments.

File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives
1.12.3 Including other files
1.13.3 Including other files
----------------------------
You can pull in the content of additional files by writing an include
@ -1002,7 +1027,7 @@ include journal, timeclock or timedot files, but not CSV files.

File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives
1.12.4 Default year
1.13.4 Default year
-------------------
You can set a default year to be used for subsequent dates which don't
@ -1028,7 +1053,7 @@ Y2010 ; change default year to 2010

File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives
1.12.5 Declaring commodities
1.13.5 Declaring commodities
----------------------------
The 'commodity' directive has several functions:
@ -1079,9 +1104,9 @@ a comma, followed by 0 or more decimal digits.
zero decimal digits is "0". (More at Amount display style.)

File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives
File: hledger_journal.info, Node: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: Directives
1.12.6 Default commodity
1.13.6 Default commodity
------------------------
The 'D' directive sets a default commodity, to be used for amounts
@ -1106,10 +1131,10 @@ D $1,000.00
b

File: hledger_journal.info, Node: Market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives
File: hledger_journal.info, Node: Declaring market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives
1.12.7 Market prices
--------------------
1.13.7 Declaring market prices
------------------------------
The 'P' directive declares a market price, which is an exchange rate
between two commodities on a certain date. (In Ledger, they are called
@ -1132,13 +1157,13 @@ dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 € $1.35
P 2010/1/1 € $1.40
The '-V/--value' flag can be used to convert reported amounts to
another commodity using these prices.
The '-V', '-X' and '--value' flags use these market prices to show
amount values in another commodity. See Valuation.

File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Market prices, Up: Directives
File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Declaring market prices, Up: Directives
1.12.8 Declaring accounts
1.13.8 Declaring accounts
-------------------------
'account' directives can be used to pre-declare accounts. Though not
@ -1171,7 +1196,7 @@ account assets:bank:checking

File: hledger_journal.info, Node: Account comments, Next: Account subdirectives, Up: Declaring accounts
1.12.8.1 Account comments
1.13.8.1 Account comments
.........................
Comments, beginning with a semicolon, can be added:
@ -1191,7 +1216,7 @@ account assets:bank:checking ; same-line comment, note 2+ spaces before ;

File: hledger_journal.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts
1.12.8.2 Account subdirectives
1.13.8.2 Account subdirectives
..............................
We also allow (and ignore) Ledger-style indented subdirectives, just for
@ -1209,7 +1234,7 @@ account ACCTNAME [ACCTTYPE] [;COMMENT]

File: hledger_journal.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts
1.12.8.3 Account types
1.13.8.3 Account types
......................
hledger recognises five types (or classes) of account: Asset, Liability,
@ -1254,7 +1279,7 @@ account - ; type:L

File: hledger_journal.info, Node: Account display order, Prev: Account types, Up: Declaring accounts
1.12.8.4 Account display order
1.13.8.4 Account display order
..............................
Account directives also set the order in which accounts are displayed,
@ -1300,7 +1325,7 @@ means:

File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives
1.12.9 Rewriting accounts
1.13.9 Rewriting accounts
-------------------------
You can define account alias rules which rewrite your account names, or
@ -1330,7 +1355,7 @@ hledger-web.

File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts
1.12.9.1 Basic aliases
1.13.9.1 Basic aliases
......................
To set an account alias, use the 'alias' directive in your journal file.
@ -1353,7 +1378,7 @@ alias checking = assets:bank:wells fargo:checking

File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts
1.12.9.2 Regex aliases
1.13.9.2 Regex aliases
......................
There is also a more powerful variant that uses a regular expression,
@ -1378,7 +1403,7 @@ whitespace.

File: hledger_journal.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: Rewriting accounts
1.12.9.3 Combining aliases
1.13.9.3 Combining aliases
..........................
You can define as many aliases as you like, using journal directives
@ -1415,7 +1440,7 @@ which aliases are being applied when.

File: hledger_journal.info, Node: Aliases and multiple files, Next: end aliases, Prev: Combining aliases, Up: Rewriting accounts
1.12.9.4 Aliases and multiple files
1.13.9.4 Aliases and multiple files
...................................
As explained at Directives and multiple files, 'alias' directives do not
@ -1447,7 +1472,7 @@ include c.journal ; also affected

File: hledger_journal.info, Node: end aliases, Prev: Aliases and multiple files, Up: Rewriting accounts
1.12.9.5 'end aliases'
1.13.9.5 'end aliases'
......................
You can clear (forget) all currently defined aliases with the 'end
@ -1458,7 +1483,7 @@ end aliases

File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives
1.12.10 Default parent account
1.13.10 Default parent account
------------------------------
You can specify a parent account which will be prepended to all accounts
@ -1499,7 +1524,7 @@ parent account.

File: hledger_journal.info, Node: Periodic transactions, Next: Auto postings, Prev: Directives, Up: Transactions
1.13 Periodic transactions
1.14 Periodic transactions
==========================
Periodic transaction rules describe transactions that recur. They allow
@ -1544,7 +1569,7 @@ read this whole section - or at least these tips:

File: hledger_journal.info, Node: Periodic rule syntax, Next: Two spaces between period expression and description!, Up: Periodic transactions
1.13.1 Periodic rule syntax
1.14.1 Periodic rule syntax
---------------------------
A periodic transaction rule looks like a normal journal entry, with the
@ -1567,7 +1592,7 @@ will be relative to Y/1/1.

File: hledger_journal.info, Node: Two spaces between period expression and description!, Next: Forecasting with periodic transactions, Prev: Periodic rule syntax, Up: Periodic transactions
1.13.2 Two spaces between period expression and description!
1.14.2 Two spaces between period expression and description!
------------------------------------------------------------
If the period expression is followed by a transaction description, these
@ -1592,7 +1617,7 @@ accidentally alter their meaning, as in this example:

File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces between period expression and description!, Up: Periodic transactions
1.13.3 Forecasting with periodic transactions
1.14.3 Forecasting with periodic transactions
---------------------------------------------
With the '--forecast' flag, each periodic transaction rule generates
@ -1645,7 +1670,7 @@ disables forecast transactions on previous dates.)

File: hledger_journal.info, Node: Budgeting with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions
1.13.4 Budgeting with periodic transactions
1.14.4 Budgeting with periodic transactions
-------------------------------------------
With the '--budget' flag, currently supported by the balance command,
@ -1661,7 +1686,7 @@ Forecasting.

File: hledger_journal.info, Node: Auto postings, Prev: Periodic transactions, Up: Transactions
1.14 Auto postings
1.15 Auto postings
==================
"Automated postings" or "auto postings" are extra postings which get
@ -1739,7 +1764,7 @@ $ hledger print --auto

File: hledger_journal.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings
1.14.1 Auto postings and multiple files
1.15.1 Auto postings and multiple files
---------------------------------------
An auto posting rule can affect any transaction in the current file, or
@ -1749,7 +1774,7 @@ sibling files (when multiple '-f'/'--file' are used - see #1212).

File: hledger_journal.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings
1.14.2 Auto postings and dates
1.15.2 Auto postings and dates
------------------------------
A posting date (or secondary date) in the matched posting, or (taking
@ -1759,7 +1784,7 @@ used in the generated posting.

File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings
1.14.3 Auto postings and transaction balancing / inferred amounts /
1.15.3 Auto postings and transaction balancing / inferred amounts /
-------------------------------------------------------------------
balance assertions Currently, auto postings are added:
@ -1775,7 +1800,7 @@ for background.

File: hledger_journal.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings
1.14.4 Auto posting tags
1.15.4 Auto posting tags
------------------------
Automated postings will have some extra tags:
@ -1799,120 +1824,122 @@ Tag Table:
Node: Top76
Node: Transactions1875
Ref: #transactions1967
Node: Dates3132
Ref: #dates3231
Node: Simple dates3296
Ref: #simple-dates3422
Node: Secondary dates3931
Ref: #secondary-dates4085
Node: Posting dates5421
Ref: #posting-dates5550
Node: Status6922
Ref: #status7043
Node: Description8751
Ref: #description8885
Node: Payee and note9205
Ref: #payee-and-note9319
Node: Comments9654
Ref: #comments9780
Node: Tags10974
Ref: #tags11089
Node: Postings12482
Ref: #postings12610
Node: Virtual Postings13636
Ref: #virtual-postings13753
Node: Account names15058
Ref: #account-names15199
Node: Amounts15686
Ref: #amounts15825
Node: Digit group marks16739
Ref: #digit-group-marks16887
Node: Amount display style17825
Ref: #amount-display-style17979
Node: Transaction prices19417
Ref: #transaction-prices19583
Node: Balance Assertions21849
Ref: #balance-assertions22029
Node: Assertions and ordering23062
Ref: #assertions-and-ordering23250
Node: Assertions and included files23950
Ref: #assertions-and-included-files24193
Node: Assertions and multiple -f options24526
Ref: #assertions-and-multiple--f-options24782
Node: Assertions and commodities24914
Ref: #assertions-and-commodities25146
Node: Assertions and prices26303
Ref: #assertions-and-prices26517
Node: Assertions and subaccounts26957
Ref: #assertions-and-subaccounts27186
Node: Assertions and virtual postings27510
Ref: #assertions-and-virtual-postings27752
Node: Assertions and precision27894
Ref: #assertions-and-precision28087
Node: Balance Assignments28354
Ref: #balance-assignments28528
Node: Balance assignments and prices29692
Ref: #balance-assignments-and-prices29864
Node: Directives30088
Ref: #directives30247
Node: Directives and multiple files35928
Ref: #directives-and-multiple-files36111
Node: Comment blocks36775
Ref: #comment-blocks36958
Node: Including other files37134
Ref: #including-other-files37314
Node: Default year37722
Ref: #default-year37891
Node: Declaring commodities38298
Ref: #declaring-commodities38481
Node: Default commodity40287
Ref: #default-commodity40463
Node: Market prices41352
Ref: #market-prices41517
Node: Declaring accounts42358
Ref: #declaring-accounts42534
Node: Account comments43459
Ref: #account-comments43622
Node: Account subdirectives44046
Ref: #account-subdirectives44241
Node: Account types44554
Ref: #account-types44738
Node: Account display order46377
Ref: #account-display-order46547
Node: Rewriting accounts47698
Ref: #rewriting-accounts47883
Node: Basic aliases48640
Ref: #basic-aliases48786
Node: Regex aliases49490
Ref: #regex-aliases49662
Node: Combining aliases50380
Ref: #combining-aliases50573
Node: Aliases and multiple files51849
Ref: #aliases-and-multiple-files52058
Node: end aliases52637
Ref: #end-aliases52794
Node: Default parent account52895
Ref: #default-parent-account53063
Node: Periodic transactions53947
Ref: #periodic-transactions54122
Node: Periodic rule syntax55994
Ref: #periodic-rule-syntax56200
Node: Two spaces between period expression and description!56904
Ref: #two-spaces-between-period-expression-and-description57223
Node: Forecasting with periodic transactions57907
Ref: #forecasting-with-periodic-transactions58212
Node: Budgeting with periodic transactions60238
Ref: #budgeting-with-periodic-transactions60477
Node: Auto postings60926
Ref: #auto-postings61066
Node: Auto postings and multiple files63245
Ref: #auto-postings-and-multiple-files63449
Node: Auto postings and dates63658
Ref: #auto-postings-and-dates63932
Node: Auto postings and transaction balancing / inferred amounts / balance assertions64107
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions64458
Node: Auto posting tags64800
Ref: #auto-posting-tags65015
Node: Dates3251
Ref: #dates3350
Node: Simple dates3415
Ref: #simple-dates3541
Node: Secondary dates4050
Ref: #secondary-dates4204
Node: Posting dates5540
Ref: #posting-dates5669
Node: Status7041
Ref: #status7162
Node: Description8870
Ref: #description9004
Node: Payee and note9324
Ref: #payee-and-note9438
Node: Comments9773
Ref: #comments9899
Node: Tags11093
Ref: #tags11208
Node: Postings12601
Ref: #postings12729
Node: Virtual postings13755
Ref: #virtual-postings13872
Node: Account names15177
Ref: #account-names15318
Node: Amounts15805
Ref: #amounts15944
Node: Digit group marks17052
Ref: #digit-group-marks17200
Node: Amount display style18138
Ref: #amount-display-style18292
Node: Transaction prices19729
Ref: #transaction-prices19901
Node: Lot prices and lot dates22233
Ref: #lot-prices-and-lot-dates22430
Node: Balance assertions22918
Ref: #balance-assertions23104
Node: Assertions and ordering24137
Ref: #assertions-and-ordering24325
Node: Assertions and included files25025
Ref: #assertions-and-included-files25268
Node: Assertions and multiple -f options25601
Ref: #assertions-and-multiple--f-options25857
Node: Assertions and commodities25989
Ref: #assertions-and-commodities26221
Node: Assertions and prices27378
Ref: #assertions-and-prices27592
Node: Assertions and subaccounts28032
Ref: #assertions-and-subaccounts28261
Node: Assertions and virtual postings28585
Ref: #assertions-and-virtual-postings28827
Node: Assertions and precision28969
Ref: #assertions-and-precision29162
Node: Balance assignments29429
Ref: #balance-assignments29603
Node: Balance assignments and prices30767
Ref: #balance-assignments-and-prices30939
Node: Directives31163
Ref: #directives31322
Node: Directives and multiple files37013
Ref: #directives-and-multiple-files37196
Node: Comment blocks37860
Ref: #comment-blocks38043
Node: Including other files38219
Ref: #including-other-files38399
Node: Default year38807
Ref: #default-year38976
Node: Declaring commodities39383
Ref: #declaring-commodities39566
Node: Default commodity41372
Ref: #default-commodity41558
Node: Declaring market prices42447
Ref: #declaring-market-prices42642
Node: Declaring accounts43499
Ref: #declaring-accounts43685
Node: Account comments44610
Ref: #account-comments44773
Node: Account subdirectives45197
Ref: #account-subdirectives45392
Node: Account types45705
Ref: #account-types45889
Node: Account display order47528
Ref: #account-display-order47698
Node: Rewriting accounts48849
Ref: #rewriting-accounts49034
Node: Basic aliases49791
Ref: #basic-aliases49937
Node: Regex aliases50641
Ref: #regex-aliases50813
Node: Combining aliases51531
Ref: #combining-aliases51724
Node: Aliases and multiple files53000
Ref: #aliases-and-multiple-files53209
Node: end aliases53788
Ref: #end-aliases53945
Node: Default parent account54046
Ref: #default-parent-account54214
Node: Periodic transactions55098
Ref: #periodic-transactions55273
Node: Periodic rule syntax57145
Ref: #periodic-rule-syntax57351
Node: Two spaces between period expression and description!58055
Ref: #two-spaces-between-period-expression-and-description58374
Node: Forecasting with periodic transactions59058
Ref: #forecasting-with-periodic-transactions59363
Node: Budgeting with periodic transactions61389
Ref: #budgeting-with-periodic-transactions61628
Node: Auto postings62077
Ref: #auto-postings62217
Node: Auto postings and multiple files64396
Ref: #auto-postings-and-multiple-files64600
Node: Auto postings and dates64809
Ref: #auto-postings-and-dates65083
Node: Auto postings and transaction balancing / inferred amounts / balance assertions65258
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions65609
Node: Auto posting tags65951
Ref: #auto-posting-tags66166

End Tag Table

49
hledger-lib/hledger_journal.txt
View File

@ -57,7 +57,8 @@ FILE FORMAT
line, and any following indented lines beginning with a semicolon)
o 0 or more indented posting lines, describing what was transferred and
the accounts involved.
the accounts involved (indented comment lines are also allowed, but
not blank lines or non-indented lines).
Here's a simple journal file containing one transaction:
@ -295,7 +296,7 @@ FILE FORMAT
ces. But if you accidentally leave only one space (or tab) before the
amount, the amount will be considered part of the account name.
Virtual Postings
Virtual postings
A posting with a parenthesised account name is called a virtual posting
or unbalanced posting, which means it is exempt from the usual rule
that a transaction's postings must balance add up to zero.
@ -359,12 +360,19 @@ FILE FORMAT
3 "no. 42 green apples"
Amounts can be negative. The minus sign can be written before or after
a left-side commodity symbol:
Amounts can be preceded by a minus sign (or a plus sign, though plus is
the default), The sign can be written before or after a left-side com-
modity symbol:
-$1
$-1
One or more spaces between the sign and the number are acceptable when
parsing (but they won't be displayed in output):
+ $1
$- 1
Scientific E notation is allowed:
1E-6
@ -413,8 +421,8 @@ FILE FORMAT
o Otherwise the format of the first posting amount in that commodity
seen in the journal is used. But the number of decimal places ("pre-
cision") will be the maximum from all posting amounts in that comm-
modity.
cision") will be the maximum from all posting amounts in that commod-
ity.
o Or if there are no such amounts in the journal, a default format is
used (like $1000.00).
@ -464,8 +472,9 @@ FILE FORMAT
assets:euros EUR100 ; one hundred euros purchased
assets:dollars $-135 ; for $135
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
PRICE}, which hledger currently ignores).
5. Like 1 and 2, but the @ or @@ is parenthesised; this is for compati-
bility with Ledger journals (Virtual posting costs), and in hledger
is equivalent to 1 and 2.
Use the -B/--cost flag to convert amounts to their transaction price's
commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger).
@ -491,7 +500,16 @@ FILE FORMAT
EUR-100 assets:dollars # <- the dollars' selling price
EUR100 assets:euros
Balance Assertions
Lot prices and lot dates
Ledger allows another kind of price, lot price (four variants: {UNIT-
PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}),
and/or a lot date ([DATE]) to be specified. These are normally used to
select a lot when selling investments. hledger will parse these, for
compatibility with Ledger journals, but currently ignores them. A
transaction price, lot price and/or lot date may appear in any order,
after the posting amount and before the balance assertion if any.
Balance assertions
hledger supports Ledger-style balance assertions in journal files.
These look like, for example, = EXPECTEDBALANCE following a posting's
amount. Eg here we assert the expected dollar balance in accounts a
@ -614,7 +632,7 @@ FILE FORMAT
limit the display precision, but this will not affect balance asser-
tions. Balance assertion failure messages show exact amounts.
Balance Assignments
Balance assignments
Ledger-style balance assignments are also supported. These are like
balance assertions, but with no posting amount on the left side of the
equals sign; instead it is calculated automatically so as to satisfy
@ -710,6 +728,9 @@ FILE FORMAT
commodity commodity in re-
ports, when -V is
used
Y declare a year for yearless following in-
dates line/included en-
tries until end of
@ -863,7 +884,7 @@ FILE FORMAT
a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
b
Market prices
Declaring market prices
The P directive declares a market price, which is an exchange rate be-
tween two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange,
@ -886,8 +907,8 @@ FILE FORMAT
P 2009/1/1 EUR $1.35
P 2010/1/1 EUR $1.40
The -V/--value flag can be used to convert reported amounts to another
commodity using these prices.
The -V, -X and --value flags use these market prices to show amount
values in another commodity. See Valuation.
Declaring accounts
account directives can be used to pre-declare accounts. Though not re-
@ -1458,4 +1479,4 @@ SEE ALSO
hledger 1.17.99 March 2020 hledger_journal(5)
hledger 1.17.99 May 2020 hledger_journal(5)

2
hledger-lib/hledger_timeclock.5
View File

@ -1,5 +1,5 @@
.TH "hledger_timeclock" "5" "March 2020" "hledger 1.17.99" "hledger User Manuals"
.TH "hledger_timeclock" "5" "May 2020" "hledger 1.17.99" "hledger User Manuals"

2
hledger-lib/hledger_timeclock.txt
View File

@ -78,4 +78,4 @@ SEE ALSO
hledger 1.17.99 March 2020 hledger_timeclock(5)
hledger 1.17.99 May 2020 hledger_timeclock(5)

2
hledger-lib/hledger_timedot.5
View File

@ -1,5 +1,5 @@
.TH "hledger_timedot" "5" "March 2020" "hledger 1.17.99" "hledger User Manuals"
.TH "hledger_timedot" "5" "May 2020" "hledger 1.17.99" "hledger User Manuals"

2
hledger-lib/hledger_timedot.txt
View File

@ -161,4 +161,4 @@ SEE ALSO
hledger 1.17.99 March 2020 hledger_timedot(5)
hledger 1.17.99 May 2020 hledger_timedot(5)

2
hledger-ui/defs.m4
View File

@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion.
m4_define({{_version_}}, {{1.17.99}})m4_dnl
m4_dnl
m4_dnl Date to show in man pages. Updated by make setdate.
m4_define({{_monthyear_}}, {{March 2020}})m4_dnl
m4_define({{_monthyear_}}, {{May 2020}})m4_dnl

2
hledger-ui/hledger-ui.1
View File

@ -1,5 +1,5 @@
.TH "hledger-ui" "1" "March 2020" "hledger-ui 1.17.99" "hledger User Manuals"
.TH "hledger-ui" "1" "May 2020" "hledger-ui 1.17.99" "hledger User Manuals"

2
hledger-ui/hledger-ui.txt
View File

@ -441,4 +441,4 @@ SEE ALSO
hledger-ui 1.17.99 March 2020 hledger-ui(1)
hledger-ui 1.17.99 May 2020 hledger-ui(1)

2
hledger-web/defs.m4
View File

@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion.
m4_define({{_version_}}, {{1.17.99}})m4_dnl
m4_dnl
m4_dnl Date to show in man pages. Updated by make setdate.
m4_define({{_monthyear_}}, {{March 2020}})m4_dnl
m4_define({{_monthyear_}}, {{May 2020}})m4_dnl

219
hledger-web/hledger-web.1
View File

@ -1,5 +1,5 @@
.TH "hledger-web" "1" "March 2020" "hledger-web 1.17.99" "hledger User Manuals"
.TH "hledger-web" "1" "May 2020" "hledger-web 1.17.99" "hledger User Manuals"
@ -316,10 +316,20 @@ message until the file has been fixed.
that both machine clocks are roughly in step.)
.SH JSON API
.PP
In addition to the web UI, hledger-web provides some API routes that
serve JSON in response to GET requests.
(And when started with \f[C]--serve-api\f[R], it provides only these
routes.):
In addition to the web UI, hledger-web also serves a JSON API that can
be used to get data or add new transactions.
If you want the JSON API only, you can use the \f[C]--serve-api\f[R]
flag.
Eg:
.IP
.nf
\f[C]
$ hledger-web -f examples/sample.journal --serve-api
\&...
\f[R]
.fi
.PP
You can get JSON data from these routes:
.IP
.nf
\f[C]
@ -328,48 +338,201 @@ routes.):
/prices
/commodities
/accounts
/accounttransactions/#AccountName
/accounttransactions/ACCOUNTNAME
\f[R]
.fi
.PP
Also, you can append a new transaction to the journal by sending a PUT
request to \f[C]/add\f[R] (hledger-web only).
As with the web UI\[aq]s add form, hledger-web must be started with the
\f[C]add\f[R] capability for this (enabled by default).
Eg, all account names in the journal (similar to the accounts command):
.IP
.nf
\f[C]
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
[
\[dq]assets\[dq],
\[dq]assets:bank\[dq],
\[dq]assets:bank:checking\[dq],
\[dq]assets:bank:saving\[dq],
\[dq]assets:cash\[dq],
\[dq]expenses\[dq],
\[dq]expenses:food\[dq],
\[dq]expenses:supplies\[dq],
\[dq]income\[dq],
\[dq]income:gifts\[dq],
\[dq]income:salary\[dq],
\[dq]liabilities\[dq],
\[dq]liabilities:debts\[dq]
]
\f[R]
.fi
.PP
The payload should be a valid hledger transaction as JSON, similar to
what you get from \f[C]/transactions\f[R] or
\f[C]/accounttransactions\f[R].
Or all transactions:
.IP
.nf
\f[C]
$ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
[
{
\[dq]tcode\[dq]: \[dq]\[dq],
\[dq]tcomment\[dq]: \[dq]\[dq],
\[dq]tdate\[dq]: \[dq]2008-01-01\[dq],
\[dq]tdate2\[dq]: null,
\[dq]tdescription\[dq]: \[dq]income\[dq],
\[dq]tindex\[dq]: 1,
\[dq]tpostings\[dq]: [
{
\[dq]paccount\[dq]: \[dq]assets:bank:checking\[dq],
\[dq]pamount\[dq]: [
{
\[dq]acommodity\[dq]: \[dq]$\[dq],
\[dq]aismultiplier\[dq]: false,
\[dq]aprice\[dq]: null,
\&...
\f[R]
.fi
.PP
Another way to generate test data is with the
\f[C]readJsonFile\f[R]/\f[C]writeJsonFile\f[R] helpers in
Hledger.Web.Json, which can write or read most of hledger\[aq]s data
types to or from a file.
Eg here we write the first transaction of a sample journal:
Most of the JSON corresponds to hledger\[aq]s data types; for details of
what the fields mean, see the Hledger.Data.Json haddock docs and click
on the various data types, eg Transaction.
And for a higher level understanding, see the journal manual.
.PP
In some cases there is outer JSON corresponding to a \[dq]Report\[dq]
type.
To understand that, go to the Hledger.Web.Handler.MiscR haddock and look
at the source for the appropriate handler to see what it returns.
Eg for \f[C]/accounttransactions\f[R] it\[aq]s getAccounttransactionsR,
returning a \[dq]\f[C]accountTransactionsReport ...\f[R]\[dq].
Looking up the haddock for that we can see that /accounttransactions
returns an AccountTransactionsReport, which consists of a report title
and a list of AccountTransactionsReportItem (etc).
.PP
You can add a new transaction to the journal with a PUT request to
\f[C]/add\f[R], if hledger-web was started with the \f[C]add\f[R]
capability (enabled by default).
The payload must be the full, exact JSON representation of a hledger
transaction (partial data won\[aq]t do).
You can get sample JSON from \f[C]/transactions\f[R] or
\f[C]/accounttransactions\f[R], or you can export it with
hledger-lib\[aq]s \f[C]writeJsonFile\f[R] helper, like so:
.IP
.nf
\f[C]
$ make ghci-web
>>> :m +*Hledger.Web.Json
>>> writeJsonFile \[dq]txn.json\[dq] (head $ jtxns samplejournal)
>>> import Hledger
>>> writeJsonFile \[dq]txn.json\[dq] (head $ jtxns samplejournal) -- export samplejournal\[aq]s first txn
>>> :q
$ python -m json.tool <txn.json >txn.pretty.json # optional: make human-readable
\f[R]
.fi
.PP
(sample output & discussion)
.PP
And here\[aq]s how to test adding that with curl:
If you like, reformat the json to make it human-readable:
.IP
.nf
\f[C]
$ curl -s http://127.0.0.1:5000/add -X PUT -H \[aq]Content-Type: application/json\[aq] --data-binary \[at]txn.pretty.json; echo
$ python -m json.tool txn.json >pretty
$ mv pretty txn.json
\f[R]
.fi
.PP
By default, both the server-side HTML UI and the JSON API are served.
Running with \f[C]--serve-api\f[R] disables the former, useful if you
only want to serve the API.
Here\[aq]s how it looks as of hledger-1.17 (remember, this JSON
corresponds to hledger\[aq]s Transaction and related data types):
.IP
.nf
\f[C]
{
\[dq]tcode\[dq]: \[dq]\[dq],
\[dq]tcomment\[dq]: \[dq]\[dq],
\[dq]tdate\[dq]: \[dq]2008-01-01\[dq],
\[dq]tdate2\[dq]: null,
\[dq]tdescription\[dq]: \[dq]income\[dq],
\[dq]tindex\[dq]: 1,
\[dq]tpostings\[dq]: [
{
\[dq]paccount\[dq]: \[dq]assets:bank:checking\[dq],
\[dq]pamount\[dq]: [
{
\[dq]acommodity\[dq]: \[dq]$\[dq],
\[dq]aismultiplier\[dq]: false,
\[dq]aprice\[dq]: null,
\[dq]aquantity\[dq]: {
\[dq]decimalMantissa\[dq]: 10000000000,
\[dq]decimalPlaces\[dq]: 10,
\[dq]floatingPoint\[dq]: 1
},
\[dq]astyle\[dq]: {
\[dq]ascommodityside\[dq]: \[dq]L\[dq],
\[dq]ascommodityspaced\[dq]: false,
\[dq]asdecimalpoint\[dq]: \[dq].\[dq],
\[dq]asdigitgroups\[dq]: null,
\[dq]asprecision\[dq]: 2
}
}
],
\[dq]pbalanceassertion\[dq]: null,
\[dq]pcomment\[dq]: \[dq]\[dq],
\[dq]pdate\[dq]: null,
\[dq]pdate2\[dq]: null,
\[dq]poriginal\[dq]: null,
\[dq]pstatus\[dq]: \[dq]Unmarked\[dq],
\[dq]ptags\[dq]: [],
\[dq]ptransaction_\[dq]: \[dq]1\[dq],
\[dq]ptype\[dq]: \[dq]RegularPosting\[dq]
},
{
\[dq]paccount\[dq]: \[dq]income:salary\[dq],
\[dq]pamount\[dq]: [
{
\[dq]acommodity\[dq]: \[dq]$\[dq],
\[dq]aismultiplier\[dq]: false,
\[dq]aprice\[dq]: null,
\[dq]aquantity\[dq]: {
\[dq]decimalMantissa\[dq]: -10000000000,
\[dq]decimalPlaces\[dq]: 10,
\[dq]floatingPoint\[dq]: -1
},
\[dq]astyle\[dq]: {
\[dq]ascommodityside\[dq]: \[dq]L\[dq],
\[dq]ascommodityspaced\[dq]: false,
\[dq]asdecimalpoint\[dq]: \[dq].\[dq],
\[dq]asdigitgroups\[dq]: null,
\[dq]asprecision\[dq]: 2
}
}
],
\[dq]pbalanceassertion\[dq]: null,
\[dq]pcomment\[dq]: \[dq]\[dq],
\[dq]pdate\[dq]: null,
\[dq]pdate2\[dq]: null,
\[dq]poriginal\[dq]: null,
\[dq]pstatus\[dq]: \[dq]Unmarked\[dq],
\[dq]ptags\[dq]: [],
\[dq]ptransaction_\[dq]: \[dq]1\[dq],
\[dq]ptype\[dq]: \[dq]RegularPosting\[dq]
}
],
\[dq]tprecedingcomment\[dq]: \[dq]\[dq],
\[dq]tsourcepos\[dq]: {
\[dq]contents\[dq]: [
\[dq]\[dq],
[
1,
1
]
],
\[dq]tag\[dq]: \[dq]JournalSourcePos\[dq]
},
\[dq]tstatus\[dq]: \[dq]Unmarked\[dq],
\[dq]ttags\[dq]: []
}
\f[R]
.fi
.PP
And here\[aq]s how to test adding it with curl.
This should add a new entry to your journal:
.IP
.nf
\f[C]
$ curl http://127.0.0.1:5000/add -X PUT -H \[aq]Content-Type: application/json\[aq] --data-binary \[at]txn.json
\f[R]
.fi
.SH ENVIRONMENT
.PP
\f[B]LEDGER_FILE\f[R] The journal file path when not specified with

200
hledger-web/hledger-web.info
View File

@ -330,45 +330,187 @@ File: hledger-web.info, Node: JSON API, Next: ENVIRONMENT, Prev: RELOADING,
5 JSON API
**********
In addition to the web UI, hledger-web provides some API routes that
serve JSON in response to GET requests. (And when started with
'--serve-api', it provides only these routes.):
In addition to the web UI, hledger-web also serves a JSON API that can
be used to get data or add new transactions. If you want the JSON API
only, you can use the '--serve-api' flag. Eg:
$ hledger-web -f examples/sample.journal --serve-api
...
You can get JSON data from these routes:
/accountnames
/transactions
/prices
/commodities
/accounts
/accounttransactions/#AccountName
/accounttransactions/ACCOUNTNAME
Also, you can append a new transaction to the journal by sending a
PUT request to '/add' (hledger-web only). As with the web UI's add
form, hledger-web must be started with the 'add' capability for this
(enabled by default).
Eg, all account names in the journal (similar to the accounts
command):
The payload should be a valid hledger transaction as JSON, similar to
what you get from '/transactions' or '/accounttransactions'.
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
[
"assets",
"assets:bank",
"assets:bank:checking",
"assets:bank:saving",
"assets:cash",
"expenses",
"expenses:food",
"expenses:supplies",
"income",
"income:gifts",
"income:salary",
"liabilities",
"liabilities:debts"
]
Another way to generate test data is with the
'readJsonFile'/'writeJsonFile' helpers in Hledger.Web.Json, which can
write or read most of hledger's data types to or from a file. Eg here
we write the first transaction of a sample journal:
Or all transactions:
$ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
[
{
"tcode": "",
"tcomment": "",
"tdate": "2008-01-01",
"tdate2": null,
"tdescription": "income",
"tindex": 1,
"tpostings": [
{
"paccount": "assets:bank:checking",
"pamount": [
{
"acommodity": "$",
"aismultiplier": false,
"aprice": null,
...
Most of the JSON corresponds to hledger's data types; for details of
what the fields mean, see the Hledger.Data.Json haddock docs and click
on the various data types, eg Transaction. And for a higher level
understanding, see the journal manual.
In some cases there is outer JSON corresponding to a "Report" type.
To understand that, go to the Hledger.Web.Handler.MiscR haddock and look
at the source for the appropriate handler to see what it returns. Eg
for '/accounttransactions' it's getAccounttransactionsR, returning a
"'accountTransactionsReport ...'". Looking up the haddock for that we
can see that /accounttransactions returns an AccountTransactionsReport,
which consists of a report title and a list of
AccountTransactionsReportItem (etc).
You can add a new transaction to the journal with a PUT request to
'/add', if hledger-web was started with the 'add' capability (enabled by
default). The payload must be the full, exact JSON representation of a
hledger transaction (partial data won't do). You can get sample JSON
from '/transactions' or '/accounttransactions', or you can export it
with hledger-lib's 'writeJsonFile' helper, like so:
$ make ghci-web
>>> :m +*Hledger.Web.Json
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal)
>>> import Hledger
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal) -- export samplejournal's first txn
>>> :q
$ python -m json.tool <txn.json >txn.pretty.json # optional: make human-readable
(sample output & discussion)
If you like, reformat the json to make it human-readable:
And here's how to test adding that with curl:
$ python -m json.tool txn.json >pretty
$ mv pretty txn.json
$ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo
Here's how it looks as of hledger-1.17 (remember, this JSON
corresponds to hledger's Transaction and related data types):
By default, both the server-side HTML UI and the JSON API are served.
Running with '--serve-api' disables the former, useful if you only want
to serve the API.
{
"tcode": "",
"tcomment": "",
"tdate": "2008-01-01",
"tdate2": null,
"tdescription": "income",
"tindex": 1,
"tpostings": [
{
"paccount": "assets:bank:checking",
"pamount": [
{
"acommodity": "$",
"aismultiplier": false,
"aprice": null,
"aquantity": {
"decimalMantissa": 10000000000,
"decimalPlaces": 10,
"floatingPoint": 1
},
"astyle": {
"ascommodityside": "L",
"ascommodityspaced": false,
"asdecimalpoint": ".",
"asdigitgroups": null,
"asprecision": 2
}
}
],
"pbalanceassertion": null,
"pcomment": "",
"pdate": null,
"pdate2": null,
"poriginal": null,
"pstatus": "Unmarked",
"ptags": [],
"ptransaction_": "1",
"ptype": "RegularPosting"
},
{
"paccount": "income:salary",
"pamount": [
{
"acommodity": "$",
"aismultiplier": false,
"aprice": null,
"aquantity": {
"decimalMantissa": -10000000000,
"decimalPlaces": 10,
"floatingPoint": -1
},
"astyle": {
"ascommodityside": "L",
"ascommodityspaced": false,
"asdecimalpoint": ".",
"asdigitgroups": null,
"asprecision": 2
}
}
],
"pbalanceassertion": null,
"pcomment": "",
"pdate": null,
"pdate2": null,
"poriginal": null,
"pstatus": "Unmarked",
"ptags": [],
"ptransaction_": "1",
"ptype": "RegularPosting"
}
],
"tprecedingcomment": "",
"tsourcepos": {
"contents": [
"",
[
1,
1
]
],
"tag": "JournalSourcePos"
},
"tstatus": "Unmarked",
"ttags": []
}
And here's how to test adding it with curl. This should add a new
entry to your journal:
$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json

File: hledger-web.info, Node: ENVIRONMENT, Next: FILES, Prev: JSON API, Up: Top
@ -437,12 +579,12 @@ Node: RELOADING10567
Ref: #reloading10701
Node: JSON API11134
Ref: #json-api11248
Node: ENVIRONMENT12686
Ref: #environment12802
Node: FILES13535
Ref: #files13635
Node: BUGS13848
Ref: #bugs13926
Node: ENVIRONMENT16812
Ref: #environment16928
Node: FILES17661
Ref: #files17761
Node: BUGS17974
Ref: #bugs18052

End Tag Table

189
hledger-web/hledger-web.txt
View File

@ -289,45 +289,186 @@ RELOADING
that both machine clocks are roughly in step.)
JSON API
In addition to the web UI, hledger-web provides some API routes that
serve JSON in response to GET requests. (And when started with
--serve-api, it provides only these routes.):
In addition to the web UI, hledger-web also serves a JSON API that can
be used to get data or add new transactions. If you want the JSON API
only, you can use the --serve-api flag. Eg:
$ hledger-web -f examples/sample.journal --serve-api
...
You can get JSON data from these routes:
/accountnames
/transactions
/prices
/commodities
/accounts
/accounttransactions/#AccountName
/accounttransactions/ACCOUNTNAME
Also, you can append a new transaction to the journal by sending a PUT
request to /add (hledger-web only). As with the web UI's add form,
hledger-web must be started with the add capability for this (enabled
by default).
Eg, all account names in the journal (similar to the accounts command):
The payload should be a valid hledger transaction as JSON, similar to
what you get from /transactions or /accounttransactions.
$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
[
"assets",
"assets:bank",
"assets:bank:checking",
"assets:bank:saving",
"assets:cash",
"expenses",
"expenses:food",
"expenses:supplies",
"income",
"income:gifts",
"income:salary",
"liabilities",
"liabilities:debts"
]
Another way to generate test data is with the readJsonFile/writeJson-
File helpers in Hledger.Web.Json, which can write or read most of
hledger's data types to or from a file. Eg here we write the first
transaction of a sample journal:
Or all transactions:
$ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
[
{
"tcode": "",
"tcomment": "",
"tdate": "2008-01-01",
"tdate2": null,
"tdescription": "income",
"tindex": 1,
"tpostings": [
{
"paccount": "assets:bank:checking",
"pamount": [
{
"acommodity": "$",
"aismultiplier": false,
"aprice": null,
...
Most of the JSON corresponds to hledger's data types; for details of
what the fields mean, see the Hledger.Data.Json haddock docs and click
on the various data types, eg Transaction. And for a higher level un-
derstanding, see the journal manual.
In some cases there is outer JSON corresponding to a "Report" type. To
understand that, go to the Hledger.Web.Handler.MiscR haddock and look
at the source for the appropriate handler to see what it returns. Eg
for /accounttransactions it's getAccounttransactionsR, returning a "ac-
countTransactionsReport ...". Looking up the haddock for that we can
see that /accounttransactions returns an AccountTransactionsReport,
which consists of a report title and a list of AccountTransactionsRe-
portItem (etc).
You can add a new transaction to the journal with a PUT request to
/add, if hledger-web was started with the add capability (enabled by
default). The payload must be the full, exact JSON representation of a
hledger transaction (partial data won't do). You can get sample JSON
from /transactions or /accounttransactions, or you can export it with
hledger-lib's writeJsonFile helper, like so:
$ make ghci-web
>>> :m +*Hledger.Web.Json
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal)
>>> import Hledger
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal) -- export samplejournal's first txn
>>> :q
$ python -m json.tool <txn.json >txn.pretty.json # optional: make human-readable
(sample output & discussion)
If you like, reformat the json to make it human-readable:
And here's how to test adding that with curl:
$ python -m json.tool txn.json >pretty
$ mv pretty txn.json
$ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo
Here's how it looks as of hledger-1.17 (remember, this JSON corresponds
to hledger's Transaction and related data types):
By default, both the server-side HTML UI and the JSON API are served.
Running with --serve-api disables the former, useful if you only want
to serve the API.
{
"tcode": "",
"tcomment": "",
"tdate": "2008-01-01",
"tdate2": null,
"tdescription": "income",
"tindex": 1,
"tpostings": [
{
"paccount": "assets:bank:checking",
"pamount": [
{
"acommodity": "$",
"aismultiplier": false,
"aprice": null,
"aquantity": {
"decimalMantissa": 10000000000,
"decimalPlaces": 10,
"floatingPoint": 1
},
"astyle": {
"ascommodityside": "L",
"ascommodityspaced": false,
"asdecimalpoint": ".",
"asdigitgroups": null,
"asprecision": 2
}
}
],
"pbalanceassertion": null,
"pcomment": "",
"pdate": null,
"pdate2": null,
"poriginal": null,
"pstatus": "Unmarked",
"ptags": [],
"ptransaction_": "1",
"ptype": "RegularPosting"
},
{
"paccount": "income:salary",
"pamount": [
{
"acommodity": "$",
"aismultiplier": false,
"aprice": null,
"aquantity": {
"decimalMantissa": -10000000000,
"decimalPlaces": 10,
"floatingPoint": -1
},
"astyle": {
"ascommodityside": "L",
"ascommodityspaced": false,
"asdecimalpoint": ".",
"asdigitgroups": null,
"asprecision": 2
}
}
],
"pbalanceassertion": null,
"pcomment": "",
"pdate": null,
"pdate2": null,
"poriginal": null,
"pstatus": "Unmarked",
"ptags": [],
"ptransaction_": "1",
"ptype": "RegularPosting"
}
],
"tprecedingcomment": "",
"tsourcepos": {
"contents": [
"",
[
1,
1
]
],
"tag": "JournalSourcePos"
},
"tstatus": "Unmarked",
"ttags": []
}
And here's how to test adding it with curl. This should add a new en-
try to your journal:
$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
ENVIRONMENT
LEDGER_FILE The journal file path when not specified with -f. Default:
@ -392,4 +533,4 @@ SEE ALSO
hledger-web 1.17.99 March 2020 hledger-web(1)
hledger-web 1.17.99 May 2020 hledger-web(1)

2
hledger/defs.m4
View File

@ -4,4 +4,4 @@ m4_dnl Program version. Updated by make setversion.
m4_define({{_version_}}, {{1.17.99}})m4_dnl
m4_dnl
m4_dnl Date to show in man pages. Updated by make setdate.
m4_define({{_monthyear_}}, {{March 2020}})m4_dnl
m4_define({{_monthyear_}}, {{May 2020}})m4_dnl

194
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t
.TH "hledger" "1" "March 2020" "hledger 1.17.99" "hledger User Manuals"
.TH "hledger" "1" "May 2020" "hledger 1.17.99" "hledger User Manuals"
@ -1136,20 +1136,28 @@ account alias directives and options:
\f[C]--alias /REGEX/=REPLACEMENT\f[R]
.PP
hledger\[aq]s regular expressions come from the regex-tdfa library.
In general they:
.IP \[bu] 2
are case insensitive
.IP \[bu] 2
are infix matching (do not need to match the entire thing being matched)
.IP \[bu] 2
are POSIX extended regular expressions
.IP \[bu] 2
also support GNU word boundaries (\[rs]<, \[rs]>, \[rs]b, \[rs]B)
.IP \[bu] 2
and parenthesised capturing groups and numeric backreferences in
replacement strings
.IP \[bu] 2
do not support mode modifiers like (?s)
If they\[aq]re not doing what you expect, it\[aq]s important to know
exactly what they support:
.IP "1." 3
they are case insensitive
.IP "2." 3
they are infix matching (they do not need to match the entire thing
being matched)
.IP "3." 3
they are POSIX ERE (extended regular expressions)
.IP "4." 3
they also support GNU word boundaries (\f[C]\[rs]b\f[R],
\f[C]\[rs]B\f[R], \f[C]\[rs]<\f[R], \f[C]\[rs]>\f[R])
.IP "5." 3
they do not support backreferences; if you write \f[C]\[rs]1\f[R], it
will match the digit \f[C]1\f[R].
Except when doing text replacement, eg in account aliases, where
backreferences can be used in the replacement string to reference
capturing groups in the search regexp.
.IP "6." 3
they do not support mode modifiers (\f[C](?s)\f[R]), character classes
(\f[C]\[rs]w\f[R], \f[C]\[rs]d\f[R]), or anything else not mentioned
above.
.PP
Some things to note:
.IP \[bu] 2
@ -1671,31 +1679,48 @@ $ hledger balance --pivot member acct:.
\f[R]
.fi
.SS Valuation
.PP
hledger can show cost reports, where amounts are converted to their cost
or sale amount at transaction time; or value reports, where amounts are
converted to their market value in another currency/commodity at a
specified date (using market prices inferred from your transactions, or
declared with P directives).
.PP
We call this \[dq]valuation\[dq], and it is controlled by the
\f[C]--value=VALUATIONTYPE[,COMMODITY]\f[R] option.
It can get a little involved, so we cover all the details below.
But most of the time, all you need to do is use these simpler flags
instead:
.IP \[bu] 2
\f[C]-B\f[R] to convert to cost/sale amount, or
.IP \[bu] 2
\f[C]-V\f[R] to convert to market value in your base currency.
Or occasionally,
.IP \[bu] 2
\f[C]-X COMMODITY\f[R] to convert to market value in some other
currency.
.SS -B: Cost
.PP
The \f[C]-B/--cost\f[R] flag converts amounts to their cost (or selling
price) at transaction time, if they have a transaction price specified.
This flag is equivalent to \f[C]--value=cost\f[R], described below.
.SS -V: Market value
The \f[C]-B/--cost\f[R] flag converts amounts to their cost or sale
amount at transaction time, if they have a transaction price specified.
(It is equivalent to \f[C]--value=cost\f[R].)
.SS -V: Value
.PP
The \f[C]-V/--market\f[R] flag converts reported amounts to their market
value in a default valuation commodity, using the market prices in
effect on a default valuation date.
For single period reports, the valuation date is today (equivalent to
\f[C]--value=now\f[R]); for multiperiod reports, it is the last day of
each subperiod (equivalent to \f[C]--value=end\f[R]).
The \f[C]-V/--market\f[R] flag converts reported amounts to market value
in their \f[I]default valuation commodity\f[R], using the market prices
in effect on a \f[I]default valuation date\f[R].
(More on these below.)
.PP
The default valuation commodity is the one referenced in the latest
applicable market price dated on or before the valuation date.
If most of your P declarations lead to a single home currency, this will
usually be what you want.
(To specify the commodity, see -X below.)
Typically your P declarations or currency exchange transactions
reference a single base currency, and -V will pick that.
.PP
Note that in hledger, market prices are always declared explicitly with
P directives; we do not infer them from transaction prices as Ledger
does.
The default valuation date is today for single period reports
(equivalent to \f[C]--value=now\f[R]), or the last day of each subperiod
for multiperiod reports (equivalent to \f[C]--value=end\f[R]).
.PP
Here\[aq]s a quick example of -V:
An example:
.IP
.nf
\f[C]
@ -1743,8 +1768,31 @@ $ hledger -f t.j bal -N euros -V
.PP
The \f[C]-X/--exchange\f[R] option is like \f[C]-V\f[R], except it
specifies the target commodity you would like to convert to.
It is equivalent to \f[C]--value=now,COMM\f[R] or
\f[C]--value=end,COMM\f[R].
(It is equivalent to \f[C]--value=now,COMM\f[R] or
\f[C]--value=end,COMM\f[R].)
.SS Market prices
.PP
To convert a commodity A to commodity B, hledger looks for a suitable
market price (exchange rate) in the following ways, in this order of
preference:
.IP "1." 3
a \f[I]declared market price\f[R] - the latest P directive specifying
the exchange rate from A to B, dated on or before the valuation date.
.IP "2." 3
a \f[I]transaction-implied market price\f[R] - a market price matching
the transaction price used in the latest transaction where A is
converted to B, dated on or before the valuation date.
(\f[I]since hledger 1.18; experimental\f[R])
.IP "3." 3
a \f[I]reverse declared market price\f[R] - calculated by inverting a
declared market price from B to A.
.IP "4." 3
a \f[I]reverse transaction-implied market price\f[R] - calculated by
inverting a transaction-implied market price from B to A.
.IP "5." 3
an \f[I]indirect market price\f[R] - calculated by combining the
shortest chain of market prices (any of the above types) leading from A
to B.
.SS --value: Flexible valuation
.PP
\f[I](experimental, added 201905)\f[R]
@ -2243,9 +2291,6 @@ otherwise the latest transaction date in the journal, otherwise today.
\f[I]report interval\f[R]
a flag (-D/-W/-M/-Q/-Y) or period expression that activates the
report\[aq]s multi-period mode (whether showing one or many subperiods).
.SS Combining -B, -V, -X, --value
.PP
The rightmost of these flags wins.
.SH COMMANDS
.PP
hledger provides a number of subcommands; \f[C]hledger\f[R] with no
@ -4173,7 +4218,7 @@ $ hledger test -- -pData.Amount --color=never
.PP
For help on these, see https://github.com/feuerbach/tasty#options
(\f[C]-- --help\f[R] currently doesn\[aq]t show them).
.SS Add-on Commands
.SS Add-on commands
.PP
hledger also searches for external add-on commands, and will include
these in the commands list.
@ -4312,45 +4357,42 @@ The command \f[C]env | grep LEDGER_FILE\f[R] should show it.
You may need to use \f[C]export\f[R].
Here\[aq]s an explanation.
.PP
\f[B]\[dq]Illegal byte sequence\[dq] or \[dq]Invalid or incomplete
multibyte or wide character\[dq] errors\f[R]
\f[B]Getting errors like \[dq]Illegal byte sequence\[dq] or \[dq]Invalid
or incomplete multibyte or wide character\[dq] or
\[dq]commitAndReleaseBuffer: invalid argument (invalid
character)\[dq]\f[R]
.PD 0
.P
.PD
In order to handle non-ascii letters and symbols (like \[Po]), hledger
needs an appropriate locale.
This is usually configured system-wide; you can also configure it
temporarily.
The locale may need to be one that supports UTF-8, if you built hledger
with GHC < 7.2 (or possibly always, I\[aq]m not sure yet).
Programs compiled with GHC (hledger, haskell build tools, etc.) need to
have a UTF-8-aware locale configured in the environment, otherwise they
will fail with these kinds of errors when they encounter non-ascii
characters.
.PP
Here\[aq]s an example of setting the locale temporarily, on ubuntu
gnu/linux:
To fix it, set the LANG environment variable to some locale which
supports UTF-8.
The locale you choose must be installed on your system.
.PP
Here\[aq]s an example of setting LANG temporarily, on Ubuntu GNU/Linux:
.IP
.nf
\f[C]
$ file my.journal
my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded
$ locale -a
my.journal: UTF-8 Unicode text # the file is UTF8-encoded
$ echo $LANG
C # LANG is set to the default locale, which does not support UTF8
$ locale -a # which locales are installed ?
C
en_US.utf8 # <- a UTF8-aware locale is available
en_US.utf8 # here\[aq]s a UTF8-aware one we can use
POSIX
$ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command
$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command
\f[R]
.fi
.PP
Here\[aq]s one way to set it permanently, there are probably better
ways:
.IP
.nf
\f[C]
$ echo \[dq]export LANG=en_US.UTF-8\[dq] >>\[ti]/.bash_profile
$ bash --login
\f[R]
.fi
.PP
If we preferred to use eg \f[C]fr_FR.utf8\f[R], we might have to install
that first:
If available, \f[C]C.UTF-8\f[R] will also work.
If your preferred locale isn\[aq]t listed by \f[C]locale -a\f[R], you
might need to install it.
Eg on Ubuntu/Debian:
.IP
.nf
\f[C]
@ -4368,9 +4410,27 @@ $ LANG=fr_FR.utf8 hledger -f my.journal print
\f[R]
.fi
.PP
Note some platforms allow variant locale spellings, but not all (ubuntu
accepts \f[C]fr_FR.UTF8\f[R], mac osx requires exactly
\f[C]fr_FR.UTF-8\f[R]).
Here\[aq]s how you could set it permanently, if you use a bash shell:
.IP
.nf
\f[C]
$ echo \[dq]export LANG=en_US.utf8\[dq] >>\[ti]/.bash_profile
$ bash --login
\f[R]
.fi
.PP
Exact spelling and capitalisation may be important.
Note the difference on MacOS (\f[C]UTF-8\f[R], not \f[C]utf8\f[R]).
Some platforms (eg ubuntu) allow variant spellings, but others (eg
macos) require it to be exact:
.IP
.nf
\f[C]
$ locale -a | grep -iE en_us.*utf
en_US.UTF-8
$ LANG=en_US.UTF-8 hledger -f my.journal print
\f[R]
.fi
.SH "REPORTING BUGS"

471
hledger/hledger.info
View File

@ -1052,17 +1052,22 @@ hledger uses regular expressions in a number of places:
* account alias directives and options: 'alias /REGEX/ =
REPLACEMENT', '--alias /REGEX/=REPLACEMENT'
hledger's regular expressions come from the regex-tdfa library. In
general they:
hledger's regular expressions come from the regex-tdfa library. If
they're not doing what you expect, it's important to know exactly what
they support:
* are case insensitive
* are infix matching (do not need to match the entire thing being
matched)
* are POSIX extended regular expressions
* also support GNU word boundaries (\<, \>, \b, \B)
* and parenthesised capturing groups and numeric backreferences in
replacement strings
* do not support mode modifiers like (?s)
1. they are case insensitive
2. they are infix matching (they do not need to match the entire thing
being matched)
3. they are POSIX ERE (extended regular expressions)
4. they also support GNU word boundaries ('\b', '\B', '\<', '\>')
5. they do not support backreferences; if you write '\1', it will
match the digit '1'. Except when doing text replacement, eg in
account aliases, where backreferences can be used in the
replacement string to reference capturing groups in the search
regexp.
6. they do not support mode modifiers ('(?s)'), character classes
('\w', '\d'), or anything else not mentioned above.
Some things to note:
@ -1365,47 +1370,61 @@ File: hledger.info, Node: Valuation, Prev: Pivoting, Up: OPTIONS
2.17 Valuation
==============
hledger can show cost reports, where amounts are converted to their cost
or sale amount at transaction time; or value reports, where amounts are
converted to their market value in another currency/commodity at a
specified date (using market prices inferred from your transactions, or
declared with P directives).
We call this "valuation", and it is controlled by the
'--value=VALUATIONTYPE[,COMMODITY]' option. It can get a little
involved, so we cover all the details below. But most of the time, all
you need to do is use these simpler flags instead:
* '-B' to convert to cost/sale amount, or
* '-V' to convert to market value in your base currency. Or
occasionally,
* '-X COMMODITY' to convert to market value in some other currency.
* Menu:
* -B Cost::
* -V Market value::
* -V Value::
* -X Market value in specified commodity::
* Market prices::
* --value Flexible valuation::
* Effect of --value on reports::
* Combining -B -V -X --value::

File: hledger.info, Node: -B Cost, Next: -V Market value, Up: Valuation
File: hledger.info, Node: -B Cost, Next: -V Value, Up: Valuation
2.17.1 -B: Cost
---------------
The '-B/--cost' flag converts amounts to their cost (or selling price)
at transaction time, if they have a transaction price specified. This
flag is equivalent to '--value=cost', described below.
The '-B/--cost' flag converts amounts to their cost or sale amount at
transaction time, if they have a transaction price specified. (It is
equivalent to '--value=cost'.)

File: hledger.info, Node: -V Market value, Next: -X Market value in specified commodity, Prev: -B Cost, Up: Valuation
File: hledger.info, Node: -V Value, Next: -X Market value in specified commodity, Prev: -B Cost, Up: Valuation
2.17.2 -V: Market value
-----------------------
2.17.2 -V: Value
----------------
The '-V/--market' flag converts reported amounts to their market value
in a default valuation commodity, using the market prices in effect on a
default valuation date. For single period reports, the valuation date
is today (equivalent to '--value=now'); for multiperiod reports, it is
the last day of each subperiod (equivalent to '--value=end').
The '-V/--market' flag converts reported amounts to market value in
their _default valuation commodity_, using the market prices in effect
on a _default valuation date_. (More on these below.)
The default valuation commodity is the one referenced in the latest
applicable market price dated on or before the valuation date. If most
of your P declarations lead to a single home currency, this will usually
be what you want. (To specify the commodity, see -X below.)
applicable market price dated on or before the valuation date.
Typically your P declarations or currency exchange transactions
reference a single base currency, and -V will pick that.
Note that in hledger, market prices are always declared explicitly
with P directives; we do not infer them from transaction prices as
Ledger does.
The default valuation date is today for single period reports
(equivalent to '--value=now'), or the last day of each subperiod for
multiperiod reports (equivalent to '--value=end').
Here's a quick example of -V:
An example:
; one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10
@ -1435,19 +1454,47 @@ $ hledger -f t.j bal -N euros -V
$103.00 assets:euros

File: hledger.info, Node: -X Market value in specified commodity, Next: --value Flexible valuation, Prev: -V Market value, Up: Valuation
File: hledger.info, Node: -X Market value in specified commodity, Next: Market prices, Prev: -V Value, Up: Valuation
2.17.3 -X: Market value in specified commodity
----------------------------------------------
The '-X/--exchange' option is like '-V', except it specifies the target
commodity you would like to convert to. It is equivalent to
'--value=now,COMM' or '--value=end,COMM'.
commodity you would like to convert to. (It is equivalent to
'--value=now,COMM' or '--value=end,COMM'.)

File: hledger.info, Node: --value Flexible valuation, Next: Effect of --value on reports, Prev: -X Market value in specified commodity, Up: Valuation
File: hledger.info, Node: Market prices, Next: --value Flexible valuation, Prev: -X Market value in specified commodity, Up: Valuation
2.17.4 -value: Flexible valuation
2.17.4 Market prices
--------------------
To convert a commodity A to commodity B, hledger looks for a suitable
market price (exchange rate) in the following ways, in this order of
preference:
1. a _declared market price_ - the latest P directive specifying the
exchange rate from A to B, dated on or before the valuation date.
2. a _transaction-implied market price_ - a market price matching the
transaction price used in the latest transaction where A is
converted to B, dated on or before the valuation date. (_since
hledger 1.18; experimental_)
3. a _reverse declared market price_ - calculated by inverting a
declared market price from B to A.
4. a _reverse transaction-implied market price_ - calculated by
inverting a transaction-implied market price from B to A.
5. an _indirect market price_ - calculated by combining the shortest
chain of market prices (any of the above types) leading from A to
B.

File: hledger.info, Node: --value Flexible valuation, Next: Effect of --value on reports, Prev: Market prices, Up: Valuation
2.17.5 -value: Flexible valuation
---------------------------------
_(experimental, added 201905)_
@ -1617,9 +1664,9 @@ $ hledger print -X A
b -0.50A

File: hledger.info, Node: Effect of --value on reports, Next: Combining -B -V -X --value, Prev: --value Flexible valuation, Up: Valuation
File: hledger.info, Node: Effect of --value on reports, Prev: --value Flexible valuation, Up: Valuation
2.17.5 Effect of -value on reports
2.17.6 Effect of -value on reports
----------------------------------
Here is a reference for how '--value' currently affects each part of
@ -1732,14 +1779,6 @@ _report interval_
report's multi-period mode (whether showing one or many
subperiods).

File: hledger.info, Node: Combining -B -V -X --value, Prev: Effect of --value on reports, Up: Valuation
2.17.6 Combining -B, -V, -X, -value
-----------------------------------
The rightmost of these flags wins.

File: hledger.info, Node: COMMANDS, Next: ENVIRONMENT, Prev: OPTIONS, Up: Top
@ -1793,7 +1832,7 @@ detailed command help.
* stats::
* tags::
* test::
* Add-on Commands::
* Add-on commands::

File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS
@ -3494,7 +3533,7 @@ considered. With -values flag, the tags' unique values are listed
instead.

File: hledger.info, Node: test, Next: Add-on Commands, Prev: tags, Up: COMMANDS
File: hledger.info, Node: test, Next: Add-on commands, Prev: tags, Up: COMMANDS
3.29 test
=========
@ -3521,9 +3560,9 @@ $ hledger test -- -pData.Amount --color=never
('-- --help' currently doesn't show them).

File: hledger.info, Node: Add-on Commands, Prev: test, Up: COMMANDS
File: hledger.info, Node: Add-on commands, Prev: test, Up: COMMANDS
3.30 Add-on Commands
3.30 Add-on commands
====================
hledger also searches for external add-on commands, and will include
@ -3562,7 +3601,7 @@ interfaces. These are maintained and released along with hledger:
* interest::

File: hledger.info, Node: ui, Next: web, Up: Add-on Commands
File: hledger.info, Node: ui, Next: web, Up: Add-on commands
3.30.1 ui
---------
@ -3570,7 +3609,7 @@ File: hledger.info, Node: ui, Next: web, Up: Add-on Commands
hledger-ui provides an efficient terminal interface.

File: hledger.info, Node: web, Next: iadd, Prev: ui, Up: Add-on Commands
File: hledger.info, Node: web, Next: iadd, Prev: ui, Up: Add-on commands
3.30.2 web
----------
@ -3580,7 +3619,7 @@ hledger-web provides a simple web interface.
Third party add-ons, maintained separately from hledger, include:

File: hledger.info, Node: iadd, Next: interest, Prev: web, Up: Add-on Commands
File: hledger.info, Node: iadd, Next: interest, Prev: web, Up: Add-on commands
3.30.3 iadd
-----------
@ -3589,7 +3628,7 @@ hledger-iadd is a more interactive, terminal UI replacement for the add
command.

File: hledger.info, Node: interest, Prev: iadd, Up: Add-on Commands
File: hledger.info, Node: interest, Prev: iadd, Up: Add-on commands
3.30.4 interest
---------------
@ -3689,32 +3728,32 @@ file*
variable. The command 'env | grep LEDGER_FILE' should show it. You may
need to use 'export'. Here's an explanation.
*"Illegal byte sequence" or "Invalid or incomplete multibyte or wide
character" errors*
In order to handle non-ascii letters and symbols (like £), hledger needs
an appropriate locale. This is usually configured system-wide; you can
also configure it temporarily. The locale may need to be one that
supports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
I'm not sure yet).
*Getting errors like "Illegal byte sequence" or "Invalid or
incomplete multibyte or wide character" or "commitAndReleaseBuffer:
invalid argument (invalid character)"*
Programs compiled with GHC (hledger, haskell build tools, etc.) need to
have a UTF-8-aware locale configured in the environment, otherwise they
will fail with these kinds of errors when they encounter non-ascii
characters.
Here's an example of setting the locale temporarily, on ubuntu
gnu/linux:
To fix it, set the LANG environment variable to some locale which
supports UTF-8. The locale you choose must be installed on your system.
Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:
$ file my.journal
my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded
$ locale -a
my.journal: UTF-8 Unicode text # the file is UTF8-encoded
$ echo $LANG
C # LANG is set to the default locale, which does not support UTF8
$ locale -a # which locales are installed ?
C
en_US.utf8 # <- a UTF8-aware locale is available
en_US.utf8 # here's a UTF8-aware one we can use
POSIX
$ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command
$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command
Here's one way to set it permanently, there are probably better ways:
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
$ bash --login
If we preferred to use eg 'fr_FR.utf8', we might have to install that
first:
If available, 'C.UTF-8' will also work. If your preferred locale
isn't listed by 'locale -a', you might need to install it. Eg on
Ubuntu/Debian:
$ apt-get install language-pack-fr
$ locale -a
@ -3728,8 +3767,18 @@ fr_LU.utf8
POSIX
$ LANG=fr_FR.utf8 hledger -f my.journal print
Note some platforms allow variant locale spellings, but not all
(ubuntu accepts 'fr_FR.UTF8', mac osx requires exactly 'fr_FR.UTF-8').
Here's how you could set it permanently, if you use a bash shell:
$ echo "export LANG=en_US.utf8" >>~/.bash_profile
$ bash --login
Exact spelling and capitalisation may be important. Note the
difference on MacOS ('UTF-8', not 'utf8'). Some platforms (eg ubuntu)
allow variant spellings, but others (eg macos) require it to be exact:
$ locale -a | grep -iE en_us.*utf
en_US.UTF-8
$ LANG=en_US.UTF-8 hledger -f my.journal print

Tag Table:
@ -3780,141 +3829,141 @@ Node: Output format32576
Ref: #output-format32726
Node: Regular expressions34774
Ref: #regular-expressions34931
Node: Smart dates36292
Ref: #smart-dates36443
Node: Report start & end date37804
Ref: #report-start-end-date37976
Node: Report intervals39414
Ref: #report-intervals39579
Node: Period expressions39969
Ref: #period-expressions40129
Node: Depth limiting44255
Ref: #depth-limiting44399
Node: Pivoting44741
Ref: #pivoting44864
Node: Valuation46540
Ref: #valuation46642
Node: -B Cost46822
Ref: #b-cost46933
Node: -V Market value47131
Ref: #v-market-value47305
Node: -X Market value in specified commodity48737
Ref: #x-market-value-in-specified-commodity48976
Node: --value Flexible valuation49152
Ref: #value-flexible-valuation49378
Node: Effect of --value on reports53883
Ref: #effect-of---value-on-reports54099
Node: Combining -B -V -X --value59645
Ref: #combining--b--v--x---value59828
Node: COMMANDS59864
Ref: #commands59972
Node: accounts61056
Ref: #accounts61154
Node: activity61853
Ref: #activity61963
Node: add62346
Ref: #add62445
Node: balance65184
Ref: #balance65295
Node: Classic balance report66753
Ref: #classic-balance-report66926
Node: Customising the classic balance report68295
Ref: #customising-the-classic-balance-report68523
Node: Colour support70599
Ref: #colour-support70766
Node: Flat mode70939
Ref: #flat-mode71087
Node: Depth limited balance reports71500
Ref: #depth-limited-balance-reports71685
Node: Percentages72141
Ref: #percentages72307
Node: Multicolumn balance report73444
Ref: #multicolumn-balance-report73624
Node: Budget report78886
Ref: #budget-report79029
Node: Nested budgets84295
Ref: #nested-budgets84407
Ref: #output-format-187888
Node: balancesheet88085
Ref: #balancesheet88221
Node: balancesheetequity89687
Ref: #balancesheetequity89836
Node: cashflow90559
Ref: #cashflow90687
Node: check-dates91866
Ref: #check-dates91993
Node: check-dupes92272
Ref: #check-dupes92396
Node: close92689
Ref: #close92803
Node: close usage94325
Ref: #close-usage94418
Node: commodities97231
Ref: #commodities97358
Node: descriptions97440
Ref: #descriptions97568
Node: diff97749
Ref: #diff97855
Node: files98902
Ref: #files99002
Node: help99149
Ref: #help99249
Node: import100330
Ref: #import100444
Node: Importing balance assignments101337
Ref: #importing-balance-assignments101485
Node: incomestatement102134
Ref: #incomestatement102267
Node: notes103754
Ref: #notes103867
Node: payees103993
Ref: #payees104099
Node: prices104257
Ref: #prices104363
Node: print104704
Ref: #print104814
Node: print-unique109600
Ref: #print-unique109726
Node: register110011
Ref: #register110138
Node: Custom register output114310
Ref: #custom-register-output114439
Node: register-match115776
Ref: #register-match115910
Node: rewrite116261
Ref: #rewrite116376
Node: Re-write rules in a file118231
Ref: #re-write-rules-in-a-file118365
Node: Diff output format119575
Ref: #diff-output-format119744
Node: rewrite vs print --auto120836
Ref: #rewrite-vs.-print---auto121015
Node: roi121571
Ref: #roi121669
Node: stats122681
Ref: #stats122780
Node: tags123568
Ref: #tags123666
Node: test123960
Ref: #test124068
Node: Add-on Commands124815
Ref: #add-on-commands124932
Node: ui126275
Ref: #ui126363
Node: web126417
Ref: #web126520
Node: iadd126636
Ref: #iadd126747
Node: interest126829
Ref: #interest126936
Node: ENVIRONMENT127176
Ref: #environment127288
Node: FILES128117
Ref: #files-1128220
Node: LIMITATIONS128433
Ref: #limitations128552
Node: TROUBLESHOOTING129294
Ref: #troubleshooting129407
Node: Smart dates36667
Ref: #smart-dates36818
Node: Report start & end date38179
Ref: #report-start-end-date38351
Node: Report intervals39789
Ref: #report-intervals39954
Node: Period expressions40344
Ref: #period-expressions40504
Node: Depth limiting44630
Ref: #depth-limiting44774
Node: Pivoting45116
Ref: #pivoting45239
Node: Valuation46915
Ref: #valuation47017
Node: -B Cost47937
Ref: #b-cost48041
Node: -V Value48213
Ref: #v-value48366
Node: -X Market value in specified commodity49639
Ref: #x-market-value-in-specified-commodity49858
Node: Market prices50036
Ref: #market-prices50221
Node: --value Flexible valuation51146
Ref: #value-flexible-valuation51347
Node: Effect of --value on reports55852
Ref: #effect-of---value-on-reports56033
Node: COMMANDS61579
Ref: #commands61687
Node: accounts62771
Ref: #accounts62869
Node: activity63568
Ref: #activity63678
Node: add64061
Ref: #add64160
Node: balance66899
Ref: #balance67010
Node: Classic balance report68468
Ref: #classic-balance-report68641
Node: Customising the classic balance report70010
Ref: #customising-the-classic-balance-report70238
Node: Colour support72314
Ref: #colour-support72481
Node: Flat mode72654
Ref: #flat-mode72802
Node: Depth limited balance reports73215
Ref: #depth-limited-balance-reports73400
Node: Percentages73856
Ref: #percentages74022
Node: Multicolumn balance report75159
Ref: #multicolumn-balance-report75339
Node: Budget report80601
Ref: #budget-report80744
Node: Nested budgets86010
Ref: #nested-budgets86122
Ref: #output-format-189603
Node: balancesheet89800
Ref: #balancesheet89936
Node: balancesheetequity91402
Ref: #balancesheetequity91551
Node: cashflow92274
Ref: #cashflow92402
Node: check-dates93581
Ref: #check-dates93708
Node: check-dupes93987
Ref: #check-dupes94111
Node: close94404
Ref: #close94518
Node: close usage96040
Ref: #close-usage96133
Node: commodities98946
Ref: #commodities99073
Node: descriptions99155
Ref: #descriptions99283
Node: diff99464
Ref: #diff99570
Node: files100617
Ref: #files100717
Node: help100864
Ref: #help100964
Node: import102045
Ref: #import102159
Node: Importing balance assignments103052
Ref: #importing-balance-assignments103200
Node: incomestatement103849
Ref: #incomestatement103982
Node: notes105469
Ref: #notes105582
Node: payees105708
Ref: #payees105814
Node: prices105972
Ref: #prices106078
Node: print106419
Ref: #print106529
Node: print-unique111315
Ref: #print-unique111441
Node: register111726
Ref: #register111853
Node: Custom register output116025
Ref: #custom-register-output116154
Node: register-match117491
Ref: #register-match117625
Node: rewrite117976
Ref: #rewrite118091
Node: Re-write rules in a file119946
Ref: #re-write-rules-in-a-file120080
Node: Diff output format121290
Ref: #diff-output-format121459
Node: rewrite vs print --auto122551
Ref: #rewrite-vs.-print---auto122730
Node: roi123286
Ref: #roi123384
Node: stats124396
Ref: #stats124495
Node: tags125283
Ref: #tags125381
Node: test125675
Ref: #test125783
Node: Add-on commands126530
Ref: #add-on-commands126647
Node: ui127990
Ref: #ui128078
Node: web128132
Ref: #web128235
Node: iadd128351
Ref: #iadd128462
Node: interest128544
Ref: #interest128651
Node: ENVIRONMENT128891
Ref: #environment129003
Node: FILES129832
Ref: #files-1129935
Node: LIMITATIONS130148
Ref: #limitations130267
Node: TROUBLESHOOTING131009
Ref: #troubleshooting131122

End Tag Table

166
hledger/hledger.txt
View File

@ -896,22 +896,26 @@ OPTIONS
o account alias directives and options: alias /REGEX/ = REPLACEMENT,
--alias /REGEX/=REPLACEMENT
hledger's regular expressions come from the regex-tdfa library. In
general they:
hledger's regular expressions come from the regex-tdfa library. If
they're not doing what you expect, it's important to know exactly what
they support:
o are case insensitive
1. they are case insensitive
o are infix matching (do not need to match the entire thing being
matched)
2. they are infix matching (they do not need to match the entire thing
being matched)
o are POSIX extended regular expressions
3. they are POSIX ERE (extended regular expressions)
o also support GNU word boundaries (\<, \>, \b, \B)
4. they also support GNU word boundaries (\b, \B, \<, \>)
o and parenthesised capturing groups and numeric backreferences in re-
placement strings
5. they do not support backreferences; if you write \1, it will match
the digit 1. Except when doing text replacement, eg in account
aliases, where backreferences can be used in the replacement string
to reference capturing groups in the search regexp.
o do not support mode modifiers like (?s)
6. they do not support mode modifiers ((?s)), character classes (\w,
\d), or anything else not mentioned above.
Some things to note:
@ -1069,8 +1073,6 @@ OPTIONS
-p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon-
to 2009/4/1" day
-p "monthly in starts on 2018/11/01
2008/11/25"
-p "quarterly from starts on 2009/04/01, ends on 2009/06/30,
@ -1183,28 +1185,44 @@ OPTIONS
-2 EUR
Valuation
-B: Cost
The -B/--cost flag converts amounts to their cost (or selling price) at
transaction time, if they have a transaction price specified. This
flag is equivalent to --value=cost, described below.
hledger can show cost reports, where amounts are converted to their
cost or sale amount at transaction time; or value reports, where
amounts are converted to their market value in another currency/commod-
ity at a specified date (using market prices inferred from your trans-
actions, or declared with P directives).
-V: Market value
The -V/--market flag converts reported amounts to their market value in
a default valuation commodity, using the market prices in effect on a
default valuation date. For single period reports, the valuation date
is today (equivalent to --value=now); for multiperiod reports, it is
the last day of each subperiod (equivalent to --value=end).
We call this "valuation", and it is controlled by the --value=VALUA-
TIONTYPE[,COMMODITY] option. It can get a little involved, so we cover
all the details below. But most of the time, all you need to do is use
these simpler flags instead:
o -B to convert to cost/sale amount, or
o -V to convert to market value in your base currency. Or occasion-
ally,
o -X COMMODITY to convert to market value in some other currency.
-B: Cost
The -B/--cost flag converts amounts to their cost or sale amount at
transaction time, if they have a transaction price specified. (It is
equivalent to --value=cost.)
-V: Value
The -V/--market flag converts reported amounts to market value in their
default valuation commodity, using the market prices in effect on a de-
fault valuation date. (More on these below.)
The default valuation commodity is the one referenced in the latest ap-
plicable market price dated on or before the valuation date. If most
of your P declarations lead to a single home currency, this will usu-
ally be what you want. (To specify the commodity, see -X below.)
plicable market price dated on or before the valuation date. Typically
your P declarations or currency exchange transactions reference a sin-
gle base currency, and -V will pick that.
Note that in hledger, market prices are always declared explicitly with
P directives; we do not infer them from transaction prices as Ledger
does.
The default valuation date is today for single period reports (equiva-
lent to --value=now), or the last day of each subperiod for multiperiod
reports (equivalent to --value=end).
Here's a quick example of -V:
An example:
; one euro is worth this many dollars from nov 1
P 2016/11/01 EUR $1.10
@ -1235,8 +1253,30 @@ OPTIONS
-X: Market value in specified commodity
The -X/--exchange option is like -V, except it specifies the target
commodity you would like to convert to. It is equivalent to
--value=now,COMM or --value=end,COMM.
commodity you would like to convert to. (It is equivalent to
--value=now,COMM or --value=end,COMM.)
Market prices
To convert a commodity A to commodity B, hledger looks for a suitable
market price (exchange rate) in the following ways, in this order of
preference:
1. a declared market price - the latest P directive specifying the ex-
change rate from A to B, dated on or before the valuation date.
2. a transaction-implied market price - a market price matching the
transaction price used in the latest transaction where A is con-
verted to B, dated on or before the valuation date. (since hledger
1.18; experimental)
3. a reverse declared market price - calculated by inverting a declared
market price from B to A.
4. a reverse transaction-implied market price - calculated by inverting
a transaction-implied market price from B to A.
5. an indirect market price - calculated by combining the shortest
chain of market prices (any of the above types) leading from A to B.
--value: Flexible valuation
(experimental, added 201905)
@ -1414,7 +1454,6 @@ OPTIONS
Report type -B, -V, -X --value=then --value=end --value=DATE,
--value=cost --value=now
------------------------------------------------------------------------------------------
print
posting cost value at re- value at value at re- value at
amounts port end or posting date port or DATE/today
@ -1438,6 +1477,8 @@ OPTIONS
amounts terval, val-
(with report ued at inter-
interval) val start
running to- sum/average sum/average sum/average sum/average sum/average
tal/average of displayed of displayed of displayed of displayed of displayed
values values values values values
@ -1508,9 +1549,6 @@ OPTIONS
report's multi-period mode (whether showing one or many subperi-
ods).
Combining -B, -V, -X, --value
The rightmost of these flags wins.
COMMANDS
hledger provides a number of subcommands; hledger with no arguments
shows a list.
@ -3007,7 +3045,7 @@ COMMANDS
For help on these, see https://github.com/feuerbach/tasty#options (--
--help currently doesn't show them).
Add-on Commands
Add-on commands
hledger also searches for external add-on commands, and will include
these in the commands list. These are programs or scripts in your PATH
whose name starts with hledger- and ends with a recognised file exten-
@ -3121,32 +3159,32 @@ TROUBLESHOOTING
variable. The command env | grep LEDGER_FILE should show it. You may
need to use export. Here's an explanation.
"Illegal byte sequence" or "Invalid or incomplete multibyte or wide
character" errors
In order to handle non-ascii letters and symbols (like ), hledger needs
an appropriate locale. This is usually configured system-wide; you can
also configure it temporarily. The locale may need to be one that sup-
ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
I'm not sure yet).
Getting errors like "Illegal byte sequence" or "Invalid or incomplete
multibyte or wide character" or "commitAndReleaseBuffer: invalid argu-
ment (invalid character)"
Programs compiled with GHC (hledger, haskell build tools, etc.) need to
have a UTF-8-aware locale configured in the environment, otherwise they
will fail with these kinds of errors when they encounter non-ascii
characters.
Here's an example of setting the locale temporarily, on ubuntu
gnu/linux:
To fix it, set the LANG environment variable to some locale which sup-
ports UTF-8. The locale you choose must be installed on your system.
Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:
$ file my.journal
my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded
$ locale -a
my.journal: UTF-8 Unicode text # the file is UTF8-encoded
$ echo $LANG
C # LANG is set to the default locale, which does not support UTF8
$ locale -a # which locales are installed ?
C
en_US.utf8 # <- a UTF8-aware locale is available
en_US.utf8 # here's a UTF8-aware one we can use
POSIX
$ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command
$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command
Here's one way to set it permanently, there are probably better ways:
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
$ bash --login
If we preferred to use eg fr_FR.utf8, we might have to install that
first:
If available, C.UTF-8 will also work. If your preferred locale isn't
listed by locale -a, you might need to install it. Eg on Ubuntu/De-
bian:
$ apt-get install language-pack-fr
$ locale -a
@ -3160,8 +3198,18 @@ TROUBLESHOOTING
POSIX
$ LANG=fr_FR.utf8 hledger -f my.journal print
Note some platforms allow variant locale spellings, but not all (ubuntu
accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8).
Here's how you could set it permanently, if you use a bash shell:
$ echo "export LANG=en_US.utf8" >>~/.bash_profile
$ bash --login
Exact spelling and capitalisation may be important. Note the differ-
ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow
variant spellings, but others (eg macos) require it to be exact:
$ locale -a | grep -iE en_us.*utf
en_US.UTF-8
$ LANG=en_US.UTF-8 hledger -f my.journal print
@ -3188,4 +3236,4 @@ SEE ALSO
hledger 1.17.99 March 2020 hledger(1)
hledger 1.17.99 May 2020 hledger(1)