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_define({{_version_}}, {{1.17.99}})m4_dnl
m4_dnl m4_dnl
m4_dnl Date to show in man pages. Updated by make setdate. 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 .\"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] By default this is named like the CSV file with a \f[C].rules\f[R]
extension added. extension added.
Eg when reading \f[C]FILE.csv\f[R], hledger also looks for 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] You can specify a different rules file with the \f[C]--rules-file\f[R]
option. option.
If a rules file is not found, hledger will create a sample rules file, 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 Posting field names
.SS account .SS account
.PP .PP
\f[C]accountN\f[R], where N is 1 to 9, causes a posting to be generated, \f[C]accountN\f[R], where N is 1 to 99, causes a posting to be
with that account name. generated, with that account name.
.PP .PP
Most often there are two postings, so you\[aq]ll want to set Most often there are two postings, so you\[aq]ll want to set
\f[C]account1\f[R] and \f[C]account2\f[R]. \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 .SS amount
.PP .PP
\f[C]amountN\f[R] sets posting N\[aq]s amount. \f[C]amountN\f[R] sets posting N\[aq]s amount.
If the CSV uses separate fields for debit and credit amounts, you can If the CSV uses separate fields for inflows and outflows, you can use
use \f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] instead. \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 .PP
Also, for compatibility with hledger <1.17: \f[C]amount\f[R] or There is also an older, unnumbered form of these names, suitable for
\f[C]amount-in\f[R]/\f[C]amount-out\f[R] with no number sets the amount 2-posting transactions, which sets both posting 1\[aq]s and (negated)
for postings 1 and 2. posting 2\[aq]s amount: \f[C]amount\f[R], or \f[C]amount-in\f[R] and
For posting 2 the amount is negated, and converted to cost if \f[C]amount-out\f[R].
there\[aq]s a transaction price. 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 .SS currency
.PP .PP
If the CSV has the currency symbol in a separate field (ie, not part of If the CSV has the currency symbol in a separate field (ie, not part of
@ -620,13 +636,19 @@ REGEX
.PP .PP
REGEX is a case-insensitive regular expression which tries to match REGEX is a case-insensitive regular expression which tries to match
anywhere within the CSV record. anywhere within the CSV record.
It is a POSIX extended regular expressions with some additions (see It is a POSIX ERE (extended regular expression) that also supports GNU
Regular expressions in the hledger manual). word boundaries (\f[C]\[rs]b\f[R], \f[C]\[rs]B\f[R], \f[C]\[rs]<\f[R],
Note: the \[dq]CSV record\[dq] it is matched against is not the original \f[C]\[rs]>\f[R]), and nothing else.
record, but a synthetic one, with enclosing double quotes or whitespace If you have trouble, be sure to check our
removed, and always comma-separated. https://hledger.org/hledger.html#regular-expressions doc.
(Eg, an SSV record \f[C]2020-01-01; \[dq]Acme, Inc.\[dq]; 1,000\f[R] .PP
appears to REGEX as \f[C]2020-01-01,Acme, Inc.,1,000\f[R]). 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 .PP
Or, MATCHER can be a field matcher, like this: Or, MATCHER can be a field matcher, like this:
.IP .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_. 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 By default this is named like the CSV file with a '.rules' extension
added. Eg when reading 'FILE.csv', hledger also looks for added. Eg when reading 'FILE.csv', hledger also looks for
'FILE.csv.rules' in the same directory. You can specify a different 'FILE.csv.rules' in the same directory as 'FILE.csv'. You can specify a
rules file with the '--rules-file' option. If a rules file is not different rules file with the '--rules-file' option. If a rules file is
found, hledger will create a sample rules file, which you'll need to not found, hledger will create a sample rules file, which you'll need to
adjust. adjust.
This file contains rules describing the CSV data (header line, fields 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 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. that account name.
Most often there are two postings, so you'll want to set 'account1' 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 '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' inflows and outflows, you can use 'amountN-in' and 'amountN-out'
instead. 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 There is also an older, unnumbered form of these names, suitable for
'amount-in'/'amount-out' with no number sets the amount for postings 1 2-posting transactions, which sets both posting 1's and (negated)
and 2. For posting 2 the amount is negated, and converted to cost if posting 2's amount: 'amount', or 'amount-in' and 'amount-out'. This is
there's a transaction price. 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 File: hledger_csv.info, Node: currency, Next: balance, Prev: amount, Up: Posting field names
@ -599,13 +611,17 @@ descriptions.
REGEX REGEX
REGEX is a case-insensitive regular expression which tries to match REGEX is a case-insensitive regular expression which tries to match
anywhere within the CSV record. It is a POSIX extended regular anywhere within the CSV record. It is a POSIX ERE (extended regular
expressions with some additions (see Regular expressions in the hledger expression) that also supports GNU word boundaries ('\b', '\B', '\<',
manual). Note: the "CSV record" it is matched against is not the '\>'), and nothing else. If you have trouble, be sure to check our
original record, but a synthetic one, with enclosing double quotes or https://hledger.org/hledger.html#regular-expressions doc.
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, Important note: the record that is matched is not the original
Inc.,1,000'). 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: Or, MATCHER can be a field matcher, like this:
@ -1019,74 +1035,74 @@ command the user specified.
 
Tag Table: Tag Table:
Node: Top72 Node: Top72
Node: EXAMPLES2099 Node: EXAMPLES2113
Ref: #examples2205 Ref: #examples2219
Node: Basic2413 Node: Basic2427
Ref: #basic2513 Ref: #basic2527
Node: Bank of Ireland3055 Node: Bank of Ireland3069
Ref: #bank-of-ireland3190 Ref: #bank-of-ireland3204
Node: Amazon4652 Node: Amazon4666
Ref: #amazon4770 Ref: #amazon4784
Node: Paypal6489 Node: Paypal6503
Ref: #paypal6583 Ref: #paypal6597
Node: CSV RULES14227 Node: CSV RULES14241
Ref: #csv-rules14336 Ref: #csv-rules14350
Node: skip14612 Node: skip14626
Ref: #skip14705 Ref: #skip14719
Node: fields15080 Node: fields15094
Ref: #fields15202 Ref: #fields15216
Node: Transaction field names16367 Node: Transaction field names16381
Ref: #transaction-field-names16527 Ref: #transaction-field-names16541
Node: Posting field names16638 Node: Posting field names16652
Ref: #posting-field-names16790 Ref: #posting-field-names16804
Node: account16860 Node: account16874
Ref: #account16976 Ref: #account16990
Node: amount17512 Node: amount17527
Ref: #amount17643 Ref: #amount17658
Node: currency18024 Node: currency18765
Ref: #currency18159 Ref: #currency18900
Node: balance18365 Node: balance19106
Ref: #balance18499 Ref: #balance19240
Node: comment18816 Node: comment19557
Ref: #comment18933 Ref: #comment19674
Node: field assignment19096 Node: field assignment19837
Ref: #field-assignment19239 Ref: #field-assignment19980
Node: separator20057 Node: separator20798
Ref: #separator20186 Ref: #separator20927
Node: if20597 Node: if21338
Ref: #if20699 Ref: #if21440
Node: end22618 Node: end23596
Ref: #end22724 Ref: #end23702
Node: date-format22948 Node: date-format23926
Ref: #date-format23080 Ref: #date-format24058
Node: newest-first23829 Node: newest-first24807
Ref: #newest-first23967 Ref: #newest-first24945
Node: include24650 Node: include25628
Ref: #include24779 Ref: #include25757
Node: balance-type25223 Node: balance-type26201
Ref: #balance-type25343 Ref: #balance-type26321
Node: TIPS26043 Node: TIPS27021
Ref: #tips26125 Ref: #tips27103
Node: Rapid feedback26381 Node: Rapid feedback27359
Ref: #rapid-feedback26498 Ref: #rapid-feedback27476
Node: Valid CSV26958 Node: Valid CSV27936
Ref: #valid-csv27088 Ref: #valid-csv28066
Node: File Extension27280 Node: File Extension28258
Ref: #file-extension27432 Ref: #file-extension28410
Node: Reading multiple CSV files27842 Node: Reading multiple CSV files28820
Ref: #reading-multiple-csv-files28027 Ref: #reading-multiple-csv-files29005
Node: Valid transactions28268 Node: Valid transactions29246
Ref: #valid-transactions28446 Ref: #valid-transactions29424
Node: Deduplicating importing29074 Node: Deduplicating importing30052
Ref: #deduplicating-importing29253 Ref: #deduplicating-importing30231
Node: Setting amounts30286 Node: Setting amounts31264
Ref: #setting-amounts30455 Ref: #setting-amounts31433
Node: Setting currency/commodity31441 Node: Setting currency/commodity32419
Ref: #setting-currencycommodity31633 Ref: #setting-currencycommodity32611
Node: Referencing other fields32436 Node: Referencing other fields33414
Ref: #referencing-other-fields32636 Ref: #referencing-other-fields33614
Node: How CSV rules are evaluated33533 Node: How CSV rules are evaluated34511
Ref: #how-csv-rules-are-evaluated33706 Ref: #how-csv-rules-are-evaluated34684
 
End Tag Table 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 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. 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 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 same directory as FILE.csv. You can specify a different rules file
--rules-file option. If a rules file is not found, hledger will create with the --rules-file option. If a rules file is not found, hledger
a sample rules file, which you'll need to adjust. will create a sample rules file, which you'll need to adjust.
This file contains rules describing the CSV data (header line, fields This file contains rules describing the CSV data (header line, fields
layout, date format etc.), and how to construct hledger journal entries layout, date format etc.), and how to construct hledger journal entries
@ -377,7 +377,7 @@ CSV RULES
Posting field names Posting field names
account 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. that account name.
Most often there are two postings, so you'll want to set account1 and Most often there are two postings, so you'll want to set account1 and
@ -391,13 +391,24 @@ CSV RULES
amount amount
amountN sets posting N's amount. If the CSV uses separate fields for 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- inflows and outflows, you can use amountN-in and amountN-out instead.
stead. 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- There is also an older, unnumbered form of these names, suitable for
out with no number sets the amount for postings 1 and 2. For posting 2 2-posting transactions, which sets both posting 1's and (negated) post-
the amount is negated, and converted to cost if there's a transaction ing 2's amount: amount, or amount-in and amount-out. This is still
price. 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 currency
If the CSV has the currency symbol in a separate field (ie, not part of If the CSV has the currency symbol in a separate field (ie, not part of
@ -474,12 +485,17 @@ CSV RULES
REGEX REGEX
REGEX is a case-insensitive regular expression which tries to match REGEX is a case-insensitive regular expression which tries to match
anywhere within the CSV record. It is a POSIX extended regular expres- anywhere within the CSV record. It is a POSIX ERE (extended regular
sions with some additions (see Regular expressions in the hledger man- expression) that also supports GNU word boundaries (\b, \B, \<, \>),
ual). Note: the "CSV record" it is matched against is not the original and nothing else. If you have trouble, be sure to check our
record, but a synthetic one, with enclosing double quotes or whitespace https://hledger.org/hledger.html#regular-expressions doc.
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). 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: 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 .\"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) and any following indented lines beginning with a semicolon)
.IP \[bu] 2 .IP \[bu] 2
0 or more indented \f[I]posting\f[R] lines, describing what was 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 .PP
Here\[aq]s a simple journal file containing one transaction: Here\[aq]s a simple journal file containing one transaction:
.IP .IP
@ -409,7 +410,7 @@ amount.
This makes it easy to write account names containing spaces. This makes it easy to write account names containing spaces.
But if you accidentally leave only one space (or tab) before the amount, But if you accidentally leave only one space (or tab) before the amount,
the amount will be considered part of the account name. the amount will be considered part of the account name.
.SS Virtual Postings .SS Virtual postings
.PP .PP
A posting with a parenthesised account name is called a \f[I]virtual 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 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] \f[R]
.fi .fi
.PP .PP
Amounts can be negative. Amounts can be preceded by a minus sign (or a plus sign, though plus is
The minus sign can be written before or after a left-side commodity the default), The sign can be written before or after a left-side
symbol: commodity symbol:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -515,6 +516,16 @@ $-1
\f[R] \f[R]
.fi .fi
.PP .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: Scientific E notation is allowed:
.IP .IP
.nf .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 Otherwise the format of the first posting amount in that commodity seen
in the journal is used. in the journal is used.
But the number of decimal places (\[dq]precision\[dq]) will be the 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 .IP \[bu] 2
Or if there are no such amounts in the journal, a default format is used Or if there are no such amounts in the journal, a default format is used
(like \f[C]$1000.00\f[R]). (like \f[C]$1000.00\f[R]).
@ -659,9 +670,10 @@ hledger infer the price that balances the transaction:
\f[R] \f[R]
.fi .fi
.RE .RE
.PP .IP "5." 3
(Ledger users: Ledger uses a different syntax for fixed prices, Like 1 and 2, but the \f[C]\[at]\f[R] or \f[C]\[at]\[at]\f[R] is
\f[C]{=UNITPRICE}\f[R], which hledger currently ignores). parenthesised; this is for compatibility with Ledger journals (Virtual
posting costs), and in hledger is equivalent to 1 and 2.
.PP .PP
Use the \f[C]-B/--cost\f[R] flag to convert amounts to their transaction Use the \f[C]-B/--cost\f[R] flag to convert amounts to their transaction
price\[aq]s commodity, if any. price\[aq]s commodity, if any.
@ -700,7 +712,18 @@ $ hledger bal -N --flat -B
\[Eu]100 assets:euros \[Eu]100 assets:euros
\f[R] \f[R]
.fi .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 .PP
hledger supports Ledger-style balance assertions in journal files. hledger supports Ledger-style balance assertions in journal files.
These look like, for example, \f[C]= EXPECTEDBALANCE\f[R] following a 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 Eg a commodity directive may limit the display precision, but this will
not affect balance assertions. not affect balance assertions.
Balance assertion failure messages show exact amounts. Balance assertion failure messages show exact amounts.
.SS Balance Assignments .SS Balance assignments
.PP .PP
Ledger-style balance assignments are also supported. Ledger-style balance assignments are also supported.
These are like balance assertions, but with no posting amount on the These are like balance assertions, but with no posting amount on the
@ -1237,7 +1260,7 @@ D $1,000.00
b b
\f[R] \f[R]
.fi .fi
.SS Market prices .SS Declaring market prices
.PP .PP
The \f[C]P\f[R] directive declares a market price, which is an exchange The \f[C]P\f[R] directive declares a market price, which is an exchange
rate between two commodities on a certain date. rate between two commodities on a certain date.
@ -1270,8 +1293,9 @@ P 2010/1/1 \[Eu] $1.40
\f[R] \f[R]
.fi .fi
.PP .PP
The \f[C]-V/--value\f[R] flag can be used to convert reported amounts to The \f[C]-V\f[R], \f[C]-X\f[R] and \f[C]--value\f[R] flags use these
another commodity using these prices. market prices to show amount values in another commodity.
See Valuation.
.SS Declaring accounts .SS Declaring accounts
.PP .PP
\f[C]account\f[R] directives can be used to pre-declare accounts. \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 * a comment (any remaining text following a semicolon until end of
line, and any following indented lines beginning with a semicolon) line, and any following indented lines beginning with a semicolon)
* 0 or more indented _posting_ lines, describing what was transferred * 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: Here's a simple journal file containing one transaction:
@ -81,8 +82,9 @@ optional fields, separated by spaces:
* Account names:: * Account names::
* Amounts:: * Amounts::
* Transaction prices:: * Transaction prices::
* Balance Assertions:: * Lot prices and lot dates::
* Balance Assignments:: * Balance assertions::
* Balance assignments::
* Directives:: * Directives::
* Periodic transactions:: * Periodic transactions::
* Auto postings:: * Auto postings::
@ -377,12 +379,12 @@ the amount, the amount will be considered part of the account name.
* Menu: * 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 A posting with a parenthesised account name is called a _virtual
@ -459,12 +461,19 @@ must be enclosed in double quotes:
3 "no. 42 green apples" 3 "no. 42 green apples"
Amounts can be negative. The minus sign can be written before or Amounts can be preceded by a minus sign (or a plus sign, though plus
after a left-side commodity symbol: is the default), The sign can be written before or after a left-side
commodity symbol:
-$1 -$1
$-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: Scientific E notation is allowed:
1E-6 1E-6
@ -529,7 +538,7 @@ as written). The display style is chosen as follows:
* Otherwise the format of the first posting amount in that commodity * Otherwise the format of the first posting amount in that commodity
seen in the journal is used. But the number of decimal places seen in the journal is used. But the number of decimal places
("precision") will be the maximum from all posting amounts in that ("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 * Or if there are no such amounts in the journal, a default format is
used (like '$1000.00'). 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.) 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 1.9 Transaction prices
====================== ======================
@ -584,8 +593,9 @@ certain date.
assets:euros €100 ; one hundred euros purchased assets:euros €100 ; one hundred euros purchased
assets:dollars $-135 ; for $135 assets:dollars $-135 ; for $135
(Ledger users: Ledger uses a different syntax for fixed prices, 4. 5. Like 1 and 2, but the '@' or '@@' is parenthesised; this is for
'{=UNITPRICE}', which hledger currently ignores). 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 Use the '-B/--cost' flag to convert amounts to their transaction
price's commodity, if any. (mnemonic: "B" is from "cost Basis", as in 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 €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. hledger supports Ledger-style balance assertions in journal files.
@ -651,9 +676,9 @@ does not disable balance assignments, below).
* Assertions and precision:: * 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 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. 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 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. 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 Balance assertions don't work well across files specified with multiple
-f options. Use include or concatenate the files instead. -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 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€ 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 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). _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 The balance assertions above ('=' and '==') do not count the balance
@ -774,9 +799,9 @@ eg:
checking 1 ==* 11 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 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. 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 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. 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 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:: * 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 A transaction price in a balance assignment will cause the calculated
@ -848,9 +873,9 @@ $ hledger print --explicit
(a) $1 @ €2 = $1 @ €2 (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, 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:: * Default year::
* Declaring commodities:: * Declaring commodities::
* Default commodity:: * Default commodity::
* Market prices:: * Declaring market prices::
* Declaring accounts:: * Declaring accounts::
* Rewriting accounts:: * Rewriting accounts::
* Default parent account:: * 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 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, 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 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, 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 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 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 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 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 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: 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.) 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 The 'D' directive sets a default commodity, to be used for amounts
@ -1106,10 +1131,10 @@ D $1,000.00
b 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 The 'P' directive declares a market price, which is an exchange rate
between two commodities on a certain date. (In Ledger, they are called 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 2009/1/1 € $1.35
P 2010/1/1 € $1.40 P 2010/1/1 € $1.40
The '-V/--value' flag can be used to convert reported amounts to The '-V', '-X' and '--value' flags use these market prices to show
another commodity using these prices. 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 '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 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: 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 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 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 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, 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 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, 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 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 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 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. 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 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, 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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, 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 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 "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 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 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 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 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 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: 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 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: Automated postings will have some extra tags:
@ -1799,120 +1824,122 @@ Tag Table:
Node: Top76 Node: Top76
Node: Transactions1875 Node: Transactions1875
Ref: #transactions1967 Ref: #transactions1967
Node: Dates3132 Node: Dates3251
Ref: #dates3231 Ref: #dates3350
Node: Simple dates3296 Node: Simple dates3415
Ref: #simple-dates3422 Ref: #simple-dates3541
Node: Secondary dates3931 Node: Secondary dates4050
Ref: #secondary-dates4085 Ref: #secondary-dates4204
Node: Posting dates5421 Node: Posting dates5540
Ref: #posting-dates5550 Ref: #posting-dates5669
Node: Status6922 Node: Status7041
Ref: #status7043 Ref: #status7162
Node: Description8751 Node: Description8870
Ref: #description8885 Ref: #description9004
Node: Payee and note9205 Node: Payee and note9324
Ref: #payee-and-note9319 Ref: #payee-and-note9438
Node: Comments9654 Node: Comments9773
Ref: #comments9780 Ref: #comments9899
Node: Tags10974 Node: Tags11093
Ref: #tags11089 Ref: #tags11208
Node: Postings12482 Node: Postings12601
Ref: #postings12610 Ref: #postings12729
Node: Virtual Postings13636 Node: Virtual postings13755
Ref: #virtual-postings13753 Ref: #virtual-postings13872
Node: Account names15058 Node: Account names15177
Ref: #account-names15199 Ref: #account-names15318
Node: Amounts15686 Node: Amounts15805
Ref: #amounts15825 Ref: #amounts15944
Node: Digit group marks16739 Node: Digit group marks17052
Ref: #digit-group-marks16887 Ref: #digit-group-marks17200
Node: Amount display style17825 Node: Amount display style18138
Ref: #amount-display-style17979 Ref: #amount-display-style18292
Node: Transaction prices19417 Node: Transaction prices19729
Ref: #transaction-prices19583 Ref: #transaction-prices19901
Node: Balance Assertions21849 Node: Lot prices and lot dates22233
Ref: #balance-assertions22029 Ref: #lot-prices-and-lot-dates22430
Node: Assertions and ordering23062 Node: Balance assertions22918
Ref: #assertions-and-ordering23250 Ref: #balance-assertions23104
Node: Assertions and included files23950 Node: Assertions and ordering24137
Ref: #assertions-and-included-files24193 Ref: #assertions-and-ordering24325
Node: Assertions and multiple -f options24526 Node: Assertions and included files25025
Ref: #assertions-and-multiple--f-options24782 Ref: #assertions-and-included-files25268
Node: Assertions and commodities24914 Node: Assertions and multiple -f options25601
Ref: #assertions-and-commodities25146 Ref: #assertions-and-multiple--f-options25857
Node: Assertions and prices26303 Node: Assertions and commodities25989
Ref: #assertions-and-prices26517 Ref: #assertions-and-commodities26221
Node: Assertions and subaccounts26957 Node: Assertions and prices27378
Ref: #assertions-and-subaccounts27186 Ref: #assertions-and-prices27592
Node: Assertions and virtual postings27510 Node: Assertions and subaccounts28032
Ref: #assertions-and-virtual-postings27752 Ref: #assertions-and-subaccounts28261
Node: Assertions and precision27894 Node: Assertions and virtual postings28585
Ref: #assertions-and-precision28087 Ref: #assertions-and-virtual-postings28827
Node: Balance Assignments28354 Node: Assertions and precision28969
Ref: #balance-assignments28528 Ref: #assertions-and-precision29162
Node: Balance assignments and prices29692 Node: Balance assignments29429
Ref: #balance-assignments-and-prices29864 Ref: #balance-assignments29603
Node: Directives30088 Node: Balance assignments and prices30767
Ref: #directives30247 Ref: #balance-assignments-and-prices30939
Node: Directives and multiple files35928 Node: Directives31163
Ref: #directives-and-multiple-files36111 Ref: #directives31322
Node: Comment blocks36775 Node: Directives and multiple files37013
Ref: #comment-blocks36958 Ref: #directives-and-multiple-files37196
Node: Including other files37134 Node: Comment blocks37860
Ref: #including-other-files37314 Ref: #comment-blocks38043
Node: Default year37722 Node: Including other files38219
Ref: #default-year37891 Ref: #including-other-files38399
Node: Declaring commodities38298 Node: Default year38807
Ref: #declaring-commodities38481 Ref: #default-year38976
Node: Default commodity40287 Node: Declaring commodities39383
Ref: #default-commodity40463 Ref: #declaring-commodities39566
Node: Market prices41352 Node: Default commodity41372
Ref: #market-prices41517 Ref: #default-commodity41558
Node: Declaring accounts42358 Node: Declaring market prices42447
Ref: #declaring-accounts42534 Ref: #declaring-market-prices42642
Node: Account comments43459 Node: Declaring accounts43499
Ref: #account-comments43622 Ref: #declaring-accounts43685
Node: Account subdirectives44046 Node: Account comments44610
Ref: #account-subdirectives44241 Ref: #account-comments44773
Node: Account types44554 Node: Account subdirectives45197
Ref: #account-types44738 Ref: #account-subdirectives45392
Node: Account display order46377 Node: Account types45705
Ref: #account-display-order46547 Ref: #account-types45889
Node: Rewriting accounts47698 Node: Account display order47528
Ref: #rewriting-accounts47883 Ref: #account-display-order47698
Node: Basic aliases48640 Node: Rewriting accounts48849
Ref: #basic-aliases48786 Ref: #rewriting-accounts49034
Node: Regex aliases49490 Node: Basic aliases49791
Ref: #regex-aliases49662 Ref: #basic-aliases49937
Node: Combining aliases50380 Node: Regex aliases50641
Ref: #combining-aliases50573 Ref: #regex-aliases50813
Node: Aliases and multiple files51849 Node: Combining aliases51531
Ref: #aliases-and-multiple-files52058 Ref: #combining-aliases51724
Node: end aliases52637 Node: Aliases and multiple files53000
Ref: #end-aliases52794 Ref: #aliases-and-multiple-files53209
Node: Default parent account52895 Node: end aliases53788
Ref: #default-parent-account53063 Ref: #end-aliases53945
Node: Periodic transactions53947 Node: Default parent account54046
Ref: #periodic-transactions54122 Ref: #default-parent-account54214
Node: Periodic rule syntax55994 Node: Periodic transactions55098
Ref: #periodic-rule-syntax56200 Ref: #periodic-transactions55273
Node: Two spaces between period expression and description!56904 Node: Periodic rule syntax57145
Ref: #two-spaces-between-period-expression-and-description57223 Ref: #periodic-rule-syntax57351
Node: Forecasting with periodic transactions57907 Node: Two spaces between period expression and description!58055
Ref: #forecasting-with-periodic-transactions58212 Ref: #two-spaces-between-period-expression-and-description58374
Node: Budgeting with periodic transactions60238 Node: Forecasting with periodic transactions59058
Ref: #budgeting-with-periodic-transactions60477 Ref: #forecasting-with-periodic-transactions59363
Node: Auto postings60926 Node: Budgeting with periodic transactions61389
Ref: #auto-postings61066 Ref: #budgeting-with-periodic-transactions61628
Node: Auto postings and multiple files63245 Node: Auto postings62077
Ref: #auto-postings-and-multiple-files63449 Ref: #auto-postings62217
Node: Auto postings and dates63658 Node: Auto postings and multiple files64396
Ref: #auto-postings-and-dates63932 Ref: #auto-postings-and-multiple-files64600
Node: Auto postings and transaction balancing / inferred amounts / balance assertions64107 Node: Auto postings and dates64809
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions64458 Ref: #auto-postings-and-dates65083
Node: Auto posting tags64800 Node: Auto postings and transaction balancing / inferred amounts / balance assertions65258
Ref: #auto-posting-tags65015 Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions65609
Node: Auto posting tags65951
Ref: #auto-posting-tags66166
 
End Tag Table 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) line, and any following indented lines beginning with a semicolon)
o 0 or more indented posting lines, describing what was transferred and 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: 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 ces. But if you accidentally leave only one space (or tab) before the
amount, the amount will be considered part of the account name. 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 A posting with a parenthesised account name is called a virtual posting
or unbalanced posting, which means it is exempt from the usual rule or unbalanced posting, which means it is exempt from the usual rule
that a transaction's postings must balance add up to zero. that a transaction's postings must balance add up to zero.
@ -359,12 +360,19 @@ FILE FORMAT
3 "no. 42 green apples" 3 "no. 42 green apples"
Amounts can be negative. The minus sign can be written before or after Amounts can be preceded by a minus sign (or a plus sign, though plus is
a left-side commodity symbol: the default), The sign can be written before or after a left-side com-
modity symbol:
-$1 -$1
$-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: Scientific E notation is allowed:
1E-6 1E-6
@ -413,8 +421,8 @@ FILE FORMAT
o Otherwise the format of the first posting amount in that commodity 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- 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- cision") will be the maximum from all posting amounts in that commod-
modity. ity.
o Or if there are no such amounts in the journal, a default format is o Or if there are no such amounts in the journal, a default format is
used (like $1000.00). used (like $1000.00).
@ -464,8 +472,9 @@ FILE FORMAT
assets:euros EUR100 ; one hundred euros purchased assets:euros EUR100 ; one hundred euros purchased
assets:dollars $-135 ; for $135 assets:dollars $-135 ; for $135
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- 5. Like 1 and 2, but the @ or @@ is parenthesised; this is for compati-
PRICE}, which hledger currently ignores). 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 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). 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 EUR-100 assets:dollars # <- the dollars' selling price
EUR100 assets:euros 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. hledger supports Ledger-style balance assertions in journal files.
These look like, for example, = EXPECTEDBALANCE following a posting's These look like, for example, = EXPECTEDBALANCE following a posting's
amount. Eg here we assert the expected dollar balance in accounts a 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- limit the display precision, but this will not affect balance asser-
tions. Balance assertion failure messages show exact amounts. tions. Balance assertion failure messages show exact amounts.
Balance Assignments Balance assignments
Ledger-style balance assignments are also supported. These are like Ledger-style balance assignments are also supported. These are like
balance assertions, but with no posting amount on the left side of the balance assertions, but with no posting amount on the left side of the
equals sign; instead it is calculated automatically so as to satisfy equals sign; instead it is calculated automatically so as to satisfy
@ -710,6 +728,9 @@ FILE FORMAT
commodity commodity in re- commodity commodity in re-
ports, when -V is ports, when -V is
used used
Y declare a year for yearless following in- Y declare a year for yearless following in-
dates line/included en- dates line/included en-
tries until end of tries until end of
@ -863,7 +884,7 @@ FILE FORMAT
a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
b b
Market prices Declaring market prices
The P directive declares a market price, which is an exchange rate be- 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 tween two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange, "historical prices".) These are often obtained from a stock exchange,
@ -886,8 +907,8 @@ FILE FORMAT
P 2009/1/1 EUR $1.35 P 2009/1/1 EUR $1.35
P 2010/1/1 EUR $1.40 P 2010/1/1 EUR $1.40
The -V/--value flag can be used to convert reported amounts to another The -V, -X and --value flags use these market prices to show amount
commodity using these prices. values in another commodity. See Valuation.
Declaring accounts Declaring accounts
account directives can be used to pre-declare accounts. Though not re- 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_define({{_version_}}, {{1.17.99}})m4_dnl
m4_dnl m4_dnl
m4_dnl Date to show in man pages. Updated by make setdate. 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_define({{_version_}}, {{1.17.99}})m4_dnl
m4_dnl m4_dnl
m4_dnl Date to show in man pages. Updated by make setdate. 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.) that both machine clocks are roughly in step.)
.SH JSON API .SH JSON API
.PP .PP
In addition to the web UI, hledger-web provides some API routes that In addition to the web UI, hledger-web also serves a JSON API that can
serve JSON in response to GET requests. be used to get data or add new transactions.
(And when started with \f[C]--serve-api\f[R], it provides only these If you want the JSON API only, you can use the \f[C]--serve-api\f[R]
routes.): 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 .IP
.nf .nf
\f[C] \f[C]
@ -328,48 +338,201 @@ routes.):
/prices /prices
/commodities /commodities
/accounts /accounts
/accounttransactions/#AccountName /accounttransactions/ACCOUNTNAME
\f[R] \f[R]
.fi .fi
.PP .PP
Also, you can append a new transaction to the journal by sending a PUT Eg, all account names in the journal (similar to the accounts command):
request to \f[C]/add\f[R] (hledger-web only). .IP
As with the web UI\[aq]s add form, hledger-web must be started with the .nf
\f[C]add\f[R] capability for this (enabled by default). \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 .PP
The payload should be a valid hledger transaction as JSON, similar to Or all transactions:
what you get from \f[C]/transactions\f[R] or .IP
\f[C]/accounttransactions\f[R]. .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 .PP
Another way to generate test data is with the Most of the JSON corresponds to hledger\[aq]s data types; for details of
\f[C]readJsonFile\f[R]/\f[C]writeJsonFile\f[R] helpers in what the fields mean, see the Hledger.Data.Json haddock docs and click
Hledger.Web.Json, which can write or read most of hledger\[aq]s data on the various data types, eg Transaction.
types to or from a file. And for a higher level understanding, see the journal manual.
Eg here we write the first transaction of a sample journal: .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 .IP
.nf .nf
\f[C] \f[C]
$ make ghci-web $ make ghci-web
>>> :m +*Hledger.Web.Json >>> import Hledger
>>> writeJsonFile \[dq]txn.json\[dq] (head $ jtxns samplejournal) >>> writeJsonFile \[dq]txn.json\[dq] (head $ jtxns samplejournal) -- export samplejournal\[aq]s first txn
>>> :q >>> :q
$ python -m json.tool <txn.json >txn.pretty.json # optional: make human-readable
\f[R] \f[R]
.fi .fi
.PP .PP
(sample output & discussion) If you like, reformat the json to make it human-readable:
.PP
And here\[aq]s how to test adding that with curl:
.IP .IP
.nf .nf
\f[C] \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] \f[R]
.fi .fi
.PP .PP
By default, both the server-side HTML UI and the JSON API are served. Here\[aq]s how it looks as of hledger-1.17 (remember, this JSON
Running with \f[C]--serve-api\f[R] disables the former, useful if you corresponds to hledger\[aq]s Transaction and related data types):
only want to serve the API. .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 .SH ENVIRONMENT
.PP .PP
\f[B]LEDGER_FILE\f[R] The journal file path when not specified with \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 5 JSON API
********** **********
In addition to the web UI, hledger-web provides some API routes that In addition to the web UI, hledger-web also serves a JSON API that can
serve JSON in response to GET requests. (And when started with be used to get data or add new transactions. If you want the JSON API
'--serve-api', it provides only these routes.): 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 /accountnames
/transactions /transactions
/prices /prices
/commodities /commodities
/accounts /accounts
/accounttransactions/#AccountName /accounttransactions/ACCOUNTNAME
Also, you can append a new transaction to the journal by sending a Eg, all account names in the journal (similar to the accounts
PUT request to '/add' (hledger-web only). As with the web UI's add command):
form, hledger-web must be started with the 'add' capability for this
(enabled by default).
The payload should be a valid hledger transaction as JSON, similar to $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
what you get from '/transactions' or '/accounttransactions'. [
"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 Or all transactions:
'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 $ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
we write the first transaction of a sample journal: [
{
"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 $ make ghci-web
>>> :m +*Hledger.Web.Json >>> import Hledger
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal) >>> writeJsonFile "txn.json" (head $ jtxns samplejournal) -- export samplejournal's first txn
>>> :q >>> :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 "tcode": "",
to serve the API. "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 File: hledger-web.info, Node: ENVIRONMENT, Next: FILES, Prev: JSON API, Up: Top
@ -437,12 +579,12 @@ Node: RELOADING10567
Ref: #reloading10701 Ref: #reloading10701
Node: JSON API11134 Node: JSON API11134
Ref: #json-api11248 Ref: #json-api11248
Node: ENVIRONMENT12686 Node: ENVIRONMENT16812
Ref: #environment12802 Ref: #environment16928
Node: FILES13535 Node: FILES17661
Ref: #files13635 Ref: #files17761
Node: BUGS13848 Node: BUGS17974
Ref: #bugs13926 Ref: #bugs18052
 
End Tag Table End Tag Table

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

@ -289,45 +289,186 @@ RELOADING
that both machine clocks are roughly in step.) that both machine clocks are roughly in step.)
JSON API JSON API
In addition to the web UI, hledger-web provides some API routes that In addition to the web UI, hledger-web also serves a JSON API that can
serve JSON in response to GET requests. (And when started with be used to get data or add new transactions. If you want the JSON API
--serve-api, it provides only these routes.): 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 /accountnames
/transactions /transactions
/prices /prices
/commodities /commodities
/accounts /accounts
/accounttransactions/#AccountName /accounttransactions/ACCOUNTNAME
Also, you can append a new transaction to the journal by sending a PUT Eg, all account names in the journal (similar to the accounts command):
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).
The payload should be a valid hledger transaction as JSON, similar to $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
what you get from /transactions or /accounttransactions. [
"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- Or all transactions:
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 $ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
transaction of a sample journal: [
{
"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 $ make ghci-web
>>> :m +*Hledger.Web.Json >>> import Hledger
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal) >>> writeJsonFile "txn.json" (head $ jtxns samplejournal) -- export samplejournal's first txn
>>> :q >>> :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 "tcode": "",
to serve the API. "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 ENVIRONMENT
LEDGER_FILE The journal file path when not specified with -f. Default: 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_define({{_version_}}, {{1.17.99}})m4_dnl
m4_dnl m4_dnl
m4_dnl Date to show in man pages. Updated by make setdate. 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 .\"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] \f[C]--alias /REGEX/=REPLACEMENT\f[R]
.PP .PP
hledger\[aq]s regular expressions come from the regex-tdfa library. hledger\[aq]s regular expressions come from the regex-tdfa library.
In general they: If they\[aq]re not doing what you expect, it\[aq]s important to know
.IP \[bu] 2 exactly what they support:
are case insensitive .IP "1." 3
.IP \[bu] 2 they are case insensitive
are infix matching (do not need to match the entire thing being matched) .IP "2." 3
.IP \[bu] 2 they are infix matching (they do not need to match the entire thing
are POSIX extended regular expressions being matched)
.IP \[bu] 2 .IP "3." 3
also support GNU word boundaries (\[rs]<, \[rs]>, \[rs]b, \[rs]B) they are POSIX ERE (extended regular expressions)
.IP \[bu] 2 .IP "4." 3
and parenthesised capturing groups and numeric backreferences in they also support GNU word boundaries (\f[C]\[rs]b\f[R],
replacement strings \f[C]\[rs]B\f[R], \f[C]\[rs]<\f[R], \f[C]\[rs]>\f[R])
.IP \[bu] 2 .IP "5." 3
do not support mode modifiers like (?s) 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 .PP
Some things to note: Some things to note:
.IP \[bu] 2 .IP \[bu] 2
@ -1671,31 +1679,48 @@ $ hledger balance --pivot member acct:.
\f[R] \f[R]
.fi .fi
.SS Valuation .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 .SS -B: Cost
.PP .PP
The \f[C]-B/--cost\f[R] flag converts amounts to their cost (or selling The \f[C]-B/--cost\f[R] flag converts amounts to their cost or sale
price) at transaction time, if they have a transaction price specified. amount at transaction time, if they have a transaction price specified.
This flag is equivalent to \f[C]--value=cost\f[R], described below. (It is equivalent to \f[C]--value=cost\f[R].)
.SS -V: Market value .SS -V: Value
.PP .PP
The \f[C]-V/--market\f[R] flag converts reported amounts to their market The \f[C]-V/--market\f[R] flag converts reported amounts to market value
value in a default valuation commodity, using the market prices in in their \f[I]default valuation commodity\f[R], using the market prices
effect on a default valuation date. in effect on a \f[I]default valuation date\f[R].
For single period reports, the valuation date is today (equivalent to (More on these below.)
\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]).
.PP .PP
The default valuation commodity is the one referenced in the latest The default valuation commodity is the one referenced in the latest
applicable market price dated on or before the valuation date. applicable market price dated on or before the valuation date.
If most of your P declarations lead to a single home currency, this will Typically your P declarations or currency exchange transactions
usually be what you want. reference a single base currency, and -V will pick that.
(To specify the commodity, see -X below.)
.PP .PP
Note that in hledger, market prices are always declared explicitly with The default valuation date is today for single period reports
P directives; we do not infer them from transaction prices as Ledger (equivalent to \f[C]--value=now\f[R]), or the last day of each subperiod
does. for multiperiod reports (equivalent to \f[C]--value=end\f[R]).
.PP .PP
Here\[aq]s a quick example of -V: An example:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -1743,8 +1768,31 @@ $ hledger -f t.j bal -N euros -V
.PP .PP
The \f[C]-X/--exchange\f[R] option is like \f[C]-V\f[R], except it 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. specifies the target commodity you would like to convert to.
It is equivalent to \f[C]--value=now,COMM\f[R] or (It is equivalent to \f[C]--value=now,COMM\f[R] or
\f[C]--value=end,COMM\f[R]. \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 .SS --value: Flexible valuation
.PP .PP
\f[I](experimental, added 201905)\f[R] \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] \f[I]report interval\f[R]
a flag (-D/-W/-M/-Q/-Y) or period expression that activates the 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). 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 .SH COMMANDS
.PP .PP
hledger provides a number of subcommands; \f[C]hledger\f[R] with no hledger provides a number of subcommands; \f[C]hledger\f[R] with no
@ -4173,7 +4218,7 @@ $ hledger test -- -pData.Amount --color=never
.PP .PP
For help on these, see https://github.com/feuerbach/tasty#options For help on these, see https://github.com/feuerbach/tasty#options
(\f[C]-- --help\f[R] currently doesn\[aq]t show them). (\f[C]-- --help\f[R] currently doesn\[aq]t show them).
.SS Add-on Commands .SS Add-on commands
.PP .PP
hledger also searches for external add-on commands, and will include hledger also searches for external add-on commands, and will include
these in the commands list. 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]. You may need to use \f[C]export\f[R].
Here\[aq]s an explanation. Here\[aq]s an explanation.
.PP .PP
\f[B]\[dq]Illegal byte sequence\[dq] or \[dq]Invalid or incomplete \f[B]Getting errors like \[dq]Illegal byte sequence\[dq] or \[dq]Invalid
multibyte or wide character\[dq] errors\f[R] or incomplete multibyte or wide character\[dq] or
\[dq]commitAndReleaseBuffer: invalid argument (invalid
character)\[dq]\f[R]
.PD 0 .PD 0
.P .P
.PD .PD
In order to handle non-ascii letters and symbols (like \[Po]), hledger Programs compiled with GHC (hledger, haskell build tools, etc.) need to
needs an appropriate locale. have a UTF-8-aware locale configured in the environment, otherwise they
This is usually configured system-wide; you can also configure it will fail with these kinds of errors when they encounter non-ascii
temporarily. characters.
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).
.PP .PP
Here\[aq]s an example of setting the locale temporarily, on ubuntu To fix it, set the LANG environment variable to some locale which
gnu/linux: 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 .IP
.nf .nf
\f[C] \f[C]
$ file my.journal $ file my.journal
my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded my.journal: UTF-8 Unicode text # the file is UTF8-encoded
$ locale -a $ echo $LANG
C # LANG is set to the default locale, which does not support UTF8
$ locale -a # which locales are installed ?
C C
en_US.utf8 # <- a UTF8-aware locale is available en_US.utf8 # here\[aq]s a UTF8-aware one we can use
POSIX 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] \f[R]
.fi .fi
.PP .PP
Here\[aq]s one way to set it permanently, there are probably better If available, \f[C]C.UTF-8\f[R] will also work.
ways: If your preferred locale isn\[aq]t listed by \f[C]locale -a\f[R], you
.IP might need to install it.
.nf Eg on Ubuntu/Debian:
\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:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -4368,9 +4410,27 @@ $ LANG=fr_FR.utf8 hledger -f my.journal print
\f[R] \f[R]
.fi .fi
.PP .PP
Note some platforms allow variant locale spellings, but not all (ubuntu Here\[aq]s how you could set it permanently, if you use a bash shell:
accepts \f[C]fr_FR.UTF8\f[R], mac osx requires exactly .IP
\f[C]fr_FR.UTF-8\f[R]). .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" .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/ = * account alias directives and options: 'alias /REGEX/ =
REPLACEMENT', '--alias /REGEX/=REPLACEMENT' REPLACEMENT', '--alias /REGEX/=REPLACEMENT'
hledger's regular expressions come from the regex-tdfa library. In hledger's regular expressions come from the regex-tdfa library. If
general they: they're not doing what you expect, it's important to know exactly what
they support:
* are case insensitive 1. they are case insensitive
* are infix matching (do not need to match the entire thing being 2. they are infix matching (they do not need to match the entire thing
matched) being matched)
* are POSIX extended regular expressions 3. they are POSIX ERE (extended regular expressions)
* also support GNU word boundaries (\<, \>, \b, \B) 4. they also support GNU word boundaries ('\b', '\B', '\<', '\>')
* and parenthesised capturing groups and numeric backreferences in 5. they do not support backreferences; if you write '\1', it will
replacement strings match the digit '1'. Except when doing text replacement, eg in
* do not support mode modifiers like (?s) 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: Some things to note:
@ -1365,47 +1370,61 @@ File: hledger.info, Node: Valuation, Prev: Pivoting, Up: OPTIONS
2.17 Valuation 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: * Menu:
* -B Cost:: * -B Cost::
* -V Market value:: * -V Value::
* -X Market value in specified commodity:: * -X Market value in specified commodity::
* Market prices::
* --value Flexible valuation:: * --value Flexible valuation::
* Effect of --value on reports:: * 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 2.17.1 -B: Cost
--------------- ---------------
The '-B/--cost' flag converts amounts to their cost (or selling price) The '-B/--cost' flag converts amounts to their cost or sale amount at
at transaction time, if they have a transaction price specified. This transaction time, if they have a transaction price specified. (It is
flag is equivalent to '--value=cost', described below. 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 The '-V/--market' flag converts reported amounts to market value in
in a default valuation commodity, using the market prices in effect on a their _default valuation commodity_, using the market prices in effect
default valuation date. For single period reports, the valuation date on a _default valuation date_. (More on these below.)
is today (equivalent to '--value=now'); for multiperiod reports, it is
the last day of each subperiod (equivalent to '--value=end').
The default valuation commodity is the one referenced in the latest The default valuation commodity is the one referenced in the latest
applicable market price dated on or before the valuation date. If most applicable market price dated on or before the valuation date.
of your P declarations lead to a single home currency, this will usually Typically your P declarations or currency exchange transactions
be what you want. (To specify the commodity, see -X below.) reference a single base currency, and -V will pick that.
Note that in hledger, market prices are always declared explicitly The default valuation date is today for single period reports
with P directives; we do not infer them from transaction prices as (equivalent to '--value=now'), or the last day of each subperiod for
Ledger does. 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 ; one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10 P 2016/11/01 € $1.10
@ -1435,19 +1454,47 @@ $ hledger -f t.j bal -N euros -V
$103.00 assets:euros $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 2.17.3 -X: Market value in specified commodity
---------------------------------------------- ----------------------------------------------
The '-X/--exchange' option is like '-V', except it specifies the target The '-X/--exchange' option is like '-V', except it specifies the target
commodity you would like to convert to. It is equivalent to commodity you would like to convert to. (It is equivalent to
'--value=now,COMM' or '--value=end,COMM'. '--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)_ _(experimental, added 201905)_
@ -1617,9 +1664,9 @@ $ hledger print -X A
b -0.50A 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 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 report's multi-period mode (whether showing one or many
subperiods). 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 File: hledger.info, Node: COMMANDS, Next: ENVIRONMENT, Prev: OPTIONS, Up: Top
@ -1793,7 +1832,7 @@ detailed command help.
* stats:: * stats::
* tags:: * tags::
* test:: * test::
* Add-on Commands:: * Add-on commands::
 
File: hledger.info, Node: accounts, Next: activity, Up: 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. 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 3.29 test
========= =========
@ -3521,9 +3560,9 @@ $ hledger test -- -pData.Amount --color=never
('-- --help' currently doesn't show them). ('-- --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 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:: * 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 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. 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 3.30.2 web
---------- ----------
@ -3580,7 +3619,7 @@ hledger-web provides a simple web interface.
Third party add-ons, maintained separately from hledger, include: 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 3.30.3 iadd
----------- -----------
@ -3589,7 +3628,7 @@ hledger-iadd is a more interactive, terminal UI replacement for the add
command. 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 3.30.4 interest
--------------- ---------------
@ -3689,32 +3728,32 @@ file*
variable. The command 'env | grep LEDGER_FILE' should show it. You may variable. The command 'env | grep LEDGER_FILE' should show it. You may
need to use 'export'. Here's an explanation. need to use 'export'. Here's an explanation.
*"Illegal byte sequence" or "Invalid or incomplete multibyte or wide *Getting errors like "Illegal byte sequence" or "Invalid or
character" errors* incomplete multibyte or wide character" or "commitAndReleaseBuffer:
In order to handle non-ascii letters and symbols (like £), hledger needs invalid argument (invalid character)"*
an appropriate locale. This is usually configured system-wide; you can Programs compiled with GHC (hledger, haskell build tools, etc.) need to
also configure it temporarily. The locale may need to be one that have a UTF-8-aware locale configured in the environment, otherwise they
supports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, will fail with these kinds of errors when they encounter non-ascii
I'm not sure yet). characters.
Here's an example of setting the locale temporarily, on ubuntu To fix it, set the LANG environment variable to some locale which
gnu/linux: 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 $ file my.journal
my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded my.journal: UTF-8 Unicode text # the file is UTF8-encoded
$ locale -a $ echo $LANG
C # LANG is set to the default locale, which does not support UTF8
$ locale -a # which locales are installed ?
C C
en_US.utf8 # <- a UTF8-aware locale is available en_US.utf8 # here's a UTF8-aware one we can use
POSIX 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: 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
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile Ubuntu/Debian:
$ bash --login
If we preferred to use eg 'fr_FR.utf8', we might have to install that
first:
$ apt-get install language-pack-fr $ apt-get install language-pack-fr
$ locale -a $ locale -a
@ -3728,8 +3767,18 @@ fr_LU.utf8
POSIX POSIX
$ LANG=fr_FR.utf8 hledger -f my.journal print $ LANG=fr_FR.utf8 hledger -f my.journal print
Note some platforms allow variant locale spellings, but not all Here's how you could set it permanently, if you use a bash shell:
(ubuntu accepts 'fr_FR.UTF8', mac osx requires exactly 'fr_FR.UTF-8').
$ 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: Tag Table:
@ -3780,141 +3829,141 @@ Node: Output format32576
Ref: #output-format32726 Ref: #output-format32726
Node: Regular expressions34774 Node: Regular expressions34774
Ref: #regular-expressions34931 Ref: #regular-expressions34931
Node: Smart dates36292 Node: Smart dates36667
Ref: #smart-dates36443 Ref: #smart-dates36818
Node: Report start & end date37804 Node: Report start & end date38179
Ref: #report-start-end-date37976 Ref: #report-start-end-date38351
Node: Report intervals39414 Node: Report intervals39789
Ref: #report-intervals39579 Ref: #report-intervals39954
Node: Period expressions39969 Node: Period expressions40344
Ref: #period-expressions40129 Ref: #period-expressions40504
Node: Depth limiting44255 Node: Depth limiting44630
Ref: #depth-limiting44399 Ref: #depth-limiting44774
Node: Pivoting44741 Node: Pivoting45116
Ref: #pivoting44864 Ref: #pivoting45239
Node: Valuation46540 Node: Valuation46915
Ref: #valuation46642 Ref: #valuation47017
Node: -B Cost46822 Node: -B Cost47937
Ref: #b-cost46933 Ref: #b-cost48041
Node: -V Market value47131 Node: -V Value48213
Ref: #v-market-value47305 Ref: #v-value48366
Node: -X Market value in specified commodity48737 Node: -X Market value in specified commodity49639
Ref: #x-market-value-in-specified-commodity48976 Ref: #x-market-value-in-specified-commodity49858
Node: --value Flexible valuation49152 Node: Market prices50036
Ref: #value-flexible-valuation49378 Ref: #market-prices50221
Node: Effect of --value on reports53883 Node: --value Flexible valuation51146
Ref: #effect-of---value-on-reports54099 Ref: #value-flexible-valuation51347
Node: Combining -B -V -X --value59645 Node: Effect of --value on reports55852
Ref: #combining--b--v--x---value59828 Ref: #effect-of---value-on-reports56033
Node: COMMANDS59864 Node: COMMANDS61579
Ref: #commands59972 Ref: #commands61687
Node: accounts61056 Node: accounts62771
Ref: #accounts61154 Ref: #accounts62869
Node: activity61853 Node: activity63568
Ref: #activity61963 Ref: #activity63678
Node: add62346 Node: add64061
Ref: #add62445 Ref: #add64160
Node: balance65184 Node: balance66899
Ref: #balance65295 Ref: #balance67010
Node: Classic balance report66753 Node: Classic balance report68468
Ref: #classic-balance-report66926 Ref: #classic-balance-report68641
Node: Customising the classic balance report68295 Node: Customising the classic balance report70010
Ref: #customising-the-classic-balance-report68523 Ref: #customising-the-classic-balance-report70238
Node: Colour support70599 Node: Colour support72314
Ref: #colour-support70766 Ref: #colour-support72481
Node: Flat mode70939 Node: Flat mode72654
Ref: #flat-mode71087 Ref: #flat-mode72802
Node: Depth limited balance reports71500 Node: Depth limited balance reports73215
Ref: #depth-limited-balance-reports71685 Ref: #depth-limited-balance-reports73400
Node: Percentages72141 Node: Percentages73856
Ref: #percentages72307 Ref: #percentages74022
Node: Multicolumn balance report73444 Node: Multicolumn balance report75159
Ref: #multicolumn-balance-report73624 Ref: #multicolumn-balance-report75339
Node: Budget report78886 Node: Budget report80601
Ref: #budget-report79029 Ref: #budget-report80744
Node: Nested budgets84295 Node: Nested budgets86010
Ref: #nested-budgets84407 Ref: #nested-budgets86122
Ref: #output-format-187888 Ref: #output-format-189603
Node: balancesheet88085 Node: balancesheet89800
Ref: #balancesheet88221 Ref: #balancesheet89936
Node: balancesheetequity89687 Node: balancesheetequity91402
Ref: #balancesheetequity89836 Ref: #balancesheetequity91551
Node: cashflow90559 Node: cashflow92274
Ref: #cashflow90687 Ref: #cashflow92402
Node: check-dates91866 Node: check-dates93581
Ref: #check-dates91993 Ref: #check-dates93708
Node: check-dupes92272 Node: check-dupes93987
Ref: #check-dupes92396 Ref: #check-dupes94111
Node: close92689 Node: close94404
Ref: #close92803 Ref: #close94518
Node: close usage94325 Node: close usage96040
Ref: #close-usage94418 Ref: #close-usage96133
Node: commodities97231 Node: commodities98946
Ref: #commodities97358 Ref: #commodities99073
Node: descriptions97440 Node: descriptions99155
Ref: #descriptions97568 Ref: #descriptions99283
Node: diff97749 Node: diff99464
Ref: #diff97855 Ref: #diff99570
Node: files98902 Node: files100617
Ref: #files99002 Ref: #files100717
Node: help99149 Node: help100864
Ref: #help99249 Ref: #help100964
Node: import100330 Node: import102045
Ref: #import100444 Ref: #import102159
Node: Importing balance assignments101337 Node: Importing balance assignments103052
Ref: #importing-balance-assignments101485 Ref: #importing-balance-assignments103200
Node: incomestatement102134 Node: incomestatement103849
Ref: #incomestatement102267 Ref: #incomestatement103982
Node: notes103754 Node: notes105469
Ref: #notes103867 Ref: #notes105582
Node: payees103993 Node: payees105708
Ref: #payees104099 Ref: #payees105814
Node: prices104257 Node: prices105972
Ref: #prices104363 Ref: #prices106078
Node: print104704 Node: print106419
Ref: #print104814 Ref: #print106529
Node: print-unique109600 Node: print-unique111315
Ref: #print-unique109726 Ref: #print-unique111441
Node: register110011 Node: register111726
Ref: #register110138 Ref: #register111853
Node: Custom register output114310 Node: Custom register output116025
Ref: #custom-register-output114439 Ref: #custom-register-output116154
Node: register-match115776 Node: register-match117491
Ref: #register-match115910 Ref: #register-match117625
Node: rewrite116261 Node: rewrite117976
Ref: #rewrite116376 Ref: #rewrite118091
Node: Re-write rules in a file118231 Node: Re-write rules in a file119946
Ref: #re-write-rules-in-a-file118365 Ref: #re-write-rules-in-a-file120080
Node: Diff output format119575 Node: Diff output format121290
Ref: #diff-output-format119744 Ref: #diff-output-format121459
Node: rewrite vs print --auto120836 Node: rewrite vs print --auto122551
Ref: #rewrite-vs.-print---auto121015 Ref: #rewrite-vs.-print---auto122730
Node: roi121571 Node: roi123286
Ref: #roi121669 Ref: #roi123384
Node: stats122681 Node: stats124396
Ref: #stats122780 Ref: #stats124495
Node: tags123568 Node: tags125283
Ref: #tags123666 Ref: #tags125381
Node: test123960 Node: test125675
Ref: #test124068 Ref: #test125783
Node: Add-on Commands124815 Node: Add-on commands126530
Ref: #add-on-commands124932 Ref: #add-on-commands126647
Node: ui126275 Node: ui127990
Ref: #ui126363 Ref: #ui128078
Node: web126417 Node: web128132
Ref: #web126520 Ref: #web128235
Node: iadd126636 Node: iadd128351
Ref: #iadd126747 Ref: #iadd128462
Node: interest126829 Node: interest128544
Ref: #interest126936 Ref: #interest128651
Node: ENVIRONMENT127176 Node: ENVIRONMENT128891
Ref: #environment127288 Ref: #environment129003
Node: FILES128117 Node: FILES129832
Ref: #files-1128220 Ref: #files-1129935
Node: LIMITATIONS128433 Node: LIMITATIONS130148
Ref: #limitations128552 Ref: #limitations130267
Node: TROUBLESHOOTING129294 Node: TROUBLESHOOTING131009
Ref: #troubleshooting129407 Ref: #troubleshooting131122
 
End Tag Table End Tag Table

166
hledger/hledger.txt
View File

@ -896,22 +896,26 @@ OPTIONS
o account alias directives and options: alias /REGEX/ = REPLACEMENT, o account alias directives and options: alias /REGEX/ = REPLACEMENT,
--alias /REGEX/=REPLACEMENT --alias /REGEX/=REPLACEMENT
hledger's regular expressions come from the regex-tdfa library. In hledger's regular expressions come from the regex-tdfa library. If
general they: 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 2. they are infix matching (they do not need to match the entire thing
matched) 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- 5. they do not support backreferences; if you write \1, it will match
placement strings 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: Some things to note:
@ -1069,8 +1073,6 @@ OPTIONS
-p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon-
to 2009/4/1" day to 2009/4/1" day
-p "monthly in starts on 2018/11/01 -p "monthly in starts on 2018/11/01
2008/11/25" 2008/11/25"
-p "quarterly from starts on 2009/04/01, ends on 2009/06/30, -p "quarterly from starts on 2009/04/01, ends on 2009/06/30,
@ -1183,28 +1185,44 @@ OPTIONS
-2 EUR -2 EUR
Valuation Valuation
-B: Cost hledger can show cost reports, where amounts are converted to their
The -B/--cost flag converts amounts to their cost (or selling price) at cost or sale amount at transaction time; or value reports, where
transaction time, if they have a transaction price specified. This amounts are converted to their market value in another currency/commod-
flag is equivalent to --value=cost, described below. ity at a specified date (using market prices inferred from your trans-
actions, or declared with P directives).
-V: Market value We call this "valuation", and it is controlled by the --value=VALUA-
The -V/--market flag converts reported amounts to their market value in TIONTYPE[,COMMODITY] option. It can get a little involved, so we cover
a default valuation commodity, using the market prices in effect on a all the details below. But most of the time, all you need to do is use
default valuation date. For single period reports, the valuation date these simpler flags instead:
is today (equivalent to --value=now); for multiperiod reports, it is
the last day of each subperiod (equivalent to --value=end). 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- The default valuation commodity is the one referenced in the latest ap-
plicable market price dated on or before the valuation date. If most plicable market price dated on or before the valuation date. Typically
of your P declarations lead to a single home currency, this will usu- your P declarations or currency exchange transactions reference a sin-
ally be what you want. (To specify the commodity, see -X below.) gle base currency, and -V will pick that.
Note that in hledger, market prices are always declared explicitly with The default valuation date is today for single period reports (equiva-
P directives; we do not infer them from transaction prices as Ledger lent to --value=now), or the last day of each subperiod for multiperiod
does. reports (equivalent to --value=end).
Here's a quick example of -V: An example:
; one euro is worth this many dollars from nov 1 ; one euro is worth this many dollars from nov 1
P 2016/11/01 EUR $1.10 P 2016/11/01 EUR $1.10
@ -1235,8 +1253,30 @@ OPTIONS
-X: Market value in specified commodity -X: Market value in specified commodity
The -X/--exchange option is like -V, except it specifies the target The -X/--exchange option is like -V, except it specifies the target
commodity you would like to convert to. It is equivalent to commodity you would like to convert to. (It is equivalent to
--value=now,COMM or --value=end,COMM. --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 --value: Flexible valuation
(experimental, added 201905) (experimental, added 201905)
@ -1414,7 +1454,6 @@ OPTIONS
Report type -B, -V, -X --value=then --value=end --value=DATE, Report type -B, -V, -X --value=then --value=end --value=DATE,
--value=cost --value=now --value=cost --value=now
------------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------------
print print
posting cost value at re- value at value at re- value at posting cost value at re- value at value at re- value at
amounts port end or posting date port or DATE/today amounts port end or posting date port or DATE/today
@ -1438,6 +1477,8 @@ OPTIONS
amounts terval, val- amounts terval, val-
(with report ued at inter- (with report ued at inter-
interval) val start interval) val start
running to- sum/average sum/average sum/average sum/average sum/average running to- sum/average sum/average sum/average sum/average sum/average
tal/average of displayed of displayed of displayed of displayed of displayed tal/average of displayed of displayed of displayed of displayed of displayed
values values values values values values values values values values
@ -1508,9 +1549,6 @@ OPTIONS
report's multi-period mode (whether showing one or many subperi- report's multi-period mode (whether showing one or many subperi-
ods). ods).
Combining -B, -V, -X, --value
The rightmost of these flags wins.
COMMANDS COMMANDS
hledger provides a number of subcommands; hledger with no arguments hledger provides a number of subcommands; hledger with no arguments
shows a list. shows a list.
@ -3007,7 +3045,7 @@ COMMANDS
For help on these, see https://github.com/feuerbach/tasty#options (-- For help on these, see https://github.com/feuerbach/tasty#options (--
--help currently doesn't show them). --help currently doesn't show them).
Add-on Commands Add-on commands
hledger also searches for external add-on commands, and will include hledger also searches for external add-on commands, and will include
these in the commands list. These are programs or scripts in your PATH 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- 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 variable. The command env | grep LEDGER_FILE should show it. You may
need to use export. Here's an explanation. need to use export. Here's an explanation.
"Illegal byte sequence" or "Invalid or incomplete multibyte or wide Getting errors like "Illegal byte sequence" or "Invalid or incomplete
character" errors multibyte or wide character" or "commitAndReleaseBuffer: invalid argu-
In order to handle non-ascii letters and symbols (like ), hledger needs ment (invalid character)"
an appropriate locale. This is usually configured system-wide; you can Programs compiled with GHC (hledger, haskell build tools, etc.) need to
also configure it temporarily. The locale may need to be one that sup- have a UTF-8-aware locale configured in the environment, otherwise they
ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, will fail with these kinds of errors when they encounter non-ascii
I'm not sure yet). characters.
Here's an example of setting the locale temporarily, on ubuntu To fix it, set the LANG environment variable to some locale which sup-
gnu/linux: 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 $ file my.journal
my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded my.journal: UTF-8 Unicode text # the file is UTF8-encoded
$ locale -a $ echo $LANG
C # LANG is set to the default locale, which does not support UTF8
$ locale -a # which locales are installed ?
C C
en_US.utf8 # <- a UTF8-aware locale is available en_US.utf8 # here's a UTF8-aware one we can use
POSIX 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: 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-
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile bian:
$ bash --login
If we preferred to use eg fr_FR.utf8, we might have to install that
first:
$ apt-get install language-pack-fr $ apt-get install language-pack-fr
$ locale -a $ locale -a
@ -3160,8 +3198,18 @@ TROUBLESHOOTING
POSIX POSIX
$ LANG=fr_FR.utf8 hledger -f my.journal print $ LANG=fr_FR.utf8 hledger -f my.journal print
Note some platforms allow variant locale spellings, but not all (ubuntu Here's how you could set it permanently, if you use a bash shell:
accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8).
$ 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)