From 40713ee7aae94a699353f246e03c26575f5d3a8a Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 2 Dec 2018 17:26:18 -0800 Subject: [PATCH] update embedded manuals --- hledger-api/hledger-api.1 | 2 +- hledger-api/hledger-api.info | 8 +- hledger-api/hledger-api.txt | 2 +- hledger-lib/hledger_csv.5 | 2 +- hledger-lib/hledger_csv.info | 60 ++-- hledger-lib/hledger_csv.txt | 2 +- hledger-lib/hledger_journal.5 | 315 ++++++++++++------ hledger-lib/hledger_journal.info | 494 ++++++++++++++++++----------- hledger-lib/hledger_journal.txt | 421 +++++++++++++++--------- hledger-lib/hledger_timeclock.5 | 2 +- hledger-lib/hledger_timeclock.info | 4 +- hledger-lib/hledger_timeclock.txt | 2 +- hledger-lib/hledger_timedot.5 | 2 +- hledger-lib/hledger_timedot.info | 8 +- hledger-lib/hledger_timedot.txt | 2 +- hledger-ui/hledger-ui.1 | 2 +- hledger-ui/hledger-ui.info | 32 +- hledger-ui/hledger-ui.txt | 2 +- hledger-web/hledger-web.1 | 2 +- hledger-web/hledger-web.info | 8 +- hledger-web/hledger-web.txt | 2 +- hledger/hledger.1 | 127 ++++++-- hledger/hledger.info | 463 ++++++++++++++++----------- hledger/hledger.txt | 104 ++++-- 24 files changed, 1334 insertions(+), 734 deletions(-) diff --git a/hledger-api/hledger-api.1 b/hledger-api/hledger-api.1 index eb752ebb2..c75b24f7f 100644 --- a/hledger-api/hledger-api.1 +++ b/hledger-api/hledger-api.1 @@ -1,5 +1,5 @@ -.TH "hledger\-api" "1" "September 2018" "hledger\-api 1.11.99" "hledger User Manuals" +.TH "hledger\-api" "1" "December 2018" "hledger\-api 1.12" "hledger User Manuals" diff --git a/hledger-api/hledger-api.info b/hledger-api/hledger-api.info index 8ab16d99c..118e2ba3f 100644 --- a/hledger-api/hledger-api.info +++ b/hledger-api/hledger-api.info @@ -3,8 +3,8 @@ This is hledger-api.info, produced by makeinfo version 6.5 from stdin.  File: hledger-api.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-api(1) hledger-api 1.11.99 -********************************** +hledger-api(1) hledger-api 1.12 +******************************* hledger-api is a simple web API server, intended to support client-side web apps operating on hledger data. It comes with a series of simple @@ -80,7 +80,7 @@ options as shown above.  Tag Table: Node: Top72 -Node: OPTIONS1666 -Ref: #options1751 +Node: OPTIONS1660 +Ref: #options1745  End Tag Table diff --git a/hledger-api/hledger-api.txt b/hledger-api/hledger-api.txt index 434e766f5..fbe7a2746 100644 --- a/hledger-api/hledger-api.txt +++ b/hledger-api/hledger-api.txt @@ -117,4 +117,4 @@ SEE ALSO -hledger-api 1.11.99 September 2018 hledger-api(1) +hledger-api 1.12 December 2018 hledger-api(1) diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index 0817888d2..b04c67ace 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -1,5 +1,5 @@ -.TH "hledger_csv" "5" "September 2018" "hledger 1.11.99" "hledger User Manuals" +.TH "hledger_csv" "5" "December 2018" "hledger 1.12" "hledger User Manuals" diff --git a/hledger-lib/hledger_csv.info b/hledger-lib/hledger_csv.info index 72613adc7..d8ea27c17 100644 --- a/hledger-lib/hledger_csv.info +++ b/hledger-lib/hledger_csv.info @@ -3,8 +3,8 @@ This is hledger_csv.info, produced by makeinfo version 6.5 from stdin.  File: hledger_csv.info, Node: Top, Next: CSV RULES, Up: (dir) -hledger_csv(5) hledger 1.11.99 -****************************** +hledger_csv(5) hledger 1.12 +*************************** hledger can read CSV (comma-separated value) files as if they were journal files, automatically converting each CSV record into a @@ -317,33 +317,33 @@ one rules file will be used for all the CSV files being read.  Tag Table: Node: Top72 -Node: CSV RULES2169 -Ref: #csv-rules2277 -Node: skip2539 -Ref: #skip2633 -Node: date-format2805 -Ref: #date-format2932 -Node: field list3438 -Ref: #field-list3575 -Node: field assignment4280 -Ref: #field-assignment4435 -Node: conditional block4939 -Ref: #conditional-block5093 -Node: include5989 -Ref: #include6119 -Node: newest-first6350 -Ref: #newest-first6464 -Node: CSV TIPS6875 -Ref: #csv-tips6969 -Node: CSV ordering7087 -Ref: #csv-ordering7205 -Node: CSV accounts7386 -Ref: #csv-accounts7524 -Node: CSV amounts7778 -Ref: #csv-amounts7924 -Node: CSV balance assertions8699 -Ref: #csv-balance-assertions8881 -Node: Reading multiple CSV files9086 -Ref: #reading-multiple-csv-files9256 +Node: CSV RULES2163 +Ref: #csv-rules2271 +Node: skip2533 +Ref: #skip2627 +Node: date-format2799 +Ref: #date-format2926 +Node: field list3432 +Ref: #field-list3569 +Node: field assignment4274 +Ref: #field-assignment4429 +Node: conditional block4933 +Ref: #conditional-block5087 +Node: include5983 +Ref: #include6113 +Node: newest-first6344 +Ref: #newest-first6458 +Node: CSV TIPS6869 +Ref: #csv-tips6963 +Node: CSV ordering7081 +Ref: #csv-ordering7199 +Node: CSV accounts7380 +Ref: #csv-accounts7518 +Node: CSV amounts7772 +Ref: #csv-amounts7918 +Node: CSV balance assertions8693 +Ref: #csv-balance-assertions8875 +Node: Reading multiple CSV files9080 +Ref: #reading-multiple-csv-files9250  End Tag Table diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index 74c48acd1..80b1bf7b0 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -249,4 +249,4 @@ SEE ALSO -hledger 1.11.99 September 2018 hledger_csv(5) +hledger 1.12 December 2018 hledger_csv(5) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 81c438800..c0fa10672 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -1,6 +1,6 @@ .\"t -.TH "hledger_journal" "5" "September 2018" "hledger 1.11.99" "hledger User Manuals" +.TH "hledger_journal" "5" "December 2018" "hledger 1.12" "hledger User Manuals" @@ -547,16 +547,57 @@ 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's balance within the (possibly multi\-commodity) account balance. -We could call this a partial balance assertion. -This is compatible with Ledger, and makes it possible to make assertions -about accounts containing multiple commodities. +.PD 0 +.P +.PD +This is how assertions work in Ledger also. +We could call this a \[lq]partial\[rq] balance assertion. .PP -To assert each commodity's balance in such a multi\-commodity account, -you can add multiple postings (with amount 0 if necessary). -But note that no matter how many assertions you add, you can't be sure -the account does not contain some unexpected commodity. -(We'll add support for this kind of total balance assertion if there's -demand.) +To assert the balance of more than one commodity in an account, you can +write multiple postings, each asserting one commodity's balance. +.PP +You can make a stronger kind of balance assertion, by writing a double +equals sign (\f[C]==EXPECTEDBALANCE\f[]). +This \[lq]complete\[rq] balance assertion asserts the absence of other +commodities (or, that their balance is 0, which to hledger is +equivalent.) +.IP +.nf +\f[C] +2013/1/1 +\ \ a\ \ \ $1 +\ \ a\ \ \ \ 1€ +\ \ b\ \ $\-1 +\ \ c\ \ \ \-1€ + +2013/1/2\ \ ;\ These\ assertions\ succeed +\ \ a\ \ \ \ 0\ \ =\ \ $1 +\ \ a\ \ \ \ 0\ \ =\ \ \ 1€ +\ \ b\ \ \ \ 0\ ==\ $\-1 +\ \ c\ \ \ \ 0\ ==\ \ \-1€ + +2013/1/3\ \ ;\ This\ assertion\ fails\ as\ \[aq]a\[aq]\ also\ contains\ 1€ +\ \ a\ \ \ \ 0\ ==\ \ $1 +\f[] +.fi +.PP +It's not yet possible to make a complete assertion about a balance that +has multiple commodities. +One workaround is to isolate each commodity into its own subaccount: +.IP +.nf +\f[C] +2013/1/1 +\ \ a:usd\ \ \ $1 +\ \ a:euro\ \ \ 1€ +\ \ b + +2013/1/2 +\ \ a\ \ \ \ \ \ \ \ 0\ ==\ \ 0 +\ \ a:usd\ \ \ \ 0\ ==\ $1 +\ \ a:euro\ \ \ 0\ ==\ \ 1€ +\f[] +.fi .SS Assertions and subaccounts .PP Balance assertions do not count the balance from subaccounts; they check @@ -853,10 +894,9 @@ T}@T{ T}@T{ any text T}@T{ -declare an account name & optional account code +document account names, declare account types & display order T}@T{ -account code: balance reports (except \f[C]balance\f[] single\-column -mode) +all entries in all files, before or after T} T{ \f[C]alias\f[] @@ -951,13 +991,8 @@ lw(8.9n) lw(61.1n). T{ subdirective T}@T{ -optional indented directive or unparsed text lines immediately following -a parent directive -T} -T{ -account code -T}@T{ -numeric code influencing account display order in most balance reports +optional indented directive line immediately following a parent +directive T} T{ number notation @@ -1143,58 +1178,108 @@ The \f[C]\-V/\-\-value\f[] flag can be used to convert reported amounts to another commodity using these prices. .SS Declaring accounts .PP -The \f[C]account\f[] directive predeclares account names. -The simplest form is \f[C]account\ ACCTNAME\f[], eg: -.IP -.nf -\f[C] -account\ assets:bank:checking -\f[] -.fi +\f[C]account\f[] directives can be used to pre\-declare some or all +accounts. +Though not required, they can provide several benefits: +.IP \[bu] 2 +They can document your intended chart of accounts, providing a +reference. +.IP \[bu] 2 +They can store extra information about accounts (account numbers, notes, +etc.) +.IP \[bu] 2 +They can help hledger know your accounts' types (asset, liability, +equity, revenue, expense), useful for reports like balancesheet and +incomestatement. +.IP \[bu] 2 +They control account display order in reports, allowing non\-alphabetic +sorting (eg Revenues to appear above Expenses). +.IP \[bu] 2 +They help with account name completion in the add command, +hledger\-iadd, hledger\-web, ledger\-mode etc. .PP -Currently this mainly helps with account name autocompletion in eg -hledger add, hledger\-iadd, hledger\-web, and ledger\-mode. -.PD 0 -.P -.PD -In future it will also help detect misspelled accounts. -.PP -An account directive can also have indented subdirectives following it, -which are currently ignored. Here is the full syntax: .IP .nf \f[C] -;\ account\ ACCTNAME -;\ \ \ [OPTIONALSUBDIRECTIVES] - -account\ assets:bank:checking -\ \ a\ comment -\ \ some\-tag:12345 +account\ ACCTNAME\ \ [ACCTTYPE] +\ \ [COMMENTS] \f[] .fi -.SS Account display order .PP -Account directives have another purpose: they set the order in which -accounts are displayed, in hledger reports, hledger\-ui accounts screen, -hledger\-web sidebar etc. -For example, say you have these top\-level accounts: +The simplest form just declares a hledger\-style account name, eg: .IP .nf \f[C] -$\ accounts\ \-1 -assets -equity -expenses -liabilities -misc -other -revenues +account\ assets:bank:checking +\f[] +.fi +.SS Account types +.PP +hledger recognises five types of account: asset, liability, equity, +revenue, expense. +This is useful for certain accounting\-aware reports, in particular +balancesheet, incomestatement and cashflow. +.PP +If you name your top\-level accounts with some variation of +\f[C]assets\f[], \f[C]liabilities\f[]/\f[C]debts\f[], \f[C]equity\f[], +\f[C]revenues\f[]/\f[C]income\f[], or \f[C]expenses\f[], their types are +detected automatically. +.PP +More generally, you can declare an account's type by adding one of the +letters \f[C]ALERX\f[] to its account directive, separated from the +account name by two or more spaces. +Eg: +.IP +.nf +\f[C] +account\ assets\ \ \ \ \ \ \ A +account\ liabilities\ \ L +account\ equity\ \ \ \ \ \ \ E +account\ revenues\ \ \ \ \ R +account\ expenses\ \ \ \ \ X \f[] .fi .PP -By default, they are displayed in alphabetical order. -But if you add the following account directives to the journal: +Note: if you ever override the types of those auto\-detected english +account names mentioned above, you might need to help the reports a bit: +.IP +.nf +\f[C] +;\ make\ "liabilities"\ not\ have\ the\ liability\ type,\ who\ knows\ why +account\ liabilities\ \ \ E + +;\ better\ ensure\ some\ other\ account\ has\ the\ liability\ type,\ +;\ otherwise\ balancesheet\ would\ still\ show\ "liabilities"\ under\ Liabilities\ +account\ \-\ \ \ \ \ \ \ \ \ \ \ \ \ L +\f[] +.fi +.PP +) +.SS Account comments +.PP +An account directive can also have indented comments on following lines, +eg: +.IP +.nf +\f[C] +account\ assets:bank:checking +\ \ ;\ acctno:12345 +\ \ ;\ a\ comment +\f[] +.fi +.PP +We also allow (and ignore) Ledger\-style subdirectives, with no leading +semicolon, for compatibility. +.PP +Tags in account comments, like \f[C]acctno\f[] above, currently have no +effect. +.SS Account display order +.PP +Account directives also set the order in which accounts are displayed in +reports, the hledger\-ui accounts screen, the hledger\-web sidebar, etc. +Normally accounts are listed in alphabetical order, but if you have eg +these account directives in the journal: .IP .nf \f[C] @@ -1206,27 +1291,25 @@ account\ expenses \f[] .fi .PP -the display order changes to: +you'll see those accounts listed in declaration order, not +alphabetically: .IP .nf \f[C] -$\ accounts\ \-1 +$\ hledger\ accounts\ \-1 assets liabilities equity revenues expenses -misc -other \f[] .fi .PP -Ie, declared accounts first, in the order they were declared, followed -by any undeclared accounts in alphabetic order. +Undeclared accounts, if any, are displayed last, in alphabetical order. .PP Note that sorting is done at each level of the account tree (within each group of sibling accounts under the same parent). -This directive: +And currently, this directive: .IP .nf \f[C] @@ -1237,6 +1320,10 @@ account\ other:zoo would influence the position of \f[C]zoo\f[] among \f[C]other\f[]'s subaccounts, but not the position of \f[C]other\f[] among the top\-level accounts. +This means: \- you will sometimes declare parent accounts (eg +\f[C]account\ other\f[] above) that you don't intend to post to, just to +customize their display order \- sibling accounts stay together (you +couldn't display \f[C]x:y\f[] in between \f[C]a:b\f[] and \f[C]a:c\f[]). .SS Rewriting accounts .PP You can define account alias rules which rewrite your account names, or @@ -1419,16 +1506,25 @@ date must fall on a natural boundary of the interval. Eg \f[C]monthly\ from\ 2018/1/1\f[] is valid, but \f[C]monthly\ from\ 2018/1/15\f[] is not. .PP -If you write a transaction description or same\-line comment, it must be -separated from the period expression by \f[B]two or more spaces\f[]. -Eg: +Partial or relative dates (M/D, D, tomorrow, last week) in the period +expression can work (useful or not). +They will be relative to today's date, unless a Y default year directive +is in effect, in which case they will be relative to Y/1/1. +.PP +Period expressions must be terminated by \f[B]two or more spaces\f[] if +followed by additional fields. +For example, the periodic transaction given below includes a transaction +description \[lq]paycheck\[rq], which is separated from the period +expression by a double space. +If not for the second space, hledger would attempt (and fail) to parse +\[lq]paycheck\[rq] as a part of the period expression. .IP .nf \f[C] -;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ or\ more\ spaces -;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ || -;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv -~\ every\ 2\ weeks\ from\ 2018/6\ to\ 2018/9\ \ paycheck +;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ or\ more\ spaces +;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ || +;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv +~\ every\ 2\ weeks\ from\ 2018/6/4\ to\ 2018/9\ \ paycheck \ \ \ \ assets:bank:checking\ \ \ $1500 \ \ \ \ income:acme\ inc \f[] @@ -1495,50 +1591,81 @@ Currently, this means adding extra postings (also known as \[lq]automated postings\[rq]). Transaction modifiers are enabled by the \f[C]\-\-auto\f[] flag. .PP -A transaction modifier rule looks a bit like a normal journal entry, -except the first line is an equal sign (\f[C]=\f[]) followed by a query -(mnemonic: \f[C]=\f[] suggests matching something.): +A transaction modifier rule looks quite like a normal transaction, +except the first line is an equals sign followed by a query that matches +certain postings (mnemonic: \f[C]=\f[] suggests matching). +And each \[lq]posting\[rq] is actually a posting\-generating rule: .IP .nf \f[C] -=\ expenses:gifts -\ \ \ \ budget:gifts\ \ *\-1 -\ \ \ \ assets:budget\ \ *1 +=\ QUERY +\ \ \ \ ACCT\ \ AMT +\ \ \ \ ACCT\ \ [AMT] +\ \ \ \ ... \f[] .fi .PP -The posting amounts can be of the form \f[C]*N\f[], which means \[lq]the -amount of the matched transaction's first posting, multiplied by N\[rq]. -They can also be ordinary fixed amounts. -Fixed amounts with no commodity symbol will be given the same commodity -as the matched transaction's first posting. +The posting rules look just like normal postings, except the amount can +be: +.IP \[bu] 2 +a normal amount with a commodity symbol, eg \f[C]$2\f[]. +This will be used as\-is. +.IP \[bu] 2 +a number, eg \f[C]2\f[]. +The commodity symbol (if any) from the matched posting will be added to +this. +.IP \[bu] 2 +a numeric multiplier, eg \f[C]*2\f[] (a star followed by a number N). +The matched posting's amount (and total price, if any) will be +multiplied by N. +.IP \[bu] 2 +a multiplier with a commodity symbol, eg \f[C]*$2\f[] (a star, number N, +and symbol S). +The matched posting's amount will be multiplied by N, and its commodity +symbol will be replaced with S. .PP -This example adds a corresponding (unbalanced) budget posting to every -transaction involving the \f[C]expenses:gifts\f[] account: +Some examples: .IP .nf \f[C] -=\ expenses:gifts -\ \ \ \ (budget:gifts)\ \ *\-1 +;\ every\ time\ I\ buy\ food,\ schedule\ a\ dollar\ donation +=\ expenses:food +\ \ \ \ (liabilities:charity)\ \ \ $\-1 -2017\-12\-14 -\ \ expenses:gifts\ \ $20 -\ \ assets +;\ when\ I\ buy\ a\ gift,\ also\ deduct\ that\ amount\ from\ a\ budget\ envelope\ subaccount +=\ expenses:gifts +\ \ \ \ assets:checking:gifts\ \ *\-1 +\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ *1 + +2017/12/1 +\ \ expenses:food\ \ \ \ $10 +\ \ assets:checking + +2017/12/14 +\ \ expenses:gifts\ \ \ $20 +\ \ assets:checking \f[] .fi .IP .nf \f[C] $\ hledger\ print\ \-\-auto +2017/12/01 +\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ $10 +\ \ \ \ assets:checking +\ \ \ \ (liabilities:charity)\ \ \ \ \ \ $\-1 + 2017/12/14 \ \ \ \ expenses:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ $20 -\ \ \ \ (budget:gifts)\ \ \ \ \ \ \ \ \ \ \ \ $\-20 -\ \ \ \ assets +\ \ \ \ assets:checking +\ \ \ \ assets:checking:gifts\ \ \ \ \ \-$20 +\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ $20 \f[] .fi .PP -Like postings recorded by hand, automated postings participate in -transaction balancing, missing amount inference and balance assertions. +Postings added by transaction modifiers participate in transaction +balancing, missing amount inference and balance assertions, like regular +postings. .SH EDITOR SUPPORT .PP Add\-on modes exist for various text editors, to make working with diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index d955c71ed..7a4148fdd 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -4,8 +4,8 @@ stdin.  File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir) -hledger_journal(5) hledger 1.11.99 -********************************** +hledger_journal(5) hledger 1.12 +******************************* hledger's usual data source is a plain text file containing journal entries in hledger journal format. This file represents a standard @@ -524,16 +524,46 @@ 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. We could call this a -partial balance assertion. This is compatible with Ledger, and makes it -possible to make assertions about accounts containing multiple -commodities. +(possibly multi-commodity) account balance. +This is how assertions work in Ledger also. We could call this a +"partial" balance assertion. - To assert each commodity's balance in such a multi-commodity account, -you can add multiple postings (with amount 0 if necessary). But note -that no matter how many assertions you add, you can't be sure the -account does not contain some unexpected commodity. (We'll add support -for this kind of total balance assertion if there's demand.) + 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 kind of balance assertion, by writing a +double equals sign ('==EXPECTEDBALANCE'). This "complete" balance +assertion asserts the absence of other commodities (or, that their +balance is 0, which to hledger is equivalent.) + +2013/1/1 + a $1 + a 1€ + b $-1 + c -1€ + +2013/1/2 ; These assertions succeed + a 0 = $1 + a 0 = 1€ + b 0 == $-1 + c 0 == -1€ + +2013/1/3 ; This assertion fails as 'a' also contains 1€ + 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 into its own subaccount: + +2013/1/1 + a:usd $1 + a:euro 1€ + b + +2013/1/2 + a 0 == 0 + a:usd 0 == $1 + a:euro 0 == 1€  File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and commodities, Up: Balance Assertions @@ -766,11 +796,9 @@ links to more detailed docs. directiveend subdirectivespurpose can affect (as of directive 2018/06) ----------------------------------------------------------------------------- -'account' any declare an account name & account code: - text optional account code balance reports - (except 'balance' - single-column - mode) +'account' any document account names, all entries in + text declare account types & all files, before + display order or after 'alias' 'end rewrite account names following aliases' inline/included entries until end @@ -821,10 +849,8 @@ account' apply account names inline/included And some definitions: -subdirectiveoptional indented directive or unparsed text lines - immediately following a parent directive -account numeric code influencing account display order in most -code balance reports +subdirectiveoptional indented directive line immediately following a + parent directive number how to interpret numbers when parsing journal entries (the notation identity of the decimal separator character). (Currently each commodity can have its own notation, even in the same @@ -853,7 +879,6 @@ times though. * Default commodity:: * Market prices:: * Declaring accounts:: -* Account display order:: * Rewriting accounts:: * Default parent account:: @@ -1003,52 +1028,106 @@ P 2010/1/1 € $1.40 another commodity using these prices.  -File: hledger_journal.info, Node: Declaring accounts, Next: Account display order, Prev: Market prices, Up: Directives +File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Market prices, Up: Directives 1.14.7 Declaring accounts ------------------------- -The 'account' directive predeclares account names. The simplest form is -'account ACCTNAME', eg: +'account' directives can be used to pre-declare some or all accounts. +Though not required, they can provide several benefits: + + * They can document your intended chart of accounts, providing a + reference. + * They can store extra information about accounts (account numbers, + notes, etc.) + * They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), useful for reports like balancesheet and + incomestatement. + * They control account display order in reports, allowing + non-alphabetic sorting (eg Revenues to appear above Expenses). + * They help with account name completion in the add command, + hledger-iadd, hledger-web, ledger-mode etc. + + Here is the full syntax: + +account ACCTNAME [ACCTTYPE] + [COMMENTS] + + The simplest form just declares a hledger-style account name, eg: account assets:bank:checking - Currently this mainly helps with account name autocompletion in eg -hledger add, hledger-iadd, hledger-web, and ledger-mode. -In future it will also help detect misspelled accounts. +* Menu: - An account directive can also have indented subdirectives following -it, which are currently ignored. Here is the full syntax: - -; account ACCTNAME -; [OPTIONALSUBDIRECTIVES] - -account assets:bank:checking - a comment - some-tag:12345 +* Account types:: +* Account comments:: +* Account display order::  -File: hledger_journal.info, Node: Account display order, Next: Rewriting accounts, Prev: Declaring accounts, Up: Directives +File: hledger_journal.info, Node: Account types, Next: Account comments, Up: Declaring accounts -1.14.8 Account display order ----------------------------- +1.14.7.1 Account types +...................... -Account directives have another purpose: they set the order in which -accounts are displayed, in hledger reports, hledger-ui accounts screen, -hledger-web sidebar etc. For example, say you have these top-level -accounts: +hledger recognises five types of account: asset, liability, equity, +revenue, expense. This is useful for certain accounting-aware reports, +in particular balancesheet, incomestatement and cashflow. -$ accounts -1 -assets -equity -expenses -liabilities -misc -other -revenues + If you name your top-level accounts with some variation of 'assets', +'liabilities'/'debts', 'equity', 'revenues'/'income', or 'expenses', +their types are detected automatically. - By default, they are displayed in alphabetical order. But if you add -the following account directives to the journal: + More generally, you can declare an account's type by adding one of +the letters 'ALERX' to its account directive, separated from the account +name by two or more spaces. Eg: + +account assets A +account liabilities L +account equity E +account revenues R +account expenses X + + Note: if you ever override the types of those auto-detected english +account names mentioned above, you might need to help the reports a bit: + +; make "liabilities" not have the liability type, who knows why +account liabilities E + +; better ensure some other account has the liability type, +; otherwise balancesheet would still show "liabilities" under Liabilities +account - L + + ) + + +File: hledger_journal.info, Node: Account comments, Next: Account display order, Prev: Account types, Up: Declaring accounts + +1.14.7.2 Account comments +......................... + +An account directive can also have indented comments on following lines, +eg: + +account assets:bank:checking + ; acctno:12345 + ; a comment + + We also allow (and ignore) Ledger-style subdirectives, with no +leading semicolon, for compatibility. + + Tags in account comments, like 'acctno' above, currently have no +effect. + + +File: hledger_journal.info, Node: Account display order, Prev: Account comments, Up: Declaring accounts + +1.14.7.3 Account display order +.............................. + +Account directives also set the order in which accounts are displayed in +reports, the hledger-ui accounts screen, the hledger-web sidebar, etc. +Normally accounts are listed in alphabetical order, but if you have eg +these account directives in the journal: account assets account liabilities @@ -1056,32 +1135,36 @@ account equity account revenues account expenses - the display order changes to: + you'll see those accounts listed in declaration order, not +alphabetically: -$ accounts -1 +$ hledger accounts -1 assets liabilities equity revenues expenses -misc -other - Ie, declared accounts first, in the order they were declared, -followed by any undeclared accounts in alphabetic order. + Undeclared accounts, if any, are displayed last, in alphabetical +order. Note that sorting is done at each level of the account tree (within -each group of sibling accounts under the same parent). This directive: +each group of sibling accounts under the same parent). And currently, +this directive: account other:zoo would influence the position of 'zoo' among 'other''s subaccounts, -but not the position of 'other' among the top-level accounts. +but not the position of 'other' among the top-level accounts. This +means: - you will sometimes declare parent accounts (eg 'account other' +above) that you don't intend to post to, just to customize their display +order - sibling accounts stay together (you couldn't display 'x:y' in +between 'a:b' and 'a:c').  -File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Account display order, Up: Directives +File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives -1.14.9 Rewriting accounts +1.14.8 Rewriting accounts ------------------------- You can define account alias rules which rewrite your account names, or @@ -1109,7 +1192,7 @@ hledger-web.  File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts -1.14.9.1 Basic aliases +1.14.8.1 Basic aliases ...................... To set an account alias, use the 'alias' directive in your journal file. @@ -1132,7 +1215,7 @@ alias checking = assets:bank:wells fargo:checking  File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Rewriting accounts -1.14.9.2 Regex aliases +1.14.8.2 Regex aliases ...................... There is also a more powerful variant that uses a regular expression, @@ -1157,7 +1240,7 @@ whitespace.  File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts -1.14.9.3 Multiple aliases +1.14.8.3 Multiple aliases ......................... You can define as many aliases as you like using directives or @@ -1173,7 +1256,7 @@ following order:  File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Rewriting accounts -1.14.9.4 'end aliases' +1.14.8.4 'end aliases' ...................... You can clear (forget) all currently defined aliases with the 'end @@ -1184,8 +1267,8 @@ end aliases  File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives -1.14.10 Default parent account ------------------------------- +1.14.9 Default parent account +----------------------------- You can specify a parent account which will be prepended to all accounts within a section of the journal. Use the 'apply account' and 'end apply @@ -1245,13 +1328,22 @@ the date replaced by a tilde ('~') followed by a period expression date must fall on a natural boundary of the interval. Eg 'monthly from 2018/1/1' is valid, but 'monthly from 2018/1/15' is not. - If you write a transaction description or same-line comment, it must -be separated from the period expression by *two or more spaces*. Eg: + Partial or relative dates (M/D, D, tomorrow, last week) in the period +expression can work (useful or not). They will be relative to today's +date, unless a Y default year directive is in effect, in which case they +will be relative to Y/1/1. -; 2 or more spaces -; || -; vv -~ every 2 weeks from 2018/6 to 2018/9 paycheck + Period expressions must be terminated by *two or more spaces* if +followed by additional fields. For example, the periodic transaction +given below includes a transaction description "paycheck", which is +separated from the period expression by a double space. If not for the +second space, hledger would attempt (and fail) to parse "paycheck" as a +part of the period expression. + +; 2 or more spaces +; || +; vv +~ every 2 weeks from 2018/6/4 to 2018/9 paycheck assets:bank:checking $1500 income:acme inc @@ -1330,38 +1422,64 @@ automatically to certain transactions. Currently, this means adding extra postings (also known as "automated postings"). Transaction modifiers are enabled by the '--auto' flag. - A transaction modifier rule looks a bit like a normal journal entry, -except the first line is an equal sign ('=') followed by a query -(mnemonic: '=' suggests matching something.): + A transaction modifier rule looks quite like a normal transaction, +except the first line is an equals sign followed by a query that matches +certain postings (mnemonic: '=' suggests matching). And each "posting" +is actually a posting-generating rule: += QUERY + ACCT AMT + ACCT [AMT] + ... + + The posting rules look just like normal postings, except the amount +can be: + + * a normal amount with a commodity symbol, eg '$2'. This will be + used as-is. + * a number, eg '2'. The commodity symbol (if any) from the matched + posting will be added to this. + * a numeric multiplier, eg '*2' (a star followed by a number N). The + matched posting's amount (and total price, if any) will be + multiplied by N. + * a multiplier with a commodity symbol, eg '*$2' (a star, number N, + and symbol S). The matched posting's amount will be multiplied by + N, and its commodity symbol will be replaced with S. + + Some examples: + +; every time I buy food, schedule a dollar donation += expenses:food + (liabilities:charity) $-1 + +; when I buy a gift, also deduct that amount from a budget envelope subaccount = expenses:gifts - budget:gifts *-1 - assets:budget *1 + assets:checking:gifts *-1 + assets:checking *1 - The posting amounts can be of the form '*N', which means "the amount -of the matched transaction's first posting, multiplied by N". They can -also be ordinary fixed amounts. Fixed amounts with no commodity symbol -will be given the same commodity as the matched transaction's first -posting. +2017/12/1 + expenses:food $10 + assets:checking - This example adds a corresponding (unbalanced) budget posting to -every transaction involving the 'expenses:gifts' account: - -= expenses:gifts - (budget:gifts) *-1 - -2017-12-14 - expenses:gifts $20 - assets +2017/12/14 + expenses:gifts $20 + assets:checking $ hledger print --auto +2017/12/01 + expenses:food $10 + assets:checking + (liabilities:charity) $-1 + 2017/12/14 expenses:gifts $20 - (budget:gifts) $-20 - assets + assets:checking + assets:checking:gifts -$20 + assets:checking $20 - Like postings recorded by hand, automated postings participate in -transaction balancing, missing amount inference and balance assertions. + Postings added by transaction modifiers participate in transaction +balancing, missing amount inference and balance assertions, like regular +postings.  File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top @@ -1393,93 +1511,97 @@ Code  Tag Table: Node: Top76 -Node: FILE FORMAT2378 -Ref: #file-format2502 -Node: Transactions2789 -Ref: #transactions2910 -Node: Postings3594 -Ref: #postings3721 -Node: Dates4716 -Ref: #dates4831 -Node: Simple dates4896 -Ref: #simple-dates5022 -Node: Secondary dates5388 -Ref: #secondary-dates5542 -Node: Posting dates7105 -Ref: #posting-dates7234 -Node: Status8608 -Ref: #status8728 -Node: Description10436 -Ref: #description10574 -Node: Payee and note10893 -Ref: #payee-and-note11007 -Node: Account names11249 -Ref: #account-names11392 -Node: Amounts11879 -Ref: #amounts12015 -Node: Virtual Postings15032 -Ref: #virtual-postings15191 -Node: Balance Assertions16411 -Ref: #balance-assertions16586 -Node: Assertions and ordering17482 -Ref: #assertions-and-ordering17668 -Node: Assertions and included files18368 -Ref: #assertions-and-included-files18609 -Node: Assertions and multiple -f options18942 -Ref: #assertions-and-multiple--f-options19196 -Node: Assertions and commodities19328 -Ref: #assertions-and-commodities19563 -Node: Assertions and subaccounts20259 -Ref: #assertions-and-subaccounts20491 -Node: Assertions and virtual postings21012 -Ref: #assertions-and-virtual-postings21219 -Node: Balance Assignments21361 -Ref: #balance-assignments21542 -Node: Transaction prices22662 -Ref: #transaction-prices22831 -Node: Comments25099 -Ref: #comments25233 -Node: Tags26403 -Ref: #tags26521 -Node: Directives27923 -Ref: #directives28066 -Node: Comment blocks33948 -Ref: #comment-blocks34093 -Node: Including other files34269 -Ref: #including-other-files34449 -Node: Default year34857 -Ref: #default-year35026 -Node: Declaring commodities35449 -Ref: #declaring-commodities35632 -Node: Default commodity36859 -Ref: #default-commodity37035 -Node: Market prices37671 -Ref: #market-prices37836 -Node: Declaring accounts38677 -Ref: #declaring-accounts38856 -Node: Account display order39406 -Ref: #account-display-order39596 -Node: Rewriting accounts40617 -Ref: #rewriting-accounts40805 -Node: Basic aliases41539 -Ref: #basic-aliases41685 -Node: Regex aliases42389 -Ref: #regex-aliases42560 -Node: Multiple aliases43278 -Ref: #multiple-aliases43453 -Node: end aliases43951 -Ref: #end-aliases44098 -Node: Default parent account44199 -Ref: #default-parent-account44367 -Node: Periodic transactions45251 -Ref: #periodic-transactions45433 -Node: Forecasting with periodic transactions46644 -Ref: #forecasting-with-periodic-transactions46887 -Node: Budgeting with periodic transactions48574 -Ref: #budgeting-with-periodic-transactions48813 -Node: Transaction Modifiers49272 -Ref: #transaction-modifiers49435 -Node: EDITOR SUPPORT50691 -Ref: #editor-support50809 +Node: FILE FORMAT2372 +Ref: #file-format2496 +Node: Transactions2783 +Ref: #transactions2904 +Node: Postings3588 +Ref: #postings3715 +Node: Dates4710 +Ref: #dates4825 +Node: Simple dates4890 +Ref: #simple-dates5016 +Node: Secondary dates5382 +Ref: #secondary-dates5536 +Node: Posting dates7099 +Ref: #posting-dates7228 +Node: Status8602 +Ref: #status8722 +Node: Description10430 +Ref: #description10568 +Node: Payee and note10887 +Ref: #payee-and-note11001 +Node: Account names11243 +Ref: #account-names11386 +Node: Amounts11873 +Ref: #amounts12009 +Node: Virtual Postings15026 +Ref: #virtual-postings15185 +Node: Balance Assertions16405 +Ref: #balance-assertions16580 +Node: Assertions and ordering17476 +Ref: #assertions-and-ordering17662 +Node: Assertions and included files18362 +Ref: #assertions-and-included-files18603 +Node: Assertions and multiple -f options18936 +Ref: #assertions-and-multiple--f-options19190 +Node: Assertions and commodities19322 +Ref: #assertions-and-commodities19557 +Node: Assertions and subaccounts20745 +Ref: #assertions-and-subaccounts20977 +Node: Assertions and virtual postings21498 +Ref: #assertions-and-virtual-postings21705 +Node: Balance Assignments21847 +Ref: #balance-assignments22028 +Node: Transaction prices23148 +Ref: #transaction-prices23317 +Node: Comments25585 +Ref: #comments25719 +Node: Tags26889 +Ref: #tags27007 +Node: Directives28409 +Ref: #directives28552 +Node: Comment blocks34159 +Ref: #comment-blocks34304 +Node: Including other files34480 +Ref: #including-other-files34660 +Node: Default year35068 +Ref: #default-year35237 +Node: Declaring commodities35660 +Ref: #declaring-commodities35843 +Node: Default commodity37070 +Ref: #default-commodity37246 +Node: Market prices37882 +Ref: #market-prices38047 +Node: Declaring accounts38888 +Ref: #declaring-accounts39064 +Node: Account types40021 +Ref: #account-types40170 +Node: Account comments41244 +Ref: #account-comments41429 +Node: Account display order41750 +Ref: #account-display-order41923 +Node: Rewriting accounts43045 +Ref: #rewriting-accounts43230 +Node: Basic aliases43964 +Ref: #basic-aliases44110 +Node: Regex aliases44814 +Ref: #regex-aliases44985 +Node: Multiple aliases45703 +Ref: #multiple-aliases45878 +Node: end aliases46376 +Ref: #end-aliases46523 +Node: Default parent account46624 +Ref: #default-parent-account46790 +Node: Periodic transactions47674 +Ref: #periodic-transactions47856 +Node: Forecasting with periodic transactions49559 +Ref: #forecasting-with-periodic-transactions49802 +Node: Budgeting with periodic transactions51489 +Ref: #budgeting-with-periodic-transactions51728 +Node: Transaction Modifiers52187 +Ref: #transaction-modifiers52350 +Node: EDITOR SUPPORT54331 +Ref: #editor-support54449  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index a39fd97c1..6fbf8e562 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -405,16 +405,46 @@ FILE FORMAT 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. We could call this a par- - tial balance assertion. This is compatible with Ledger, and makes it - possible to make assertions about accounts containing multiple commodi- - ties. + (possibly multi-commodity) account balance. + This is how assertions work in Ledger also. We could call this a "par- + tial" balance assertion. - To assert each commodity's balance in such a multi-commodity account, - you can add multiple postings (with amount 0 if necessary). But note - that no matter how many assertions you add, you can't be sure the - account does not contain some unexpected commodity. (We'll add support - for this kind of total balance assertion if there's demand.) + 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 kind of balance assertion, by writing a double + equals sign (==EXPECTEDBALANCE). This "complete" balance assertion + asserts the absence of other commodities (or, that their balance is 0, + which to hledger is equivalent.) + + 2013/1/1 + a $1 + a 1 + b $-1 + c -1 + + 2013/1/2 ; These assertions succeed + a 0 = $1 + a 0 = 1 + b 0 == $-1 + c 0 == -1 + + 2013/1/3 ; This assertion fails as 'a' also contains 1 + 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 + into its own subaccount: + + 2013/1/1 + a:usd $1 + a:euro 1 + b + + 2013/1/2 + a 0 == 0 + a:usd 0 == $1 + a:euro 0 == 1 Assertions and subaccounts Balance assertions do not count the balance from subaccounts; they @@ -614,40 +644,51 @@ FILE FORMAT tive directive rec- 2018/06) tives ------------------------------------------------------------------------------------------------- - account any declare an account name & account code: bal- - text optional account code ance reports - (except balance - single-column mode) + account any document account names, all entries in all + text declare account types & dis- files, before or + play order after alias end aliases rewrite account names following inline/included entries until end - of current file or + of current file or end directive - apply account end apply account prepend a common parent to following + apply account end apply account prepend a common parent to following account names inline/included entries until end - of current file or + of current file or end directive comment end comment ignore part of journal following inline/included entries until end - of current file or + of current file or end directive - commodity format declare a commodity and its number notation: + commodity format declare a commodity and its number notation: 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, number commodity: all com- + + + + + + + + + + + + + D declare a commodity, number commodity: all com- notation & display style for modityless entries - commodityless amounts in all files; num- - ber notation: fol- + commodityless amounts in all files; num- + ber notation: fol- lowing commodity- - less entries and + less entries and entries in that - commodity in all + commodity in all files; display style: amounts of that commodity in @@ -658,7 +699,7 @@ FILE FORMAT commodity commodity in reports, when -V is used - Y declare a year for yearless following + Y declare a year for yearless following dates inline/included entries until end of current file @@ -666,16 +707,11 @@ FILE FORMAT And some definitions: - subdirec- optional indented directive or unparsed text lines immedi- - tive ately following a parent directive - account numeric code influencing account display order in most bal- - code ance reports - - - - number how to interpret numbers when parsing journal entries (the - notation identity of the decimal separator character). (Currently - each commodity can have its own notation, even in the same + subdirec- optional indented directive line immediately following a par- + tive ent directive + number how to interpret numbers when parsing journal entries (the + notation identity of the decimal separator character). (Currently + each commodity can have its own notation, even in the same file.) display how to display amounts of a commodity in reports (symbol side style and spacing, digit groups, decimal separator, decimal places) @@ -683,37 +719,37 @@ FILE FORMAT scope are affected by a directive As you can see, directives vary in which journal entries and files they - affect, and whether they are focussed on input (parsing) or output + affect, and whether they are focussed on input (parsing) or output (reports). 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 + The include directive can only be used in journal files. It can include 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 @@ -733,8 +769,8 @@ FILE FORMAT assets Declaring commodities - The commodity directive declares commodities which may be used in the - journal (though currently we do not enforce this). It may be written + The commodity directive declares commodities which may be used in the + journal (though currently we do not enforce this). It may be written on a single line, like this: ; commodity EXAMPLEAMOUNT @@ -744,8 +780,8 @@ FILE FORMAT ; separating thousands with comma. commodity 1,000.0000 AAAA - or on multiple lines, using the "format" subdirective. In this case - the commodity symbol appears twice and should be the same in both + or on multiple lines, using the "format" subdirective. In this case + the commodity symbol appears twice and should be the same in both places: ; commodity SYMBOL @@ -757,19 +793,19 @@ FILE FORMAT commodity INR format INR 9,99,99,999.00 - Commodity directives have a second purpose: they define the standard + Commodity directives have a second purpose: they define the standard display format for amounts in the commodity. Normally the display for- - mat is inferred from journal entries, but this can be unpredictable; - declaring it with a commodity directive overrides this and removes - ambiguity. Towards this end, amounts in commodity directives must - always be written with a decimal point (a period or comma, followed by + mat is inferred from journal entries, but this can be unpredictable; + declaring it with a commodity directive overrides this and removes + ambiguity. Towards this end, amounts in commodity directives must + always be written with a decimal point (a period or comma, followed by 0 or more decimal digits). Default commodity - The D directive sets a default commodity (and display format), to be + 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 + 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. # commodity-less amounts should be treated as dollars @@ -784,9 +820,9 @@ FILE FORMAT a decimal point. Market prices - The P directive declares a market price, which is an exchange rate + The P directive declares a market price, which is an exchange rate between two commodities on a certain date. (In Ledger, they are called - "historical prices".) These are often obtained from a stock exchange, + "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. Here is the format: @@ -797,55 +833,97 @@ FILE FORMAT o COMMODITYA is the symbol of the commodity being priced - o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- + o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- modity, giving the price in commodity B of one unit of commodity A. - These two market price directives say that one euro was worth 1.35 US + These two market price directives say that one euro was worth 1.35 US dollars during 2009, and $1.40 from 2010 onward: P 2009/1/1 $1.35 P 2010/1/1 $1.40 - The -V/--value flag can be used to convert reported amounts to another + The -V/--value flag can be used to convert reported amounts to another commodity using these prices. Declaring accounts - The account directive predeclares account names. The simplest form is - account ACCTNAME, eg: + account directives can be used to pre-declare some or all accounts. + Though not required, they can provide several benefits: + + o They can document your intended chart of accounts, providing a refer- + ence. + + o They can store extra information about accounts (account numbers, + notes, etc.) + + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), useful for reports like balancesheet and + incomestatement. + + o They control account display order in reports, allowing non-alpha- + betic sorting (eg Revenues to appear above Expenses). + + o They help with account name completion in the add command, + hledger-iadd, hledger-web, ledger-mode etc. + + Here is the full syntax: + + account ACCTNAME [ACCTTYPE] + [COMMENTS] + + The simplest form just declares a hledger-style account name, eg: account assets:bank:checking - Currently this mainly helps with account name autocompletion in eg - hledger add, hledger-iadd, hledger-web, and ledger-mode. - In future it will also help detect misspelled accounts. + Account types + hledger recognises five types of account: asset, liability, equity, + revenue, expense. This is useful for certain accounting-aware reports, + in particular balancesheet, incomestatement and cashflow. - An account directive can also have indented subdirectives following it, - which are currently ignored. Here is the full syntax: + If you name your top-level accounts with some variation of assets, lia- + bilities/debts, equity, revenues/income, or expenses, their types are + detected automatically. - ; account ACCTNAME - ; [OPTIONALSUBDIRECTIVES] + More generally, you can declare an account's type by adding one of the + letters ALERX to its account directive, separated from the account name + by two or more spaces. Eg: + + account assets A + account liabilities L + account equity E + account revenues R + account expenses X + + Note: if you ever override the types of those auto-detected english + account names mentioned above, you might need to help the reports a + bit: + + ; make "liabilities" not have the liability type, who knows why + account liabilities E + + ; better ensure some other account has the liability type, + ; otherwise balancesheet would still show "liabilities" under Liabilities + account - L + + ) + + Account comments + An account directive can also have indented comments on following + lines, eg: account assets:bank:checking - a comment - some-tag:12345 + ; acctno:12345 + ; a comment + + We also allow (and ignore) Ledger-style subdirectives, with no leading + semicolon, for compatibility. + + Tags in account comments, like acctno above, currently have no effect. Account display order - Account directives have another purpose: they set the order in which - accounts are displayed, in hledger reports, hledger-ui accounts screen, - hledger-web sidebar etc. For example, say you have these top-level - accounts: - - $ accounts -1 - assets - equity - expenses - liabilities - misc - other - revenues - - By default, they are displayed in alphabetical order. But if you add - the following account directives to the journal: + Account directives also set the order in which accounts are displayed + in reports, the hledger-ui accounts screen, the hledger-web sidebar, + etc. Normally accounts are listed in alphabetical order, but if you + have eg these account directives in the journal: account assets account liabilities @@ -853,27 +931,30 @@ FILE FORMAT account revenues account expenses - the display order changes to: + you'll see those accounts listed in declaration order, not alphabeti- + cally: - $ accounts -1 + $ hledger accounts -1 assets liabilities equity revenues expenses - misc - other - Ie, declared accounts first, in the order they were declared, followed - by any undeclared accounts in alphabetic order. + Undeclared accounts, if any, are displayed last, in alphabetical order. Note that sorting is done at each level of the account tree (within - each group of sibling accounts under the same parent). This directive: + each group of sibling accounts under the same parent). And currently, + this directive: account other:zoo would influence the position of zoo among other's subaccounts, but not - the position of other among the top-level accounts. + the position of other among the top-level accounts. This means: - you + will sometimes declare parent accounts (eg account other above) that + you don't intend to post to, just to customize their display order - + sibling accounts stay together (you couldn't display x:y in between a:b + and a:c). Rewriting accounts You can define account alias rules which rewrite your account names, or @@ -1004,105 +1085,143 @@ FILE FORMAT date must fall on a natural boundary of the interval. Eg monthly from 2018/1/1 is valid, but monthly from 2018/1/15 is not. - If you write a transaction description or same-line comment, it must be - separated from the period expression by two or more spaces. Eg: + Partial or relative dates (M/D, D, tomorrow, last week) in the period + expression can work (useful or not). They will be relative to today's + date, unless a Y default year directive is in effect, in which case + they will be relative to Y/1/1. - ; 2 or more spaces - ; || - ; vv - ~ every 2 weeks from 2018/6 to 2018/9 paycheck + Period expressions must be terminated by two or more spaces if followed + by additional fields. For example, the periodic transaction given + below includes a transaction description "paycheck", which is separated + from the period expression by a double space. If not for the second + space, hledger would attempt (and fail) to parse "paycheck" as a part + of the period expression. + + ; 2 or more spaces + ; || + ; vv + ~ every 2 weeks from 2018/6/4 to 2018/9 paycheck assets:bank:checking $1500 income:acme inc Forecasting with periodic transactions - With the --forecast flag, each periodic transaction rule generates + With the --forecast flag, each periodic transaction rule generates future transactions recurring at the specified interval. These are not - saved in the journal, but appear in all reports. They will look like - normal transactions, but with an extra tag named recur, whose value is + saved in the journal, but appear in all reports. They will look like + normal transactions, but with an extra tag named recur, whose value is the generating period expression. - Forecast transactions start on the first occurrence, and end on the - last occurrence, of their interval within the forecast period. The + Forecast transactions start on the first occurrence, and end on the + last occurrence, of their interval within the forecast period. The forecast period: o begins on the later of o the report start date if specified with -b/-p/date: - o the day after the latest normal (non-periodic) transaction in the + o the day after the latest normal (non-periodic) transaction in the journal, or today if there are no normal transactions. - o ends on the report end date if specified with -e/-p/date:, or 180 + o ends on the report end date if specified with -e/-p/date:, or 180 days from today. - where "today" means the current date at report time. The "later of" - rule ensures that forecast transactions do not overlap normal transac- + where "today" means the current date at report time. The "later of" + rule ensures that forecast transactions do not overlap normal transac- tions in time; they will begin only after normal transactions end. - Forecasting can be useful for estimating balances into the future, and - experimenting with different scenarios. Note the start date logic + Forecasting can be useful for estimating balances into the future, and + experimenting with different scenarios. Note the start date logic means that forecasted transactions are automatically replaced by normal transactions as you add those. Forecasting can also help with data entry: describe most of your trans- - actions with periodic rules, and every so often copy the output of + actions with periodic rules, and every so often copy the output of print --forecast to the journal. You can generate one-time transactions too: just write a period expres- - sion specifying a date with no report interval. (You could also write - a normal transaction with a future date, but remember this disables + sion specifying a date with no report interval. (You could also write + a normal transaction with a future date, but remember this disables forecast transactions on previous dates.) Budgeting with periodic transactions - With the --budget flag, currently supported by the balance command, - each periodic transaction rule declares recurring budget goals for the - specified accounts. Eg the first example above declares a goal of - spending $2000 on rent (and also, a goal of depositing $2000 into - checking) every month. Goals and actual performance can then be com- + With the --budget flag, currently supported by the balance command, + each periodic transaction rule declares recurring budget goals for the + specified accounts. Eg the first example above declares a goal of + spending $2000 on rent (and also, a goal of depositing $2000 into + checking) every month. Goals and actual performance can then be com- pared in budget reports. - For more details, see: balance: Budget report and Cookbook: Budgeting + For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. Transaction Modifiers - Transaction modifier rules describe changes that should be applied - automatically to certain transactions. Currently, this means adding + Transaction modifier rules describe changes that should be applied + automatically to certain transactions. Currently, this means adding extra postings (also known as "automated postings"). Transaction modi- fiers are enabled by the --auto flag. - A transaction modifier rule looks a bit like a normal journal entry, - except the first line is an equal sign (=) followed by a query - (mnemonic: = suggests matching something.): + A transaction modifier rule looks quite like a normal transaction, + except the first line is an equals sign followed by a query that + matches certain postings (mnemonic: = suggests matching). And each + "posting" is actually a posting-generating rule: + = QUERY + ACCT AMT + ACCT [AMT] + ... + + The posting rules look just like normal postings, except the amount can + be: + + o a normal amount with a commodity symbol, eg $2. This will be used + as-is. + + o a number, eg 2. The commodity symbol (if any) from the matched post- + ing will be added to this. + + o a numeric multiplier, eg *2 (a star followed by a number N). The + matched posting's amount (and total price, if any) will be multiplied + by N. + + o a multiplier with a commodity symbol, eg *$2 (a star, number N, and + symbol S). The matched posting's amount will be multiplied by N, and + its commodity symbol will be replaced with S. + + Some examples: + + ; every time I buy food, schedule a dollar donation + = expenses:food + (liabilities:charity) $-1 + + ; when I buy a gift, also deduct that amount from a budget envelope subaccount = expenses:gifts - budget:gifts *-1 - assets:budget *1 + assets:checking:gifts *-1 + assets:checking *1 - The posting amounts can be of the form *N, which means "the amount of - the matched transaction's first posting, multiplied by N". They can - also be ordinary fixed amounts. Fixed amounts with no commodity symbol - will be given the same commodity as the matched transaction's first - posting. + 2017/12/1 + expenses:food $10 + assets:checking - This example adds a corresponding (unbalanced) budget posting to every - transaction involving the expenses:gifts account: - - = expenses:gifts - (budget:gifts) *-1 - - 2017-12-14 - expenses:gifts $20 - assets + 2017/12/14 + expenses:gifts $20 + assets:checking $ hledger print --auto + 2017/12/01 + expenses:food $10 + assets:checking + (liabilities:charity) $-1 + 2017/12/14 expenses:gifts $20 - (budget:gifts) $-20 - assets + assets:checking + assets:checking:gifts -$20 + assets:checking $20 - Like postings recorded by hand, automated postings participate in - transaction balancing, missing amount inference and balance assertions. + Postings added by transaction modifiers participate in transaction bal- + ancing, missing amount inference and balance assertions, like regular + postings. EDITOR SUPPORT Add-on modes exist for various text editors, to make working with jour- @@ -1151,4 +1270,4 @@ SEE ALSO -hledger 1.11.99 September 2018 hledger_journal(5) +hledger 1.12 December 2018 hledger_journal(5) diff --git a/hledger-lib/hledger_timeclock.5 b/hledger-lib/hledger_timeclock.5 index a49e3c1b5..769f3862a 100644 --- a/hledger-lib/hledger_timeclock.5 +++ b/hledger-lib/hledger_timeclock.5 @@ -1,5 +1,5 @@ -.TH "hledger_timeclock" "5" "September 2018" "hledger 1.11.99" "hledger User Manuals" +.TH "hledger_timeclock" "5" "December 2018" "hledger 1.12" "hledger User Manuals" diff --git a/hledger-lib/hledger_timeclock.info b/hledger-lib/hledger_timeclock.info index ae84922f1..17696bac5 100644 --- a/hledger-lib/hledger_timeclock.info +++ b/hledger-lib/hledger_timeclock.info @@ -4,8 +4,8 @@ stdin.  File: hledger_timeclock.info, Node: Top, Up: (dir) -hledger_timeclock(5) hledger 1.11.99 -************************************ +hledger_timeclock(5) hledger 1.12 +********************************* hledger can read timeclock files. As with Ledger, these are (a subset of) timeclock.el's format, containing clock-in and clock-out entries as diff --git a/hledger-lib/hledger_timeclock.txt b/hledger-lib/hledger_timeclock.txt index fc0e218de..044727fc0 100644 --- a/hledger-lib/hledger_timeclock.txt +++ b/hledger-lib/hledger_timeclock.txt @@ -77,4 +77,4 @@ SEE ALSO -hledger 1.11.99 September 2018 hledger_timeclock(5) +hledger 1.12 December 2018 hledger_timeclock(5) diff --git a/hledger-lib/hledger_timedot.5 b/hledger-lib/hledger_timedot.5 index 763a2d891..56ec37a6f 100644 --- a/hledger-lib/hledger_timedot.5 +++ b/hledger-lib/hledger_timedot.5 @@ -1,5 +1,5 @@ -.TH "hledger_timedot" "5" "September 2018" "hledger 1.11.99" "hledger User Manuals" +.TH "hledger_timedot" "5" "December 2018" "hledger 1.12" "hledger User Manuals" diff --git a/hledger-lib/hledger_timedot.info b/hledger-lib/hledger_timedot.info index e0438472f..2bd7d15e8 100644 --- a/hledger-lib/hledger_timedot.info +++ b/hledger-lib/hledger_timedot.info @@ -4,8 +4,8 @@ stdin.  File: hledger_timedot.info, Node: Top, Next: FILE FORMAT, Up: (dir) -hledger_timedot(5) hledger 1.11.99 -********************************** +hledger_timedot(5) hledger 1.12 +******************************* Timedot is a plain text format for logging dated, categorised quantities (of time, usually), supported by hledger. It is convenient for @@ -110,7 +110,7 @@ $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4  Tag Table: Node: Top76 -Node: FILE FORMAT813 -Ref: #file-format914 +Node: FILE FORMAT807 +Ref: #file-format908  End Tag Table diff --git a/hledger-lib/hledger_timedot.txt b/hledger-lib/hledger_timedot.txt index ce334b4d0..d669f6d08 100644 --- a/hledger-lib/hledger_timedot.txt +++ b/hledger-lib/hledger_timedot.txt @@ -124,4 +124,4 @@ SEE ALSO -hledger 1.11.99 September 2018 hledger_timedot(5) +hledger 1.12 December 2018 hledger_timedot(5) diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index afac2b516..3fb99beaa 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "hledger\-ui" "1" "September 2018" "hledger\-ui 1.11.99" "hledger User Manuals" +.TH "hledger\-ui" "1" "December 2018" "hledger\-ui 1.12" "hledger User Manuals" diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index c2c8bf810..9647fccb2 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -3,8 +3,8 @@ This is hledger-ui.info, produced by makeinfo version 6.5 from stdin.  File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-ui(1) hledger-ui 1.11.99 -******************************** +hledger-ui(1) hledger-ui 1.12 +***************************** hledger-ui is hledger's curses-style interface, providing an efficient full-window text UI for viewing accounts and transactions, and some @@ -396,19 +396,19 @@ to cancel the reload attempt.)  Tag Table: Node: Top71 -Node: OPTIONS1090 -Ref: #options1187 -Node: KEYS4606 -Ref: #keys4701 -Node: SCREENS7957 -Ref: #screens8042 -Node: Accounts screen8132 -Ref: #accounts-screen8260 -Node: Register screen10476 -Ref: #register-screen10631 -Node: Transaction screen12628 -Ref: #transaction-screen12786 -Node: Error screen13656 -Ref: #error-screen13778 +Node: OPTIONS1084 +Ref: #options1181 +Node: KEYS4600 +Ref: #keys4695 +Node: SCREENS7951 +Ref: #screens8036 +Node: Accounts screen8126 +Ref: #accounts-screen8254 +Node: Register screen10470 +Ref: #register-screen10625 +Node: Transaction screen12622 +Ref: #transaction-screen12780 +Node: Error screen13650 +Ref: #error-screen13772  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index ef5dcea8b..4729f5ae6 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -404,4 +404,4 @@ SEE ALSO -hledger-ui 1.11.99 September 2018 hledger-ui(1) +hledger-ui 1.12 December 2018 hledger-ui(1) diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index bca94ba94..cf6a6e4b0 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "hledger\-web" "1" "September 2018" "hledger\-web 1.11.99" "hledger User Manuals" +.TH "hledger\-web" "1" "December 2018" "hledger\-web 1.12" "hledger User Manuals" diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index eb49f2d0b..aa50d6587 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -3,8 +3,8 @@ This is hledger-web.info, produced by makeinfo version 6.5 from stdin.  File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-web(1) hledger-web 1.11.99 -********************************** +hledger-web(1) hledger-web 1.12 +******************************* hledger-web is hledger's web interface. It starts a simple web application for browsing and adding transactions, and optionally opens @@ -212,7 +212,7 @@ this, insert a '--' argument before.)  Tag Table: Node: Top72 -Node: OPTIONS3160 -Ref: #options3245 +Node: OPTIONS3154 +Ref: #options3239  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 986fcb1bf..685358e1d 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -251,4 +251,4 @@ SEE ALSO -hledger-web 1.11.99 September 2018 hledger-web(1) +hledger-web 1.12 December 2018 hledger-web(1) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 2d95aa4b6..24b4b1507 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "hledger" "1" "September 2018" "hledger 1.11.99" "hledger User Manuals" +.TH "hledger" "1" "December 2018" "hledger 1.12" "hledger User Manuals" @@ -344,46 +344,125 @@ line. To prevent this expansion of \f[C]\@\f[]\-arguments, precede them with a \f[C]\-\-\f[] argument. For more, see Save frequently used options. -.SS Special characters +.SS Special characters in arguments and queries .PP -Option and argument values which contain problematic characters should -be escaped with double quotes, backslashes, or (best) single quotes. -Problematic characters means spaces, and also characters which are -significant to your command shell, such as less\-than/greater\-than. +In shell command lines, option and argument values which contain +\[lq]problematic\[rq] characters, ie spaces, and also characters +significant to your shell such as \f[C]<\f[], \f[C]>\f[], \f[C](\f[], +\f[C])\f[], \f[C]|\f[] and \f[C]$\f[], should be escaped by enclosing +them in quotes or by writing backslashes before the characters. Eg: -\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[]. .PP -Characters which are significant both to the shell and in regular -expressions sometimes need to be double\-escaped. +\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[]. +.SS More escaping +.PP +Characters significant both to the shell and in regular expressions may +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: -\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] or -\f[C]hledger\ balance\ cur:\\\\$\f[]. .PP -When hledger is invoking an addon executable (like hledger\-ui), options -and arguments get de\-escaped once more, so you might need -\f[I]triple\f[]\-escaping. -Eg: \f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] or -\f[C]hledger\ ui\ cur:\\\\\\\\$\f[] in bash. +\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] +.PP +or: +.PP +\f[C]hledger\ balance\ cur:\\\\$\f[] +.SS Even more escaping +.PP +When hledger runs an addon executable (eg you type \f[C]hledger\ ui\f[], +hledger runs \f[C]hledger\-ui\f[]), it de\-escapes command\-line options +and arguments once, so you might need to \f[I]triple\f[]\-escape. +Eg in bash, running the ui command and matching the dollar sign, it's: +.PP +\f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] +.PP +or: +.PP +\f[C]hledger\ ui\ cur:\\\\\\\\$\f[] +.PP +If you asked why \f[I]four\f[] slashes above, this may help: +.PP +.TS +tab(@); +l l. +T{ +unescaped: +T}@T{ +\f[C]$\f[] +T} +T{ +escaped: +T}@T{ +\f[C]\\$\f[] +T} +T{ +double\-escaped: +T}@T{ +\f[C]\\\\$\f[] +T} +T{ +triple\-escaped: +T}@T{ +\f[C]\\\\\\\\$\f[] +T} +.TE +.PP (The number of backslashes in fish shell is left as an exercise for the reader.) .PP -Inside a file used for argument expansion, one less level of escaping is -enough. -(And in this case, backslashes seem to work better than quotes. -Eg: \f[C]cur:\\$\f[]). +You can always avoid the extra escaping for addons by running the addon +directly: +.PP +\f[C]hledger\-ui\ cur:\\\\$\f[] +.SS Less escaping +.PP +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: +.PP +\f[C]ghci>\ :main\ balance\ cur:\\$\f[] +.SS Command line tips .PP If in doubt, keep things simple: .IP \[bu] 2 -run add\-on executables directly +write options after the command (\f[C]hledger\ CMD\ \-OPTIONS\ ARGS\f[]) .IP \[bu] 2 -write options after the command +run add\-on executables directly (\f[C]hledger\-ui\ \-OPTIONS\ ARGS\f[]) .IP \[bu] 2 enclose problematic args in single quotes .IP \[bu] 2 if needed, also add a backslash to escape regexp metacharacters .PP -If you're really stumped, add \f[C]\-\-debug=2\f[] to troubleshoot. +To find out exactly how a command line is being parsed, add +\f[C]\-\-debug=2\f[] to troubleshoot. +.SS Unicode characters +.PP +hledger is expected to handle unicode (non\-ascii) characters, but this +requires a well\-configured environment. +.PP +To handle unicode characters in the command line or input data, a system +locale that can decode them must be configured (POSIX's default +\f[C]C\f[] locale will not work). +Eg in bash, you could do: +.IP +.nf +\f[C] +export\ LANG=en_US.UTF\-8 +\f[] +.fi +.PP +See Troubleshooting for more about this. +.PP +Unicode characters should appear correctly in hledger's output. +For the hledger and hledger\-ui tools, this requires that +.IP \[bu] 2 +your terminal supports unicode +.IP \[bu] 2 +the terminal's font includes the required unicode glyphs +.IP \[bu] 2 +the terminal is configured to display \[lq]wide\[rq] characters as +double width (otherwise report alignment will be off) .SS Input files .PP hledger reads transactions from a data file (and the add command writes @@ -2900,7 +2979,7 @@ according to various schemes. .SS irr .PP hledger\-irr calculates the internal rate of return of an investment -account. +account, but it's superseded now by the built\-in roi command. .SS Experimental add\-ons .PP These are available in source form in the hledger repo's bin/ directory; diff --git a/hledger/hledger.info b/hledger/hledger.info index 71c22fb19..814cfcdbc 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -3,8 +3,8 @@ This is hledger.info, produced by makeinfo version 6.5 from stdin.  File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir) -hledger(1) hledger 1.11.99 -************************** +hledger(1) hledger 1.12 +*********************** This is hledger's command-line interface (there are also curses and web interfaces). Its basic function is to read a plain text file describing @@ -119,7 +119,9 @@ File: hledger.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top * Command options:: * Command arguments:: * Argument files:: -* Special characters:: +* Special characters in arguments and queries:: +* Command line tips:: +* Unicode characters:: * Input files:: * Smart dates:: * Report start & end date:: @@ -277,7 +279,7 @@ Most hledger commands accept arguments after the command name, which are often a query, filtering the data in some way.  -File: hledger.info, Node: Argument files, Next: Special characters, Prev: Command arguments, Up: OPTIONS +File: hledger.info, Node: Argument files, Next: Special characters in arguments and queries, Prev: Command arguments, Up: OPTIONS 2.4 Argument files ================== @@ -288,47 +290,132 @@ prevent this expansion of '@'-arguments, precede them with a '--' argument. For more, see Save frequently used options.  -File: hledger.info, Node: Special characters, Next: Input files, Prev: Argument files, Up: OPTIONS +File: hledger.info, Node: Special characters in arguments and queries, Next: Command line tips, Prev: Argument files, Up: OPTIONS -2.5 Special characters -====================== +2.5 Special characters in arguments and queries +=============================================== -Option and argument values which contain problematic characters should -be escaped with double quotes, backslashes, or (best) single quotes. -Problematic characters means spaces, and also characters which are -significant to your command shell, such as less-than/greater-than. Eg: -'hledger register -p 'last year' "accounts receivable +In shell command lines, option and argument values which contain +"problematic" characters, ie spaces, and also characters significant to +your 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 (receivable|payable)" amt:\>100'. +* Menu: - Characters which are significant both to the shell and in regular -expressions sometimes need to be double-escaped. These include -parentheses, the pipe symbol and the dollar sign. Eg, to match the -dollar symbol, bash users should do: 'hledger balance cur:'\$'' or -'hledger balance cur:\\$'. +* More escaping:: +* Even more escaping:: +* Less escaping:: - When hledger is invoking an addon executable (like hledger-ui), -options and arguments get de-escaped once more, so you might need -_triple_-escaping. Eg: 'hledger ui cur:'\\$'' or 'hledger ui cur:\\\\$' -in bash. (The number of backslashes in fish shell is left as an -exercise for the reader.) + +File: hledger.info, Node: More escaping, Next: Even more escaping, Up: Special characters in arguments and queries - Inside a file used for argument expansion, one less level of escaping -is enough. (And in this case, backslashes seem to work better than -quotes. Eg: 'cur:\$'). +2.5.1 More escaping +------------------- - If in doubt, keep things simple: +Characters significant both to the shell and in regular expressions may +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: - * run add-on executables directly - * write options after the command + 'hledger balance cur:'\$'' + + or: + + 'hledger balance cur:\\$' + + +File: hledger.info, Node: Even more escaping, Next: Less escaping, Prev: More escaping, Up: Special characters in arguments and queries + +2.5.2 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 +command and matching the dollar sign, it's: + + 'hledger ui cur:'\\$'' + + or: + + 'hledger ui cur:\\\\$' + + If you asked why _four_ slashes above, this may help: + +unescaped: '$' +escaped: '\$' +double-escaped: '\\$' +triple-escaped: '\\\\$' + + (The number of backslashes in fish shell is left as an exercise for +the reader.) + + You can always avoid the extra escaping for addons by running the +addon directly: + + 'hledger-ui cur:\\$' + + +File: hledger.info, Node: Less escaping, Prev: Even more escaping, Up: Special characters in arguments and queries + +2.5.3 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 +than at the command line. And backslashes may work better than quotes. +Eg: + + 'ghci> :main balance cur:\$' + + +File: hledger.info, Node: Command line tips, Next: Unicode characters, Prev: Special characters in arguments and queries, Up: OPTIONS + +2.6 Command line tips +===================== + +If in doubt, keep things simple: + + * write options after the command ('hledger CMD -OPTIONS ARGS') + * run add-on executables directly ('hledger-ui -OPTIONS ARGS') * enclose problematic args in single quotes * if needed, also add a backslash to escape regexp metacharacters - If you're really stumped, add '--debug=2' to troubleshoot. + To find out exactly how a command line is being parsed, add +'--debug=2' to troubleshoot.  -File: hledger.info, Node: Input files, Next: Smart dates, Prev: Special characters, Up: OPTIONS +File: hledger.info, Node: Unicode characters, Next: Input files, Prev: Command line tips, Up: OPTIONS -2.6 Input files +2.7 Unicode characters +====================== + +hledger is expected to handle unicode (non-ascii) characters, but this +requires a well-configured environment. + + To handle unicode characters in the command line or input data, a +system locale that can decode them must be configured (POSIX's default +'C' locale will not work). Eg in bash, you could do: + +export LANG=en_US.UTF-8 + + See Troubleshooting for more about this. + + Unicode characters should appear correctly in hledger's output. For +the hledger and hledger-ui tools, this requires that + + * your terminal supports unicode + * the terminal's font includes the required unicode glyphs + * the terminal is configured to display "wide" characters as double + width (otherwise report alignment will be off) + + +File: hledger.info, Node: Input files, Next: Smart dates, Prev: Unicode characters, Up: OPTIONS + +2.8 Input files =============== hledger reads transactions from a data file (and the add command writes @@ -383,7 +470,7 @@ the files, eg: 'cat a.journal b.journal | hledger -f- CMD'.  File: hledger.info, Node: Smart dates, Next: Report start & end date, Prev: Input files, Up: OPTIONS -2.7 Smart dates +2.9 Smart dates =============== hledger's user interfaces accept a flexible "smart date" syntax (unlike @@ -416,8 +503,8 @@ results:  File: hledger.info, Node: Report start & end date, Next: Report intervals, Prev: Smart dates, Up: OPTIONS -2.8 Report start & end date -=========================== +2.10 Report start & end date +============================ Most hledger reports show the full span of time represented by the journal data, by default. So, the effective report start and end dates @@ -445,8 +532,8 @@ need to write the date _after_ the last day you want to include.  File: hledger.info, Node: Report intervals, Next: Period expressions, Prev: Report start & end date, Up: OPTIONS -2.9 Report intervals -==================== +2.11 Report intervals +===================== A report interval can be specified so that commands like register, balance and activity will divide their reports into multiple subperiods. @@ -458,7 +545,7 @@ intervals can not be specified with a query, currently.  File: hledger.info, Node: Period expressions, Next: Depth limiting, Prev: Report intervals, Up: OPTIONS -2.10 Period expressions +2.12 Period expressions ======================= The '-p/--period' option accepts period expressions, a shorthand way of @@ -566,7 +653,7 @@ start date and exclusive end date):  File: hledger.info, Node: Depth limiting, Next: Pivoting, Prev: Period expressions, Up: OPTIONS -2.11 Depth limiting +2.13 Depth limiting =================== With the '--depth N' option (short form: '-N'), commands like account, @@ -578,7 +665,7 @@ less detail. This flag has the same effect as a 'depth:' query argument  File: hledger.info, Node: Pivoting, Next: Cost, Prev: Depth limiting, Up: OPTIONS -2.12 Pivoting +2.14 Pivoting ============= Normally hledger sums amounts, and organizes them in a hierarchy, based @@ -635,7 +722,7 @@ $ hledger balance --pivot member acct:.  File: hledger.info, Node: Cost, Next: Market value, Prev: Pivoting, Up: OPTIONS -2.13 Cost +2.15 Cost ========= The '-B/--cost' flag converts amounts to their cost at transaction time, @@ -644,7 +731,7 @@ if they have a transaction price specified.  File: hledger.info, Node: Market value, Next: Combining -B and -V, Prev: Cost, Up: OPTIONS -2.14 Market value +2.16 Market value ================= The '-V/--value' flag converts reported amounts to their current market @@ -696,7 +783,7 @@ of the prices on each column's end date.)  File: hledger.info, Node: Combining -B and -V, Next: Output destination, Prev: Market value, Up: OPTIONS -2.15 Combining -B and -V +2.17 Combining -B and -V ======================== Using -B/-cost and -V/-value together is currently allowed, but the @@ -706,7 +793,7 @@ this.  File: hledger.info, Node: Output destination, Next: Output format, Prev: Combining -B and -V, Up: OPTIONS -2.16 Output destination +2.18 Output destination ======================= Some commands (print, register, stats, the balance commands) can write @@ -719,7 +806,7 @@ $ hledger balance -o FILE # write to FILE  File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS -2.17 Output format +2.19 Output format ================== Some commands can write their output in other formats. Eg print and @@ -733,7 +820,7 @@ $ hledger balance -o FILE.csv # write CSV to FILE.csv  File: hledger.info, Node: Regular expressions, Prev: Output format, Up: OPTIONS -2.18 Regular expressions +2.20 Regular expressions ======================== hledger uses regular expressions in a number of places: @@ -2419,7 +2506,7 @@ File: hledger.info, Node: irr, Prev: interest, Up: Third party add-ons --------- hledger-irr calculates the internal rate of return of an investment -account. +account, but it's superseded now by the built-in roi command.  File: hledger.info, Node: Experimental add-ons, Prev: Third party add-ons, Up: ADD-ON COMMANDS @@ -2467,142 +2554,152 @@ hledger-check.hs checks more powerful account balance assertions.  Tag Table: Node: Top68 -Node: EXAMPLES1890 -Ref: #examples1990 -Node: OPTIONS3636 -Ref: #options3738 -Node: General options4103 -Ref: #general-options4228 -Node: Command options6910 -Ref: #command-options7061 -Node: Command arguments7459 -Ref: #command-arguments7613 -Node: Argument files7734 -Ref: #argument-files7885 -Node: Special characters8151 -Ref: #special-characters8304 -Node: Input files9723 -Ref: #input-files9859 -Node: Smart dates11829 -Ref: #smart-dates11970 -Node: Report start & end date13376 -Ref: #report-start-end-date13546 -Node: Report intervals14611 -Ref: #report-intervals14774 -Node: Period expressions15175 -Ref: #period-expressions15335 -Node: Depth limiting19292 -Ref: #depth-limiting19436 -Node: Pivoting19778 -Ref: #pivoting19896 -Node: Cost21572 -Ref: #cost21680 -Node: Market value21798 -Ref: #market-value21933 -Node: Combining -B and -V23299 -Ref: #combining--b-and--v23462 -Node: Output destination23609 -Ref: #output-destination23771 -Node: Output format24054 -Ref: #output-format24206 -Node: Regular expressions24591 -Ref: #regular-expressions24728 -Node: QUERIES26089 -Ref: #queries26191 -Node: COMMANDS30153 -Ref: #commands30265 -Node: accounts31265 -Ref: #accounts31363 -Node: activity32609 -Ref: #activity32719 -Node: add33079 -Ref: #add33178 -Node: balance35839 -Ref: #balance35950 -Node: Classic balance report39033 -Ref: #classic-balance-report39206 -Node: Customising the classic balance report40575 -Ref: #customising-the-classic-balance-report40803 -Node: Colour support42877 -Ref: #colour-support43044 -Node: Flat mode43217 -Ref: #flat-mode43365 -Node: Depth limited balance reports43778 -Ref: #depth-limited-balance-reports43978 -Node: Multicolumn balance report44434 -Ref: #multicolumn-balance-report44632 -Node: Budget report49812 -Ref: #budget-report49955 -Ref: #output-format-152989 -Node: balancesheet53067 -Ref: #balancesheet53203 -Node: balancesheetequity55514 -Ref: #balancesheetequity55663 -Node: cashflow56200 -Ref: #cashflow56328 -Node: check-dates58451 -Ref: #check-dates58578 -Node: check-dupes58695 -Ref: #check-dupes58819 -Node: close58956 -Ref: #close59064 -Node: files59394 -Ref: #files59495 -Node: help59636 -Ref: #help59736 -Node: import60810 -Ref: #import60924 -Node: incomestatement61654 -Ref: #incomestatement61788 -Node: prices64192 -Ref: #prices64307 -Node: print64579 -Ref: #print64689 -Node: print-unique69583 -Ref: #print-unique69709 -Node: register69777 -Ref: #register69904 -Node: Custom register output74405 -Ref: #custom-register-output74534 -Node: register-match75764 -Ref: #register-match75898 -Node: rewrite76081 -Ref: #rewrite76196 -Node: roi76265 -Ref: #roi76363 -Node: stats76479 -Ref: #stats76578 -Node: tags77448 -Ref: #tags77546 -Node: test77782 -Ref: #test77866 -Node: ADD-ON COMMANDS78574 -Ref: #add-on-commands78684 -Node: Official add-ons79971 -Ref: #official-add-ons80111 -Node: api80198 -Ref: #api80287 -Node: ui80339 -Ref: #ui80438 -Node: web80496 -Ref: #web80585 -Node: Third party add-ons80631 -Ref: #third-party-add-ons80806 -Node: diff80941 -Ref: #diff81038 -Node: iadd81137 -Ref: #iadd81251 -Node: interest81334 -Ref: #interest81455 -Node: irr81550 -Ref: #irr81648 -Node: Experimental add-ons81726 -Ref: #experimental-add-ons81878 -Node: autosync82158 -Ref: #autosync82269 -Node: chart82508 -Ref: #chart82627 -Node: check82698 -Ref: #check82800 +Node: EXAMPLES1884 +Ref: #examples1984 +Node: OPTIONS3630 +Ref: #options3732 +Node: General options4167 +Ref: #general-options4292 +Node: Command options6974 +Ref: #command-options7125 +Node: Command arguments7523 +Ref: #command-arguments7677 +Node: Argument files7798 +Ref: #argument-files7974 +Node: Special characters in arguments and queries8240 +Ref: #special-characters-in-arguments-and-queries8474 +Node: More escaping8924 +Ref: #more-escaping9086 +Node: Even more escaping9382 +Ref: #even-more-escaping9576 +Node: Less escaping10247 +Ref: #less-escaping10409 +Node: Command line tips10654 +Ref: #command-line-tips10840 +Node: Unicode characters11217 +Ref: #unicode-characters11373 +Node: Input files12098 +Ref: #input-files12234 +Node: Smart dates14204 +Ref: #smart-dates14345 +Node: Report start & end date15751 +Ref: #report-start-end-date15923 +Node: Report intervals16988 +Ref: #report-intervals17153 +Node: Period expressions17554 +Ref: #period-expressions17714 +Node: Depth limiting21671 +Ref: #depth-limiting21815 +Node: Pivoting22157 +Ref: #pivoting22275 +Node: Cost23951 +Ref: #cost24059 +Node: Market value24177 +Ref: #market-value24312 +Node: Combining -B and -V25678 +Ref: #combining--b-and--v25841 +Node: Output destination25988 +Ref: #output-destination26150 +Node: Output format26433 +Ref: #output-format26585 +Node: Regular expressions26970 +Ref: #regular-expressions27107 +Node: QUERIES28468 +Ref: #queries28570 +Node: COMMANDS32532 +Ref: #commands32644 +Node: accounts33644 +Ref: #accounts33742 +Node: activity34988 +Ref: #activity35098 +Node: add35458 +Ref: #add35557 +Node: balance38218 +Ref: #balance38329 +Node: Classic balance report41412 +Ref: #classic-balance-report41585 +Node: Customising the classic balance report42954 +Ref: #customising-the-classic-balance-report43182 +Node: Colour support45256 +Ref: #colour-support45423 +Node: Flat mode45596 +Ref: #flat-mode45744 +Node: Depth limited balance reports46157 +Ref: #depth-limited-balance-reports46357 +Node: Multicolumn balance report46813 +Ref: #multicolumn-balance-report47011 +Node: Budget report52191 +Ref: #budget-report52334 +Ref: #output-format-155368 +Node: balancesheet55446 +Ref: #balancesheet55582 +Node: balancesheetequity57893 +Ref: #balancesheetequity58042 +Node: cashflow58579 +Ref: #cashflow58707 +Node: check-dates60830 +Ref: #check-dates60957 +Node: check-dupes61074 +Ref: #check-dupes61198 +Node: close61335 +Ref: #close61443 +Node: files61773 +Ref: #files61874 +Node: help62015 +Ref: #help62115 +Node: import63189 +Ref: #import63303 +Node: incomestatement64033 +Ref: #incomestatement64167 +Node: prices66571 +Ref: #prices66686 +Node: print66958 +Ref: #print67068 +Node: print-unique71962 +Ref: #print-unique72088 +Node: register72156 +Ref: #register72283 +Node: Custom register output76784 +Ref: #custom-register-output76913 +Node: register-match78143 +Ref: #register-match78277 +Node: rewrite78460 +Ref: #rewrite78575 +Node: roi78644 +Ref: #roi78742 +Node: stats78858 +Ref: #stats78957 +Node: tags79827 +Ref: #tags79925 +Node: test80161 +Ref: #test80245 +Node: ADD-ON COMMANDS80953 +Ref: #add-on-commands81063 +Node: Official add-ons82350 +Ref: #official-add-ons82490 +Node: api82577 +Ref: #api82666 +Node: ui82718 +Ref: #ui82817 +Node: web82875 +Ref: #web82964 +Node: Third party add-ons83010 +Ref: #third-party-add-ons83185 +Node: diff83320 +Ref: #diff83417 +Node: iadd83516 +Ref: #iadd83630 +Node: interest83713 +Ref: #interest83834 +Node: irr83929 +Ref: #irr84027 +Node: Experimental add-ons84158 +Ref: #experimental-add-ons84310 +Node: autosync84590 +Ref: #autosync84701 +Node: chart84940 +Ref: #chart85059 +Node: check85130 +Ref: #check85232  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 8181e3975..1409f56a0 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -238,41 +238,98 @@ OPTIONS prevent this expansion of @-arguments, precede them with a -- argument. For more, see Save frequently used options. - Special characters - Option and argument values which contain problematic characters should - be escaped with double quotes, backslashes, or (best) single quotes. - Problematic characters means spaces, and also characters which are sig- - nificant to your command shell, such as less-than/greater-than. Eg: + 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 + in quotes or by writing backslashes before the characters. Eg: + hledger register -p 'last year' "accounts receivable (receiv- able|payable)" amt:\>100. - Characters which are significant both to the shell and in regular - expressions sometimes need to be double-escaped. These include paren- - theses, the pipe symbol and the dollar sign. Eg, to match the dollar - symbol, bash users should do: hledger balance cur:'\$' or hledger bal- - ance cur:\\$. + More escaping + Characters significant both to the shell and in regular expressions may + 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: - When hledger is invoking an addon executable (like hledger-ui), options - and arguments get de-escaped once more, so you might need triple-escap- - ing. Eg: hledger ui cur:'\\$' or hledger ui cur:\\\\$ in bash. (The - number of backslashes in fish shell is left as an exercise for the + hledger balance cur:'\$' + + or: + + 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 + command and matching the dollar sign, it's: + + hledger ui cur:'\\$' + + or: + + hledger ui cur:\\\\$ + + If you asked why four slashes above, this may help: + + + unescaped: $ + escaped: \$ + double-escaped: \\$ + triple-escaped: \\\\$ + + (The number of backslashes in fish shell is left as an exercise for the reader.) - Inside a file used for argument expansion, one less level of escaping - is enough. (And in this case, backslashes seem to work better than - quotes. Eg: cur:\$). + You can always avoid the extra escaping for addons by running the addon + directly: + 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 + than at the command line. And backslashes may work better than quotes. + Eg: + + ghci> :main balance cur:\$ + + Command line tips If in doubt, keep things simple: - o run add-on executables directly + o write options after the command (hledger CMD -OPTIONS ARGS) - o write options after the command + o run add-on executables directly (hledger-ui -OPTIONS ARGS) o enclose problematic args in single quotes o if needed, also add a backslash to escape regexp metacharacters - If you're really stumped, add --debug=2 to troubleshoot. + To find out exactly how a command line is being parsed, add --debug=2 + to troubleshoot. + + Unicode characters + hledger is expected to handle unicode (non-ascii) characters, but this + requires a well-configured environment. + + To handle unicode characters in the command line or input data, a sys- + tem locale that can decode them must be configured (POSIX's default C + locale will not work). Eg in bash, you could do: + + export LANG=en_US.UTF-8 + + See Troubleshooting for more about this. + + Unicode characters should appear correctly in hledger's output. For + the hledger and hledger-ui tools, this requires that + + o your terminal supports unicode + + o the terminal's font includes the required unicode glyphs + + o the terminal is configured to display "wide" characters as double + width (otherwise report alignment will be off) Input files hledger reads transactions from a data file (and the add command writes @@ -340,6 +397,7 @@ OPTIONS 4+ digits, month is 1-12, day is 1-31 2004 start of year + 2004/10 start of month 10/1 month and day in current year @@ -397,7 +455,6 @@ OPTIONS rent month -p thismonth all transactions in the current month - date:2016/3/17- the above written as queries instead date:-12/1 @@ -531,7 +588,6 @@ OPTIONS -p "every 2nd Monday" - period bound- aries 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 @@ -2094,7 +2150,7 @@ ADD-ON COMMANDS irr hledger-irr calculates the internal rate of return of an investment - account. + account, but it's superseded now by the built-in roi command. Experimental add-ons These are available in source form in the hledger repo's bin/ direc- @@ -2230,4 +2286,4 @@ SEE ALSO -hledger 1.11.99 September 2018 hledger(1) +hledger 1.12 December 2018 hledger(1)