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

;doc: regen help/manuals

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2020-02-22 11:33:50 -08:00
parent b9b5702946
commit 696ec4998b
18 changed files with 1246 additions and 1168 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
hledger-lib/hledger_csv.5
View File

@ -156,7 +156,7 @@ fields date, description, amount-out, amount-in, balance
# We generate balance assertions by assigning to \[dq]balance\[dq] # We generate balance assertions by assigning to \[dq]balance\[dq]
# above, but you may sometimes need to remove these because: # above, but you may sometimes need to remove these because:
# #
# - the CSV balance differs from the true balance, # - the CSV balance differs from the true balance,
# by up to 0.0000000000005 in my experience # by up to 0.0000000000005 in my experience
# #
# - it is sometimes calculated based on non-chronological ordering, # - it is sometimes calculated based on non-chronological ordering,
@ -237,7 +237,7 @@ amount2 %amzamount
# add a third posting for fees, but only if they are non-zero. # add a third posting for fees, but only if they are non-zero.
# Commas in the data makes counting fields hard, so count from the right instead. # Commas in the data makes counting fields hard, so count from the right instead.
# (Regex translation: \[dq]a field containing a non-zero dollar amount, # (Regex translation: \[dq]a field containing a non-zero dollar amount,
# immediately before the 1 right-most fields\[dq]) # immediately before the 1 right-most fields\[dq])
if ,\[rs]$[1-9][.0-9]+(,[\[ha],]*){1}$ if ,\[rs]$[1-9][.0-9]+(,[\[ha],]*){1}$
account3 expenses:fees account3 expenses:fees
@ -298,11 +298,11 @@ date-format %-m/%-d/%Y
if if
In Progress In Progress
Temporary Hold Temporary Hold
Update to Update to
skip skip
# add more fields to the description # add more fields to the description
description %description_ %itemtitle description %description_ %itemtitle
# save some other fields as tags # save some other fields as tags
comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
@ -350,9 +350,9 @@ include common.rules
# apply some overrides specific to this csv # apply some overrides specific to this csv
# Transfers from/to bank. These are usually marked Pending, # Transfers from/to bank. These are usually marked Pending,
# which can be disregarded in this case. # which can be disregarded in this case.
if if
Bank Account Bank Account
Bank Deposit to PP Account Bank Deposit to PP Account
description %type for %referencetxnid %itemtitle description %type for %referencetxnid %itemtitle

116
hledger-lib/hledger_csv.info
View File

@ -118,7 +118,7 @@ fields date, description, amount-out, amount-in, balance
# We generate balance assertions by assigning to "balance" # We generate balance assertions by assigning to "balance"
# above, but you may sometimes need to remove these because: # above, but you may sometimes need to remove these because:
# #
# - the CSV balance differs from the true balance, # - the CSV balance differs from the true balance,
# by up to 0.0000000000005 in my experience # by up to 0.0000000000005 in my experience
# #
# - it is sometimes calculated based on non-chronological ordering, # - it is sometimes calculated based on non-chronological ordering,
@ -191,7 +191,7 @@ amount2 %amzamount
# add a third posting for fees, but only if they are non-zero. # add a third posting for fees, but only if they are non-zero.
# Commas in the data makes counting fields hard, so count from the right instead. # Commas in the data makes counting fields hard, so count from the right instead.
# (Regex translation: "a field containing a non-zero dollar amount, # (Regex translation: "a field containing a non-zero dollar amount,
# immediately before the 1 right-most fields") # immediately before the 1 right-most fields")
if ,\$[1-9][.0-9]+(,[^,]*){1}$ if ,\$[1-9][.0-9]+(,[^,]*){1}$
account3 expenses:fees account3 expenses:fees
@ -245,11 +245,11 @@ date-format %-m/%-d/%Y
if if
In Progress In Progress
Temporary Hold Temporary Hold
Update to Update to
skip skip
# add more fields to the description # add more fields to the description
description %description_ %itemtitle description %description_ %itemtitle
# save some other fields as tags # save some other fields as tags
comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
@ -297,9 +297,9 @@ include common.rules
# apply some overrides specific to this csv # apply some overrides specific to this csv
# Transfers from/to bank. These are usually marked Pending, # Transfers from/to bank. These are usually marked Pending,
# which can be disregarded in this case. # which can be disregarded in this case.
if if
Bank Account Bank Account
Bank Deposit to PP Account Bank Deposit to PP Account
description %type for %referencetxnid %itemtitle description %type for %referencetxnid %itemtitle
@ -974,58 +974,58 @@ Node: Basic2413
Ref: #basic2513 Ref: #basic2513
Node: Bank of Ireland3055 Node: Bank of Ireland3055
Ref: #bank-of-ireland3190 Ref: #bank-of-ireland3190
Node: Amazon4653 Node: Amazon4652
Ref: #amazon4771 Ref: #amazon4770
Node: Paypal6704 Node: Paypal6702
Ref: #paypal6798 Ref: #paypal6796
Node: CSV RULES14681 Node: CSV RULES14675
Ref: #csv-rules14790 Ref: #csv-rules14784
Node: skip15066 Node: skip15060
Ref: #skip15159 Ref: #skip15153
Node: fields15534 Node: fields15528
Ref: #fields15656 Ref: #fields15650
Node: Transaction field names16821 Node: Transaction field names16815
Ref: #transaction-field-names16981 Ref: #transaction-field-names16975
Node: Posting field names17092 Node: Posting field names17086
Ref: #posting-field-names17244 Ref: #posting-field-names17238
Node: field assignment18535 Node: field assignment18529
Ref: #field-assignment18678 Ref: #field-assignment18672
Node: separator19496 Node: separator19490
Ref: #separator19625 Ref: #separator19619
Node: if20036 Node: if20030
Ref: #if20138 Ref: #if20132
Node: end21854 Node: end21848
Ref: #end21960 Ref: #end21954
Node: date-format22184 Node: date-format22178
Ref: #date-format22316 Ref: #date-format22310
Node: newest-first23065 Node: newest-first23059
Ref: #newest-first23203 Ref: #newest-first23197
Node: include23886 Node: include23880
Ref: #include24015 Ref: #include24009
Node: balance-type24459 Node: balance-type24453
Ref: #balance-type24579 Ref: #balance-type24573
Node: TIPS25279 Node: TIPS25273
Ref: #tips25361 Ref: #tips25355
Node: Rapid feedback25617 Node: Rapid feedback25611
Ref: #rapid-feedback25734 Ref: #rapid-feedback25728
Node: Valid CSV26194 Node: Valid CSV26188
Ref: #valid-csv26324 Ref: #valid-csv26318
Node: File Extension26516 Node: File Extension26510
Ref: #file-extension26668 Ref: #file-extension26662
Node: Reading multiple CSV files27078 Node: Reading multiple CSV files27072
Ref: #reading-multiple-csv-files27263 Ref: #reading-multiple-csv-files27257
Node: Valid transactions27504 Node: Valid transactions27498
Ref: #valid-transactions27682 Ref: #valid-transactions27676
Node: Deduplicating importing28310 Node: Deduplicating importing28304
Ref: #deduplicating-importing28489 Ref: #deduplicating-importing28483
Node: Setting amounts29522 Node: Setting amounts29516
Ref: #setting-amounts29691 Ref: #setting-amounts29685
Node: Setting currency/commodity30677 Node: Setting currency/commodity30671
Ref: #setting-currencycommodity30869 Ref: #setting-currencycommodity30863
Node: Referencing other fields31672 Node: Referencing other fields31666
Ref: #referencing-other-fields31872 Ref: #referencing-other-fields31866
Node: How CSV rules are evaluated32769 Node: How CSV rules are evaluated32763
Ref: #how-csv-rules-are-evaluated32942 Ref: #how-csv-rules-are-evaluated32936
 
End Tag Table End Tag Table

79
hledger-lib/hledger_journal.5
View File

@ -443,7 +443,7 @@ Eg:
assets:cash $-10 ; <- these balance assets:cash $-10 ; <- these balance
expenses:food $7 ; <- expenses:food $7 ; <-
expenses:food $3 ; <- expenses:food $3 ; <-
[assets:checking:budget:food] $-10 ; <- and these balance [assets:checking:budget:food] $-10 ; <- and these balance
[assets:checking:available] $10 ; <- [assets:checking:available] $10 ; <-
(something:else) $5 ; <- not required to balance (something:else) $5 ; <- not required to balance
\f[R] \f[R]
@ -573,15 +573,15 @@ commodity INR 9,99,99,999.00
commodity 1 000 000.9455 commodity 1 000 000.9455
\f[R] \f[R]
.fi .fi
.SS Amount display format .SS Amount display style
.PP .PP
For each commodity, hledger chooses a consistent format to use when For each commodity, hledger chooses a consistent format to use when
displaying amounts. displaying amounts.
(Except price amounts, which are always displayed as written). (Except price amounts, which are always displayed as written).
The display format is chosen as follows: The display style is chosen as follows:
.IP \[bu] 2 .IP \[bu] 2
If there is a commodity directive for the commodity, that format is used If there is a commodity directive (or default commodity directive) for
(see examples above). the commodity, that format is used (see examples above).
.IP \[bu] 2 .IP \[bu] 2
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.
@ -591,13 +591,16 @@ maximum from all posting amounts in that commmodity.
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]).
.PP .PP
Price amounts, and amounts in \f[C]D\f[R] directives don\[aq]t affect Transaction prices don\[aq]t affect the amount display style directly,
the amount display format directly, but occasionally they can do so but occasionally they can do so indirectly (eg when an posting\[aq]s
indirectly. amount is inferred using a transaction price).
(Eg when D\[aq]s default commodity is applied to a commodity-less If you find this causing problems, use a commodity directive to fix the
amount, or when an amountless posting is balanced using a price\[aq]s display style.
commodity, or when -V is used.) If you find this causing problems, use a .PP
commodity directive to set the display format. In summary: amounts will be displayed much as they appear in your
journal, with the max observed number of decimal places.
If you want to see fewer decimal places in reports, use a commodity
directive to override that.
.SS Transaction prices .SS Transaction prices
.PP .PP
Within a transaction, you can note an amount\[aq]s price in another Within a transaction, you can note an amount\[aq]s price in another
@ -753,9 +756,6 @@ Use include or concatenate the files instead.
The asserted balance must be a simple single-commodity amount, and in The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity\[aq]s balance within the fact the assertion checks only this commodity\[aq]s balance within the
(possibly multi-commodity) account balance. (possibly multi-commodity) account balance.
.PD 0
.P
.PD
This is how assertions work in Ledger also. This is how assertions work in Ledger also.
We could call this a \[dq]partial\[dq] balance assertion. We could call this a \[dq]partial\[dq] balance assertion.
.PP .PP
@ -861,7 +861,7 @@ balances:
.IP .IP
.nf .nf
\f[C] \f[C]
; starting a new journal, set asset account balances ; starting a new journal, set asset account balances
2016/1/1 opening balances 2016/1/1 opening balances
assets:checking = $409.32 assets:checking = $409.32
assets:savings = $735.24 assets:savings = $735.24
@ -1130,12 +1130,13 @@ The \f[C]commodity\f[R] directive has several functions:
It declares commodities which may be used in the journal. It declares commodities which may be used in the journal.
This is currently not enforced, but can serve as documentation. This is currently not enforced, but can serve as documentation.
.IP "2." 3 .IP "2." 3
It declares what decimal mark character to expect when parsing input - It declares what decimal mark character (period or comma) to expect when
useful to disambiguate international number formats in your data. parsing input - useful to disambiguate international number formats in
your data.
(Without this, hledger will parse both \f[C]1,000\f[R] and (Without this, hledger will parse both \f[C]1,000\f[R] and
\f[C]1.000\f[R] as 1). \f[C]1.000\f[R] as 1).
.IP "3." 3 .IP "3." 3
It declares the amount display format to use in output - decimal and It declares the amount display style to use in output - decimal and
digit group marks, number of decimal places, symbol placement etc. digit group marks, number of decimal places, symbol placement etc.
.PP .PP
You are likely to run into one of the problems solved by commodity You are likely to run into one of the problems solved by commodity
@ -1180,26 +1181,34 @@ The number must include a decimal mark: either a period or a comma,
followed by 0 or more decimal digits. followed by 0 or more decimal digits.
.SS Default commodity .SS Default commodity
.PP .PP
The \f[C]D\f[R] directive sets a default commodity (and display format), The \f[C]D\f[R] directive sets a default commodity, to be used for
to be used for amounts without a commodity symbol (ie, plain numbers). amounts without a commodity symbol (ie, plain numbers).
(Note this differs from Ledger\[aq]s default commodity directive.) The This commodity will be applied to all subsequent commodity-less amounts,
commodity and display format will be applied to all subsequent or until the next \f[C]D\f[R] directive.
commodity-less amounts, or until the next \f[C]D\f[R] directive. (Note, this is different from Ledger\[aq]s \f[C]D\f[R].)
.PP
For compatibility/historical reasons, \f[C]D\f[R] also acts like a
\f[C]commodity\f[R] directive, setting the commodity\[aq]s display style
(for output) and decimal mark (for parsing input).
As with \f[C]commodity\f[R], the amount must always be written with a
decimal mark (period or comma).
If both directives are used, \f[C]commodity\f[R]\[aq]s style takes
precedence.
.PP
The syntax is \f[C]D AMOUNT\f[R].
Eg:
.IP .IP
.nf .nf
\f[C] \f[C]
; commodity-less amounts should be treated as dollars ; commodity-less amounts should be treated as dollars
; (and displayed with symbol on the left, thousands separators and two decimal places) ; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
D $1,000.00 D $1,000.00
1/1 1/1
a 5 ; <- commodity-less amount, becomes $1 a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
b b
\f[R] \f[R]
.fi .fi
.PP
As with the \f[C]commodity\f[R] directive, the amount must always be
written with a decimal point.
.SS Market prices .SS 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
@ -1331,7 +1340,7 @@ account assets ; type:Asset
account liabilities ; type:Liability account liabilities ; type:Liability
account equity ; type:Equity account equity ; type:Equity
account revenues ; type:Revenue account revenues ; type:Revenue
account expenses ; type:Expenses account expenses ; type:Expense
\f[R] \f[R]
.fi .fi
.SS Account types declared with account type codes .SS Account types declared with account type codes
@ -1360,8 +1369,8 @@ Eg:
; make \[dq]liabilities\[dq] not have the liability type - who knows why ; make \[dq]liabilities\[dq] not have the liability type - who knows why
account liabilities ; type:E account liabilities ; type:E
; we need to ensure some other account has the liability type, ; we need to ensure some other account has the liability type,
; otherwise balancesheet would still show \[dq]liabilities\[dq] under Liabilities ; otherwise balancesheet would still show \[dq]liabilities\[dq] under Liabilities
account - ; type:L account - ; type:L
\f[R] \f[R]
.fi .fi
@ -1767,8 +1776,8 @@ And each \[dq]posting\[dq] is actually a posting-generating rule:
.nf .nf
\f[C] \f[C]
= QUERY = QUERY
ACCT AMT ACCOUNT AMOUNT
ACCT [AMT] ACCOUNT [AMOUNT]
... ...
\f[R] \f[R]
.fi .fi
@ -1799,7 +1808,7 @@ Eg, note the quotes around the second query term below:
.nf .nf
\f[C] \f[C]
= expenses:groceries \[aq]expenses:dining out\[aq] = expenses:groceries \[aq]expenses:dining out\[aq]
(budget:funds:dining out) *-1 (budget:funds:dining out) *-1
\f[R] \f[R]
.fi .fi
.PP .PP

261
hledger-lib/hledger_journal.info
View File

@ -406,7 +406,7 @@ zero (separately from other postings). Eg:
assets:cash $-10 ; <- these balance assets:cash $-10 ; <- these balance
expenses:food $7 ; <- expenses:food $7 ; <-
expenses:food $3 ; <- expenses:food $3 ; <-
[assets:checking:budget:food] $-10 ; <- and these balance [assets:checking:budget:food] $-10 ; <- and these balance
[assets:checking:available] $10 ; <- [assets:checking:available] $10 ; <-
(something:else) $5 ; <- not required to balance (something:else) $5 ; <- not required to balance
@ -479,10 +479,10 @@ comma:
* Menu: * Menu:
* Digit group marks:: * Digit group marks::
* Amount display format:: * Amount display style::
 
File: hledger_journal.info, Node: Digit group marks, Next: Amount display format, Up: Amounts File: hledger_journal.info, Node: Digit group marks, Next: Amount display style, Up: Amounts
1.8.1 Digit group marks 1.8.1 Digit group marks
----------------------- -----------------------
@ -515,17 +515,17 @@ commodity INR 9,99,99,999.00
commodity 1 000 000.9455 commodity 1 000 000.9455
 
File: hledger_journal.info, Node: Amount display format, Prev: Digit group marks, Up: Amounts File: hledger_journal.info, Node: Amount display style, Prev: Digit group marks, Up: Amounts
1.8.2 Amount display format 1.8.2 Amount display style
--------------------------- --------------------------
For each commodity, hledger chooses a consistent format to use when For each commodity, hledger chooses a consistent format to use when
displaying amounts. (Except price amounts, which are always displayed displaying amounts. (Except price amounts, which are always displayed
as written). The display format is chosen as follows: as written). The display style is chosen as follows:
* If there is a commodity directive for the commodity, that format is * If there is a commodity directive (or default commodity directive)
used (see examples above). for the commodity, that format is used (see examples above).
* 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
@ -535,12 +535,15 @@ as written). The display format is chosen as follows:
* 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').
Price amounts, and amounts in 'D' directives don't affect the amount Transaction prices don't affect the amount display style directly,
display format directly, but occasionally they can do so indirectly. but occasionally they can do so indirectly (eg when an posting's amount
(Eg when D's default commodity is applied to a commodity-less amount, or is inferred using a transaction price). If you find this causing
when an amountless posting is balanced using a price's commodity, or problems, use a commodity directive to fix the display style.
when -V is used.) If you find this causing problems, use a commodity
directive to set the display format. In summary: amounts will be displayed much as they appear in your
journal, with the max observed number of decimal places. If you want to
see fewer decimal places in reports, use a commodity directive to
override that.
 
File: hledger_journal.info, Node: Transaction prices, Next: Balance Assertions, Prev: Amounts, Up: Transactions File: hledger_journal.info, Node: Transaction prices, Next: Balance Assertions, Prev: Amounts, Up: Transactions
@ -691,9 +694,8 @@ File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions
The asserted balance must be a simple single-commodity amount, and in The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. (possibly multi-commodity) account balance. This is how assertions work
This is how assertions work in Ledger also. We could call this a in Ledger also. We could call this a "partial" balance assertion.
"partial" balance assertion.
To assert the balance of more than one commodity in an account, you To assert the balance of more than one commodity in an account, you
can write multiple postings, each asserting one commodity's balance. can write multiple postings, each asserting one commodity's balance.
@ -800,7 +802,7 @@ equals sign; instead it is calculated automatically so as to satisfy the
assertion. This can be a convenience during data entry, eg when setting assertion. This can be a convenience during data entry, eg when setting
opening balances: opening balances:
; starting a new journal, set asset account balances ; starting a new journal, set asset account balances
2016/1/1 opening balances 2016/1/1 opening balances
assets:checking = $409.32 assets:checking = $409.32
assets:savings = $735.24 assets:savings = $735.24
@ -1011,14 +1013,13 @@ The 'commodity' directive has several functions:
1. It declares commodities which may be used in the journal. This is 1. It declares commodities which may be used in the journal. This is
currently not enforced, but can serve as documentation. currently not enforced, but can serve as documentation.
2. It declares what decimal mark character to expect when parsing 2. It declares what decimal mark character (period or comma) to expect
input - useful to disambiguate international number formats in your when parsing input - useful to disambiguate international number
data. (Without this, hledger will parse both '1,000' and '1.000' formats in your data. (Without this, hledger will parse both
as 1). '1,000' and '1.000' as 1).
3. It declares the amount display format to use in output - decimal 3. It declares the amount display style to use in output - decimal and
and digit group marks, number of decimal places, symbol placement digit group marks, number of decimal places, symbol placement etc.
etc.
You are likely to run into one of the problems solved by commodity You are likely to run into one of the problems solved by commodity
directives, sooner or later, so it's a good idea to just always use them directives, sooner or later, so it's a good idea to just always use them
@ -1057,23 +1058,27 @@ File: hledger_journal.info, Node: Default commodity, Next: Market prices, Pre
1.12.5 Default commodity 1.12.5 Default commodity
------------------------ ------------------------
The 'D' directive sets a default commodity (and display format), to be The 'D' directive sets a default commodity, to be used for amounts
used for amounts without a commodity symbol (ie, plain numbers). (Note without a commodity symbol (ie, plain numbers). This commodity will be
this differs from Ledger's default commodity directive.) The commodity applied to all subsequent commodity-less amounts, or until the next 'D'
and display format will be applied to all subsequent commodity-less directive. (Note, this is different from Ledger's 'D'.)
amounts, or until the next 'D' directive.
For compatibility/historical reasons, 'D' also acts like a
'commodity' directive, setting the commodity's display style (for
output) and decimal mark (for parsing input). As with 'commodity', the
amount must always be written with a decimal mark (period or comma). If
both directives are used, 'commodity''s style takes precedence.
The syntax is 'D AMOUNT'. Eg:
; commodity-less amounts should be treated as dollars ; commodity-less amounts should be treated as dollars
; (and displayed with symbol on the left, thousands separators and two decimal places) ; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
D $1,000.00 D $1,000.00
1/1 1/1
a 5 ; <- commodity-less amount, becomes $1 a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
b b
As with the 'commodity' directive, the amount must always be written
with a decimal point.
 
File: hledger_journal.info, Node: Market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives File: hledger_journal.info, Node: Market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives
@ -1197,7 +1202,7 @@ account assets ; type:Asset
account liabilities ; type:Liability account liabilities ; type:Liability
account equity ; type:Equity account equity ; type:Equity
account revenues ; type:Revenue account revenues ; type:Revenue
account expenses ; type:Expenses account expenses ; type:Expense
Account types declared with account type codes Or, you can write one Account types declared with account type codes Or, you can write one
of those letters separated from the account name by two or more spaces, of those letters separated from the account name by two or more spaces,
@ -1216,8 +1221,8 @@ need to help the reports a bit. Eg:
; make "liabilities" not have the liability type - who knows why ; make "liabilities" not have the liability type - who knows why
account liabilities ; type:E account liabilities ; type:E
; we need to ensure some other account has the liability type, ; we need to ensure some other account has the liability type,
; otherwise balancesheet would still show "liabilities" under Liabilities ; otherwise balancesheet would still show "liabilities" under Liabilities
account - ; type:L account - ; type:L
 
@ -1612,8 +1617,8 @@ certain postings (mnemonic: '=' suggests matching). And each "posting"
is actually a posting-generating rule: is actually a posting-generating rule:
= QUERY = QUERY
ACCT AMT ACCOUNT AMOUNT
ACCT [AMT] ACCOUNT [AMOUNT]
... ...
These posting-generating rules look like normal postings, except the These posting-generating rules look like normal postings, except the
@ -1635,7 +1640,7 @@ quotes, as on the command line. Eg, note the quotes around the second
query term below: query term below:
= expenses:groceries 'expenses:dining out' = expenses:groceries 'expenses:dining out'
(budget:funds:dining out) *-1 (budget:funds:dining out) *-1
These rules have global effect - a rule appearing anywhere in your These rules have global effect - a rule appearing anywhere in your
data can potentially affect any transaction, including transactions data can potentially affect any transaction, including transactions
@ -1754,92 +1759,92 @@ Node: Postings12506
Ref: #postings12634 Ref: #postings12634
Node: Virtual Postings13660 Node: Virtual Postings13660
Ref: #virtual-postings13777 Ref: #virtual-postings13777
Node: Account names15083 Node: Account names15082
Ref: #account-names15224 Ref: #account-names15223
Node: Amounts15711 Node: Amounts15710
Ref: #amounts15850 Ref: #amounts15849
Node: Digit group marks16783 Node: Digit group marks16781
Ref: #digit-group-marks16932 Ref: #digit-group-marks16929
Node: Amount display format17870 Node: Amount display style17867
Ref: #amount-display-format18027 Ref: #amount-display-style18021
Node: Transaction prices19052 Node: Transaction prices19182
Ref: #transaction-prices19218 Ref: #transaction-prices19348
Node: Balance Assertions21484 Node: Balance Assertions21614
Ref: #balance-assertions21664 Ref: #balance-assertions21794
Node: Assertions and ordering22697 Node: Assertions and ordering22827
Ref: #assertions-and-ordering22885 Ref: #assertions-and-ordering23015
Node: Assertions and included files23585 Node: Assertions and included files23715
Ref: #assertions-and-included-files23828 Ref: #assertions-and-included-files23958
Node: Assertions and multiple -f options24161 Node: Assertions and multiple -f options24291
Ref: #assertions-and-multiple--f-options24417 Ref: #assertions-and-multiple--f-options24547
Node: Assertions and commodities24549 Node: Assertions and commodities24679
Ref: #assertions-and-commodities24781 Ref: #assertions-and-commodities24911
Node: Assertions and prices25937 Node: Assertions and prices26068
Ref: #assertions-and-prices26151 Ref: #assertions-and-prices26282
Node: Assertions and subaccounts26591 Node: Assertions and subaccounts26722
Ref: #assertions-and-subaccounts26820 Ref: #assertions-and-subaccounts26951
Node: Assertions and virtual postings27144 Node: Assertions and virtual postings27275
Ref: #assertions-and-virtual-postings27386 Ref: #assertions-and-virtual-postings27517
Node: Assertions and precision27528 Node: Assertions and precision27659
Ref: #assertions-and-precision27721 Ref: #assertions-and-precision27852
Node: Balance Assignments27988 Node: Balance Assignments28119
Ref: #balance-assignments28162 Ref: #balance-assignments28293
Node: Balance assignments and prices29327 Node: Balance assignments and prices29457
Ref: #balance-assignments-and-prices29499 Ref: #balance-assignments-and-prices29629
Node: Directives29723 Node: Directives29853
Ref: #directives29882 Ref: #directives30012
Node: Comment blocks35530 Node: Comment blocks35660
Ref: #comment-blocks35675 Ref: #comment-blocks35805
Node: Including other files35851 Node: Including other files35981
Ref: #including-other-files36031 Ref: #including-other-files36161
Node: Default year36439 Node: Default year36569
Ref: #default-year36608 Ref: #default-year36738
Node: Declaring commodities37015 Node: Declaring commodities37145
Ref: #declaring-commodities37198 Ref: #declaring-commodities37328
Node: Default commodity38859 Node: Default commodity39001
Ref: #default-commodity39035 Ref: #default-commodity39177
Node: Market prices39669 Node: Market prices40066
Ref: #market-prices39834 Ref: #market-prices40231
Node: Declaring accounts40675 Node: Declaring accounts41072
Ref: #declaring-accounts40851 Ref: #declaring-accounts41248
Node: Account comments41776 Node: Account comments42173
Ref: #account-comments41939 Ref: #account-comments42336
Node: Account subdirectives42363 Node: Account subdirectives42760
Ref: #account-subdirectives42558 Ref: #account-subdirectives42955
Node: Account types42871 Node: Account types43268
Ref: #account-types43055 Ref: #account-types43452
Node: Account display order44697 Node: Account display order45091
Ref: #account-display-order44867 Ref: #account-display-order45261
Node: Rewriting accounts46018 Node: Rewriting accounts46412
Ref: #rewriting-accounts46203 Ref: #rewriting-accounts46597
Node: Basic aliases46929 Node: Basic aliases47323
Ref: #basic-aliases47075 Ref: #basic-aliases47469
Node: Regex aliases47779 Node: Regex aliases48173
Ref: #regex-aliases47951 Ref: #regex-aliases48345
Node: Combining aliases48669 Node: Combining aliases49063
Ref: #combining-aliases48847 Ref: #combining-aliases49241
Node: end aliases50123 Node: end aliases50517
Ref: #end-aliases50271 Ref: #end-aliases50665
Node: Default parent account50372 Node: Default parent account50766
Ref: #default-parent-account50538 Ref: #default-parent-account50932
Node: Periodic transactions51422 Node: Periodic transactions51816
Ref: #periodic-transactions51621 Ref: #periodic-transactions52015
Node: Periodic rule syntax53493 Node: Periodic rule syntax53887
Ref: #periodic-rule-syntax53699 Ref: #periodic-rule-syntax54093
Node: Two spaces between period expression and description!54403 Node: Two spaces between period expression and description!54797
Ref: #two-spaces-between-period-expression-and-description54722 Ref: #two-spaces-between-period-expression-and-description55116
Node: Forecasting with periodic transactions55406 Node: Forecasting with periodic transactions55800
Ref: #forecasting-with-periodic-transactions55711 Ref: #forecasting-with-periodic-transactions56105
Node: Budgeting with periodic transactions57737 Node: Budgeting with periodic transactions58131
Ref: #budgeting-with-periodic-transactions57976 Ref: #budgeting-with-periodic-transactions58370
Node: Auto postings / transaction modifiers58425 Node: Auto postings / transaction modifiers58819
Ref: #auto-postings-transaction-modifiers58637 Ref: #auto-postings-transaction-modifiers59031
Node: Auto postings and dates61122 Node: Auto postings and dates61527
Ref: #auto-postings-and-dates61379 Ref: #auto-postings-and-dates61784
Node: Auto postings and transaction balancing / inferred amounts / balance assertions61554 Node: Auto postings and transaction balancing / inferred amounts / balance assertions61959
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61929 Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62334
Node: Auto posting tags62307 Node: Auto posting tags62712
Ref: #auto-posting-tags62546 Ref: #auto-posting-tags62951
 
End Tag Table End Tag Table

230
hledger-lib/hledger_journal.txt
View File

@ -403,13 +403,13 @@ FILE FORMAT
commodity INR 9,99,99,999.00 commodity INR 9,99,99,999.00
commodity 1 000 000.9455 commodity 1 000 000.9455
Amount display format Amount display style
For each commodity, hledger chooses a consistent format to use when For each commodity, hledger chooses a consistent format to use when
displaying amounts. (Except price amounts, which are always displayed displaying amounts. (Except price amounts, which are always displayed
as written). The display format is chosen as follows: as written). The display style is chosen as follows:
o If there is a commodity directive for the commodity, that format is o If there is a commodity directive (or default commodity directive)
used (see examples above). for the commodity, that format is used (see examples above).
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-
@ -419,18 +419,21 @@ FILE FORMAT
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).
Price amounts, and amounts in D directives don't affect the amount dis- Transaction prices don't affect the amount display style directly, but
play format directly, but occasionally they can do so indirectly. (Eg occasionally they can do so indirectly (eg when an posting's amount is
when D's default commodity is applied to a commodity-less amount, or inferred using a transaction price). If you find this causing prob-
when an amountless posting is balanced using a price's commodity, or lems, use a commodity directive to fix the display style.
when -V is used.) If you find this causing problems, use a commodity
directive to set the display format. In summary: amounts will be displayed much as they appear in your jour-
nal, with the max observed number of decimal places. If you want to
see fewer decimal places in reports, use a commodity directive to over-
ride that.
Transaction prices Transaction prices
Within a transaction, you can note an amount's price in another commod- Within a transaction, you can note an amount's price in another commod-
ity. This can be used to document the cost (in a purchase) or selling ity. This can be used to document the cost (in a purchase) or selling
price (in a sale). For example, transaction prices are useful to price (in a sale). For example, transaction prices are useful to
record purchases of a foreign currency. Note transaction prices are record purchases of a foreign currency. Note transaction prices are
fixed at the time of the transaction, and do not change over time. See fixed at the time of the transaction, and do not change over time. See
also market prices, which represent prevailing exchange rates on a cer- also market prices, which represent prevailing exchange rates on a cer-
tain date. tain date.
@ -459,7 +462,7 @@ FILE FORMAT
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
PRICE}, which hledger currently ignores). PRICE}, which hledger currently ignores).
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).
Eg here is how -B affects the balance report for the example above: Eg here is how -B affects the balance report for the example above:
@ -470,8 +473,8 @@ FILE FORMAT
$-135 assets:dollars $-135 assets:dollars
$135 assets:euros # <- the euros' cost $135 assets:euros # <- the euros' cost
Note -B is sensitive to the order of postings when a transaction price Note -B is sensitive to the order of postings when a transaction price
is inferred: the inferred price will be in the commodity of the last is inferred: the inferred price will be in the commodity of the last
amount. So if example 3's postings are reversed, while the transaction amount. So if example 3's postings are reversed, while the transaction
is equivalent, -B shows something different: is equivalent, -B shows something different:
@ -484,9 +487,9 @@ FILE FORMAT
EUR100 assets:euros EUR100 assets:euros
Balance Assertions 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
and b after each posting: and b after each posting:
2013/1/1 2013/1/1
@ -498,32 +501,32 @@ FILE FORMAT
b $-1 =$-2 b $-1 =$-2
After reading a journal file, hledger will check all balance assertions After reading a journal file, hledger will check all balance assertions
and report an error if any of them fail. Balance assertions can pro- and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the cleaning up old entries. You can disable them temporarily with the
-I/--ignore-assertions flag, which can be useful for troubleshooting or -I/--ignore-assertions flag, which can be useful for troubleshooting or
for reading Ledger files. (Note: this flag currently does not disable for reading Ledger files. (Note: this flag currently does not disable
balance assignments, below). balance assignments, below).
Assertions and ordering 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
then (for postings on the same day) by parse order. Note this is dif- then (for postings on the same day) by parse order. Note this is dif-
ferent from Ledger, which sorts assertions only by parse order. (Also, ferent from Ledger, which sorts assertions only by parse order. (Also,
Ledger assertions do not see the accumulated effect of repeated post- Ledger assertions do not see the accumulated effect of repeated post-
ings to the same account within a transaction.) ings to the same account within a transaction.)
So, hledger balance assertions keep working if you reorder differently- So, hledger balance assertions keep working if you reorder differently-
dated transactions within the journal. But if you reorder same-dated dated transactions within the journal. But if you reorder same-dated
transactions or postings, assertions might break and require updating. transactions or postings, assertions might break and require updating.
This order dependence does bring an advantage: precise control over the This order dependence does bring an advantage: precise control over the
order of postings and assertions within a day, so you can assert intra- order of postings and assertions within a day, so you can assert intra-
day balances. day balances.
Assertions and included files Assertions and included files
With included files, things are a little more complicated. Including With included files, things are a little more complicated. Including
preserves the ordering of postings and assertions. If you have multi- preserves the ordering of postings and assertions. If you have multi-
ple postings to an account on the same day, split across different ple postings to an account on the same day, split across different
files, and you also want to assert the account's balance on the same files, 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. day, you'll have to put the assertion in the right file.
Assertions and multiple -f options Assertions and multiple -f options
@ -531,16 +534,15 @@ FILE FORMAT
-f options. Use include or concatenate the files instead. -f options. Use include or concatenate the files instead.
Assertions and commodities 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
fact the assertion checks only this commodity's balance within the fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. (possibly multi-commodity) account balance. This is how assertions
This is how assertions work in Ledger also. We could call this a "par- work in Ledger also. We could call this a "partial" balance assertion.
tial" balance assertion.
To assert the balance of more than one commodity in an account, you can To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity's balance. write multiple postings, each asserting one commodity's balance.
You can make a stronger "total" balance assertion by writing a double You can make a stronger "total" balance assertion by writing a double
equals sign (== EXPECTEDBALANCE). This asserts that there are no other equals sign (== EXPECTEDBALANCE). This asserts that there are no other
unasserted commodities in the account (or, that their balance is 0). unasserted commodities in the account (or, that their balance is 0).
@ -560,7 +562,7 @@ FILE FORMAT
a 0 == $1 a 0 == $1
It's not yet possible to make a complete assertion about a balance that It's not yet possible to make a complete assertion about a balance that
has multiple commodities. One workaround is to isolate each commodity has multiple commodities. One workaround is to isolate each commodity
into its own subaccount: into its own subaccount:
2013/1/1 2013/1/1
@ -574,21 +576,21 @@ FILE FORMAT
a:euro 0 == 1EUR a:euro 0 == 1EUR
Assertions and prices Assertions and prices
Balance assertions ignore transaction prices, and should normally be Balance assertions ignore transaction prices, and should normally be
written without one: written without one:
2019/1/1 2019/1/1
(a) $1 @ EUR1 = $1 (a) $1 @ EUR1 = $1
We do allow prices to be written there, however, and print shows them, We do allow prices to be written there, however, and print shows them,
even though they don't affect whether the assertion passes or fails. even though they don't affect whether the assertion passes or fails.
This is for backward compatibility (hledger's close command used to This is for backward compatibility (hledger's close command used to
generate balance assertions with prices), and because balance assign- generate balance assertions with prices), and because balance assign-
ments do use them (see below). ments do use them (see below).
Assertions and subaccounts Assertions and subaccounts
The balance assertions above (= and ==) do not count the balance from The balance assertions above (= and ==) do not count the balance from
subaccounts; they check the account's exclusive balance only. You can subaccounts; they check the account's exclusive balance only. You can
assert the balance including subaccounts by writing =* or ==*, eg: assert the balance including subaccounts by writing =* or ==*, eg:
2019/1/1 2019/1/1
@ -602,16 +604,16 @@ FILE FORMAT
tual. They are not affected by the --real/-R flag or real: query. tual. They are not affected by the --real/-R flag or real: query.
Assertions and precision Assertions and precision
Balance assertions compare the exactly calculated amounts, which are Balance assertions compare the exactly calculated amounts, which are
not always what is shown by reports. Eg a commodity directive may not always what is shown by reports. Eg a commodity directive may
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
the assertion. This can be a convenience during data entry, eg when the assertion. This can be a convenience during data entry, eg when
setting opening balances: setting opening balances:
; starting a new journal, set asset account balances ; starting a new journal, set asset account balances
@ -629,14 +631,14 @@ FILE FORMAT
expenses:misc expenses:misc
The calculated amount depends on the account's balance in the commodity The calculated amount depends on the account's balance in the commodity
at that point (which depends on the previously-dated postings of the at that point (which depends on the previously-dated postings of the
commodity to that account since the last balance assertion or assign- commodity to that account since the last balance assertion or assign-
ment). Note that using balance assignments makes your journal a little ment). Note that using balance assignments makes your journal a little
less explicit; to know the exact amount posted, you have to run hledger less explicit; to know the exact amount posted, you have to run hledger
or do the calculations yourself, instead of just reading it. or do the calculations yourself, instead of just reading it.
Balance assignments and prices 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
amount to have that price attached: amount to have that price attached:
2019/1/1 2019/1/1
@ -647,79 +649,82 @@ FILE FORMAT
(a) $1 @ EUR2 = $1 @ EUR2 (a) $1 @ EUR2 = $1 @ EUR2
Directives 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,
that influences how the journal is processed. hledger's directives are that influences how the journal is processed. hledger's directives are
based on a subset of Ledger's, but there are many differences (and also based on a subset of Ledger's, but there are many differences (and also
some differences between hledger versions). some differences between hledger versions).
Directives' behaviour and interactions can get a little bit complex, so Directives' behaviour and interactions can get a little bit complex, so
here is a table summarising the directives and their effects, with here is a table summarising the directives and their effects, with
links to more detailed docs. links to more detailed docs.
direc- end di- subdi- purpose can affect (as of direc- end di- subdi- purpose can affect (as of
tive rective rec- 2018/06) tive rective rec- 2018/06)
tives tives
------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------
account any document account names, de- all entries in all account any document account names, de- all entries in all
text clare account types & dis- files, before or text clare account types & dis- files, before or
play order after play order after
alias end rewrite account names following in- alias end rewrite account names following in-
aliases line/included en- aliases line/included en-
tries until end of tries until end of
current file or end current file or end
directive directive
apply end apply prepend a common parent to following in- apply end apply prepend a common parent to following in-
account account account names line/included en- account account account names line/included en-
tries until end of tries until end of
current file or end current file or end
directive directive
comment end com- ignore part of journal following in- comment end com- ignore part of journal following in-
ment line/included en- ment line/included en-
tries until end of tries until end of
current file or end current file or end
directive directive
commod- format declare a commodity and its number notation: commod- format declare a commodity and its number notation:
ity number notation & display following entries ity number notation & display following entries
style in that commodity style in that commodity
in all files; dis- in all files; dis-
play style: amounts play style: amounts
of that commodity of that commodity
in reports in reports
D declare a commodity to be default commodity: D declare a commodity to be default commodity:
used for commodityless following commod- used for commodityless following commod-
amounts, and its number no- ityless entries un- amounts, and its number no- ityless entries un-
tation & display style til end of current tation & display style til end of current
file; number nota- file; number nota-
tion: following en- tion: following en-
tries in that com- tries in that com-
modity until end of modity until end of
current file; dis- current file; dis-
play style: amounts play style: amounts
of that commodity of that commodity
in reports in reports
include include entries/directives what the included include include entries/directives what the included
from another file directives affect from another file directives affect
P declare a market price for a amounts of that P declare a market price for a amounts of that
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
current file current file
And some definitions: And some definitions:
subdi- optional indented directive line immediately following a parent subdi- optional indented directive line immediately following a parent
rec- directive rec- directive
tive tive
number how to interpret numbers when parsing journal entries (the iden- number how to interpret numbers when parsing journal entries (the iden-
nota- tity of the decimal separator character). (Currently each com- nota- tity of the decimal separator character). (Currently each com-
tion modity can have its own notation, even in the same file.) tion modity can have its own notation, even in the same file.)
dis- how to display amounts of a commodity in reports (symbol side dis- how to display amounts of a commodity in reports (symbol side
play and spacing, digit groups, decimal separator, decimal places) play and spacing, digit groups, decimal separator, decimal places)
style style
direc- which entries and (when there are multiple files) which files
direc- which entries and (when there are multiple files) which files
tive are affected by a directive tive are affected by a directive
scope scope
@ -727,34 +732,34 @@ FILE FORMAT
affect, and whether they are focussed on input (parsing) or output (re- affect, and whether they are focussed on input (parsing) or output (re-
ports). Some directives have multiple effects. ports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro- typically last only until the end of their defining file. This pro-
vides more simplicity and predictability, eg reports are not changed by vides more simplicity and predictability, eg reports are not changed by
writing file options in a different order. It can be surprising at writing file options in a different order. It can be surprising at
times though. times though.
Comment blocks 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,
and a line containing just end comment (or the end of the current file) and a line containing just end comment (or the end of the current file)
ends it. See also comments. ends it. See also comments.
Including other files 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
directive, like this: directive, like this:
include path/to/file.journal include path/to/file.journal
If the path does not begin with a slash, it is relative to the current If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g. file. The include file path may contain common glob patterns (e.g.
*). *).
The include directive can only be used in journal files. It can in- The include directive can only be used in journal files. It can in-
clude journal, timeclock or timedot files, but not CSV files. clude journal, timeclock or timedot files, but not CSV files.
Default year 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
specify a year. This is a line beginning with Y followed by the year. specify a year. This is a line beginning with Y followed by the year.
Eg: Eg:
Y2009 ; set default year to 2009 Y2009 ; set default year to 2009
@ -776,14 +781,15 @@ FILE FORMAT
Declaring commodities Declaring commodities
The commodity directive has several functions: The commodity directive has several functions:
1. It declares commodities which may be used in the journal. This is 1. It declares commodities which may be used in the journal. This is
currently not enforced, but can serve as documentation. currently not enforced, but can serve as documentation.
2. It declares what decimal mark character to expect when parsing input 2. It declares what decimal mark character (period or comma) to expect
- useful to disambiguate international number formats in your data. when parsing input - useful to disambiguate international number
(Without this, hledger will parse both 1,000 and 1.000 as 1). formats in your data. (Without this, hledger will parse both 1,000
and 1.000 as 1).
3. It declares the amount display format to use in output - decimal and 3. It declares the amount display style to use in output - decimal and
digit group marks, number of decimal places, symbol placement etc. digit group marks, number of decimal places, symbol placement etc.
You are likely to run into one of the problems solved by commodity di- You are likely to run into one of the problems solved by commodity di-
@ -818,23 +824,27 @@ FILE FORMAT
comma, followed by 0 or more decimal digits. comma, followed by 0 or more decimal digits.
Default commodity Default commodity
The D directive sets a default commodity (and display format), to be The D directive sets a default commodity, to be used for amounts with-
used for amounts without a commodity symbol (ie, plain numbers). (Note out a commodity symbol (ie, plain numbers). This commodity will be ap-
this differs from Ledger's default commodity directive.) The commodity plied to all subsequent commodity-less amounts, or until the next D di-
and display format will be applied to all subsequent commodity-less rective. (Note, this is different from Ledger's D.)
amounts, or until the next D directive.
For compatibility/historical reasons, D also acts like a commodity di-
rective, setting the commodity's display style (for output) and decimal
mark (for parsing input). As with commodity, the amount must always be
written with a decimal mark (period or comma). If both directives are
used, commodity's style takes precedence.
The syntax is D AMOUNT. Eg:
; commodity-less amounts should be treated as dollars ; commodity-less amounts should be treated as dollars
; (and displayed with symbol on the left, thousands separators and two decimal places) ; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
D $1,000.00 D $1,000.00
1/1 1/1
a 5 ; <- commodity-less amount, becomes $1 a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
b b
As with the commodity directive, the amount must always be written with
a decimal point.
Market prices 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
@ -935,7 +945,7 @@ FILE FORMAT
account liabilities ; type:Liability account liabilities ; type:Liability
account equity ; type:Equity account equity ; type:Equity
account revenues ; type:Revenue account revenues ; type:Revenue
account expenses ; type:Expenses account expenses ; type:Expense
Account types declared with account type codes Account types declared with account type codes
Or, you can write one of those letters separated from the account name Or, you can write one of those letters separated from the account name
@ -1281,8 +1291,8 @@ FILE FORMAT
actually a posting-generating rule: actually a posting-generating rule:
= QUERY = QUERY
ACCT AMT ACCOUNT AMOUNT
ACCT [AMT] ACCOUNT [AMOUNT]
... ...
These posting-generating rules look like normal postings, except the These posting-generating rules look like normal postings, except the

2
hledger-lib/hledger_timedot.5
View File

@ -55,7 +55,7 @@ An example:
# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
2016/2/1 2016/2/1
inc:client1 .... .... .... .... .... .... inc:client1 .... .... .... .... .... ....
fos:haskell .... .. fos:haskell .... ..
biz:research . biz:research .
2016/2/2 2016/2/2

2
hledger-lib/hledger_timedot.info
View File

@ -46,7 +46,7 @@ example:
# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
2016/2/1 2016/2/1
inc:client1 .... .... .... .... .... .... inc:client1 .... .... .... .... .... ....
fos:haskell .... .. fos:haskell .... ..
biz:research . biz:research .
2016/2/2 2016/2/2

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

@ -26,19 +26,17 @@ limited data entry capability.
It is easier than hledger\[aq]s command-line interface, and sometimes It is easier than hledger\[aq]s command-line interface, and sometimes
quicker and more convenient than the web interface. quicker and more convenient than the web interface.
.PP .PP
Note hledger-ui has some different defaults (experimental):
.IP \[bu] 2
it generates rule-based transactions and postings by default (--forecast
and --auto are always on).
.IP \[bu] 2
it hides transactions dated in the future by default (change this with
--future or the F key).
.PP
Like hledger, it reads data from one or more files in hledger journal, Like hledger, it reads data from one or more files in hledger journal,
timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows, \f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]). perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
For more about this see hledger(1), hledger_journal(5) etc. For more about this see hledger(1), hledger_journal(5) etc.
.PP
Unlike hledger, hledger-ui hides all future-dated transactions by
default.
They can be revealed, along with any rule-generated periodic
transactions, by pressing the F key (or starting with --forecast) to
enable \[dq]forecast mode\[dq].
.SH OPTIONS .SH OPTIONS
.PP .PP
Note: if invoking hledger-ui as a hledger subcommand, write \f[C]--\f[R] Note: if invoking hledger-ui as a hledger subcommand, write \f[C]--\f[R]
@ -64,9 +62,6 @@ show accounts as a list (default)
.TP .TP
\f[B]\f[CB]-T --tree\f[B]\f[R] \f[B]\f[CB]-T --tree\f[B]\f[R]
show accounts as a tree show accounts as a tree
.TP
\f[B]\f[CB]--future\f[B]\f[R]
show transactions dated later than today (normally hidden)
.PP .PP
hledger input options: hledger input options:
.TP .TP
@ -155,8 +150,9 @@ most recent applicable market price, if any)
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.
.TP .TP
\f[B]\f[CB]--forecast\f[B]\f[R] \f[B]\f[CB]--forecast\f[B]\f[R]
apply periodic transaction rules to generate future transactions, to 6 generate future transactions from periodic transaction rules, for the
months from now or report end date. next 6 months or till report end date.
In hledger-ui, also make ordinary future transactions visible.
.PP .PP
When a reporting option appears more than once in the command line, the When a reporting option appears more than once in the command line, the
last one takes precedence. last one takes precedence.
@ -218,12 +214,11 @@ account depth and transaction status (see below).
\f[C]BACKSPACE\f[R] or \f[C]DELETE\f[R] removes all filters, showing all \f[C]BACKSPACE\f[R] or \f[C]DELETE\f[R] removes all filters, showing all
transactions. transactions.
.PP .PP
As mentioned above, hledger-ui shows auto-generated periodic As mentioned above, by default hledger-ui hides future transactions -
transactions, and hides future transactions (auto-generated or not) by both ordinary transactions recorded in the journal, and periodic
default. transactions generated by rule.
\f[C]F\f[R] toggles showing and hiding these future transactions. \f[C]F\f[R] toggles forecast mode, in which future/forecasted
This is similar to using a query like \f[C]date:-tomorrow\f[R], but more transactions are shown.
convenient.
(experimental) (experimental)
.PP .PP
\f[C]ESCAPE\f[R] removes all filters and jumps back to the top screen. \f[C]ESCAPE\f[R] removes all filters and jumps back to the top screen.
@ -371,9 +366,6 @@ in flat mode but this account has subaccounts which are not shown due to
a depth limit. a depth limit.
In other words, the register always shows the transactions contributing In other words, the register always shows the transactions contributing
to the balance shown on the accounts screen. to the balance shown on the accounts screen.
.PD 0
.P
.PD
Tree mode/flat mode can be toggled with \f[C]T\f[R] here also. Tree mode/flat mode can be toggled with \f[C]T\f[R] here also.
.PP .PP
\f[C]U\f[R] toggles filtering by unmarked status, showing or hiding \f[C]U\f[R] toggles filtering by unmarked status, showing or hiding

73
hledger-ui/hledger-ui.info
View File

@ -22,19 +22,17 @@ limited data entry capability. It is easier than hledger's command-line
interface, and sometimes quicker and more convenient than the web interface, and sometimes quicker and more convenient than the web
interface. interface.
Note hledger-ui has some different defaults (experimental):
* it generates rule-based transactions and postings by default
(-forecast and -auto are always on).
* it hides transactions dated in the future by default (change this
with -future or the F key).
Like hledger, it reads data from one or more files in hledger Like hledger, it reads data from one or more files in hledger
journal, timeclock, timedot, or CSV format specified with '-f', or journal, timeclock, timedot, or CSV format specified with '-f', or
'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps '$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), 'C:/Users/USER/.hledger.journal'). For more about this see hledger(1),
hledger_journal(5) etc. hledger_journal(5) etc.
Unlike hledger, hledger-ui hides all future-dated transactions by
default. They can be revealed, along with any rule-generated periodic
transactions, by pressing the F key (or starting with -forecast) to
enable "forecast mode".
* Menu: * Menu:
* OPTIONS:: * OPTIONS::
@ -75,9 +73,6 @@ the data.
'-T --tree' '-T --tree'
show accounts as a tree show accounts as a tree
'--future'
show transactions dated later than today (normally hidden)
hledger input options: hledger input options:
@ -168,8 +163,9 @@ the data.
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.
'--forecast' '--forecast'
apply periodic transaction rules to generate future transactions, generate future transactions from periodic transaction rules, for
to 6 months from now or report end date. the next 6 months or till report end date. In hledger-ui, also
make ordinary future transactions visible.
When a reporting option appears more than once in the command line, When a reporting option appears more than once in the command line,
the last one takes precedence. the last one takes precedence.
@ -229,11 +225,10 @@ some common filters like account depth and transaction status (see
below). 'BACKSPACE' or 'DELETE' removes all filters, showing all below). 'BACKSPACE' or 'DELETE' removes all filters, showing all
transactions. transactions.
As mentioned above, hledger-ui shows auto-generated periodic As mentioned above, by default hledger-ui hides future transactions -
transactions, and hides future transactions (auto-generated or not) by both ordinary transactions recorded in the journal, and periodic
default. 'F' toggles showing and hiding these future transactions. transactions generated by rule. 'F' toggles forecast mode, in which
This is similar to using a query like 'date:-tomorrow', but more future/forecasted transactions are shown. (experimental)
convenient. (experimental)
'ESCAPE' removes all filters and jumps back to the top screen. Or, 'ESCAPE' removes all filters and jumps back to the top screen. Or,
it cancels a minibuffer edit or help dialog in progress. it cancels a minibuffer edit or help dialog in progress.
@ -380,8 +375,8 @@ a check register. Each line represents one transaction and shows:
the register if the accounts screen is in tree mode, or if it's in flat the register if the accounts screen is in tree mode, or if it's in flat
mode but this account has subaccounts which are not shown due to a depth mode but this account has subaccounts which are not shown due to a depth
limit. In other words, the register always shows the transactions limit. In other words, the register always shows the transactions
contributing to the balance shown on the accounts screen. contributing to the balance shown on the accounts screen. Tree
Tree mode/flat mode can be toggled with 'T' here also. mode/flat mode can be toggled with 'T' here also.
'U' toggles filtering by unmarked status, showing or hiding unmarked 'U' toggles filtering by unmarked status, showing or hiding unmarked
transactions. Similarly, 'P' toggles pending transactions, and 'C' transactions. Similarly, 'P' toggles pending transactions, and 'C'
@ -504,26 +499,26 @@ program is restarted.
 
Tag Table: Tag Table:
Node: Top71 Node: Top71
Node: OPTIONS1520 Node: OPTIONS1476
Ref: #options1617 Ref: #options1573
Node: KEYS5053 Node: KEYS5004
Ref: #keys5148 Ref: #keys5099
Node: SCREENS9455 Node: SCREENS9375
Ref: #screens9560 Ref: #screens9480
Node: Accounts screen9650 Node: Accounts screen9570
Ref: #accounts-screen9778 Ref: #accounts-screen9698
Node: Register screen11994 Node: Register screen11914
Ref: #register-screen12149 Ref: #register-screen12069
Node: Transaction screen14145 Node: Transaction screen14066
Ref: #transaction-screen14303 Ref: #transaction-screen14224
Node: Error screen15173 Node: Error screen15094
Ref: #error-screen15295 Ref: #error-screen15216
Node: ENVIRONMENT15539 Node: ENVIRONMENT15460
Ref: #environment15653 Ref: #environment15574
Node: FILES16460 Node: FILES16381
Ref: #files16559 Ref: #files16480
Node: BUGS16772 Node: BUGS16693
Ref: #bugs16849 Ref: #bugs16770
 
End Tag Table End Tag Table

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

@ -22,25 +22,22 @@ DESCRIPTION
line interface, and sometimes quicker and more convenient than the web line interface, and sometimes quicker and more convenient than the web
interface. interface.
Note hledger-ui has some different defaults (experimental):
o it generates rule-based transactions and postings by default (--fore-
cast and --auto are always on).
o it hides transactions dated in the future by default (change this
with --future or the F key).
Like hledger, it reads data from one or more files in hledger journal, Like hledger, it reads data from one or more files in hledger journal,
timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE,
or $HOME/.hledger.journal (on windows, perhaps or $HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal). For more about this see hledger(1), C:/Users/USER/.hledger.journal). For more about this see hledger(1),
hledger_journal(5) etc. hledger_journal(5) etc.
Unlike hledger, hledger-ui hides all future-dated transactions by de-
fault. They can be revealed, along with any rule-generated periodic
transactions, by pressing the F key (or starting with --forecast) to
enable "forecast mode".
OPTIONS OPTIONS
Note: if invoking hledger-ui as a hledger subcommand, write -- before Note: if invoking hledger-ui as a hledger subcommand, write -- before
options as shown above. options as shown above.
Any QUERYARGS are interpreted as a hledger search query which filters Any QUERYARGS are interpreted as a hledger search query which filters
the data. the data.
--watch --watch
@ -53,7 +50,7 @@ OPTIONS
start in the (first) matched account's register screen start in the (first) matched account's register screen
--change --change
show period balances (changes) at startup instead of historical show period balances (changes) at startup instead of historical
balances balances
-F --flat -F --flat
@ -62,9 +59,6 @@ OPTIONS
-T --tree -T --tree
show accounts as a tree show accounts as a tree
--future
show transactions dated later than today (normally hidden)
hledger input options: hledger input options:
-f FILE --file=FILE -f FILE --file=FILE
@ -72,7 +66,7 @@ OPTIONS
$LEDGER_FILE or $HOME/.hledger.journal) $LEDGER_FILE or $HOME/.hledger.journal)
--rules-file=RULESFILE --rules-file=RULESFILE
Conversion rules file to use when reading CSV (default: Conversion rules file to use when reading CSV (default:
FILE.rules) FILE.rules)
--separator=CHAR --separator=CHAR
@ -114,7 +108,7 @@ OPTIONS
multiperiod/multicolumn report by year multiperiod/multicolumn report by year
-p --period=PERIODEXP -p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once set start date, end date, and/or reporting interval all at once
using period expressions syntax using period expressions syntax
--date2 --date2
@ -137,22 +131,23 @@ OPTIONS
hide/aggregate accounts or postings more than NUM levels deep hide/aggregate accounts or postings more than NUM levels deep
-E --empty -E --empty
show items with zero amount, normally hidden (and vice-versa in show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web) hledger-ui/hledger-web)
-B --cost -B --cost
convert amounts to their cost at transaction time (using the convert amounts to their cost at transaction time (using the
transaction price, if any) transaction price, if any)
-V --value -V --value
convert amounts to their market value on the report end date convert amounts to their market value on the report end date
(using the most recent applicable market price, if any) (using the most recent applicable market price, if any)
--auto apply automated posting rules to modify transactions. --auto apply automated posting rules to modify transactions.
--forecast --forecast
apply periodic transaction rules to generate future transac- generate future transactions from periodic transaction rules,
tions, to 6 months from now or report end date. for the next 6 months or till report end date. In hledger-ui,
also make ordinary future transactions visible.
When a reporting option appears more than once in the command line, the When a reporting option appears more than once in the command line, the
last one takes precedence. last one takes precedence.
@ -204,105 +199,104 @@ KEYS
common filters like account depth and transaction status (see below). common filters like account depth and transaction status (see below).
BACKSPACE or DELETE removes all filters, showing all transactions. BACKSPACE or DELETE removes all filters, showing all transactions.
As mentioned above, hledger-ui shows auto-generated periodic transac- As mentioned above, by default hledger-ui hides future transactions -
tions, and hides future transactions (auto-generated or not) by de- both ordinary transactions recorded in the journal, and periodic trans-
fault. F toggles showing and hiding these future transactions. This actions generated by rule. F toggles forecast mode, in which fu-
is similar to using a query like date:-tomorrow, but more convenient. ture/forecasted transactions are shown. (experimental)
(experimental)
ESCAPE removes all filters and jumps back to the top screen. Or, it ESCAPE removes all filters and jumps back to the top screen. Or, it
cancels a minibuffer edit or help dialog in progress. cancels a minibuffer edit or help dialog in progress.
CTRL-l redraws the screen and centers the selection if possible (selec- CTRL-l redraws the screen and centers the selection if possible (selec-
tions near the top won't be centered, since we don't scroll above the tions near the top won't be centered, since we don't scroll above the
top). top).
g reloads from the data file(s) and updates the current screen and any g reloads from the data file(s) and updates the current screen and any
previous screens. (With large files, this could cause a noticeable previous screens. (With large files, this could cause a noticeable
pause.) pause.)
I toggles balance assertion checking. Disabling balance assertions I toggles balance assertion checking. Disabling balance assertions
temporarily can be useful for troubleshooting. temporarily can be useful for troubleshooting.
a runs command-line hledger's add command, and reloads the updated a runs command-line hledger's add command, and reloads the updated
file. This allows some basic data entry. file. This allows some basic data entry.
A is like a, but runs the hledger-iadd tool, which provides a terminal A is like a, but runs the hledger-iadd tool, which provides a terminal
interface. This key will be available if hledger-iadd is installed in interface. This key will be available if hledger-iadd is installed in
$PATH. $PATH.
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a "" E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a ""
-nw) on the journal file. With some editors (emacs, vi), the cursor -nw) on the journal file. With some editors (emacs, vi), the cursor
will be positioned at the current transaction when invoked from the will be positioned at the current transaction when invoked from the
register and transaction screens, and at the error location (if possi- register and transaction screens, and at the error location (if possi-
ble) when invoked from the error screen. ble) when invoked from the error screen.
q quits the application. q quits the application.
Experimental: Experimental:
B toggles cost mode, showing amounts in their transaction price's com- B toggles cost mode, showing amounts in their transaction price's com-
modity (like toggling the -B/--cost flag). modity (like toggling the -B/--cost flag).
V toggles value mode, showing amounts' current market value in their V toggles value mode, showing amounts' current market value in their
default valuation commodity (like toggling the -V/--market flag). default valuation commodity (like toggling the -V/--market flag).
Note, "current market value" means the value on the report end date if Note, "current market value" means the value on the report end date if
specified, otherwise today. To see the value on another date, you can specified, otherwise today. To see the value on another date, you can
temporarily set that as the report end date. Eg: to see a transaction temporarily set that as the report end date. Eg: to see a transaction
as it was valued on july 30, go to the accounts or register screen, as it was valued on july 30, go to the accounts or register screen,
press /, and add date:-7/30 to the query. press /, and add date:-7/30 to the query.
At most one of cost or value mode can be active at once. At most one of cost or value mode can be active at once.
There's not yet any visual reminder when cost or value mode is active; There's not yet any visual reminder when cost or value mode is active;
for now pressing B B V should reliably reset to normal mode. for now pressing B B V should reliably reset to normal mode.
With --watch active, if you save an edit to the journal file while With --watch active, if you save an edit to the journal file while
viewing the transaction screen in cost or value mode, the B/V keys will viewing the transaction screen in cost or value mode, the B/V keys will
stop working. To work around, press g to force a manual reload, or stop working. To work around, press g to force a manual reload, or
exit the transaction screen. exit the transaction screen.
Additional screen-specific keys are described below. Additional screen-specific keys are described below.
SCREENS SCREENS
Accounts screen Accounts screen
This is normally the first screen displayed. It lists accounts and This is normally the first screen displayed. It lists accounts and
their balances, like hledger's balance command. By default, it shows their balances, like hledger's balance command. By default, it shows
all accounts and their latest ending balances (including the balances all accounts and their latest ending balances (including the balances
of subaccounts). if you specify a query on the command line, it shows of subaccounts). if you specify a query on the command line, it shows
just the matched accounts and the balances from matched transactions. just the matched accounts and the balances from matched transactions.
Account names are shown as a flat list by default. Press T to toggle Account names are shown as a flat list by default. Press T to toggle
tree mode. In flat mode, account balances are exclusive of subac- tree mode. In flat mode, account balances are exclusive of subac-
counts, except where subaccounts are hidden by a depth limit (see be- counts, except where subaccounts are hidden by a depth limit (see be-
low). In tree mode, all account balances are inclusive of subaccounts. low). In tree mode, all account balances are inclusive of subaccounts.
To see less detail, press a number key, 1 to 9, to set a depth limit. To see less detail, press a number key, 1 to 9, to set a depth limit.
Or use - to decrease and +/= to increase the depth limit. 0 shows even Or use - to decrease and +/= to increase the depth limit. 0 shows even
less detail, collapsing all accounts to a single total. To remove the less detail, collapsing all accounts to a single total. To remove the
depth limit, set it higher than the maximum account depth, or press ES- depth limit, set it higher than the maximum account depth, or press ES-
CAPE. CAPE.
H toggles between showing historical balances or period balances. His- H toggles between showing historical balances or period balances. His-
torical balances (the default) are ending balances at the end of the torical balances (the default) are ending balances at the end of the
report period, taking into account all transactions before that date report period, taking into account all transactions before that date
(filtered by the filter query if any), including transactions before (filtered by the filter query if any), including transactions before
the start of the report period. In other words, historical balances the start of the report period. In other words, historical balances
are what you would see on a bank statement for that account (unless are what you would see on a bank statement for that account (unless
disturbed by a filter query). Period balances ignore transactions be- disturbed by a filter query). Period balances ignore transactions be-
fore the report start date, so they show the change in balance during fore the report start date, so they show the change in balance during
the report period. They are more useful eg when viewing a time log. the report period. They are more useful eg when viewing a time log.
U toggles filtering by unmarked status, including or excluding unmarked U toggles filtering by unmarked status, including or excluding unmarked
postings in the balances. Similarly, P toggles pending postings, and C postings in the balances. Similarly, P toggles pending postings, and C
toggles cleared postings. (By default, balances include all postings; toggles cleared postings. (By default, balances include all postings;
if you activate one or two status filters, only those postings are in- if you activate one or two status filters, only those postings are in-
cluded; and if you activate all three, the filter is removed.) cluded; and if you activate all three, the filter is removed.)
R toggles real mode, in which virtual postings are ignored. R toggles real mode, in which virtual postings are ignored.
Z toggles nonzero mode, in which only accounts with nonzero balances Z toggles nonzero mode, in which only accounts with nonzero balances
are shown (hledger-ui shows zero items by default, unlike command-line are shown (hledger-ui shows zero items by default, unlike command-line
hledger). hledger).
Press right or enter to view an account's transactions register. Press right or enter to view an account's transactions register.
@ -311,27 +305,27 @@ SCREENS
This screen shows the transactions affecting a particular account, like This screen shows the transactions affecting a particular account, like
a check register. Each line represents one transaction and shows: a check register. Each line represents one transaction and shows:
o the other account(s) involved, in abbreviated form. (If there are o the other account(s) involved, in abbreviated form. (If there are
both real and virtual postings, it shows only the accounts affected both real and virtual postings, it shows only the accounts affected
by real postings.) by real postings.)
o the overall change to the current account's balance; positive for an o the overall change to the current account's balance; positive for an
inflow to this account, negative for an outflow. inflow to this account, negative for an outflow.
o the running historical total or period total for the current account, o the running historical total or period total for the current account,
after the transaction. This can be toggled with H. Similar to the after the transaction. This can be toggled with H. Similar to the
accounts screen, the historical total is affected by transactions accounts screen, the historical total is affected by transactions
(filtered by the filter query) before the report start date, while (filtered by the filter query) before the report start date, while
the period total is not. If the historical total is not disturbed by the period total is not. If the historical total is not disturbed by
a filter query, it will be the running historical balance you would a filter query, it will be the running historical balance you would
see on a bank register for the current account. see on a bank register for the current account.
Transactions affecting this account's subaccounts will be included in Transactions affecting this account's subaccounts will be included in
the register if the accounts screen is in tree mode, or if it's in flat the register if the accounts screen is in tree mode, or if it's in flat
mode but this account has subaccounts which are not shown due to a mode but this account has subaccounts which are not shown due to a
depth limit. In other words, the register always shows the transac- depth limit. In other words, the register always shows the transac-
tions contributing to the balance shown on the accounts screen. tions contributing to the balance shown on the accounts screen. Tree
Tree mode/flat mode can be toggled with T here also. mode/flat mode can be toggled with T here also.
U toggles filtering by unmarked status, showing or hiding unmarked U toggles filtering by unmarked status, showing or hiding unmarked
transactions. Similarly, P toggles pending transactions, and C toggles transactions. Similarly, P toggles pending transactions, and C toggles

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

@ -176,8 +176,9 @@ most recent applicable market price, if any)
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.
.TP .TP
\f[B]\f[CB]--forecast\f[B]\f[R] \f[B]\f[CB]--forecast\f[B]\f[R]
apply periodic transaction rules to generate future transactions, to 6 generate future transactions from periodic transaction rules, for the
months from now or report end date. next 6 months or till report end date.
In hledger-ui, also make ordinary future transactions visible.
.PP .PP
When a reporting option appears more than once in the command line, the When a reporting option appears more than once in the command line, the
last one takes precedence. last one takes precedence.

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

@ -187,8 +187,9 @@ before options, as shown in the synopsis above.
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.
'--forecast' '--forecast'
apply periodic transaction rules to generate future transactions, generate future transactions from periodic transaction rules, for
to 6 months from now or report end date. the next 6 months or till report end date. In hledger-ui, also
make ordinary future transactions visible.
When a reporting option appears more than once in the command line, When a reporting option appears more than once in the command line,
the last one takes precedence. the last one takes precedence.
@ -428,20 +429,20 @@ Tag Table:
Node: Top72 Node: Top72
Node: OPTIONS1752 Node: OPTIONS1752
Ref: #options1857 Ref: #options1857
Node: PERMISSIONS8130 Node: PERMISSIONS8201
Ref: #permissions8269 Ref: #permissions8340
Node: EDITING UPLOADING DOWNLOADING9481 Node: EDITING UPLOADING DOWNLOADING9552
Ref: #editing-uploading-downloading9662 Ref: #editing-uploading-downloading9733
Node: RELOADING10496 Node: RELOADING10567
Ref: #reloading10630 Ref: #reloading10701
Node: JSON API11063 Node: JSON API11134
Ref: #json-api11177 Ref: #json-api11248
Node: ENVIRONMENT12618 Node: ENVIRONMENT12689
Ref: #environment12734 Ref: #environment12805
Node: FILES13467 Node: FILES13538
Ref: #files13567 Ref: #files13638
Node: BUGS13780 Node: BUGS13851
Ref: #bugs13858 Ref: #bugs13929
 
End Tag Table End Tag Table

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

@ -166,8 +166,9 @@ OPTIONS
--auto apply automated posting rules to modify transactions. --auto apply automated posting rules to modify transactions.
--forecast --forecast
apply periodic transaction rules to generate future transac- generate future transactions from periodic transaction rules,
tions, to 6 months from now or report end date. for the next 6 months or till report end date. In hledger-ui,
also make ordinary future transactions visible.
When a reporting option appears more than once in the command line, the When a reporting option appears more than once in the command line, the
last one takes precedence. last one takes precedence.
@ -186,54 +187,54 @@ OPTIONS
show debug output (levels 1-9, default: 1) show debug output (levels 1-9, default: 1)
A @FILE argument will be expanded to the contents of FILE, which should A @FILE argument will be expanded to the contents of FILE, which should
contain one command line option/argument per line. (To prevent this, contain one command line option/argument per line. (To prevent this,
insert a -- argument before.) insert a -- argument before.)
By default, hledger-web starts the web app in "transient mode" and also By default, hledger-web starts the web app in "transient mode" and also
opens it in your default web browser if possible. In this mode the web opens it in your default web browser if possible. In this mode the web
app will keep running for as long as you have it open in a browser win- app will keep running for as long as you have it open in a browser win-
dow, and will exit after two minutes of inactivity (no requests and no dow, and will exit after two minutes of inactivity (no requests and no
browser windows viewing it). With --serve, it just runs the web app browser windows viewing it). With --serve, it just runs the web app
without exiting, and logs requests to the console. With --serve-api, without exiting, and logs requests to the console. With --serve-api,
only the JSON web api (see below) is served, with the usual HTML only the JSON web api (see below) is served, with the usual HTML
server-side web UI disabled. server-side web UI disabled.
By default the server listens on IP address 127.0.0.1, accessible only By default the server listens on IP address 127.0.0.1, accessible only
to local requests. You can use --host to change this, eg --host to local requests. You can use --host to change this, eg --host
0.0.0.0 to listen on all configured addresses. 0.0.0.0 to listen on all configured addresses.
Similarly, use --port to set a TCP port other than 5000, eg if you are Similarly, use --port to set a TCP port other than 5000, eg if you are
running multiple hledger-web instances. running multiple hledger-web instances.
Both of these options are ignored when --socket is used. In this case, Both of these options are ignored when --socket is used. In this case,
it creates an AF_UNIX socket file at the supplied path and uses that it creates an AF_UNIX socket file at the supplied path and uses that
for communication. This is an alternative way of running multiple for communication. This is an alternative way of running multiple
hledger-web instances behind a reverse proxy that handles authentica- hledger-web instances behind a reverse proxy that handles authentica-
tion for different users. The path can be derived in a predictable tion for different users. The path can be derived in a predictable
way, eg by using the username within the path. As an example, nginx as way, eg by using the username within the path. As an example, nginx as
reverse proxy can use the variabel $remote_user to derive a path from reverse proxy can use the variabel $remote_user to derive a path from
the username used in a HTTP basic authentication. The following the username used in a HTTP basic authentication. The following
proxy_pass directive allows access to all hledger-web instances that proxy_pass directive allows access to all hledger-web instances that
created a socket in /tmp/hledger/: created a socket in /tmp/hledger/:
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
You can use --base-url to change the protocol, hostname, port and path You can use --base-url to change the protocol, hostname, port and path
that appear in hyperlinks, useful eg for integrating hledger-web within that appear in hyperlinks, useful eg for integrating hledger-web within
a larger website. The default is http://HOST:PORT/ using the server's a larger website. The default is http://HOST:PORT/ using the server's
configured host address and TCP port (or http://HOST if PORT is 80). configured host address and TCP port (or http://HOST if PORT is 80).
With --file-url you can set a different base url for static files, eg With --file-url you can set a different base url for static files, eg
for better caching or cookie-less serving on high performance websites. for better caching or cookie-less serving on high performance websites.
PERMISSIONS PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the By default, hledger-web allows anyone who can reach it to view the
journal and to add new transactions, but not to change existing data. journal and to add new transactions, but not to change existing data.
You can restrict who can reach it by You can restrict who can reach it by
o setting the IP address it listens on (see --host above). By default o setting the IP address it listens on (see --host above). By default
it listens on 127.0.0.1, accessible to all users on the local ma- it listens on 127.0.0.1, accessible to all users on the local ma-
chine. chine.
o putting it behind an authenticating proxy, using eg apache or nginx o putting it behind an authenticating proxy, using eg apache or nginx
@ -243,44 +244,44 @@ PERMISSIONS
You can restrict what the users who reach it can do, by You can restrict what the users who reach it can do, by
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
one or more of the following capabilities. The default value is one or more of the following capabilities. The default value is
view,add: view,add:
o view - allows viewing the journal file and all included files o view - allows viewing the journal file and all included files
o add - allows adding new transactions to the main journal file o add - allows adding new transactions to the main journal file
o manage - allows editing, uploading or downloading the main or in- o manage - allows editing, uploading or downloading the main or in-
cluded files cluded files
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default. with Sandstorm's permissions. This is disabled by default.
EDITING, UPLOADING, DOWNLOADING EDITING, UPLOADING, DOWNLOADING
If you enable the manage capability mentioned above, you'll see a new If you enable the manage capability mentioned above, you'll see a new
"spanner" button to the right of the search form. Clicking this will "spanner" button to the right of the search form. Clicking this will
let you edit, upload, or download the journal file or any files it in- let you edit, upload, or download the journal file or any files it in-
cludes. cludes.
Note, unlike any other hledger command, in this mode you (or any visi- Note, unlike any other hledger command, in this mode you (or any visi-
tor) can alter or wipe the data files. tor) can alter or wipe the data files.
Normally whenever a file is changed in this way, hledger-web saves a Normally whenever a file is changed in this way, hledger-web saves a
numbered backup (assuming file permissions allow it, the disk is not numbered backup (assuming file permissions allow it, the disk is not
full, etc.) hledger-web is not aware of version control systems, cur- full, etc.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes rently; if you use one, you'll have to arrange to commit the changes
yourself (eg with a cron job or a file watcher like entr). yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This (eg with failing balance assertions) are prevented. (Probably. This
needs re-testing.) needs re-testing.)
RELOADING RELOADING
hledger-web detects changes made to the files by other means (eg if you hledger-web detects changes made to the files by other means (eg if you
edit it directly, outside of hledger-web), and it will show the new edit it directly, outside of hledger-web), and it will show the new
data when you reload the page or navigate to a new page. If a change data when you reload the page or navigate to a new page. If a change
makes a file unparseable, hledger-web will display an error message un- makes a file unparseable, hledger-web will display an error message un-
til the file has been fixed. til the file has been fixed.
@ -288,8 +289,8 @@ 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 provides some API routes that
serve JSON in response to GET requests. (And when started with serve JSON in response to GET requests. (And when started with
--serve-api, it provides only these routes.): --serve-api, it provides only these routes.):
/accountnames /accountnames
@ -299,17 +300,17 @@ JSON API
/accounts /accounts
/accounttransactions/#AccountName /accounttransactions/#AccountName
Also, you can append a new transaction to the journal by sending a PUT Also, you can append a new transaction to the journal by sending a PUT
request to /add (hledger-web only). As with the web UI's add form, 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 hledger-web must be started with the add capability for this (enabled
by default). by default).
The payload should be a valid hledger transaction as JSON, similar to The payload should be a valid hledger transaction as JSON, similar to
what you get from /transactions or /accounttransactions. what you get from /transactions or /accounttransactions.
Another way to generate test data is with the readJsonFile/writeJson- Another way to generate test data is with the readJsonFile/writeJson-
File helpers in Hledger.Web.Json, which read or write any of hledger's File helpers in Hledger.Web.Json, which read or write any of hledger's
JSON-capable types from or to a file. Eg here we write the first JSON-capable types from or to a file. Eg here we write the first
transaction of a sample journal: transaction of a sample journal:
$ make ghci-web $ make ghci-web
@ -324,21 +325,21 @@ JSON API
$ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo $ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo
By default, both the server-side HTML UI and the JSON API are served. 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 Running with --serve-api disables the former, useful if you only want
to serve the API. to serve the API.
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:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal). nal).
A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- A typical value is ~/DIR/YYYY.journal, where DIR is a version-con-
trolled finance directory and YYYY is the current year. Or ~/DIR/cur- trolled finance directory and YYYY is the current year. Or ~/DIR/cur-
rent.journal, where current.journal is a symbolic link to YYYY.journal. rent.journal, where current.journal is a symbolic link to YYYY.journal.
On Mac computers, you can set this and other environment variables in a On Mac computers, you can set this and other environment variables in a
more thorough way that also affects applications started from the GUI more thorough way that also affects applications started from the GUI
(say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en- (say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en-
vironment.plist file containing vironment.plist file containing
@ -349,13 +350,13 @@ ENVIRONMENT
To see the effect you may need to killall Dock, or reboot. To see the effect you may need to killall Dock, or reboot.
FILES FILES
Reads data from one or more files in hledger journal, timeclock, time- Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps $HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal). C:/Users/USER/.hledger.journal).
BUGS BUGS
The need to precede options with -- when invoked from hledger is awk- The need to precede options with -- when invoked from hledger is awk-
ward. ward.
-f- doesn't work (hledger-web can't read from stdin). -f- doesn't work (hledger-web can't read from stdin).
@ -369,7 +370,7 @@ BUGS
REPORTING BUGS REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list) or hledger mail list)
@ -383,7 +384,7 @@ COPYRIGHT
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) dot(5), ledger(1)

12
hledger/Hledger/Cli/Commands/Balance.txt
View File

@ -291,14 +291,12 @@ Balance changes in 2008:
(Average is rounded to the dollar here since all journal amounts are) (Average is rounded to the dollar here since all journal amounts are)
Limitations: A limitation of multicolumn balance reports: eliding of boring parent
accounts in tree mode, as in the classic balance report, is not yet
supported.
In multicolumn reports the -V/--value flag uses the market price on the The --transpose flag can be used to exchange the rows and columns of a
report end date, for all columns (not the price on each column's end multicolumn report.
date).
Eliding of boring parent accounts in tree mode, as in the classic
balance report, is not yet supported in multicolumn reports.
Budget report Budget report

3
hledger/Hledger/Cli/Commands/Print.txt
View File

@ -39,7 +39,8 @@ will not appear in the output. Similarly, when a transaction price is
implied but not written, it will not appear in the output. You can use implied but not written, it will not appear in the output. You can use
the -x/--explicit flag to make all amounts and transaction prices the -x/--explicit flag to make all amounts and transaction prices
explicit, which can be useful for troubleshooting or for making your explicit, which can be useful for troubleshooting or for making your
journal more readable and robust against data entry errors. journal more readable and robust against data entry errors. -x is also
implied by using any of -B,-V,-X,--value.
Note, -x/--explicit will cause postings with a multi-commodity amount Note, -x/--explicit will cause postings with a multi-commodity amount
(these can arise when a multi-commodity transaction has an implicit (these can arise when a multi-commodity transaction has an implicit

67
hledger/hledger.1
View File

@ -179,7 +179,7 @@ like this:
assets:bank:checking $1000 = $1000 assets:bank:checking $1000 = $1000
assets:bank:savings $2000 = $2000 assets:bank:savings $2000 = $2000
assets:cash $100 = $100 assets:cash $100 = $100
liabilities:creditcard $-50 = $-$50 liabilities:creditcard $-50 = $-50
equity:opening/closing balances equity:opening/closing balances
\f[R] \f[R]
.fi .fi
@ -628,8 +628,9 @@ most recent applicable market price, if any)
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.
.TP .TP
\f[B]\f[CB]--forecast\f[B]\f[R] \f[B]\f[CB]--forecast\f[B]\f[R]
apply periodic transaction rules to generate future transactions, to 6 generate future transactions from periodic transaction rules, for the
months from now or report end date. next 6 months or till report end date.
In hledger-ui, also make ordinary future transactions visible.
.PP .PP
When a reporting option appears more than once in the command line, the When a reporting option appears more than once in the command line, the
last one takes precedence. last one takes precedence.
@ -1694,10 +1695,11 @@ more general \f[C]--value\f[R] option:
.IP .IP
.nf .nf
\f[C] \f[C]
--value=TYPE[,COMM] TYPE is cost, end, now or YYYY-MM-DD. --value=TYPE[,COMM] TYPE is cost, then, end, now or YYYY-MM-DD.
COMM is an optional commodity symbol. COMM is an optional commodity symbol.
Shows amounts converted to: Shows amounts converted to:
- cost commodity using transaction prices (then optionally to COMM using market prices at period end(s)) - cost commodity using transaction prices (then optionally to COMM using market prices at period end(s))
- default valuation commodity (or COMM) using market prices at posting dates
- default valuation commodity (or COMM) using market prices at period end(s) - default valuation commodity (or COMM) using market prices at period end(s)
- default valuation commodity (or COMM) using current market prices - default valuation commodity (or COMM) using current market prices
- default valuation commodity (or COMM) using market prices at some date - default valuation commodity (or COMM) using market prices at some date
@ -1710,6 +1712,11 @@ value\[dq] plus a valuation date:
\f[B]\f[CB]--value=cost\f[B]\f[R] \f[B]\f[CB]--value=cost\f[B]\f[R]
Convert amounts to cost, using the prices recorded in transactions. Convert amounts to cost, using the prices recorded in transactions.
.TP .TP
\f[B]\f[CB]--value=then\f[B]\f[R]
Convert amounts to their value in a default valuation commodity, using
market prices on each posting\[aq]s date.
This is currently supported only by the print and register commands.
.TP
\f[B]\f[CB]--value=end\f[B]\f[R] \f[B]\f[CB]--value=end\f[B]\f[R]
Convert amounts to their value in a default valuation commodity, using Convert amounts to their value in a default valuation commodity, using
market prices on the last day of the report period (or if unspecified, market prices on the last day of the report period (or if unspecified,
@ -1905,7 +1912,7 @@ Related: #329, #1083.
.PP .PP
.TS .TS
tab(@); tab(@);
lw(14.4n) lw(13.8n) lw(14.6n) lw(15.2n) lw(12.0n). lw(11.7n) lw(11.2n) lw(11.9n) lw(13.1n) lw(12.4n) lw(9.8n).
T{ T{
Report type Report type
T}@T{ T}@T{
@ -1913,6 +1920,8 @@ T}@T{
T}@T{ T}@T{
\f[C]-V\f[R], \f[C]-X\f[R] \f[C]-V\f[R], \f[C]-X\f[R]
T}@T{ T}@T{
\f[C]--value=then\f[R]
T}@T{
\f[C]--value=end\f[R] \f[C]--value=end\f[R]
T}@T{ T}@T{
\f[C]--value=DATE\f[R], \f[C]--value=now\f[R] \f[C]--value=DATE\f[R], \f[C]--value=now\f[R]
@ -1924,6 +1933,7 @@ T}@T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{
T} T}
T{ T{
posting amounts posting amounts
@ -1932,6 +1942,8 @@ cost
T}@T{ T}@T{
value at report end or today value at report end or today
T}@T{ T}@T{
value at posting date
T}@T{
value at report or journal end value at report or journal end
T}@T{ T}@T{
value at DATE/today value at DATE/today
@ -1946,12 +1958,15 @@ T}@T{
unchanged unchanged
T}@T{ T}@T{
unchanged unchanged
T}@T{
unchanged
T} T}
T{ T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{
T} T}
T{ T{
\f[B]register\f[R] \f[B]register\f[R]
@ -1959,6 +1974,7 @@ T}@T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{
T} T}
T{ T{
starting balance (with -H) starting balance (with -H)
@ -1967,6 +1983,8 @@ cost
T}@T{ T}@T{
value at day before report or journal start value at day before report or journal start
T}@T{ T}@T{
not supported
T}@T{
value at day before report or journal start value at day before report or journal start
T}@T{ T}@T{
value at DATE/today value at DATE/today
@ -1978,6 +1996,8 @@ cost
T}@T{ T}@T{
value at report end or today value at report end or today
T}@T{ T}@T{
value at posting date
T}@T{
value at report or journal end value at report or journal end
T}@T{ T}@T{
value at DATE/today value at DATE/today
@ -1989,6 +2009,8 @@ summarised cost
T}@T{ T}@T{
value at period ends value at period ends
T}@T{ T}@T{
sum of postings in interval, valued at interval start
T}@T{
value at period ends value at period ends
T}@T{ T}@T{
value at DATE/today value at DATE/today
@ -2003,12 +2025,15 @@ T}@T{
sum/average of displayed values sum/average of displayed values
T}@T{ T}@T{
sum/average of displayed values sum/average of displayed values
T}@T{
sum/average of displayed values
T} T}
T{ T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{
T} T}
T{ T{
\f[B]balance (bs, bse, cf, is..)\f[R] \f[B]balance (bs, bse, cf, is..)\f[R]
@ -2016,6 +2041,7 @@ T}@T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{
T} T}
T{ T{
balances (no report interval) balances (no report interval)
@ -2024,6 +2050,8 @@ sums of costs
T}@T{ T}@T{
value at report end or today of sums of postings value at report end or today of sums of postings
T}@T{ T}@T{
not supported
T}@T{
value at report or journal end of sums of postings value at report or journal end of sums of postings
T}@T{ T}@T{
value at DATE/today of sums of postings value at DATE/today of sums of postings
@ -2035,6 +2063,8 @@ sums of costs
T}@T{ T}@T{
value at period ends of sums of postings value at period ends of sums of postings
T}@T{ T}@T{
not supported
T}@T{
value at period ends of sums of postings value at period ends of sums of postings
T}@T{ T}@T{
value at DATE/today of sums of postings value at DATE/today of sums of postings
@ -2046,6 +2076,8 @@ sums of costs of postings before report start
T}@T{ T}@T{
sums of postings before report start sums of postings before report start
T}@T{ T}@T{
not supported
T}@T{
sums of postings before report start sums of postings before report start
T}@T{ T}@T{
sums of postings before report start sums of postings before report start
@ -2057,6 +2089,8 @@ like balances
T}@T{ T}@T{
like balances like balances
T}@T{ T}@T{
not supported
T}@T{
like balances like balances
T}@T{ T}@T{
like balances like balances
@ -2068,6 +2102,8 @@ sum of displayed values
T}@T{ T}@T{
sum of displayed values sum of displayed values
T}@T{ T}@T{
not supported
T}@T{
sum of displayed values sum of displayed values
T}@T{ T}@T{
sum of displayed values sum of displayed values
@ -2079,6 +2115,8 @@ sums/averages of displayed values
T}@T{ T}@T{
sums/averages of displayed values sums/averages of displayed values
T}@T{ T}@T{
not supported
T}@T{
sums/averages of displayed values sums/averages of displayed values
T}@T{ T}@T{
sums/averages of displayed values sums/averages of displayed values
@ -2090,6 +2128,8 @@ sums of displayed values
T}@T{ T}@T{
sums of displayed values sums of displayed values
T}@T{ T}@T{
not supported
T}@T{
sums of displayed values sums of displayed values
T}@T{ T}@T{
sums of displayed values sums of displayed values
@ -2101,6 +2141,8 @@ sum/average of column totals
T}@T{ T}@T{
sum/average of column totals sum/average of column totals
T}@T{ T}@T{
not supported
T}@T{
sum/average of column totals sum/average of column totals
T}@T{ T}@T{
sum/average of column totals sum/average of column totals
@ -2110,6 +2152,7 @@ T}@T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{ T}@T{
T}@T{
T} T}
.TE .TE
.PP .PP
@ -2668,14 +2711,12 @@ Balance changes in 2008:
\f[R] \f[R]
.fi .fi
.PP .PP
Limitations: A limitation of multicolumn balance reports: eliding of boring parent
accounts in tree mode, as in the classic balance report, is not yet
supported.
.PP .PP
In multicolumn reports the \f[C]-V/--value\f[R] flag uses the market The \f[C]--transpose\f[R] flag can be used to exchange the rows and
price on the report end date, for all columns (not the price on each columns of a multicolumn report.
column\[aq]s end date).
.PP
Eliding of boring parent accounts in tree mode, as in the classic
balance report, is not yet supported in multicolumn reports.
.SS Budget report .SS Budget report
.PP .PP
With \f[C]--budget\f[R], extra columns are displayed showing budget With \f[C]--budget\f[R], extra columns are displayed showing budget
@ -3521,6 +3562,8 @@ You can use the \f[C]-x\f[R]/\f[C]--explicit\f[R] flag to make all
amounts and transaction prices explicit, which can be useful for amounts and transaction prices explicit, which can be useful for
troubleshooting or for making your journal more readable and robust troubleshooting or for making your journal more readable and robust
against data entry errors. against data entry errors.
\f[C]-x\f[R] is also implied by using any of
\f[C]-B\f[R],\f[C]-V\f[R],\f[C]-X\f[R],\f[C]--value\f[R].
.PP .PP
Note, \f[C]-x\f[R]/\f[C]--explicit\f[R] will cause postings with a Note, \f[C]-x\f[R]/\f[C]--explicit\f[R] will cause postings with a
multi-commodity amount (these can arise when a multi-commodity multi-commodity amount (these can arise when a multi-commodity

493
hledger/hledger.info
View File

@ -186,7 +186,7 @@ balances on this date. Here are two ways to do it:
assets:bank:checking $1000 = $1000 assets:bank:checking $1000 = $1000
assets:bank:savings $2000 = $2000 assets:bank:savings $2000 = $2000
assets:cash $100 = $100 assets:cash $100 = $100
liabilities:creditcard $-50 = $-$50 liabilities:creditcard $-50 = $-50
equity:opening/closing balances equity:opening/closing balances
These are start-of-day balances, ie whatever was in the account at These are start-of-day balances, ie whatever was in the account at
@ -621,8 +621,9 @@ by most hledger commands, run 'hledger -h'.
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.
'--forecast' '--forecast'
apply periodic transaction rules to generate future transactions, generate future transactions from periodic transaction rules, for
to 6 months from now or report end date. the next 6 months or till report end date. In hledger-ui, also
make ordinary future transactions visible.
When a reporting option appears more than once in the command line, When a reporting option appears more than once in the command line,
the last one takes precedence. the last one takes precedence.
@ -1415,10 +1416,11 @@ _(experimental, added 201905)_
'-B', '-V' and '-X' are special cases of the more general '--value' '-B', '-V' and '-X' are special cases of the more general '--value'
option: option:
--value=TYPE[,COMM] TYPE is cost, end, now or YYYY-MM-DD. --value=TYPE[,COMM] TYPE is cost, then, end, now or YYYY-MM-DD.
COMM is an optional commodity symbol. COMM is an optional commodity symbol.
Shows amounts converted to: Shows amounts converted to:
- cost commodity using transaction prices (then optionally to COMM using market prices at period end(s)) - cost commodity using transaction prices (then optionally to COMM using market prices at period end(s))
- default valuation commodity (or COMM) using market prices at posting dates
- default valuation commodity (or COMM) using market prices at period end(s) - default valuation commodity (or COMM) using market prices at period end(s)
- default valuation commodity (or COMM) using current market prices - default valuation commodity (or COMM) using current market prices
- default valuation commodity (or COMM) using market prices at some date - default valuation commodity (or COMM) using market prices at some date
@ -1429,6 +1431,11 @@ a valuation date:
'--value=cost' '--value=cost'
Convert amounts to cost, using the prices recorded in transactions. Convert amounts to cost, using the prices recorded in transactions.
'--value=then'
Convert amounts to their value in a default valuation commodity,
using market prices on each posting's date. This is currently
supported only by the print and register commands.
'--value=end' '--value=end'
Convert amounts to their value in a default valuation commodity, Convert amounts to their value in a default valuation commodity,
@ -1582,67 +1589,76 @@ troubleshooting or reporting bugs. See also the definitions and notes
below. If you find problems, please report them, ideally with a below. If you find problems, please report them, ideally with a
reproducible example. Related: #329, #1083. reproducible example. Related: #329, #1083.
Report type '-B', '-V', '-X' '--value=end' '--value=DATE', Report '-B', '-V', '-X' '--value=then' '--value=end' '--value=DATE',
'--value=cost' '--value=now' type '--value=cost' '--value=now'
----------------------------------------------------------------------------- -------------------------------------------------------------------------------
*print* *print*
posting cost value at value at value at posting cost value at value at value at value at
amounts report end or report or DATE/today amounts report end posting date report or DATE/today
today journal end or today journal end
balance unchanged unchanged unchanged unchanged balance unchanged unchanged unchanged unchanged unchanged
assertions / assertions
/
assignments assignments
*register* *register*
starting cost value at day value at day value at starting cost value at not value at value at
balance (with before report before report DATE/today balance day before supported day before DATE/today
-H) or journal or journal (with -H) report or report or
start start journal journal
posting cost value at value at value at start start
amounts (no report end or report or DATE/today posting cost value at value at value at value at
report today journal end amounts report end posting date report or DATE/today
(no report or today journal end
interval) interval)
summary summarised value at value at value at summary summarised value at sum of value at value at
posting cost period ends period ends DATE/today posting cost period postings in period ends DATE/today
amounts (with amounts ends interval,
report (with valued at
interval) report interval
running sum/average sum/average sum/average of sum/average interval) start
total/average of displayed of displayed displayed of running sum/average sum/average sum/average sum/average sum/average
values values values displayed total/averageof of of displayed of of
values displayed displayed values displayed displayed
*balance (bs, values values values values
bse, cf, *balance
is..)* (bs, bse,
balances (no sums of value at value at value at cf, is..)*
report costs report end or report or DATE/today balances sums of value at not value at value at
interval) today of sums journal end of of sums of (no report costs report end supported report or DATE/today
of postings sums of postings interval) or today journal end of sums
postings of sums of of sums of of
balances sums of value at value at value at postings postings postings
(with report costs period ends period ends of DATE/today balances sums of value at not value at value at
interval) of sums of sums of of sums of (with costs period supported period ends DATE/today
postings postings postings report ends of of sums of of sums
starting sums of sums of sums of sums of interval) sums of postings of
balances costs of postings postings postings postings postings
(with report postings before report before report before starting sums of sums of not sums of sums of
interval and before start start report balances costs of postings supported postings postings
-H) report start start (with postings before before before
budget like like balances like balances like report before report report report
amounts with balances balances interval report start start start
and -H) start
budget like like not like like
amounts balances balances supported balances balances
with
-budget -budget
grand total sum of sum of sum of sum of grand sum of sum of not sum of sum of
(no report displayed displayed displayed displayed total (no displayed displayed supported displayed displayed
interval) values values values values report values values values values
row sums/averages sums/averages sums/averages sums/averages interval)
totals/averages of displayed of displayed of displayed of row sums/averagessums/averagesnot sums/averages sums/averages
(with report values values values displayed totals/averagesof of supported of of
interval) values (with displayed displayed displayed displayed
column totals sums of sums of sums of sums of report values values values values
displayed displayed displayed displayed interval)
values values values values column sums of sums of not sums of sums of
grand sum/average sum/average sum/average of sum/average totals displayed displayed supported displayed displayed
total/average of column of column column totals of column values values values values
totals totals totals grand sum/average sum/average not sum/average sum/average
total/averageof column of column supported of column of
totals totals totals column
totals
*Additional notes* *Additional notes*
@ -2200,14 +2216,12 @@ Balance changes in 2008:
(Average is rounded to the dollar here since all journal amounts are) (Average is rounded to the dollar here since all journal amounts are)
Limitations: A limitation of multicolumn balance reports: eliding of boring parent
accounts in tree mode, as in the classic balance report, is not yet
supported.
In multicolumn reports the '-V/--value' flag uses the market price on The '--transpose' flag can be used to exchange the rows and columns
the report end date, for all columns (not the price on each column's end of a multicolumn report.
date).
Eliding of boring parent accounts in tree mode, as in the classic
balance report, is not yet supported in multicolumn reports.
 
File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance
@ -2984,7 +2998,8 @@ will not appear in the output. Similarly, when a transaction price is
implied but not written, it will not appear in the output. You can use implied but not written, it will not appear in the output. You can use
the '-x'/'--explicit' flag to make all amounts and transaction prices the '-x'/'--explicit' flag to make all amounts and transaction prices
explicit, which can be useful for troubleshooting or for making your explicit, which can be useful for troubleshooting or for making your
journal more readable and robust against data entry errors. journal more readable and robust against data entry errors. '-x' is
also implied by using any of '-B','-V','-X','--value'.
Note, '-x'/'--explicit' will cause postings with a multi-commodity Note, '-x'/'--explicit' will cause postings with a multi-commodity
amount (these can arise when a multi-commodity transaction has an amount (these can arise when a multi-commodity transaction has an
@ -3678,177 +3693,177 @@ Node: Starting a journal file4414
Ref: #starting-a-journal-file4612 Ref: #starting-a-journal-file4612
Node: Setting opening balances5800 Node: Setting opening balances5800
Ref: #setting-opening-balances5996 Ref: #setting-opening-balances5996
Node: Recording transactions9138 Node: Recording transactions9137
Ref: #recording-transactions9318 Ref: #recording-transactions9317
Node: Reconciling9874 Node: Reconciling9873
Ref: #reconciling10017 Ref: #reconciling10016
Node: Reporting12274 Node: Reporting12273
Ref: #reporting12414 Ref: #reporting12413
Node: Migrating to a new file16413 Node: Migrating to a new file16412
Ref: #migrating-to-a-new-file16561 Ref: #migrating-to-a-new-file16560
Node: OPTIONS16860 Node: OPTIONS16859
Ref: #options16967 Ref: #options16966
Node: General options17337 Node: General options17336
Ref: #general-options17462 Ref: #general-options17461
Node: Command options20161 Node: Command options20231
Ref: #command-options20312 Ref: #command-options20382
Node: Command arguments20710 Node: Command arguments20780
Ref: #command-arguments20857 Ref: #command-arguments20927
Node: Queries21737 Node: Queries21807
Ref: #queries21892 Ref: #queries21962
Node: Special characters in arguments and queries25854 Node: Special characters in arguments and queries25924
Ref: #special-characters-in-arguments-and-queries26082 Ref: #special-characters-in-arguments-and-queries26152
Node: More escaping26533 Node: More escaping26603
Ref: #more-escaping26695 Ref: #more-escaping26765
Node: Even more escaping26991 Node: Even more escaping27061
Ref: #even-more-escaping27185 Ref: #even-more-escaping27255
Node: Less escaping27856 Node: Less escaping27926
Ref: #less-escaping28018 Ref: #less-escaping28088
Node: Unicode characters28263 Node: Unicode characters28333
Ref: #unicode-characters28445 Ref: #unicode-characters28515
Node: Input files29857 Node: Input files29927
Ref: #input-files30000 Ref: #input-files30070
Node: Output destination31929 Node: Output destination31999
Ref: #output-destination32081 Ref: #output-destination32151
Node: Output format32364 Node: Output format32434
Ref: #output-format32514 Ref: #output-format32584
Node: Regular expressions32899 Node: Regular expressions32969
Ref: #regular-expressions33056 Ref: #regular-expressions33126
Node: Smart dates34417 Node: Smart dates34487
Ref: #smart-dates34568 Ref: #smart-dates34638
Node: Report start & end date35929 Node: Report start & end date35999
Ref: #report-start-end-date36101 Ref: #report-start-end-date36171
Node: Report intervals37539 Node: Report intervals37609
Ref: #report-intervals37704 Ref: #report-intervals37774
Node: Period expressions38094 Node: Period expressions38164
Ref: #period-expressions38254 Ref: #period-expressions38324
Node: Depth limiting42380 Node: Depth limiting42450
Ref: #depth-limiting42524 Ref: #depth-limiting42594
Node: Pivoting42866 Node: Pivoting42936
Ref: #pivoting42989 Ref: #pivoting43059
Node: Valuation44665 Node: Valuation44735
Ref: #valuation44767 Ref: #valuation44837
Node: -B Cost44947 Node: -B Cost45017
Ref: #b-cost45058 Ref: #b-cost45128
Node: -V Market value45256 Node: -V Market value45326
Ref: #v-market-value45430 Ref: #v-market-value45500
Node: -X Market value in specified commodity46862 Node: -X Market value in specified commodity46932
Ref: #x-market-value-in-specified-commodity47101 Ref: #x-market-value-in-specified-commodity47171
Node: --value Flexible valuation47277 Node: --value Flexible valuation47347
Ref: #value-flexible-valuation47503 Ref: #value-flexible-valuation47573
Node: Effect of --value on reports51693 Node: Effect of --value on reports52078
Ref: #effect-of---value-on-reports51909 Ref: #effect-of---value-on-reports52294
Node: Combining -B -V -X --value56840 Node: Combining -B -V -X --value57840
Ref: #combining--b--v--x---value57023 Ref: #combining--b--v--x---value58023
Node: COMMANDS57059 Node: COMMANDS58059
Ref: #commands57167 Ref: #commands58167
Node: accounts58251 Node: accounts59251
Ref: #accounts58349 Ref: #accounts59349
Node: activity59048 Node: activity60048
Ref: #activity59158 Ref: #activity60158
Node: add59541 Node: add60541
Ref: #add59640 Ref: #add60640
Node: balance62379 Node: balance63379
Ref: #balance62490 Ref: #balance63490
Node: Classic balance report63948 Node: Classic balance report64948
Ref: #classic-balance-report64121 Ref: #classic-balance-report65121
Node: Customising the classic balance report65490 Node: Customising the classic balance report66490
Ref: #customising-the-classic-balance-report65718 Ref: #customising-the-classic-balance-report66718
Node: Colour support67794 Node: Colour support68794
Ref: #colour-support67961 Ref: #colour-support68961
Node: Flat mode68134 Node: Flat mode69134
Ref: #flat-mode68282 Ref: #flat-mode69282
Node: Depth limited balance reports68695 Node: Depth limited balance reports69695
Ref: #depth-limited-balance-reports68880 Ref: #depth-limited-balance-reports69880
Node: Percentages69336 Node: Percentages70336
Ref: #percentages69502 Ref: #percentages70502
Node: Multicolumn balance report70639 Node: Multicolumn balance report71639
Ref: #multicolumn-balance-report70819 Ref: #multicolumn-balance-report71819
Node: Budget report76133 Node: Budget report77081
Ref: #budget-report76276 Ref: #budget-report77224
Node: Nested budgets81478 Node: Nested budgets82426
Ref: #nested-budgets81590 Ref: #nested-budgets82538
Ref: #output-format-185071 Ref: #output-format-186019
Node: balancesheet85149 Node: balancesheet86097
Ref: #balancesheet85285 Ref: #balancesheet86233
Node: balancesheetequity86668 Node: balancesheetequity87616
Ref: #balancesheetequity86817 Ref: #balancesheetequity87765
Node: cashflow87378 Node: cashflow88326
Ref: #cashflow87506 Ref: #cashflow88454
Node: check-dates88602 Node: check-dates89550
Ref: #check-dates88729 Ref: #check-dates89677
Node: check-dupes89008 Node: check-dupes89956
Ref: #check-dupes89132 Ref: #check-dupes90080
Node: close89425 Node: close90373
Ref: #close89539 Ref: #close90487
Node: close usage91061 Node: close usage92009
Ref: #close-usage91154 Ref: #close-usage92102
Node: commodities93967 Node: commodities94915
Ref: #commodities94094 Ref: #commodities95042
Node: descriptions94176 Node: descriptions95124
Ref: #descriptions94304 Ref: #descriptions95252
Node: diff94485 Node: diff95433
Ref: #diff94591 Ref: #diff95539
Node: files95638 Node: files96586
Ref: #files95738 Ref: #files96686
Node: help95885 Node: help96833
Ref: #help95985 Ref: #help96933
Node: import97066 Node: import98014
Ref: #import97180 Ref: #import98128
Node: Importing balance assignments98073 Node: Importing balance assignments99021
Ref: #importing-balance-assignments98221 Ref: #importing-balance-assignments99169
Node: incomestatement98870 Node: incomestatement99818
Ref: #incomestatement99003 Ref: #incomestatement99951
Node: notes100407 Node: notes101355
Ref: #notes100520 Ref: #notes101468
Node: payees100646 Node: payees101594
Ref: #payees100752 Ref: #payees101700
Node: prices100910 Node: prices101858
Ref: #prices101016 Ref: #prices101964
Node: print101357 Node: print102305
Ref: #print101467 Ref: #print102415
Node: print-unique106111 Node: print-unique107123
Ref: #print-unique106237 Ref: #print-unique107249
Node: register106522 Node: register107534
Ref: #register106649 Ref: #register107661
Node: Custom register output110821 Node: Custom register output111833
Ref: #custom-register-output110950 Ref: #custom-register-output111962
Node: register-match112212 Node: register-match113224
Ref: #register-match112346 Ref: #register-match113358
Node: rewrite112697 Node: rewrite113709
Ref: #rewrite112812 Ref: #rewrite113824
Node: Re-write rules in a file114667 Node: Re-write rules in a file115679
Ref: #re-write-rules-in-a-file114801 Ref: #re-write-rules-in-a-file115813
Node: Diff output format116011 Node: Diff output format117023
Ref: #diff-output-format116180 Ref: #diff-output-format117192
Node: rewrite vs print --auto117272 Node: rewrite vs print --auto118284
Ref: #rewrite-vs.-print---auto117451 Ref: #rewrite-vs.-print---auto118463
Node: roi118007 Node: roi119019
Ref: #roi118105 Ref: #roi119117
Node: stats119117 Node: stats120129
Ref: #stats119216 Ref: #stats120228
Node: tags120004 Node: tags121016
Ref: #tags120102 Ref: #tags121114
Node: test120396 Node: test121408
Ref: #test120504 Ref: #test121516
Node: Add-on Commands121251 Node: Add-on Commands122263
Ref: #add-on-commands121368 Ref: #add-on-commands122380
Node: ui122711 Node: ui123723
Ref: #ui122799 Ref: #ui123811
Node: web122853 Node: web123865
Ref: #web122956 Ref: #web123968
Node: iadd123072 Node: iadd124084
Ref: #iadd123183 Ref: #iadd124195
Node: interest123265 Node: interest124277
Ref: #interest123372 Ref: #interest124384
Node: ENVIRONMENT123612 Node: ENVIRONMENT124624
Ref: #environment123724 Ref: #environment124736
Node: FILES124553 Node: FILES125565
Ref: #files-1124656 Ref: #files-1125668
Node: LIMITATIONS124869 Node: LIMITATIONS125881
Ref: #limitations124988 Ref: #limitations126000
Node: TROUBLESHOOTING125730 Node: TROUBLESHOOTING126742
Ref: #troubleshooting125843 Ref: #troubleshooting126855
 
End Tag Table End Tag Table

713
hledger/hledger.txt
View File

File diff suppressed because it is too large Load Diff