From 696ec4998b997bebe4d8394989dede0e1420481f Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 22 Feb 2020 11:33:50 -0800 Subject: [PATCH] ;doc: regen help/manuals [ci skip] --- hledger-lib/hledger_csv.5 | 12 +- hledger-lib/hledger_csv.info | 116 ++-- hledger-lib/hledger_journal.5 | 79 +-- hledger-lib/hledger_journal.info | 261 +++++---- hledger-lib/hledger_journal.txt | 230 ++++---- hledger-lib/hledger_timedot.5 | 2 +- hledger-lib/hledger_timedot.info | 2 +- hledger-ui/hledger-ui.1 | 36 +- hledger-ui/hledger-ui.info | 73 ++- hledger-ui/hledger-ui.txt | 154 +++-- hledger-web/hledger-web.1 | 5 +- hledger-web/hledger-web.info | 33 +- hledger-web/hledger-web.txt | 123 ++-- hledger/Hledger/Cli/Commands/Balance.txt | 12 +- hledger/Hledger/Cli/Commands/Print.txt | 3 +- hledger/hledger.1 | 67 ++- hledger/hledger.info | 493 ++++++++-------- hledger/hledger.txt | 713 ++++++++++++----------- 18 files changed, 1246 insertions(+), 1168 deletions(-) diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index d5d04de0b..a28d80a88 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -156,7 +156,7 @@ fields date, description, amount-out, amount-in, balance # We generate balance assertions by assigning to \[dq]balance\[dq] # 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 # # - 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. # 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]) if ,\[rs]$[1-9][.0-9]+(,[\[ha],]*){1}$ account3 expenses:fees @@ -298,11 +298,11 @@ date-format %-m/%-d/%Y if In Progress Temporary Hold -Update to +Update to skip # add more fields to the description -description %description_ %itemtitle +description %description_ %itemtitle # save some other fields as tags 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 -# 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. -if +if Bank Account Bank Deposit to PP Account description %type for %referencetxnid %itemtitle diff --git a/hledger-lib/hledger_csv.info b/hledger-lib/hledger_csv.info index aa0430a14..aa0c97535 100644 --- a/hledger-lib/hledger_csv.info +++ b/hledger-lib/hledger_csv.info @@ -118,7 +118,7 @@ fields date, description, amount-out, amount-in, balance # We generate balance assertions by assigning to "balance" # 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 # # - 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. # 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") if ,\$[1-9][.0-9]+(,[^,]*){1}$ account3 expenses:fees @@ -245,11 +245,11 @@ date-format %-m/%-d/%Y if In Progress Temporary Hold -Update to +Update to skip # add more fields to the description -description %description_ %itemtitle +description %description_ %itemtitle # save some other fields as tags 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 -# 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. -if +if Bank Account Bank Deposit to PP Account description %type for %referencetxnid %itemtitle @@ -974,58 +974,58 @@ Node: Basic2413 Ref: #basic2513 Node: Bank of Ireland3055 Ref: #bank-of-ireland3190 -Node: Amazon4653 -Ref: #amazon4771 -Node: Paypal6704 -Ref: #paypal6798 -Node: CSV RULES14681 -Ref: #csv-rules14790 -Node: skip15066 -Ref: #skip15159 -Node: fields15534 -Ref: #fields15656 -Node: Transaction field names16821 -Ref: #transaction-field-names16981 -Node: Posting field names17092 -Ref: #posting-field-names17244 -Node: field assignment18535 -Ref: #field-assignment18678 -Node: separator19496 -Ref: #separator19625 -Node: if20036 -Ref: #if20138 -Node: end21854 -Ref: #end21960 -Node: date-format22184 -Ref: #date-format22316 -Node: newest-first23065 -Ref: #newest-first23203 -Node: include23886 -Ref: #include24015 -Node: balance-type24459 -Ref: #balance-type24579 -Node: TIPS25279 -Ref: #tips25361 -Node: Rapid feedback25617 -Ref: #rapid-feedback25734 -Node: Valid CSV26194 -Ref: #valid-csv26324 -Node: File Extension26516 -Ref: #file-extension26668 -Node: Reading multiple CSV files27078 -Ref: #reading-multiple-csv-files27263 -Node: Valid transactions27504 -Ref: #valid-transactions27682 -Node: Deduplicating importing28310 -Ref: #deduplicating-importing28489 -Node: Setting amounts29522 -Ref: #setting-amounts29691 -Node: Setting currency/commodity30677 -Ref: #setting-currencycommodity30869 -Node: Referencing other fields31672 -Ref: #referencing-other-fields31872 -Node: How CSV rules are evaluated32769 -Ref: #how-csv-rules-are-evaluated32942 +Node: Amazon4652 +Ref: #amazon4770 +Node: Paypal6702 +Ref: #paypal6796 +Node: CSV RULES14675 +Ref: #csv-rules14784 +Node: skip15060 +Ref: #skip15153 +Node: fields15528 +Ref: #fields15650 +Node: Transaction field names16815 +Ref: #transaction-field-names16975 +Node: Posting field names17086 +Ref: #posting-field-names17238 +Node: field assignment18529 +Ref: #field-assignment18672 +Node: separator19490 +Ref: #separator19619 +Node: if20030 +Ref: #if20132 +Node: end21848 +Ref: #end21954 +Node: date-format22178 +Ref: #date-format22310 +Node: newest-first23059 +Ref: #newest-first23197 +Node: include23880 +Ref: #include24009 +Node: balance-type24453 +Ref: #balance-type24573 +Node: TIPS25273 +Ref: #tips25355 +Node: Rapid feedback25611 +Ref: #rapid-feedback25728 +Node: Valid CSV26188 +Ref: #valid-csv26318 +Node: File Extension26510 +Ref: #file-extension26662 +Node: Reading multiple CSV files27072 +Ref: #reading-multiple-csv-files27257 +Node: Valid transactions27498 +Ref: #valid-transactions27676 +Node: Deduplicating importing28304 +Ref: #deduplicating-importing28483 +Node: Setting amounts29516 +Ref: #setting-amounts29685 +Node: Setting currency/commodity30671 +Ref: #setting-currencycommodity30863 +Node: Referencing other fields31666 +Ref: #referencing-other-fields31866 +Node: How CSV rules are evaluated32763 +Ref: #how-csv-rules-are-evaluated32936  End Tag Table diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index ea1c571b9..2c31428d3 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -443,7 +443,7 @@ Eg: assets:cash $-10 ; <- these balance expenses:food $7 ; <- expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance + [assets:checking:budget:food] $-10 ; <- and these balance [assets:checking:available] $10 ; <- (something:else) $5 ; <- not required to balance \f[R] @@ -573,15 +573,15 @@ commodity INR 9,99,99,999.00 commodity 1 000 000.9455 \f[R] .fi -.SS Amount display format +.SS Amount display style .PP For each commodity, hledger chooses a consistent format to use when displaying amounts. (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 -If there is a commodity directive for the commodity, that format is used -(see examples above). +If there is a commodity directive (or default commodity directive) for +the commodity, that format is used (see examples above). .IP \[bu] 2 Otherwise the format of the first posting amount in that commodity seen 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 (like \f[C]$1000.00\f[R]). .PP -Price amounts, and amounts in \f[C]D\f[R] directives don\[aq]t affect -the amount display format directly, but occasionally they can do so -indirectly. -(Eg when D\[aq]s default commodity is applied to a commodity-less -amount, or when an amountless posting is balanced using a price\[aq]s -commodity, or when -V is used.) If you find this causing problems, use a -commodity directive to set the display format. +Transaction prices don\[aq]t affect the amount display style directly, +but occasionally they can do so indirectly (eg when an posting\[aq]s +amount is inferred using a transaction price). +If you find this causing problems, use a commodity directive to fix the +display style. +.PP +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 .PP 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 fact the assertion checks only this commodity\[aq]s balance within the (possibly multi-commodity) account balance. -.PD 0 -.P -.PD This is how assertions work in Ledger also. We could call this a \[dq]partial\[dq] balance assertion. .PP @@ -861,7 +861,7 @@ balances: .IP .nf \f[C] -; starting a new journal, set asset account balances +; starting a new journal, set asset account balances 2016/1/1 opening balances assets:checking = $409.32 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. This is currently not enforced, but can serve as documentation. .IP "2." 3 -It declares what decimal mark character to expect when parsing input - -useful to disambiguate international number formats in your data. +It declares what decimal mark character (period or comma) to expect when +parsing input - useful to disambiguate international number formats in +your data. (Without this, hledger will parse both \f[C]1,000\f[R] and \f[C]1.000\f[R] as 1). .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. .PP 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. .SS Default commodity .PP -The \f[C]D\f[R] directive sets a default commodity (and display format), -to be used for amounts without a commodity symbol (ie, plain numbers). -(Note this differs from Ledger\[aq]s default commodity directive.) The -commodity and display format will be applied to all subsequent -commodity-less amounts, or until the next \f[C]D\f[R] directive. +The \f[C]D\f[R] directive sets a default commodity, to be used for +amounts without a commodity symbol (ie, plain numbers). +This commodity will be applied to all subsequent 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 .nf \f[C] ; 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 1/1 - a 5 ; <- commodity-less amount, becomes $1 + a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 b \f[R] .fi -.PP -As with the \f[C]commodity\f[R] directive, the amount must always be -written with a decimal point. .SS Market prices .PP 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 equity ; type:Equity account revenues ; type:Revenue -account expenses ; type:Expenses +account expenses ; type:Expense \f[R] .fi .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 account liabilities ; type:E -; we need to ensure some other account has the liability type, -; otherwise balancesheet would still show \[dq]liabilities\[dq] under Liabilities +; we need to ensure some other account has the liability type, +; otherwise balancesheet would still show \[dq]liabilities\[dq] under Liabilities account - ; type:L \f[R] .fi @@ -1767,8 +1776,8 @@ And each \[dq]posting\[dq] is actually a posting-generating rule: .nf \f[C] = QUERY - ACCT AMT - ACCT [AMT] + ACCOUNT AMOUNT + ACCOUNT [AMOUNT] ... \f[R] .fi @@ -1799,7 +1808,7 @@ Eg, note the quotes around the second query term below: .nf \f[C] = expenses:groceries \[aq]expenses:dining out\[aq] - (budget:funds:dining out) *-1 + (budget:funds:dining out) *-1 \f[R] .fi .PP diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index ea5e891f1..677ff908a 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -406,7 +406,7 @@ zero (separately from other postings). Eg: assets:cash $-10 ; <- these balance expenses:food $7 ; <- expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance + [assets:checking:budget:food] $-10 ; <- and these balance [assets:checking:available] $10 ; <- (something:else) $5 ; <- not required to balance @@ -479,10 +479,10 @@ comma: * Menu: * 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 ----------------------- @@ -515,17 +515,17 @@ commodity INR 9,99,99,999.00 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 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 - used (see examples above). + * If there is a commodity directive (or default commodity directive) + for the commodity, that format is used (see examples above). * Otherwise the format of the first posting amount in that commodity seen in the journal is used. But the number of decimal places @@ -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 used (like '$1000.00'). - Price amounts, and amounts in 'D' directives don't affect the amount -display format directly, but occasionally they can do so indirectly. -(Eg when D's default commodity is applied to a commodity-less amount, or -when an amountless posting is balanced using a price's commodity, or -when -V is used.) If you find this causing problems, use a commodity -directive to set the display format. + Transaction prices don't affect the amount display style directly, +but occasionally they can do so indirectly (eg when an posting's amount +is inferred using a transaction price). If you find this causing +problems, use a commodity directive to fix the display style. + + 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 @@ -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 fact the assertion checks only this commodity's balance within the -(possibly multi-commodity) account balance. -This is how assertions work in Ledger also. We could call this a -"partial" balance assertion. +(possibly multi-commodity) account balance. This is how assertions work +in Ledger also. We could call this a "partial" balance assertion. To assert the balance of more than one commodity in an account, you 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 opening balances: -; starting a new journal, set asset account balances +; starting a new journal, set asset account balances 2016/1/1 opening balances assets:checking = $409.32 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 currently not enforced, but can serve as documentation. - 2. It declares what decimal mark character to expect when parsing - input - useful to disambiguate international number formats in your - data. (Without this, hledger will parse both '1,000' and '1.000' - as 1). + 2. It declares what decimal mark character (period or comma) to expect + when parsing input - useful to disambiguate international number + 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 digit group marks, number of decimal places, symbol placement - etc. + 3. It declares the amount display style to use in output - decimal and + digit group marks, number of decimal places, symbol placement etc. 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 @@ -1057,23 +1058,27 @@ File: hledger_journal.info, Node: Default commodity, Next: Market prices, Pre 1.12.5 Default commodity ------------------------ -The 'D' directive sets a default commodity (and display format), to be -used for amounts without a commodity symbol (ie, plain numbers). (Note -this differs from Ledger's default commodity directive.) The commodity -and display format will be applied to all subsequent commodity-less -amounts, or until the next 'D' directive. +The 'D' directive sets a default commodity, to be used for amounts +without a commodity symbol (ie, plain numbers). This commodity will be +applied to all subsequent commodity-less amounts, or until the next 'D' +directive. (Note, this is different from Ledger's 'D'.) + + 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 -; (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 1/1 - a 5 ; <- commodity-less amount, becomes $1 + a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 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 @@ -1197,7 +1202,7 @@ account assets ; type:Asset account liabilities ; type:Liability account equity ; type:Equity account revenues ; type:Revenue -account expenses ; type:Expenses +account expenses ; type:Expense 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, @@ -1216,8 +1221,8 @@ need to help the reports a bit. Eg: ; make "liabilities" not have the liability type - who knows why account liabilities ; type:E -; we need to ensure some other account has the liability type, -; otherwise balancesheet would still show "liabilities" under Liabilities +; we need to ensure some other account has the liability type, +; otherwise balancesheet would still show "liabilities" under Liabilities account - ; type:L  @@ -1612,8 +1617,8 @@ certain postings (mnemonic: '=' suggests matching). And each "posting" is actually a posting-generating rule: = QUERY - ACCT AMT - ACCT [AMT] + ACCOUNT AMOUNT + ACCOUNT [AMOUNT] ... 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: = 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 data can potentially affect any transaction, including transactions @@ -1754,92 +1759,92 @@ Node: Postings12506 Ref: #postings12634 Node: Virtual Postings13660 Ref: #virtual-postings13777 -Node: Account names15083 -Ref: #account-names15224 -Node: Amounts15711 -Ref: #amounts15850 -Node: Digit group marks16783 -Ref: #digit-group-marks16932 -Node: Amount display format17870 -Ref: #amount-display-format18027 -Node: Transaction prices19052 -Ref: #transaction-prices19218 -Node: Balance Assertions21484 -Ref: #balance-assertions21664 -Node: Assertions and ordering22697 -Ref: #assertions-and-ordering22885 -Node: Assertions and included files23585 -Ref: #assertions-and-included-files23828 -Node: Assertions and multiple -f options24161 -Ref: #assertions-and-multiple--f-options24417 -Node: Assertions and commodities24549 -Ref: #assertions-and-commodities24781 -Node: Assertions and prices25937 -Ref: #assertions-and-prices26151 -Node: Assertions and subaccounts26591 -Ref: #assertions-and-subaccounts26820 -Node: Assertions and virtual postings27144 -Ref: #assertions-and-virtual-postings27386 -Node: Assertions and precision27528 -Ref: #assertions-and-precision27721 -Node: Balance Assignments27988 -Ref: #balance-assignments28162 -Node: Balance assignments and prices29327 -Ref: #balance-assignments-and-prices29499 -Node: Directives29723 -Ref: #directives29882 -Node: Comment blocks35530 -Ref: #comment-blocks35675 -Node: Including other files35851 -Ref: #including-other-files36031 -Node: Default year36439 -Ref: #default-year36608 -Node: Declaring commodities37015 -Ref: #declaring-commodities37198 -Node: Default commodity38859 -Ref: #default-commodity39035 -Node: Market prices39669 -Ref: #market-prices39834 -Node: Declaring accounts40675 -Ref: #declaring-accounts40851 -Node: Account comments41776 -Ref: #account-comments41939 -Node: Account subdirectives42363 -Ref: #account-subdirectives42558 -Node: Account types42871 -Ref: #account-types43055 -Node: Account display order44697 -Ref: #account-display-order44867 -Node: Rewriting accounts46018 -Ref: #rewriting-accounts46203 -Node: Basic aliases46929 -Ref: #basic-aliases47075 -Node: Regex aliases47779 -Ref: #regex-aliases47951 -Node: Combining aliases48669 -Ref: #combining-aliases48847 -Node: end aliases50123 -Ref: #end-aliases50271 -Node: Default parent account50372 -Ref: #default-parent-account50538 -Node: Periodic transactions51422 -Ref: #periodic-transactions51621 -Node: Periodic rule syntax53493 -Ref: #periodic-rule-syntax53699 -Node: Two spaces between period expression and description!54403 -Ref: #two-spaces-between-period-expression-and-description54722 -Node: Forecasting with periodic transactions55406 -Ref: #forecasting-with-periodic-transactions55711 -Node: Budgeting with periodic transactions57737 -Ref: #budgeting-with-periodic-transactions57976 -Node: Auto postings / transaction modifiers58425 -Ref: #auto-postings-transaction-modifiers58637 -Node: Auto postings and dates61122 -Ref: #auto-postings-and-dates61379 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions61554 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61929 -Node: Auto posting tags62307 -Ref: #auto-posting-tags62546 +Node: Account names15082 +Ref: #account-names15223 +Node: Amounts15710 +Ref: #amounts15849 +Node: Digit group marks16781 +Ref: #digit-group-marks16929 +Node: Amount display style17867 +Ref: #amount-display-style18021 +Node: Transaction prices19182 +Ref: #transaction-prices19348 +Node: Balance Assertions21614 +Ref: #balance-assertions21794 +Node: Assertions and ordering22827 +Ref: #assertions-and-ordering23015 +Node: Assertions and included files23715 +Ref: #assertions-and-included-files23958 +Node: Assertions and multiple -f options24291 +Ref: #assertions-and-multiple--f-options24547 +Node: Assertions and commodities24679 +Ref: #assertions-and-commodities24911 +Node: Assertions and prices26068 +Ref: #assertions-and-prices26282 +Node: Assertions and subaccounts26722 +Ref: #assertions-and-subaccounts26951 +Node: Assertions and virtual postings27275 +Ref: #assertions-and-virtual-postings27517 +Node: Assertions and precision27659 +Ref: #assertions-and-precision27852 +Node: Balance Assignments28119 +Ref: #balance-assignments28293 +Node: Balance assignments and prices29457 +Ref: #balance-assignments-and-prices29629 +Node: Directives29853 +Ref: #directives30012 +Node: Comment blocks35660 +Ref: #comment-blocks35805 +Node: Including other files35981 +Ref: #including-other-files36161 +Node: Default year36569 +Ref: #default-year36738 +Node: Declaring commodities37145 +Ref: #declaring-commodities37328 +Node: Default commodity39001 +Ref: #default-commodity39177 +Node: Market prices40066 +Ref: #market-prices40231 +Node: Declaring accounts41072 +Ref: #declaring-accounts41248 +Node: Account comments42173 +Ref: #account-comments42336 +Node: Account subdirectives42760 +Ref: #account-subdirectives42955 +Node: Account types43268 +Ref: #account-types43452 +Node: Account display order45091 +Ref: #account-display-order45261 +Node: Rewriting accounts46412 +Ref: #rewriting-accounts46597 +Node: Basic aliases47323 +Ref: #basic-aliases47469 +Node: Regex aliases48173 +Ref: #regex-aliases48345 +Node: Combining aliases49063 +Ref: #combining-aliases49241 +Node: end aliases50517 +Ref: #end-aliases50665 +Node: Default parent account50766 +Ref: #default-parent-account50932 +Node: Periodic transactions51816 +Ref: #periodic-transactions52015 +Node: Periodic rule syntax53887 +Ref: #periodic-rule-syntax54093 +Node: Two spaces between period expression and description!54797 +Ref: #two-spaces-between-period-expression-and-description55116 +Node: Forecasting with periodic transactions55800 +Ref: #forecasting-with-periodic-transactions56105 +Node: Budgeting with periodic transactions58131 +Ref: #budgeting-with-periodic-transactions58370 +Node: Auto postings / transaction modifiers58819 +Ref: #auto-postings-transaction-modifiers59031 +Node: Auto postings and dates61527 +Ref: #auto-postings-and-dates61784 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions61959 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62334 +Node: Auto posting tags62712 +Ref: #auto-posting-tags62951  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 9cb567e92..723df75de 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -403,13 +403,13 @@ FILE FORMAT commodity INR 9,99,99,999.00 commodity 1 000 000.9455 - Amount display format + Amount display style For each commodity, hledger chooses a consistent format to use when 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 - used (see examples above). + o If there is a commodity directive (or default commodity directive) + for the commodity, that format is used (see examples above). 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- @@ -419,18 +419,21 @@ FILE FORMAT o Or if there are no such amounts in the journal, a default format is used (like $1000.00). - Price amounts, and amounts in D directives don't affect the amount dis- - play format directly, but occasionally they can do so indirectly. (Eg - when D's default commodity is applied to a commodity-less amount, or - when an amountless posting is balanced using a price's commodity, or - when -V is used.) If you find this causing problems, use a commodity - directive to set the display format. + Transaction prices don't affect the amount display style directly, but + occasionally they can do so indirectly (eg when an posting's amount is + inferred using a transaction price). If you find this causing prob- + lems, use a commodity directive to fix the display style. + + 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 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 - price (in a sale). For example, transaction prices are useful to - record purchases of a foreign currency. Note transaction prices are + 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 + record purchases of a foreign currency. Note transaction prices are 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- tain date. @@ -459,7 +462,7 @@ FILE FORMAT (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- 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). Eg here is how -B affects the balance report for the example above: @@ -470,8 +473,8 @@ FILE FORMAT $-135 assets:dollars $135 assets:euros # <- the euros' cost - 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 + 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 amount. So if example 3's postings are reversed, while the transaction is equivalent, -B shows something different: @@ -484,9 +487,9 @@ FILE FORMAT EUR100 assets:euros Balance Assertions - hledger supports Ledger-style balance assertions in journal files. - These look like, for example, = EXPECTEDBALANCE following a posting's - amount. Eg here we assert the expected dollar balance in accounts a + hledger supports Ledger-style balance assertions in journal files. + These look like, for example, = EXPECTEDBALANCE following a posting's + amount. Eg here we assert the expected dollar balance in accounts a and b after each posting: 2013/1/1 @@ -498,32 +501,32 @@ FILE FORMAT b $-1 =$-2 After reading a journal file, hledger will check all balance assertions - and report an error if any of them fail. Balance assertions can pro- - tect you from, eg, inadvertently disrupting reconciled balances while - cleaning up old entries. You can disable them temporarily with the + and report an error if any of them fail. Balance assertions can pro- + tect you from, eg, inadvertently disrupting reconciled balances while + cleaning up old entries. You can disable them temporarily with the -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). Assertions and ordering - 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- + 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- 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.) So, hledger balance assertions keep working if you reorder differently- - dated transactions within the journal. But if you reorder same-dated - transactions or postings, assertions might break and require updating. + dated transactions within the journal. But if you reorder same-dated + transactions or postings, assertions might break and require updating. This order dependence does bring an advantage: precise control over the order of postings and assertions within a day, so you can assert intra- day balances. Assertions and included files - With included files, things are a little more complicated. Including - preserves the ordering of postings and assertions. If you have multi- - 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 + With included files, things are a little more complicated. Including + preserves the ordering of postings and assertions. If you have multi- + 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 day, you'll have to put the assertion in the right file. Assertions and multiple -f options @@ -531,16 +534,15 @@ FILE FORMAT -f options. Use include or concatenate the files instead. Assertions and commodities - The asserted balance must be a simple single-commodity amount, and in - fact the assertion checks only this commodity's balance within the - (possibly multi-commodity) account balance. - This is how assertions work in Ledger also. We could call this a "par- - tial" balance assertion. + The asserted balance must be a simple single-commodity amount, and in + fact the assertion checks only this commodity's balance within the + (possibly multi-commodity) account balance. This is how assertions + work in Ledger also. We could call this a "partial" balance assertion. To assert the balance of more than one commodity in an account, you can 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 unasserted commodities in the account (or, that their balance is 0). @@ -560,7 +562,7 @@ FILE FORMAT a 0 == $1 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: 2013/1/1 @@ -574,21 +576,21 @@ FILE FORMAT a:euro 0 == 1EUR Assertions and prices - Balance assertions ignore transaction prices, and should normally be + Balance assertions ignore transaction prices, and should normally be written without one: 2019/1/1 (a) $1 @ EUR1 = $1 - 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. - This is for backward compatibility (hledger's close command used to - generate balance assertions with prices), and because balance assign- + 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. + This is for backward compatibility (hledger's close command used to + generate balance assertions with prices), and because balance assign- ments do use them (see below). Assertions and subaccounts - The balance assertions above (= and ==) do not count the balance from - subaccounts; they check the account's exclusive balance only. You can + The balance assertions above (= and ==) do not count the balance from + subaccounts; they check the account's exclusive balance only. You can assert the balance including subaccounts by writing =* or ==*, eg: 2019/1/1 @@ -602,16 +604,16 @@ FILE FORMAT tual. They are not affected by the --real/-R flag or real: query. Assertions and precision - Balance assertions compare the exactly calculated amounts, which are - not always what is shown by reports. Eg a commodity directive may - limit the display precision, but this will not affect balance asser- + Balance assertions compare the exactly calculated amounts, which are + not always what is shown by reports. Eg a commodity directive may + limit the display precision, but this will not affect balance asser- tions. Balance assertion failure messages show exact amounts. Balance Assignments - Ledger-style balance assignments are also supported. These are like - balance assertions, but with no posting amount on the left side of the - equals sign; instead it is calculated automatically so as to satisfy - the assertion. This can be a convenience during data entry, eg when + Ledger-style balance assignments are also supported. These are like + balance assertions, but with no posting amount on the left side of the + equals sign; instead it is calculated automatically so as to satisfy + the assertion. This can be a convenience during data entry, eg when setting opening balances: ; starting a new journal, set asset account balances @@ -629,14 +631,14 @@ FILE FORMAT expenses:misc The calculated amount depends on the account's balance in the commodity - at that point (which depends on the previously-dated postings of the - commodity to that account since the last balance assertion or assign- + at that point (which depends on the previously-dated postings of the + commodity to that account since the last balance assertion or assign- ment). Note that using balance assignments makes your journal a little less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it. 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: 2019/1/1 @@ -647,79 +649,82 @@ FILE FORMAT (a) $1 @ EUR2 = $1 @ EUR2 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 based on a subset of Ledger's, but there are many differences (and also some differences between hledger versions). 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. - direc- end di- subdi- purpose can affect (as of + direc- end di- subdi- purpose can affect (as of tive rective rec- 2018/06) tives ------------------------------------------------------------------------------------ - account any document account names, de- all entries in all - text clare account types & dis- files, before or + account any document account names, de- all entries in all + text clare account types & dis- files, before or play order after alias end rewrite account names following in- aliases line/included en- - tries until end of + tries until end of current file or end 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- - tries until end of + tries until end of current file or end directive comment end com- ignore part of journal following in- ment line/included en- - tries until end of + tries until end of current file or end 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 style in that commodity - in all files; dis- + in all files; dis- play style: amounts of that commodity in reports - D declare a commodity to be default commodity: + D declare a commodity to be default commodity: used for commodityless following commod- - amounts, and its number no- ityless entries un- - tation & display style til end of current - file; number nota- + amounts, and its number no- ityless entries un- + tation & display style til end of current + file; number nota- tion: following en- - tries in that com- + tries in that com- modity until end of - current file; dis- + current file; dis- play style: amounts of that commodity in reports include include entries/directives what the included from another file directives affect P declare a market price for a amounts of that - commodity commodity in re- - ports, when -V is + commodity commodity in re- + ports, when -V is used - Y declare a year for yearless following in- + Y declare a year for yearless following in- dates line/included en- - tries until end of + tries until end of current file And some definitions: - subdi- optional indented directive line immediately following a parent + subdi- optional indented directive line immediately following a parent rec- directive tive 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.) - 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) 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 scope @@ -727,34 +732,34 @@ FILE FORMAT affect, and whether they are focussed on input (parsing) or output (re- ports). Some directives have multiple effects. - 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 - typically last only until the end of their defining file. This pro- + 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 + typically last only until the end of their defining file. This pro- 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. 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) ends it. See also comments. 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: include path/to/file.journal - 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. + 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. *). - 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. Default year - 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. + 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. Eg: Y2009 ; set default year to 2009 @@ -776,14 +781,15 @@ FILE FORMAT Declaring commodities 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. - 2. It declares what decimal mark character to expect when parsing input - - useful to disambiguate international number formats in your data. - (Without this, hledger will parse both 1,000 and 1.000 as 1). + 2. It declares what decimal mark character (period or comma) to expect + when parsing input - useful to disambiguate international number + 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. 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. Default commodity - The D directive sets a default commodity (and display format), to be - used for amounts without a commodity symbol (ie, plain numbers). (Note - this differs from Ledger's default commodity directive.) The commodity - and display format will be applied to all subsequent commodity-less - amounts, or until the next D directive. + The D directive sets a default commodity, to be used for amounts with- + out a commodity symbol (ie, plain numbers). This commodity will be ap- + plied to all subsequent commodity-less amounts, or until the next D di- + rective. (Note, this is different from Ledger's D.) + + 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 - ; (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 1/1 - a 5 ; <- commodity-less amount, becomes $1 + a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 b - As with the commodity directive, the amount must always be written with - a decimal point. - Market prices The P directive declares a market price, which is an exchange rate be- tween two commodities on a certain date. (In Ledger, they are called @@ -935,7 +945,7 @@ FILE FORMAT account liabilities ; type:Liability account equity ; type:Equity account revenues ; type:Revenue - account expenses ; type:Expenses + account expenses ; type:Expense Account types declared with account type codes Or, you can write one of those letters separated from the account name @@ -1281,8 +1291,8 @@ FILE FORMAT actually a posting-generating rule: = QUERY - ACCT AMT - ACCT [AMT] + ACCOUNT AMOUNT + ACCOUNT [AMOUNT] ... These posting-generating rules look like normal postings, except the diff --git a/hledger-lib/hledger_timedot.5 b/hledger-lib/hledger_timedot.5 index 3cd9d5be7..b0233eb67 100644 --- a/hledger-lib/hledger_timedot.5 +++ b/hledger-lib/hledger_timedot.5 @@ -55,7 +55,7 @@ An example: # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. 2016/2/1 inc:client1 .... .... .... .... .... .... -fos:haskell .... .. +fos:haskell .... .. biz:research . 2016/2/2 diff --git a/hledger-lib/hledger_timedot.info b/hledger-lib/hledger_timedot.info index 7aa2682f5..97b237999 100644 --- a/hledger-lib/hledger_timedot.info +++ b/hledger-lib/hledger_timedot.info @@ -46,7 +46,7 @@ example: # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. 2016/2/1 inc:client1 .... .... .... .... .... .... -fos:haskell .... .. +fos:haskell .... .. biz:research . 2016/2/2 diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 3ee0934ae..ccc6b580f 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -26,19 +26,17 @@ limited data entry capability. It is easier than hledger\[aq]s command-line interface, and sometimes quicker and more convenient than the web interface. .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, 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, perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]). 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 .PP 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 \f[B]\f[CB]-T --tree\f[B]\f[R] show accounts as a tree -.TP -\f[B]\f[CB]--future\f[B]\f[R] -show transactions dated later than today (normally hidden) .PP hledger input options: .TP @@ -155,8 +150,9 @@ most recent applicable market price, if any) apply automated posting rules to modify transactions. .TP \f[B]\f[CB]--forecast\f[B]\f[R] -apply periodic transaction rules to generate future transactions, to 6 -months from now or report end date. +generate future transactions from periodic transaction rules, for the +next 6 months or till report end date. +In hledger-ui, also make ordinary future transactions visible. .PP When a reporting option appears more than once in the command line, the 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 transactions. .PP -As mentioned above, hledger-ui shows auto-generated periodic -transactions, and hides future transactions (auto-generated or not) by -default. -\f[C]F\f[R] toggles showing and hiding these future transactions. -This is similar to using a query like \f[C]date:-tomorrow\f[R], but more -convenient. +As mentioned above, by default hledger-ui hides future transactions - +both ordinary transactions recorded in the journal, and periodic +transactions generated by rule. +\f[C]F\f[R] toggles forecast mode, in which future/forecasted +transactions are shown. (experimental) .PP \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. In other words, the register always shows the transactions contributing 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. .PP \f[C]U\f[R] toggles filtering by unmarked status, showing or hiding diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index f2da998e4..c3fdbdc61 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -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. - 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 journal, timeclock, timedot, or CSV format specified with '-f', or '$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps 'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), 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: * OPTIONS:: @@ -75,9 +73,6 @@ the data. '-T --tree' show accounts as a tree -'--future' - - show transactions dated later than today (normally hidden) hledger input options: @@ -168,8 +163,9 @@ the data. apply automated posting rules to modify transactions. '--forecast' - apply periodic transaction rules to generate future transactions, - to 6 months from now or report end date. + generate future transactions from periodic transaction rules, 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 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 transactions. - As mentioned above, hledger-ui shows auto-generated periodic -transactions, and hides future transactions (auto-generated or not) by -default. 'F' toggles showing and hiding these future transactions. -This is similar to using a query like 'date:-tomorrow', but more -convenient. (experimental) + As mentioned above, by default hledger-ui hides future transactions - +both ordinary transactions recorded in the journal, and periodic +transactions generated by rule. 'F' toggles forecast mode, in which +future/forecasted transactions are shown. (experimental) 'ESCAPE' removes all filters and jumps back to the top screen. Or, 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 mode but this account has subaccounts which are not shown due to a depth limit. In other words, the register always shows the transactions -contributing to the balance shown on the accounts screen. -Tree mode/flat mode can be toggled with 'T' here also. +contributing to the balance shown on the accounts screen. Tree +mode/flat mode can be toggled with 'T' here also. 'U' toggles filtering by unmarked status, showing or hiding unmarked transactions. Similarly, 'P' toggles pending transactions, and 'C' @@ -504,26 +499,26 @@ program is restarted.  Tag Table: Node: Top71 -Node: OPTIONS1520 -Ref: #options1617 -Node: KEYS5053 -Ref: #keys5148 -Node: SCREENS9455 -Ref: #screens9560 -Node: Accounts screen9650 -Ref: #accounts-screen9778 -Node: Register screen11994 -Ref: #register-screen12149 -Node: Transaction screen14145 -Ref: #transaction-screen14303 -Node: Error screen15173 -Ref: #error-screen15295 -Node: ENVIRONMENT15539 -Ref: #environment15653 -Node: FILES16460 -Ref: #files16559 -Node: BUGS16772 -Ref: #bugs16849 +Node: OPTIONS1476 +Ref: #options1573 +Node: KEYS5004 +Ref: #keys5099 +Node: SCREENS9375 +Ref: #screens9480 +Node: Accounts screen9570 +Ref: #accounts-screen9698 +Node: Register screen11914 +Ref: #register-screen12069 +Node: Transaction screen14066 +Ref: #transaction-screen14224 +Node: Error screen15094 +Ref: #error-screen15216 +Node: ENVIRONMENT15460 +Ref: #environment15574 +Node: FILES16381 +Ref: #files16480 +Node: BUGS16693 +Ref: #bugs16770  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 814722f95..1bbc30655 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -22,25 +22,22 @@ DESCRIPTION line interface, and sometimes quicker and more convenient than the web 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, timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, or $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). For more about this see hledger(1), 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 - 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. - Any QUERYARGS are interpreted as a hledger search query which filters + Any QUERYARGS are interpreted as a hledger search query which filters the data. --watch @@ -53,7 +50,7 @@ OPTIONS start in the (first) matched account's register screen --change - show period balances (changes) at startup instead of historical + show period balances (changes) at startup instead of historical balances -F --flat @@ -62,9 +59,6 @@ OPTIONS -T --tree show accounts as a tree - --future - show transactions dated later than today (normally hidden) - hledger input options: -f FILE --file=FILE @@ -72,7 +66,7 @@ OPTIONS $LEDGER_FILE or $HOME/.hledger.journal) --rules-file=RULESFILE - Conversion rules file to use when reading CSV (default: + Conversion rules file to use when reading CSV (default: FILE.rules) --separator=CHAR @@ -114,7 +108,7 @@ OPTIONS multiperiod/multicolumn report by year -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 --date2 @@ -137,22 +131,23 @@ OPTIONS hide/aggregate accounts or postings more than NUM levels deep -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) -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) -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) --auto apply automated posting rules to modify transactions. --forecast - apply periodic transaction rules to generate future transac- - tions, to 6 months from now or report end date. + generate future transactions from periodic transaction rules, + 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 last one takes precedence. @@ -204,105 +199,104 @@ KEYS common filters like account depth and transaction status (see below). BACKSPACE or DELETE removes all filters, showing all transactions. - As mentioned above, hledger-ui shows auto-generated periodic transac- - tions, and hides future transactions (auto-generated or not) by de- - fault. F toggles showing and hiding these future transactions. This - is similar to using a query like date:-tomorrow, but more convenient. - (experimental) + As mentioned above, by default hledger-ui hides future transactions - + both ordinary transactions recorded in the journal, and periodic trans- + actions generated by rule. F toggles forecast mode, in which fu- + ture/forecasted transactions are shown. (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. 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). - g reloads from the data file(s) and updates the current screen and any - previous screens. (With large files, this could cause a noticeable + g reloads from the data file(s) and updates the current screen and any + previous screens. (With large files, this could cause a noticeable pause.) - I toggles balance assertion checking. Disabling balance assertions + I toggles balance assertion checking. Disabling balance assertions 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. - 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 + 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 $PATH. - E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a "" - -nw) on the journal file. With some editors (emacs, vi), the cursor - will be positioned at the current transaction when invoked from the - register and transaction screens, and at the error location (if possi- + E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a "" + -nw) on the journal file. With some editors (emacs, vi), the cursor + will be positioned at the current transaction when invoked from the + register and transaction screens, and at the error location (if possi- ble) when invoked from the error screen. q quits the application. 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). - V toggles value mode, showing amounts' current market value in their - default valuation commodity (like toggling the -V/--market flag). - 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 - 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, + V toggles value mode, showing amounts' current market value in their + default valuation commodity (like toggling the -V/--market flag). + 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 + 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, press /, and add date:-7/30 to the query. 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. - 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 - 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. Additional screen-specific keys are described below. SCREENS Accounts screen - This is normally the first screen displayed. It lists accounts and - their balances, like hledger's balance command. By default, it shows - all accounts and their latest ending balances (including the balances - of subaccounts). if you specify a query on the command line, it shows + This is normally the first screen displayed. It lists accounts and + their balances, like hledger's balance command. By default, it shows + all accounts and their latest ending balances (including the balances + of subaccounts). if you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions. - 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- - counts, except where subaccounts are hidden by a depth limit (see be- + 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- + counts, except where subaccounts are hidden by a depth limit (see be- 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 - 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- CAPE. H toggles between showing historical balances or period balances. His- - torical balances (the default) are ending balances at the end of the - report period, taking into account all transactions before that date - (filtered by the filter query if any), including transactions before - the start of the report period. In other words, historical balances - are what you would see on a bank statement for that account (unless - disturbed by a filter query). Period balances ignore transactions be- - fore the report start date, so they show the change in balance during + torical balances (the default) are ending balances at the end of the + report period, taking into account all transactions before that date + (filtered by the filter query if any), including transactions before + the start of the report period. In other words, historical balances + are what you would see on a bank statement for that account (unless + disturbed by a filter query). Period balances ignore transactions be- + 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. U toggles filtering by unmarked status, including or excluding unmarked postings in the balances. Similarly, P toggles pending postings, and C - toggles cleared postings. (By default, balances include all postings; - if you activate one or two status filters, only those postings are in- + toggles cleared postings. (By default, balances include all postings; + if you activate one or two status filters, only those postings are in- cluded; and if you activate all three, the filter is removed.) R toggles real mode, in which virtual postings are ignored. - Z toggles nonzero mode, in which only accounts with nonzero balances - are shown (hledger-ui shows zero items by default, unlike command-line + Z toggles nonzero mode, in which only accounts with nonzero balances + are shown (hledger-ui shows zero items by default, unlike command-line hledger). 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 a check register. Each line represents one transaction and shows: - o the other account(s) involved, in abbreviated form. (If there are - both real and virtual postings, it shows only the accounts affected + o the other account(s) involved, in abbreviated form. (If there are + both real and virtual postings, it shows only the accounts affected 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. o the running historical total or period total for the current account, - after the transaction. This can be toggled with H. Similar to the - accounts screen, the historical total is affected by transactions - (filtered by the filter query) before the report start date, while + after the transaction. This can be toggled with H. Similar to the + accounts screen, the historical total is affected by transactions + (filtered by the filter query) before the report start date, while 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. - 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 - mode but this account has subaccounts which are not shown due to a - depth limit. In other words, the register always shows the transac- - tions contributing to the balance shown on the accounts screen. - Tree mode/flat mode can be toggled with T here also. + mode but this account has subaccounts which are not shown due to a + depth limit. In other words, the register always shows the transac- + tions contributing to the balance shown on the accounts screen. Tree + mode/flat mode can be toggled with T here also. U toggles filtering by unmarked status, showing or hiding unmarked transactions. Similarly, P toggles pending transactions, and C toggles diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index c9d7ca692..78cfbb5fd 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -176,8 +176,9 @@ most recent applicable market price, if any) apply automated posting rules to modify transactions. .TP \f[B]\f[CB]--forecast\f[B]\f[R] -apply periodic transaction rules to generate future transactions, to 6 -months from now or report end date. +generate future transactions from periodic transaction rules, for the +next 6 months or till report end date. +In hledger-ui, also make ordinary future transactions visible. .PP When a reporting option appears more than once in the command line, the last one takes precedence. diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index 439d4ff5e..3956591b9 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -187,8 +187,9 @@ before options, as shown in the synopsis above. apply automated posting rules to modify transactions. '--forecast' - apply periodic transaction rules to generate future transactions, - to 6 months from now or report end date. + generate future transactions from periodic transaction rules, 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 last one takes precedence. @@ -428,20 +429,20 @@ Tag Table: Node: Top72 Node: OPTIONS1752 Ref: #options1857 -Node: PERMISSIONS8130 -Ref: #permissions8269 -Node: EDITING UPLOADING DOWNLOADING9481 -Ref: #editing-uploading-downloading9662 -Node: RELOADING10496 -Ref: #reloading10630 -Node: JSON API11063 -Ref: #json-api11177 -Node: ENVIRONMENT12618 -Ref: #environment12734 -Node: FILES13467 -Ref: #files13567 -Node: BUGS13780 -Ref: #bugs13858 +Node: PERMISSIONS8201 +Ref: #permissions8340 +Node: EDITING UPLOADING DOWNLOADING9552 +Ref: #editing-uploading-downloading9733 +Node: RELOADING10567 +Ref: #reloading10701 +Node: JSON API11134 +Ref: #json-api11248 +Node: ENVIRONMENT12689 +Ref: #environment12805 +Node: FILES13538 +Ref: #files13638 +Node: BUGS13851 +Ref: #bugs13929  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 4379cf8e8..ed21ec333 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -166,8 +166,9 @@ OPTIONS --auto apply automated posting rules to modify transactions. --forecast - apply periodic transaction rules to generate future transac- - tions, to 6 months from now or report end date. + generate future transactions from periodic transaction rules, + 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 last one takes precedence. @@ -186,54 +187,54 @@ OPTIONS show debug output (levels 1-9, default: 1) 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.) 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 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 - browser windows viewing it). With --serve, it just runs the web app - without exiting, and logs requests to the console. With --serve-api, - only the JSON web api (see below) is served, with the usual HTML + 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 + without exiting, and logs requests to the console. With --serve-api, + only the JSON web api (see below) is served, with the usual HTML server-side web UI disabled. - 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 + 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 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. 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 - for communication. This is an alternative way of running multiple - hledger-web instances behind a reverse proxy that handles authentica- - tion for different users. The path can be derived in a predictable + it creates an AF_UNIX socket file at the supplied path and uses that + for communication. This is an alternative way of running multiple + hledger-web instances behind a reverse proxy that handles authentica- + 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 - reverse proxy can use the variabel $remote_user to derive a path from - the username used in a HTTP basic authentication. The following - proxy_pass directive allows access to all hledger-web instances that + reverse proxy can use the variabel $remote_user to derive a path from + the username used in a HTTP basic authentication. The following + proxy_pass directive allows access to all hledger-web instances that created a socket in /tmp/hledger/: 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 - 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). - 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. 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. You can restrict who can reach it by - 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- + 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- chine. 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 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: o view - allows viewing the journal file and all included files 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 - o using the --capabilities-header=HTTPHEADER flag to specify a HTTP - header from which it will read capabilities to enable. hledger-web - on Sandstorm uses the X-Sandstorm-Permissions header to integrate + o using the --capabilities-header=HTTPHEADER flag to specify a HTTP + header from which it will read capabilities to enable. hledger-web + on Sandstorm uses the X-Sandstorm-Permissions header to integrate with Sandstorm's permissions. This is disabled by default. EDITING, UPLOADING, DOWNLOADING - 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 - let you edit, upload, or download the journal file or any files it in- + 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 + let you edit, upload, or download the journal file or any files it in- 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. - Normally whenever a file is changed in this way, hledger-web saves a - numbered backup (assuming file permissions allow it, the disk is not - 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 + Normally whenever a file is changed in this way, hledger-web saves a + numbered backup (assuming file permissions allow it, the disk is not + 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 yourself (eg with a cron job or a file watcher like entr). - Changes which would leave the journal file(s) unparseable or non-valid - (eg with failing balance assertions) are prevented. (Probably. This + Changes which would leave the journal file(s) unparseable or non-valid + (eg with failing balance assertions) are prevented. (Probably. This needs re-testing.) RELOADING 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 - data when you reload the page or navigate to a new page. If a change + 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 makes a file unparseable, hledger-web will display an error message un- til the file has been fixed. @@ -288,8 +289,8 @@ RELOADING that both machine clocks are roughly in step.) JSON API - In addition to the web UI, hledger-web provides some API routes that - serve JSON in response to GET requests. (And when started with + In addition to the web UI, hledger-web provides some API routes that + serve JSON in response to GET requests. (And when started with --serve-api, it provides only these routes.): /accountnames @@ -299,17 +300,17 @@ JSON API /accounts /accounttransactions/#AccountName - Also, you can append a new transaction to the journal by sending a PUT - request to /add (hledger-web only). As with the web UI's add form, - hledger-web must be started with the add capability for this (enabled + Also, you can append a new transaction to the journal by sending a PUT + request to /add (hledger-web only). As with the web UI's add form, + hledger-web must be started with the add capability for this (enabled by default). - 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. - 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 - JSON-capable types from or to a file. Eg here we write the first + 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 + JSON-capable types from or to a file. Eg here we write the first transaction of a sample journal: $ 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 - 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 + By default, both the server-side HTML UI and the JSON API are served. + Running with --serve-api disables the former, useful if you only want to serve the API. ENVIRONMENT 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). - 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- + 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- 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 - 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- vironment.plist file containing @@ -349,13 +350,13 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). 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. -f- doesn't work (hledger-web can't read from stdin). @@ -369,7 +370,7 @@ 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) @@ -383,7 +384,7 @@ COPYRIGHT 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- dot(5), ledger(1) diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index c48898553..b16229cb7 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -291,14 +291,12 @@ Balance changes in 2008: (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 -report end date, for all columns (not the price on each column's end -date). - -Eliding of boring parent accounts in tree mode, as in the classic -balance report, is not yet supported in multicolumn reports. +The --transpose flag can be used to exchange the rows and columns of a +multicolumn report. Budget report diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index fe872cf7a..bcf298a48 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -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 the -x/--explicit flag to make all amounts and transaction prices 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 (these can arise when a multi-commodity transaction has an implicit diff --git a/hledger/hledger.1 b/hledger/hledger.1 index df96fbdb7..c5e036344 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -179,7 +179,7 @@ like this: assets:bank:checking $1000 = $1000 assets:bank:savings $2000 = $2000 assets:cash $100 = $100 - liabilities:creditcard $-50 = $-$50 + liabilities:creditcard $-50 = $-50 equity:opening/closing balances \f[R] .fi @@ -628,8 +628,9 @@ most recent applicable market price, if any) apply automated posting rules to modify transactions. .TP \f[B]\f[CB]--forecast\f[B]\f[R] -apply periodic transaction rules to generate future transactions, to 6 -months from now or report end date. +generate future transactions from periodic transaction rules, for the +next 6 months or till report end date. +In hledger-ui, also make ordinary future transactions visible. .PP When a reporting option appears more than once in the command line, the last one takes precedence. @@ -1694,10 +1695,11 @@ more general \f[C]--value\f[R] option: .IP .nf \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. Shows amounts converted to: - 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 current market prices - 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] Convert amounts to cost, using the prices recorded in transactions. .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] Convert amounts to their value in a default valuation commodity, using market prices on the last day of the report period (or if unspecified, @@ -1905,7 +1912,7 @@ Related: #329, #1083. .PP .TS 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{ Report type T}@T{ @@ -1913,6 +1920,8 @@ T}@T{ T}@T{ \f[C]-V\f[R], \f[C]-X\f[R] T}@T{ +\f[C]--value=then\f[R] +T}@T{ \f[C]--value=end\f[R] T}@T{ \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{ posting amounts @@ -1932,6 +1942,8 @@ cost T}@T{ value at report end or today T}@T{ +value at posting date +T}@T{ value at report or journal end T}@T{ value at DATE/today @@ -1946,12 +1958,15 @@ T}@T{ unchanged T}@T{ unchanged +T}@T{ +unchanged T} T{ T}@T{ T}@T{ T}@T{ T}@T{ +T}@T{ T} T{ \f[B]register\f[R] @@ -1959,6 +1974,7 @@ T}@T{ T}@T{ T}@T{ T}@T{ +T}@T{ T} T{ starting balance (with -H) @@ -1967,6 +1983,8 @@ cost T}@T{ value at day before report or journal start T}@T{ +not supported +T}@T{ value at day before report or journal start T}@T{ value at DATE/today @@ -1978,6 +1996,8 @@ cost T}@T{ value at report end or today T}@T{ +value at posting date +T}@T{ value at report or journal end T}@T{ value at DATE/today @@ -1989,6 +2009,8 @@ summarised cost T}@T{ value at period ends T}@T{ +sum of postings in interval, valued at interval start +T}@T{ value at period ends T}@T{ value at DATE/today @@ -2003,12 +2025,15 @@ T}@T{ sum/average of displayed values T}@T{ 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{ \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{ balances (no report interval) @@ -2024,6 +2050,8 @@ sums of costs T}@T{ value at report end or today of sums of postings T}@T{ +not supported +T}@T{ value at report or journal end of sums of postings T}@T{ value at DATE/today of sums of postings @@ -2035,6 +2063,8 @@ sums of costs T}@T{ value at period ends of sums of postings T}@T{ +not supported +T}@T{ value at period ends of sums of postings T}@T{ value at DATE/today of sums of postings @@ -2046,6 +2076,8 @@ sums of costs of postings before report start T}@T{ sums of postings before report start T}@T{ +not supported +T}@T{ sums of postings before report start T}@T{ sums of postings before report start @@ -2057,6 +2089,8 @@ like balances T}@T{ like balances T}@T{ +not supported +T}@T{ like balances T}@T{ like balances @@ -2068,6 +2102,8 @@ sum of displayed values T}@T{ sum of displayed values T}@T{ +not supported +T}@T{ sum of displayed values T}@T{ sum of displayed values @@ -2079,6 +2115,8 @@ sums/averages of displayed values T}@T{ sums/averages of displayed values T}@T{ +not supported +T}@T{ sums/averages of displayed values T}@T{ sums/averages of displayed values @@ -2090,6 +2128,8 @@ sums of displayed values T}@T{ sums of displayed values T}@T{ +not supported +T}@T{ sums of displayed values T}@T{ sums of displayed values @@ -2101,6 +2141,8 @@ sum/average of column totals T}@T{ sum/average of column totals T}@T{ +not supported +T}@T{ sum/average of column totals T}@T{ sum/average of column totals @@ -2110,6 +2152,7 @@ T}@T{ T}@T{ T}@T{ T}@T{ +T}@T{ T} .TE .PP @@ -2668,14 +2711,12 @@ Balance changes in 2008: \f[R] .fi .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 -In multicolumn reports the \f[C]-V/--value\f[R] flag uses the market -price on the report end date, for all columns (not the price on each -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. +The \f[C]--transpose\f[R] flag can be used to exchange the rows and +columns of a multicolumn report. .SS Budget report .PP 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 troubleshooting or for making your journal more readable and robust 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 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 diff --git a/hledger/hledger.info b/hledger/hledger.info index a2b46ef8f..a8bcb5739 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -186,7 +186,7 @@ balances on this date. Here are two ways to do it: assets:bank:checking $1000 = $1000 assets:bank:savings $2000 = $2000 assets:cash $100 = $100 - liabilities:creditcard $-50 = $-$50 + liabilities:creditcard $-50 = $-50 equity:opening/closing balances 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. '--forecast' - apply periodic transaction rules to generate future transactions, - to 6 months from now or report end date. + generate future transactions from periodic transaction rules, 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 last one takes precedence. @@ -1415,10 +1416,11 @@ _(experimental, added 201905)_ '-B', '-V' and '-X' are special cases of the more general '--value' 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. Shows amounts converted to: - 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 current market prices - default valuation commodity (or COMM) using market prices at some date @@ -1429,6 +1431,11 @@ a valuation date: '--value=cost' 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' 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 reproducible example. Related: #329, #1083. -Report type '-B', '-V', '-X' '--value=end' '--value=DATE', - '--value=cost' '--value=now' ------------------------------------------------------------------------------ +Report '-B', '-V', '-X' '--value=then' '--value=end' '--value=DATE', +type '--value=cost' '--value=now' +------------------------------------------------------------------------------- *print* -posting cost value at value at value at -amounts report end or report or DATE/today - today journal end -balance unchanged unchanged unchanged unchanged -assertions / +posting cost value at value at value at value at +amounts report end posting date report or DATE/today + or today journal end +balance unchanged unchanged unchanged unchanged unchanged +assertions +/ assignments *register* -starting cost value at day value at day value at -balance (with before report before report DATE/today --H) or journal or journal - start start -posting cost value at value at value at -amounts (no report end or report or DATE/today -report today journal end +starting cost value at not value at value at +balance day before supported day before DATE/today +(with -H) report or report or + journal journal + start start +posting cost value at value at value at value at +amounts report end posting date report or DATE/today +(no report or today journal end interval) -summary summarised value at value at value at -posting cost period ends period ends DATE/today -amounts (with -report -interval) -running sum/average sum/average sum/average of sum/average -total/average of displayed of displayed displayed of - values values values displayed - values -*balance (bs, -bse, cf, -is..)* -balances (no sums of value at value at value at -report costs report end or report or DATE/today -interval) today of sums journal end of of sums of - of postings sums of postings - postings -balances sums of value at value at value at -(with report costs period ends period ends of DATE/today -interval) of sums of sums of of sums of - postings postings postings -starting sums of sums of sums of sums of -balances costs of postings postings postings -(with report postings before report before report before -interval and before start start report --H) report start start -budget like like balances like balances like -amounts with balances balances +summary summarised value at sum of value at value at +posting cost period postings in period ends DATE/today +amounts ends interval, +(with valued at +report interval +interval) start +running sum/average sum/average sum/average sum/average sum/average +total/averageof of of displayed of of + displayed displayed values displayed displayed + values values values values +*balance +(bs, bse, +cf, is..)* +balances sums of value at not value at value at +(no report costs report end supported report or DATE/today +interval) or today journal end of sums + of sums of of sums of of + postings postings postings +balances sums of value at not value at value at +(with costs period supported period ends DATE/today +report ends of of sums of of sums +interval) sums of postings of + postings postings +starting sums of sums of not sums of sums of +balances costs of postings supported postings postings +(with postings before before before +report before report report report +interval report start start start +and -H) start +budget like like not like like +amounts balances balances supported balances balances +with -budget -grand total sum of sum of sum of sum of -(no report displayed displayed displayed displayed -interval) values values values values -row sums/averages sums/averages sums/averages sums/averages -totals/averages of displayed of displayed of displayed of -(with report values values values displayed -interval) values -column totals sums of sums of sums of sums of - displayed displayed displayed displayed - values values values values -grand sum/average sum/average sum/average of sum/average -total/average of column of column column totals of column - totals totals totals +grand sum of sum of not sum of sum of +total (no displayed displayed supported displayed displayed +report values values values values +interval) +row sums/averagessums/averagesnot sums/averages sums/averages +totals/averagesof of supported of of +(with displayed displayed displayed displayed +report values values values values +interval) +column sums of sums of not sums of sums of +totals displayed displayed supported displayed displayed + values values values values +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* @@ -2200,14 +2216,12 @@ Balance changes in 2008: (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 report end date, for all columns (not the price on each column's end -date). - - Eliding of boring parent accounts in tree mode, as in the classic -balance report, is not yet supported in multicolumn reports. + The '--transpose' flag can be used to exchange the rows and columns +of a multicolumn report.  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 the '-x'/'--explicit' flag to make all amounts and transaction prices 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 (these can arise when a multi-commodity transaction has an @@ -3678,177 +3693,177 @@ Node: Starting a journal file4414 Ref: #starting-a-journal-file4612 Node: Setting opening balances5800 Ref: #setting-opening-balances5996 -Node: Recording transactions9138 -Ref: #recording-transactions9318 -Node: Reconciling9874 -Ref: #reconciling10017 -Node: Reporting12274 -Ref: #reporting12414 -Node: Migrating to a new file16413 -Ref: #migrating-to-a-new-file16561 -Node: OPTIONS16860 -Ref: #options16967 -Node: General options17337 -Ref: #general-options17462 -Node: Command options20161 -Ref: #command-options20312 -Node: Command arguments20710 -Ref: #command-arguments20857 -Node: Queries21737 -Ref: #queries21892 -Node: Special characters in arguments and queries25854 -Ref: #special-characters-in-arguments-and-queries26082 -Node: More escaping26533 -Ref: #more-escaping26695 -Node: Even more escaping26991 -Ref: #even-more-escaping27185 -Node: Less escaping27856 -Ref: #less-escaping28018 -Node: Unicode characters28263 -Ref: #unicode-characters28445 -Node: Input files29857 -Ref: #input-files30000 -Node: Output destination31929 -Ref: #output-destination32081 -Node: Output format32364 -Ref: #output-format32514 -Node: Regular expressions32899 -Ref: #regular-expressions33056 -Node: Smart dates34417 -Ref: #smart-dates34568 -Node: Report start & end date35929 -Ref: #report-start-end-date36101 -Node: Report intervals37539 -Ref: #report-intervals37704 -Node: Period expressions38094 -Ref: #period-expressions38254 -Node: Depth limiting42380 -Ref: #depth-limiting42524 -Node: Pivoting42866 -Ref: #pivoting42989 -Node: Valuation44665 -Ref: #valuation44767 -Node: -B Cost44947 -Ref: #b-cost45058 -Node: -V Market value45256 -Ref: #v-market-value45430 -Node: -X Market value in specified commodity46862 -Ref: #x-market-value-in-specified-commodity47101 -Node: --value Flexible valuation47277 -Ref: #value-flexible-valuation47503 -Node: Effect of --value on reports51693 -Ref: #effect-of---value-on-reports51909 -Node: Combining -B -V -X --value56840 -Ref: #combining--b--v--x---value57023 -Node: COMMANDS57059 -Ref: #commands57167 -Node: accounts58251 -Ref: #accounts58349 -Node: activity59048 -Ref: #activity59158 -Node: add59541 -Ref: #add59640 -Node: balance62379 -Ref: #balance62490 -Node: Classic balance report63948 -Ref: #classic-balance-report64121 -Node: Customising the classic balance report65490 -Ref: #customising-the-classic-balance-report65718 -Node: Colour support67794 -Ref: #colour-support67961 -Node: Flat mode68134 -Ref: #flat-mode68282 -Node: Depth limited balance reports68695 -Ref: #depth-limited-balance-reports68880 -Node: Percentages69336 -Ref: #percentages69502 -Node: Multicolumn balance report70639 -Ref: #multicolumn-balance-report70819 -Node: Budget report76133 -Ref: #budget-report76276 -Node: Nested budgets81478 -Ref: #nested-budgets81590 -Ref: #output-format-185071 -Node: balancesheet85149 -Ref: #balancesheet85285 -Node: balancesheetequity86668 -Ref: #balancesheetequity86817 -Node: cashflow87378 -Ref: #cashflow87506 -Node: check-dates88602 -Ref: #check-dates88729 -Node: check-dupes89008 -Ref: #check-dupes89132 -Node: close89425 -Ref: #close89539 -Node: close usage91061 -Ref: #close-usage91154 -Node: commodities93967 -Ref: #commodities94094 -Node: descriptions94176 -Ref: #descriptions94304 -Node: diff94485 -Ref: #diff94591 -Node: files95638 -Ref: #files95738 -Node: help95885 -Ref: #help95985 -Node: import97066 -Ref: #import97180 -Node: Importing balance assignments98073 -Ref: #importing-balance-assignments98221 -Node: incomestatement98870 -Ref: #incomestatement99003 -Node: notes100407 -Ref: #notes100520 -Node: payees100646 -Ref: #payees100752 -Node: prices100910 -Ref: #prices101016 -Node: print101357 -Ref: #print101467 -Node: print-unique106111 -Ref: #print-unique106237 -Node: register106522 -Ref: #register106649 -Node: Custom register output110821 -Ref: #custom-register-output110950 -Node: register-match112212 -Ref: #register-match112346 -Node: rewrite112697 -Ref: #rewrite112812 -Node: Re-write rules in a file114667 -Ref: #re-write-rules-in-a-file114801 -Node: Diff output format116011 -Ref: #diff-output-format116180 -Node: rewrite vs print --auto117272 -Ref: #rewrite-vs.-print---auto117451 -Node: roi118007 -Ref: #roi118105 -Node: stats119117 -Ref: #stats119216 -Node: tags120004 -Ref: #tags120102 -Node: test120396 -Ref: #test120504 -Node: Add-on Commands121251 -Ref: #add-on-commands121368 -Node: ui122711 -Ref: #ui122799 -Node: web122853 -Ref: #web122956 -Node: iadd123072 -Ref: #iadd123183 -Node: interest123265 -Ref: #interest123372 -Node: ENVIRONMENT123612 -Ref: #environment123724 -Node: FILES124553 -Ref: #files-1124656 -Node: LIMITATIONS124869 -Ref: #limitations124988 -Node: TROUBLESHOOTING125730 -Ref: #troubleshooting125843 +Node: Recording transactions9137 +Ref: #recording-transactions9317 +Node: Reconciling9873 +Ref: #reconciling10016 +Node: Reporting12273 +Ref: #reporting12413 +Node: Migrating to a new file16412 +Ref: #migrating-to-a-new-file16560 +Node: OPTIONS16859 +Ref: #options16966 +Node: General options17336 +Ref: #general-options17461 +Node: Command options20231 +Ref: #command-options20382 +Node: Command arguments20780 +Ref: #command-arguments20927 +Node: Queries21807 +Ref: #queries21962 +Node: Special characters in arguments and queries25924 +Ref: #special-characters-in-arguments-and-queries26152 +Node: More escaping26603 +Ref: #more-escaping26765 +Node: Even more escaping27061 +Ref: #even-more-escaping27255 +Node: Less escaping27926 +Ref: #less-escaping28088 +Node: Unicode characters28333 +Ref: #unicode-characters28515 +Node: Input files29927 +Ref: #input-files30070 +Node: Output destination31999 +Ref: #output-destination32151 +Node: Output format32434 +Ref: #output-format32584 +Node: Regular expressions32969 +Ref: #regular-expressions33126 +Node: Smart dates34487 +Ref: #smart-dates34638 +Node: Report start & end date35999 +Ref: #report-start-end-date36171 +Node: Report intervals37609 +Ref: #report-intervals37774 +Node: Period expressions38164 +Ref: #period-expressions38324 +Node: Depth limiting42450 +Ref: #depth-limiting42594 +Node: Pivoting42936 +Ref: #pivoting43059 +Node: Valuation44735 +Ref: #valuation44837 +Node: -B Cost45017 +Ref: #b-cost45128 +Node: -V Market value45326 +Ref: #v-market-value45500 +Node: -X Market value in specified commodity46932 +Ref: #x-market-value-in-specified-commodity47171 +Node: --value Flexible valuation47347 +Ref: #value-flexible-valuation47573 +Node: Effect of --value on reports52078 +Ref: #effect-of---value-on-reports52294 +Node: Combining -B -V -X --value57840 +Ref: #combining--b--v--x---value58023 +Node: COMMANDS58059 +Ref: #commands58167 +Node: accounts59251 +Ref: #accounts59349 +Node: activity60048 +Ref: #activity60158 +Node: add60541 +Ref: #add60640 +Node: balance63379 +Ref: #balance63490 +Node: Classic balance report64948 +Ref: #classic-balance-report65121 +Node: Customising the classic balance report66490 +Ref: #customising-the-classic-balance-report66718 +Node: Colour support68794 +Ref: #colour-support68961 +Node: Flat mode69134 +Ref: #flat-mode69282 +Node: Depth limited balance reports69695 +Ref: #depth-limited-balance-reports69880 +Node: Percentages70336 +Ref: #percentages70502 +Node: Multicolumn balance report71639 +Ref: #multicolumn-balance-report71819 +Node: Budget report77081 +Ref: #budget-report77224 +Node: Nested budgets82426 +Ref: #nested-budgets82538 +Ref: #output-format-186019 +Node: balancesheet86097 +Ref: #balancesheet86233 +Node: balancesheetequity87616 +Ref: #balancesheetequity87765 +Node: cashflow88326 +Ref: #cashflow88454 +Node: check-dates89550 +Ref: #check-dates89677 +Node: check-dupes89956 +Ref: #check-dupes90080 +Node: close90373 +Ref: #close90487 +Node: close usage92009 +Ref: #close-usage92102 +Node: commodities94915 +Ref: #commodities95042 +Node: descriptions95124 +Ref: #descriptions95252 +Node: diff95433 +Ref: #diff95539 +Node: files96586 +Ref: #files96686 +Node: help96833 +Ref: #help96933 +Node: import98014 +Ref: #import98128 +Node: Importing balance assignments99021 +Ref: #importing-balance-assignments99169 +Node: incomestatement99818 +Ref: #incomestatement99951 +Node: notes101355 +Ref: #notes101468 +Node: payees101594 +Ref: #payees101700 +Node: prices101858 +Ref: #prices101964 +Node: print102305 +Ref: #print102415 +Node: print-unique107123 +Ref: #print-unique107249 +Node: register107534 +Ref: #register107661 +Node: Custom register output111833 +Ref: #custom-register-output111962 +Node: register-match113224 +Ref: #register-match113358 +Node: rewrite113709 +Ref: #rewrite113824 +Node: Re-write rules in a file115679 +Ref: #re-write-rules-in-a-file115813 +Node: Diff output format117023 +Ref: #diff-output-format117192 +Node: rewrite vs print --auto118284 +Ref: #rewrite-vs.-print---auto118463 +Node: roi119019 +Ref: #roi119117 +Node: stats120129 +Ref: #stats120228 +Node: tags121016 +Ref: #tags121114 +Node: test121408 +Ref: #test121516 +Node: Add-on Commands122263 +Ref: #add-on-commands122380 +Node: ui123723 +Ref: #ui123811 +Node: web123865 +Ref: #web123968 +Node: iadd124084 +Ref: #iadd124195 +Node: interest124277 +Ref: #interest124384 +Node: ENVIRONMENT124624 +Ref: #environment124736 +Node: FILES125565 +Ref: #files-1125668 +Node: LIMITATIONS125881 +Ref: #limitations126000 +Node: TROUBLESHOOTING126742 +Ref: #troubleshooting126855  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 0a6a8e136..f240d12b8 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -144,7 +144,7 @@ COMMON TASKS assets:bank:checking $1000 = $1000 assets:bank:savings $2000 = $2000 assets:cash $100 = $100 - liabilities:creditcard $-50 = $-$50 + liabilities:creditcard $-50 = $-50 equity:opening/closing balances These are start-of-day balances, ie whatever was in the account at @@ -525,8 +525,9 @@ OPTIONS --auto apply automated posting rules to modify transactions. --forecast - apply periodic transaction rules to generate future transac- - tions, to 6 months from now or report end date. + generate future transactions from periodic transaction rules, + 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 last one takes precedence. @@ -537,26 +538,26 @@ OPTIONS To see options for a particular command, including command-specific op- tions, run: hledger COMMAND -h. - Command-specific options must be written after the command name, eg: + Command-specific options must be written after the command name, eg: hledger print -x. - Additionally, if the command is an addon, you may need to put its op- - tions after a double-hyphen, eg: hledger ui -- --watch. Or, you can + Additionally, if the command is an addon, you may need to put its op- + tions after a double-hyphen, eg: hledger ui -- --watch. Or, you can run the addon executable directly: hledger-ui --watch. Command arguments - Most hledger commands accept arguments after the command name, which + Most hledger commands accept arguments after the command name, which are often a query, filtering the data in some way. - You can save a set of command line options/arguments in a file, and - then reuse them by writing @FILENAME as a command line argument. Eg: - hledger bal @foo.args. (To prevent this, eg if you have an argument - that begins with a literal @, precede it with --, eg: hledger bal -- + You can save a set of command line options/arguments in a file, and + then reuse them by writing @FILENAME as a command line argument. Eg: + hledger bal @foo.args. (To prevent this, eg if you have an argument + that begins with a literal @, precede it with --, eg: hledger bal -- @ARG). - Inside the argument file, each line should contain just one option or + Inside the argument file, each line should contain just one option or argument. Avoid the use of spaces, except inside quotes (or you'll see - a confusing error). Between a flag and its argument, use = (or noth- + a confusing error). Between a flag and its argument, use = (or noth- ing). Bad: assets depth:2 @@ -568,7 +569,7 @@ OPTIONS depth:2 -X=USD - For special characters (see below), use one less level of quoting than + For special characters (see below), use one less level of quoting than you would at the command prompt. Bad: -X"$" @@ -580,16 +581,16 @@ OPTIONS See also: Save frequently used options. Queries - One of hledger's strengths is being able to quickly report on precise - subsets of your data. Most commands accept an optional query expres- - sion, written as arguments after the command name, to filter the data - by date, account name or other criteria. The syntax is similar to a + One of hledger's strengths is being able to quickly report on precise + subsets of your data. Most commands accept an optional query expres- + sion, written as arguments after the command name, to filter the data + by date, account name or other criteria. The syntax is similar to a web search: one or more space-separated search terms, quotes to enclose - whitespace, prefixes to match specific fields, a not: prefix to negate + whitespace, prefixes to match specific fields, a not: prefix to negate the match. - We do not yet support arbitrary boolean combinations of search terms; - instead most commands show transactions/postings/accounts which match + We do not yet support arbitrary boolean combinations of search terms; + instead most commands show transactions/postings/accounts which match (or negatively match): o any of the description terms AND @@ -610,31 +611,31 @@ OPTIONS o match all the other terms. - The following kinds of search terms can be used. Remember these can + The following kinds of search terms can be used. Remember these can also be prefixed with not:, eg to exclude a particular subaccount. REGEX, acct:REGEX - match account names by this regular expression. (With no pre- + match account names by this regular expression. (With no pre- fix, acct: is assumed.) same as above amt:N, amt:N, amt:>=N - match postings with a single-commodity amount that is equal to, - less than, or greater than N. (Multi-commodity amounts are not + match postings with a single-commodity amount that is equal to, + less than, or greater than N. (Multi-commodity amounts are not tested, and will always match.) The comparison has two modes: if N is preceded by a + or - sign (or is 0), the two signed numbers - are compared. Otherwise, the absolute magnitudes are compared, + are compared. Otherwise, the absolute magnitudes are compared, ignoring sign. code:REGEX match by transaction code (eg check number) cur:REGEX - match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a par- + match postings or transactions including any amounts whose cur- + rency/commodity symbol is fully matched by REGEX. (For a par- tial match, use .*REGEX.*). Note, to match characters which are regex-significant, like the dollar sign ($), you need to prepend - \. And when using the command line you need to add one more - level of quoting to hide it from the shell, so eg do: hledger + \. And when using the command line you need to add one more + level of quoting to hide it from the shell, so eg do: hledger print cur:'\$' or hledger print cur:\\$. desc:REGEX @@ -642,20 +643,20 @@ OPTIONS date:PERIODEXPR match dates within the specified period. PERIODEXPR is a period - expression (with no report interval). Examples: date:2016, - date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the - --date2 command line flag is present, this matches secondary + expression (with no report interval). Examples: date:2016, + date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the + --date2 command line flag is present, this matches secondary dates instead. date2:PERIODEXPR match secondary dates within the specified period. depth:N - match (or display, depending on command) accounts at or above + match (or display, depending on command) accounts at or above this depth note:REGEX - match transaction notes (part of description right of |, or + match transaction notes (part of description right of |, or whole description when there's no |) payee:REGEX @@ -669,35 +670,35 @@ OPTIONS match unmarked, pending, or cleared transactions respectively tag:REGEX[=REGEX] - match by tag name, and optionally also by tag value. Note a - tag: query is considered to match a transaction if it matches - any of the postings. Also remember that postings inherit the + match by tag name, and optionally also by tag value. Note a + tag: query is considered to match a transaction if it matches + any of the postings. Also remember that postings inherit the tags of their parent transaction. The following special search term is used automatically in hledger-web, only: inacct:ACCTNAME - tells hledger-web to show the transaction register for this ac- + tells hledger-web to show the transaction register for this ac- count. Can be filtered further with acct etc. Some of these can also be expressed as command-line options (eg depth:2 - is equivalent to --depth 2). Generally you can mix options and query - arguments, and the resulting query will be their intersection (perhaps + is equivalent to --depth 2). Generally you can mix options and query + arguments, and the resulting query will be their intersection (perhaps excluding the -p/--period option). Special characters in arguments and queries In shell command lines, option and argument values which contain "prob- lematic" characters, ie spaces, and also characters significant to your - shell such as <, >, (, ), | and $, should be escaped by enclosing them + shell such as <, >, (, ), | and $, should be escaped by enclosing them in quotes or by writing backslashes before the characters. Eg: - hledger register -p 'last year' "accounts receivable (receiv- + hledger register -p 'last year' "accounts receivable (receiv- able|payable)" amt:\>100. More escaping Characters significant both to the shell and in regular expressions may - need one extra level of escaping. These include parentheses, the pipe + need one extra level of escaping. These include parentheses, the pipe symbol and the dollar sign. Eg, to match the dollar symbol, bash users should do: @@ -708,9 +709,9 @@ OPTIONS hledger balance cur:\\$ Even more escaping - When hledger runs an addon executable (eg you type hledger ui, hledger - runs hledger-ui), it de-escapes command-line options and arguments - once, so you might need to triple-escape. Eg in bash, running the ui + When hledger runs an addon executable (eg you type hledger ui, hledger + runs hledger-ui), it de-escapes command-line options and arguments + once, so you might need to triple-escape. Eg in bash, running the ui command and matching the dollar sign, it's: hledger ui cur:'\\$' @@ -735,8 +736,8 @@ OPTIONS hledger-ui cur:\\$ Less escaping - Inside an argument file, or in the search field of hledger-ui or - hledger-web, or at a GHCI prompt, you need one less level of escaping + Inside an argument file, or in the search field of hledger-ui or + hledger-web, or at a GHCI prompt, you need one less level of escaping than at the command line. And backslashes may work better than quotes. Eg: @@ -745,41 +746,41 @@ OPTIONS Unicode characters hledger is expected to handle non-ascii characters correctly: - o they should be parsed correctly in input files and on the command - line, by all hledger tools (add, iadd, hledger-web's search/add/edit + o they should be parsed correctly in input files and on the command + line, by all hledger tools (add, iadd, hledger-web's search/add/edit forms, etc.) - o they should be displayed correctly by all hledger tools, and on- + o they should be displayed correctly by all hledger tools, and on- screen alignment should be preserved. This requires a well-configured environment. Here are some tips: - o A system locale must be configured, and it must be one that can de- - code the characters being used. In bash, you can set a locale like - this: export LANG=en_US.UTF-8. There are some more details in Trou- - bleshooting. This step is essential - without it, hledger will quit - on encountering a non-ascii character (as with all GHC-compiled pro- + o A system locale must be configured, and it must be one that can de- + code the characters being used. In bash, you can set a locale like + this: export LANG=en_US.UTF-8. There are some more details in Trou- + bleshooting. This step is essential - without it, hledger will quit + on encountering a non-ascii character (as with all GHC-compiled pro- grams). - o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) must support unicode o the terminal must be using a font which includes the required unicode glyphs - o the terminal should be configured to display wide characters as dou- + o the terminal should be configured to display wide characters as dou- ble width (for report alignment) - o on Windows, for best results you should run hledger in the same kind - of environment in which it was built. Eg hledger built in the stan- - dard CMD.EXE environment (like the binaries on our download page) - might show display problems when run in a cygwin or msys terminal, + o on Windows, for best results you should run hledger in the same kind + of environment in which it was built. Eg hledger built in the stan- + dard CMD.EXE environment (like the binaries on our download page) + might show display problems when run in a cygwin or msys terminal, and vice versa. (See eg #961). Input files hledger reads transactions from a data file (and the add command writes to it). By default this file is $HOME/.hledger.journal (or on Windows, - something like C:/Users/USER/.hledger.journal). You can override this + something like C:/Users/USER/.hledger.journal). You can override this with the $LEDGER_FILE environment variable: $ setenv LEDGER_FILE ~/finance/2016.journal @@ -793,24 +794,24 @@ OPTIONS $ cat some.journal | hledger -f- - Usually the data file is in hledger's journal format, but it can also - be one of several other formats, listed below. hledger detects the - format automatically based on the file extension, or if that is not + Usually the data file is in hledger's journal format, but it can also + be one of several other formats, listed below. hledger detects the + format automatically based on the file extension, or if that is not recognised, by trying each built-in "reader" in turn: Reader: Reads: Used for file extensions: ----------------------------------------------------------------------------- - journal hledger's journal format, also .journal .j .hledger .ledger + journal hledger's journal format, also .journal .j .hledger .ledger some Ledger journals - time- timeclock files (precise time .timeclock + time- timeclock files (precise time .timeclock clock logging) timedot timedot files (approximate time .timedot logging) - csv comma-separated values (data .csv + csv comma-separated values (data .csv interchange) - If needed (eg to ensure correct error messages when a file has the - "wrong" extension), you can force a specific reader/format by prepend- + If needed (eg to ensure correct error messages when a file has the + "wrong" extension), you can force a specific reader/format by prepend- ing it to the file path with a colon. Examples: $ hledger -f csv:/some/csv-file.dat stats @@ -821,23 +822,23 @@ OPTIONS o directives in one file will not affect the other files - o balance assertions will not see any account balances from previous + o balance assertions will not see any account balances from previous files If you need those, either use the include directive, or concatenate the files, eg: cat a.journal b.journal | hledger -f- CMD. Output destination - Some commands (print, register, stats, the balance commands) can write - their output to a destination other than the console. This is con- + Some commands (print, register, stats, the balance commands) can write + their output to a destination other than the console. This is con- trolled by the -o/--output-file option. $ hledger balance -o - # write to stdout (the default) $ hledger balance -o FILE # write to FILE Output format - Some commands can write their output in other formats. Eg print and - register can output CSV, and the balance commands can output CSV or + Some commands can write their output in other formats. Eg print and + register can output CSV, and the balance commands can output CSV or HTML. This is controlled by the -O/--output-format option, or by spec- ifying a .csv or .html file extension with -o/--output-file. @@ -847,54 +848,54 @@ OPTIONS Regular expressions hledger uses regular expressions in a number of places: - o query terms, on the command line and in the hledger-web search form: + o query terms, on the command line and in the hledger-web search form: REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX o CSV rules conditional blocks: if REGEX ... - o account alias directives and options: alias /REGEX/ = REPLACEMENT, + o account alias directives and options: alias /REGEX/ = REPLACEMENT, --alias /REGEX/=REPLACEMENT - hledger's regular expressions come from the regex-tdfa library. In + hledger's regular expressions come from the regex-tdfa library. In general they: o are case insensitive - o are infix matching (do not need to match the entire thing being + o are infix matching (do not need to match the entire thing being matched) o are POSIX extended regular expressions o also support GNU word boundaries (\<, \>, \b, \B) - o and parenthesised capturing groups and numeric backreferences in re- + o and parenthesised capturing groups and numeric backreferences in re- placement strings o do not support mode modifiers like (?s) Some things to note: - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, these are not required. - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts with the dollar sign in hledger-web, write cur:\$. - o On the command line, some metacharacters like $ have a special mean- + o On the command line, some metacharacters like $ have a special mean- ing to the shell and so must be escaped at least once more. See Spe- cial characters. Smart dates hledger's user interfaces accept a flexible "smart date" syntax (unlike - dates in the journal file). Smart dates allow some english words, can - be relative to today's date, and can have less-significant date parts + dates in the journal file). Smart dates allow some english words, can + be relative to today's date, and can have less-significant date parts omitted (defaulting to 1). Examples: - 2004/10/1, 2004-01-01, exact date, several separators allowed. Year + 2004/10/1, 2004-01-01, exact date, several separators allowed. Year 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 2004 start of year 2004/10 start of month @@ -909,44 +910,44 @@ OPTIONS 20181201 8 digit YYYYMMDD with valid year month and day 201812 6 digit YYYYMM with valid year and month - Counterexamples - malformed digit sequences might give surprising re- + Counterexamples - malformed digit sequences might give surprising re- sults: - 201813 6 digits with an invalid month is parsed as start of + 201813 6 digits with an invalid month is parsed as start of 6-digit year - 20181301 8 digits with an invalid month is parsed as start of + 20181301 8 digits with an invalid month is parsed as start of 8-digit year 20181232 8 digits with an invalid day gives an error 201801012 9+ digits beginning with a valid YYYYMMDD gives an error Report start & end date - Most hledger reports show the full span of time represented by the + Most hledger reports show the full span of time represented by the journal data, by default. So, the effective report start and end dates - will be the earliest and latest transaction or posting dates found in + will be the earliest and latest transaction or posting dates found in the journal. - Often you will want to see a shorter time span, such as the current - month. You can specify a start and/or end date using -b/--begin, + Often you will want to see a shorter time span, such as the current + month. You can specify a start and/or end date using -b/--begin, -e/--end, -p/--period or a date: query (described below). All of these accept the smart date syntax. Some notes: - o As in Ledger, end dates are exclusive, so you need to write the date + o As in Ledger, end dates are exclusive, so you need to write the date after the last day you want to include. - o As noted in reporting options: among start/end dates specified with + o As noted in reporting options: among start/end dates specified with options, the last (i.e. right-most) option takes precedence. - o The effective report start and end dates are the intersection of the - start/end dates from options and that from date: queries. That is, - date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the + o The effective report start and end dates are the intersection of the + start/end dates from options and that from date: queries. That is, + date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the smallest common time span. Examples: -b 2016/3/17 begin on St. Patrick's day 2016 - -e 12/1 end at the start of december 1st of the current year + -e 12/1 end at the start of december 1st of the current year (11/30 will be the last date included) -b thismonth all transactions on or after the 1st of the current month -p thismonth all transactions in the current month @@ -957,31 +958,31 @@ OPTIONS Report intervals A report interval can be specified so that commands like register, bal- - ance and activity will divide their reports into multiple subperiods. - The basic intervals can be selected with one of -D/--daily, - -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- - plex intervals may be specified with a period expression. Report in- + ance and activity will divide their reports into multiple subperiods. + The basic intervals can be selected with one of -D/--daily, + -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- + plex intervals may be specified with a period expression. Report in- tervals can not be specified with a query. Period expressions - The -p/--period option accepts period expressions, a shorthand way of + The -p/--period option accepts period expressions, a shorthand way of expressing a start date, end date, and/or report interval all at once. - Here's a basic period expression specifying the first quarter of 2009. - Note, hledger always treats start dates as inclusive and end dates as + Here's a basic period expression specifying the first quarter of 2009. + Note, hledger always treats start dates as inclusive and end dates as exclusive: -p "from 2009/1/1 to 2009/4/1" - Keywords like "from" and "to" are optional, and so are the spaces, as - long as you don't run two dates together. "to" can also be written as + Keywords like "from" and "to" are optional, and so are the spaces, as + long as you don't run two dates together. "to" can also be written as "-". These are equivalent to the above: -p "2009/1/1 2009/4/1" -p2009/1/1to2009/4/1 -p2009/1/1-2009/4/1 - Dates are smart dates, so if the current year is 2009, the above can + Dates are smart dates, so if the current year is 2009, the above can also be written as: -p "1/1 4/1" @@ -995,63 +996,63 @@ OPTIONS 1, 2009 -p "from 2009/1" the same -p "from 2009" the same - - -p "to 2009" everything before january + -p "to 2009" everything before january 1, 2009 - A single date with no "from" or "to" defines both the start and end + A single date with no "from" or "to" defines both the start and end date like so: - -p "2009" the year 2009; equivalent + -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of jan; equiva- + -p "2009/1" the month of jan; equiva- lent to "2009/1/1 to 2009/2/1" - -p "2009/1/1" just that day; equivalent + + -p "2009/1/1" just that day; equivalent to "2009/1/1 to 2009/1/2" - The argument of -p can also begin with, or be, a report interval ex- + The argument of -p can also begin with, or be, a report interval ex- pression. The basic report intervals are daily, weekly, monthly, quar- - terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y - flags. Between report interval and start/end dates (if any), the word + terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y + flags. Between report interval and start/end dates (if any), the word in is optional. Examples: -p "weekly from 2009/1/1 to 2009/4/1" -p "monthly in 2008" -p "quarterly" - Note that weekly, monthly, quarterly and yearly intervals will always + Note that weekly, monthly, quarterly and yearly intervals will always start on the first day on week, month, quarter or year accordingly, and - will end on the last day of same period, even if associated period ex- + will end on the last day of same period, even if associated period ex- pression specifies different explicit start and end date. For example: - -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- + -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- to 2009/4/1" day - -p "monthly in starts on 2018/11/01 + -p "monthly in starts on 2018/11/01 2008/11/25" - -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, + -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009 -p "yearly from starts on 2009/01/01, first day of 2009 2009-12-29" - The following more complex report intervals are also supported: bi- + The following more complex report intervals are also supported: bi- weekly, bimonthly, every day|week|month|quarter|year, every N days|weeks|months|quarters|years. - All of these will start on the first day of the requested period and + All of these will start on the first day of the requested period and end on the last one, as described above. Examples: - -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, + -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, 2008/03/01, ... -p "every 2 weeks" starts on closest preceding Monday - -p "every 5 month from periods will have boundaries on 2009/03/01, + -p "every 5 month from periods will have boundaries on 2009/03/01, 2009/03" 2009/08/01, ... - If you want intervals that start on arbitrary day of your choosing and + If you want intervals that start on arbitrary day of your choosing and span a week, month or year, you need to use any of the following: every Nth day of week, every , every Nth day [of month], every @@ -1062,44 +1063,43 @@ OPTIONS -p "every 2nd day of periods will go from Tue to Tue week" - -p "every Tue" same - -p "every 15th day" period boundaries will be on 15th of each + -p "every 15th day" period boundaries will be on 15th of each month - -p "every 2nd Monday" period boundaries will be on second Monday of + -p "every 2nd Monday" period boundaries will be on second Monday of each month -p "every 11/05" yearly periods with boundaries on 5th of Nov -p "every 5th Nov" same -p "every Nov 5th" same - Show historical balances at end of 15th each month (N is exclusive end + Show historical balances at end of 15th each month (N is exclusive end date): hledger balance -H -p "every 16th day" - Group postings from start of wednesday to end of next tuesday (N is + Group postings from start of wednesday to end of next tuesday (N is start date and exclusive end date): hledger register checking -p "every 3rd day of week" Depth limiting With the --depth N option (short form: -N), commands like account, bal- - ance and register will show only the uppermost accounts in the account - tree, down to level N. Use this when you want a summary with less de- + ance and register will show only the uppermost accounts in the account + tree, down to level N. Use this when you want a summary with less de- tail. This flag has the same effect as a depth: query argument (so -2, --depth=2 or depth:2 are basically equivalent). Pivoting Normally hledger sums amounts, and organizes them in a hierarchy, based - on account name. The --pivot FIELD option causes it to sum and orga- - nize hierarchy based on the value of some other field instead. FIELD + on account name. The --pivot FIELD option causes it to sum and orga- + nize hierarchy based on the value of some other field instead. FIELD can be: code, description, payee, note, or the full name (case insensi- tive) of any tag. As with account names, values containing colon:sepa- rated:parts will be displayed hierarchically in reports. - --pivot is a general option affecting all reports; you can think of + --pivot is a general option affecting all reports; you can think of hledger transforming the journal before any other processing, replacing - every posting's account name with the value of the specified field on + every posting's account name with the value of the specified field on that posting, inheriting it from the transaction or using a blank value if it's not present. @@ -1125,7 +1125,7 @@ OPTIONS -------------------- 0 - One way to show only amounts with a member: value (using a query, de- + One way to show only amounts with a member: value (using a query, de- scribed below): $ hledger balance --pivot member tag:member=. @@ -1133,7 +1133,7 @@ OPTIONS -------------------- -2 EUR - Another way (the acct: query matches against the pivoted "account + Another way (the acct: query matches against the pivoted "account name"): $ hledger balance --pivot member acct:. @@ -1144,23 +1144,23 @@ OPTIONS Valuation -B: Cost The -B/--cost flag converts amounts to their cost (or selling price) at - transaction time, if they have a transaction price specified. This + transaction time, if they have a transaction price specified. This flag is equivalent to --value=cost, described below. -V: Market value The -V/--market flag converts reported amounts to their market value in - a default valuation commodity, using the market prices in effect on a - default valuation date. For single period reports, the valuation date - is today (equivalent to --value=now); for multiperiod reports, it is + a default valuation commodity, using the market prices in effect on a + default valuation date. For single period reports, the valuation date + is today (equivalent to --value=now); for multiperiod reports, it is the last day of each subperiod (equivalent to --value=end). The default valuation commodity is the one referenced in the latest ap- - plicable market price dated on or before the valuation date. If most - of your P declarations lead to a single home currency, this will usu- + plicable market price dated on or before the valuation date. If most + of your P declarations lead to a single home currency, this will usu- ally be what you want. (To specify the commodity, see -X below.) Note that in hledger, market prices are always declared explicitly with - P directives; we do not infer them from transaction prices as Ledger + P directives; we do not infer them from transaction prices as Ledger does. Here's a quick example of -V: @@ -1186,15 +1186,15 @@ OPTIONS $ hledger -f t.j bal -N euros -V -e 2016/11/4 $110.00 assets:euros - What are they worth after 2016/12/21 ? (no report end date specified, + What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) $ hledger -f t.j bal -N euros -V $103.00 assets:euros -X: Market value in specified commodity - The -X/--exchange option is like -V, except it specifies the target - commodity you would like to convert to. It is equivalent to + The -X/--exchange option is like -V, except it specifies the target + commodity you would like to convert to. It is equivalent to --value=now,COMM or --value=end,COMM. --value: Flexible valuation @@ -1202,10 +1202,11 @@ OPTIONS -B, -V and -X are special cases of the more general --value 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. Shows amounts converted to: - 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 current market prices - default valuation commodity (or COMM) using market prices at some date @@ -1214,43 +1215,48 @@ OPTIONS valuation date: --value=cost - Convert amounts to cost, using the prices recorded in transac- + Convert amounts to cost, using the prices recorded in transac- tions. + --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 Convert amounts to their value in a default valuation commodity, - using market prices on the last day of the report period (or if + using market prices on the last day of the report period (or if unspecified, the journal's end date); or in multiperiod reports, market prices on the last day of each subperiod. --value=now - Convert amounts to their value in default valuation commodity + Convert amounts to their value in default valuation commodity using current market prices (as of when report is generated). --value=YYYY-MM-DD - Convert amounts to their value in default valuation commodity + Convert amounts to their value in default valuation commodity using market prices on this date. - The default valuation commodity is the commodity mentioned in the most + The default valuation commodity is the commodity mentioned in the most recent applicable market price declaration. When all your price decla- - rations lead to a single home currency, this will usually do what you + rations lead to a single home currency, this will usually do what you want. To select a different valuation commodity, add the optional ,COMM part: - a comma, then the target commodity's symbol. Eg: --value=now,EUR. + a comma, then the target commodity's symbol. Eg: --value=now,EUR. hledger will do its best to convert amounts to this commodity, using: o declared prices (from source commodity to valuation commodity) - o reverse prices (declared prices from valuation to source commodity, + o reverse prices (declared prices from valuation to source commodity, inverted) - o indirect prices (prices calculated from the shortest chain of de- + o indirect prices (prices calculated from the shortest chain of de- clared or reverse prices from source to valuation commodity) in that order. - Here are some examples showing the effect of --value as seen with + Here are some examples showing the effect of --value as seen with print: P 2000-01-01 A 1 B @@ -1288,7 +1294,7 @@ OPTIONS 2000-02-01 (a) 2 B - With no report period specified, that shows the value as of the last + With no report period specified, that shows the value as of the last day of the journal (2000-03-01): $ hledger -f- print --value=end @@ -1325,7 +1331,7 @@ OPTIONS 2000-03-01 (a) 1 B - You may need to explicitly set a commodity's display style, when re- + You may need to explicitly set a commodity's display style, when re- verse prices are used. Eg this output might be surprising: P 2000-01-01 A 2B @@ -1339,10 +1345,10 @@ OPTIONS a 0 b 0 - Explanation: because there's no amount or commodity directive specify- - ing a display style for A, 0.5A gets the default style, which shows no + Explanation: because there's no amount or commodity directive specify- + ing a display style for A, 0.5A gets the default style, which shows no decimal digits. Because the displayed amount looks like zero, the com- - modity symbol and minus sign are not displayed either. Adding a com- + modity symbol and minus sign are not displayed either. Adding a com- modity directive sets a more useful display style for A: P 2000-01-01 A 2B @@ -1358,68 +1364,76 @@ OPTIONS b -0.50A Effect of --value on reports - Here is a reference for how --value currently affects each part of - hledger's reports. It's work in progress, but may be useful for trou- - bleshooting or reporting bugs. See also the definitions and notes be- - low. If you find problems, please report them, ideally with a repro- + Here is a reference for how --value currently affects each part of + hledger's reports. It's work in progress, but may be useful for trou- + bleshooting or reporting bugs. See also the definitions and notes be- + low. If you find problems, please report them, ideally with a repro- ducible example. Related: #329, #1083. - Report type -B, -V, -X --value=end --value=DATE, - --value=cost --value=now - ------------------------------------------------------------------------------------- + Report type -B, -V, -X --value=then --value=end --value=DATE, + --value=cost --value=now + ------------------------------------------------------------------------------------------ print - posting cost value at report value at report value at - amounts end or today or journal end DATE/today - balance asser- unchanged unchanged unchanged unchanged - tions / as- - signments + posting cost value at re- value at value at re- value at + amounts port end or posting date port or DATE/today + today journal end + balance as- unchanged unchanged unchanged unchanged unchanged + sertions / + assignments register - starting bal- cost value at day value at day value at - ance (with -H) before report before report DATE/today - or journal or journal - start start - posting cost value at report value at report value at - amounts (no end or today or journal end DATE/today - report inter- - val) - summary post- summarised value at period value at period value at - ing amounts cost ends ends DATE/today - (with report - interval) - running to- sum/average of sum/average of sum/average of sum/average - tal/average displayed val- displayed val- displayed val- of displayed - ues ues ues values - - balance (bs, - bse, cf, is..) - balances (no sums of costs value at report value at report value at - report inter- end or today of or journal end DATE/today of - val) sums of post- of sums of sums of post- - ings postings ings - - balances (with sums of costs value at period value at period value at - report inter- ends of sums of ends of sums of DATE/today of - val) postings postings sums of post- - ings - starting bal- sums of costs sums of post- sums of post- sums of post- - ances (with of postings ings before re- ings before re- ings before - report inter- before report port start port start report start - val and -H) start - budget amounts like balances like balances like balances like balances - with --budget - grand total sum of dis- sum of dis- sum of dis- sum of dis- - (no report in- played values played values played values played values + starting cost value at day not supported value at day value at + balance before re- before re- DATE/today + (with -H) port or port or + journal journal + start start + posting cost value at re- value at value at re- value at + amounts (no port end or posting date port or DATE/today + report in- today journal end terval) - row totals/av- sums/averages sums/averages sums/averages sums/averages - erages (with of displayed of displayed of displayed of displayed - report inter- values values values values - val) - column totals sums of dis- sums of dis- sums of dis- sums of dis- - played values played values played values played values - grand to- sum/average of sum/average of sum/average of sum/average - tal/average column totals column totals column totals of column to- - tals + summary summarised value at pe- sum of post- value at pe- value at + posting cost riod ends ings in in- riod ends DATE/today + amounts terval, val- + (with report ued at inter- + interval) val start + running to- sum/average sum/average sum/average sum/average sum/average + tal/average of displayed of displayed of displayed of displayed of displayed + values values values values values + + balance (bs, + bse, cf, + is..) + balances (no sums of value at re- not supported value at re- value at + report in- costs port end or port or DATE/today of + terval) today of journal end sums of post- + sums of of sums of ings + postings postings + balances sums of value at pe- not supported value at pe- value at + (with report costs riod ends of riod ends of DATE/today of + interval) sums of sums of sums of post- + postings postings ings + starting sums of sums of not supported sums of sums of post- + balances costs of postings be- postings be- ings before + (with report postings be- fore report fore report report start + interval and fore report start start + -H) start + budget like bal- like bal- not supported like bal- like balances + amounts with ances ances ances + --budget + grand total sum of dis- sum of dis- not supported sum of dis- sum of dis- + (no report played val- played val- played val- played values + interval) ues ues ues + row to- sums/aver- sums/aver- not supported sums/aver- sums/averages + tals/aver- ages of dis- ages of dis- ages of dis- of displayed + ages (with played val- played val- played val- values + report in- ues ues ues + terval) + column to- sums of dis- sums of dis- not supported sums of dis- sums of dis- + tals played val- played val- played val- played values + ues ues ues + grand to- sum/average sum/average not supported sum/average sum/average + tal/average of column of column of column of column to- + totals totals totals tals Additional notes @@ -1880,14 +1894,12 @@ COMMANDS (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 - report end date, for all columns (not the price on each column's end - date). - - Eliding of boring parent accounts in tree mode, as in the classic bal- - ance report, is not yet supported in multicolumn reports. + The --transpose flag can be used to exchange the rows and columns of a + multicolumn report. Budget report With --budget, extra columns are displayed showing budget goals for @@ -2542,37 +2554,38 @@ COMMANDS plied but not written, it will not appear in the output. You can use the -x/--explicit flag to make all amounts and transaction prices ex- plicit, 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 - (these can arise when a multi-commodity transaction has an implicit - amount) to be split into multiple single-commodity postings, keeping + Note, -x/--explicit will cause postings with a multi-commodity amount + (these can arise when a multi-commodity transaction has an implicit + amount) to be split into multiple single-commodity postings, keeping the output parseable. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost using that price. This can be used for troubleshooting. - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is no similar-enough match, no transaction will be shown. With --new, for each FILE being read, hledger reads (and writes) a spe- - cial state file (.latest.FILE in the same directory), containing the - latest transaction date(s) that were seen last time FILE was read. - When this file is found, only transactions with newer dates (and new - transactions on the latest date) are printed. This is useful for ig- - noring already-seen entries in import data, such as downloaded CSV + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for ig- + noring already-seen entries in import data, such as downloaded CSV files. Eg: $ hledger -f bank1.csv print --new (shows transactions added since last print --new on this file) - This assumes that transactions added to FILE always have same or in- - creasing dates, and that transactions on the same day do not get re- + This assumes that transactions added to FILE always have same or in- + creasing dates, and that transactions on the same day do not get re- ordered. See also the import command. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -2589,20 +2602,20 @@ COMMANDS "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) print-unique @@ -2626,7 +2639,7 @@ COMMANDS Show postings and their running total. The register command displays postings in date order, one per line, and - their running total. This is typically used with a query selecting a + their running total. This is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -2637,8 +2650,8 @@ COMMANDS With --date2, it shows and sorts by secondary date instead. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -2648,18 +2661,18 @@ COMMANDS The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one ac- + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- count and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account to- + bers. It's also useful to show postings on the checking account to- gether with the related account: $ hledger register --related --invert assets:checking @@ -2671,7 +2684,7 @@ COMMANDS 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -2688,7 +2701,7 @@ COMMANDS 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth op- + Often, you'll want to see just one line per interval. The --depth op- tion helps with this, causing subaccounts to be aggregated: $ hledger register --monthly assets --depth 1h @@ -2696,17 +2709,17 @@ COMMANDS 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of in- - tervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of in- + tervals. This ensures that the first and last intervals are full length and comparable to the others in the report. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not a bash shell variable) or by using the --width/-w option. - The description and account columns normally share the space equally + The description and account columns normally share the space equally (about half of (width - 40) each). You can adjust this by adding a de- scription width as part of --width's argument, comma-separated: --width W,D . Here's a diagram (won't display correctly in --help): @@ -2724,27 +2737,27 @@ COMMANDS $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. register-match register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. If there are multiple equally - good matches, it shows the most recent. Query options (options, not - arguments) can be used to restrict the search space. Helps ledger-au- + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps ledger-au- tosync detect already-seen transactions when importing. rewrite rewrite Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print + For now the only rewrite available is adding new postings, like print --auto. This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds + the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- + posting amounts can be fixed, or a multiplier of the existing transac- tion's first posting amount. Examples: @@ -2760,7 +2773,7 @@ COMMANDS (reserve:grocery) *0.25 ; reserve 25% for grocery (reserve:) *0.25 ; reserve 25% for grocery - Note the single quotes to protect the dollar sign from bash, and the + Note the single quotes to protect the dollar sign from bash, and the two spaces between account and amount. More: @@ -2770,16 +2783,16 @@ COMMANDS $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - Argument for --add-posting option is a usual posting of transaction - with an exception for amount specification. More precisely, you can + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can use '*' (star symbol) before the amount to indicate that that this is a - factor for an amount of original matched posting. If the amount in- + factor for an amount of original matched posting. If the amount in- cludes a commodity name, the new posting amount will be in the new com- - modity; otherwise, it will be in the matched posting amount's commod- + modity; otherwise, it will be in the matched posting amount's commod- ity. Re-write rules in a file - During the run this tool will execute so called "Automated Transac- + During the run this tool will execute so called "Automated Transac- tions" found in any journal it process. I.e instead of specifying this operations in command line you can put them in a journal file. @@ -2794,7 +2807,7 @@ COMMANDS budget:gifts *-1 assets:budget *1 - Note that '=' (equality symbol) that is used instead of date in trans- + Note that '=' (equality symbol) that is used instead of date in trans- actions you usually write. It indicates the query by which you want to match the posting to add new ones. @@ -2807,12 +2820,12 @@ COMMANDS --add-posting 'assets:budget *1' \ > rewritten-tidy-output.journal - It is important to understand that relative order of such entries in - journal is important. You can re-use result of previously added post- + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- ings. Diff output format - To use this tool for batch modification of your journal files you may + To use this tool for batch modification of your journal files you may find useful output in form of unified diff. $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' @@ -2836,10 +2849,10 @@ COMMANDS If you'll pass this through patch tool you'll get transactions contain- ing the posting that matches your query be updated. Note that multiple - files might be update according to list of input files specified via + files might be update according to list of input files specified via --file options and include directives inside of these files. - Be careful. Whole transaction being re-formatted in a style of output + Be careful. Whole transaction being re-formatted in a style of output from hledger print. See also: @@ -2847,48 +2860,48 @@ COMMANDS https://github.com/simonmichael/hledger/issues/99 rewrite vs. print --auto - This command predates print --auto, and currently does much the same + This command predates print --auto, and currently does much the same thing, but with these differences: - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect only child files. - o rewrite's query limits which transactions can be rewritten; all are + o rewrite's query limits which transactions can be rewritten; all are printed. print --auto's query limits which transactions are printed. - o rewrite applies rules specified on command line or in the journal. + o rewrite applies rules specified on command line or in the journal. print --auto applies rules specified in the journal. roi roi - Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. - This command assumes that you have account(s) that hold nothing but + This command assumes that you have account(s) that hold nothing but your investments and whenever you record current appraisal/valuation of these investments you offset unrealized profit and loss into account(s) that, again, hold nothing but unrealized profit and loss. - Any transactions affecting balance of investment account(s) and not - originating from unrealized profit and loss account(s) are assumed to + Any transactions affecting balance of investment account(s) and not + originating from unrealized profit and loss account(s) are assumed to be your investments or withdrawals. - At a minimum, you need to supply a query (which could be just an ac- + At a minimum, you need to supply a query (which could be just an ac- count name) to select your investments with --inv, and another query to identify your profit and loss transactions with --pnl. - It will compute and display the internalized rate of return (IRR) and - time-weighted rate of return (TWR) for your investments for the time - period requested. Both rates of return are annualized before display, + It will compute and display the internalized rate of return (IRR) and + time-weighted rate of return (TWR) for your investments for the time + period requested. Both rates of return are annualized before display, regardless of the length of reporting interval. stats stats Show some journal statistics. - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report for each report period. Example: @@ -2906,14 +2919,14 @@ COMMANDS Commodities : 1 ($) Market prices : 12 ($) - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. tags tags - List all the tag names used in the journal. With a TAGREGEX argument, - only tag names matching the regular expression (case insensitive) are - shown. With QUERY arguments, only transactions matching the query are + List all the tag names used in the journal. With a TAGREGEX argument, + only tag names matching the regular expression (case insensitive) are + shown. With QUERY arguments, only transactions matching the query are considered. With --values flag, the tags' unique values are listed in- stead. @@ -2921,13 +2934,13 @@ COMMANDS test Run built-in unit tests. - This command runs the unit tests built in to hledger and hledger-lib, - printing the results on stdout. If any test fails, the exit code will + This command runs the unit tests built in to hledger and hledger-lib, + printing the results on stdout. If any test fails, the exit code will be non-zero. - This is mainly used by hledger developers, but you can also use it to - sanity-check the installed hledger executable on your platform. All - tests are expected to pass - if you ever see a failure, please report + This is mainly used by hledger developers, but you can also use it to + sanity-check the installed hledger executable on your platform. All + tests are expected to pass - if you ever see a failure, please report as a bug! This command also accepts tasty test runner options, written after a -- @@ -2936,35 +2949,35 @@ COMMANDS $ hledger test -- -pData.Amount --color=never - For help on these, see https://github.com/feuerbach/tasty#options (-- + For help on these, see https://github.com/feuerbach/tasty#options (-- --help currently doesn't show them). Add-on Commands - hledger also searches for external add-on commands, and will include + hledger also searches for external add-on commands, and will include these in the commands list. These are programs or scripts in your PATH - whose name starts with hledger- and ends with a recognised file exten- + whose name starts with hledger- and ends with a recognised file exten- sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). - Add-ons can be invoked like any hledger command, but there are a few + Add-ons can be invoked like any hledger command, but there are a few things to be aware of. Eg if the hledger-web add-on is installed, - o hledger -h web shows hledger's help, while hledger web -h shows + o hledger -h web shows hledger's help, while hledger web -h shows hledger-web's help. - o Flags specific to the add-on must have a preceding -- to hide them - from hledger. So hledger web --serve --port 9000 will be rejected; + o Flags specific to the add-on must have a preceding -- to hide them + from hledger. So hledger web --serve --port 9000 will be rejected; you must use hledger web -- --serve --port 9000. o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger (and - haskell) library functions that built-in commands do, for command-line + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger (and + haskell) library functions that built-in commands do, for command-line options, journal parsing, reporting, etc. - Two important add-ons are the hledger-ui and hledger-web user inter- + Two important add-ons are the hledger-ui and hledger-web user inter- faces. These are maintained and released along with hledger: ui @@ -2983,23 +2996,23 @@ COMMANDS hledger-interest generates interest transactions for an account accord- ing to various schemes. - A few more experimental or old add-ons can be found in hledger's bin/ + A few more experimental or old add-ons can be found in hledger's bin/ directory. These are typically prototypes and not guaranteed to work. ENVIRONMENT - COLUMNS The screen width used by the register command. Default: the + COLUMNS The screen width used by the register command. Default: the full terminal width. 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). - 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- + 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- 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 - 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- vironment.plist file containing @@ -3010,13 +3023,13 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). LIMITATIONS - The need to precede addon command options with -- when invoked from + The need to precede addon command options with -- when invoked from hledger is awkward. When input data contains non-ascii characters, a suitable system locale @@ -3032,33 +3045,33 @@ LIMITATIONS In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. - Not all of Ledger's journal file syntax is supported. See file format + Not all of Ledger's journal file syntax is supported. See file format differences. - On large data files, hledger is slower and uses more memory than + On large data files, hledger is slower and uses more memory than Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and re- - member you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and re- + member you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command 'hledger' found" stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, + be added to your PATH environment variable. Eg on unix-like systems, that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors In order to handle non-ascii letters and symbols (like ), hledger needs an appropriate locale. This is usually configured system-wide; you can also configure it temporarily. The locale may need to be one that sup- - ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, I'm not sure yet). Here's an example of setting the locale temporarily, on ubuntu @@ -3077,7 +3090,7 @@ TROUBLESHOOTING $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ bash --login - If we preferred to use eg fr_FR.utf8, we might have to install that + If we preferred to use eg fr_FR.utf8, we might have to install that first: $ apt-get install language-pack-fr @@ -3098,7 +3111,7 @@ TROUBLESHOOTING 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) @@ -3112,7 +3125,7 @@ COPYRIGHT 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- dot(5), ledger(1)