diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index a28d80a88..55f5149f3 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -1,6 +1,6 @@ .\"t -.TH "hledger_csv" "5" "February 2020" "hledger 1.16.99" "hledger User Manuals" +.TH "hledger_csv" "5" "March 2020" "hledger 1.17" "hledger User Manuals" @@ -236,10 +236,7 @@ amount2 %amzamount #include categorisation.rules # add a third posting for fees, but only if they are non-zero. -# Commas in the data makes counting fields hard, so count from the right instead. -# (Regex translation: \[dq]a field containing a non-zero dollar amount, -# immediately before the 1 right-most fields\[dq]) -if ,\[rs]$[1-9][.0-9]+(,[\[ha],]*){1}$ +if %fees [1-9] account3 expenses:fees amount3 %fees \f[R] @@ -308,13 +305,11 @@ description %description_ %itemtitle comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ # convert to short currency symbols -# Note: in conditional block regexps, the line of csv being matched is -# a synthetic one: the unquoted field values, with commas between them. -if ,USD, +if %currency USD currency $ -if ,EUR, +if %currency EUR currency E -if ,GBP, +if %currency GBP currency P # generate postings @@ -328,9 +323,8 @@ amount1 %netamount # (account2 is set below) amount2 -%grossamount -# if there\[aq]s a fee (9th field), add a third posting for the money taken by paypal. -# TODO: This regexp fails when fields contain a comma (generates a third posting with zero amount) -if \[ha]([\[ha],]+,){8}[\[ha]0] +# if there\[aq]s a fee, add a third posting for the money taken by paypal. +if %feeamount [1-9] account3 expenses:banking:paypal amount3 -%feeamount comment3 business: @@ -338,11 +332,11 @@ if \[ha]([\[ha],]+,){8}[\[ha]0] # choose an account for the second posting # override the default account names: -# if amount (8th field) is positive, it\[aq]s income (a debit) -if \[ha]([\[ha],]+,){7}[0-9] +# if the amount is positive, it\[aq]s income (a debit) +if %grossamount \[ha][\[ha]-] account2 income:unknown # if negative, it\[aq]s an expense (a credit) -if \[ha]([\[ha],]+,){7}- +if %grossamount \[ha]- account2 expenses:unknown # apply common rules for setting account2 & other tweaks @@ -585,13 +579,13 @@ See also: File Extension. .IP .nf \f[C] -if PATTERN +if MATCHER RULE if -PATTERN -PATTERN -PATTERN +MATCHER +MATCHER +MATCHER RULE RULE \f[R] @@ -602,28 +596,40 @@ applied only to CSV records which match certain patterns. They are often used for customising account names based on transaction descriptions. .PP -A single pattern can be written on the same line as the \[dq]if\[dq]; or -multiple patterns can be written on the following lines, non-indented. -Multiple patterns are OR\[aq]d (any one of them can match). -Patterns are case-insensitive regular expressions which try to match -anywhere within the whole CSV record (POSIX extended regular expressions -with some additions, see -https://hledger.org/hledger.html#regular-expressions). -Note the CSV record they see is close to, but not identical to, the one -in the CSV file; enclosing double quotes will be removed, and the -separator character is always comma. -.PP -It\[aq]s not yet easy to match within a specific field. -If the data does not contain commas, you can hack it with a regular -expression like: +Each MATCHER can be a record matcher, which looks like this: .IP .nf \f[C] -# match \[dq]foo\[dq] in the fourth field -if \[ha]([\[ha],]*,){3}foo +REGEX \f[R] .fi .PP +REGEX is a case-insensitive regular expression which tries to match +anywhere within the CSV record. +It is a POSIX extended regular expressions with some additions (see +Regular expressions in the hledger manual). +Note: the \[dq]CSV record\[dq] it is matched against is not the original +record, but a synthetic one, with enclosing double quotes or whitespace +removed, and always comma-separated. +(Eg, an SSV record \f[C]2020-01-01; \[dq]Acme, Inc.\[dq]; 1,000\f[R] +appears to REGEX as \f[C]2020-01-01,Acme, Inc.,1,000\f[R]). +.PP +Or, MATCHER can be a field matcher, like this: +.IP +.nf +\f[C] +%CSVFIELD REGEX +\f[R] +.fi +.PP +which matches just the content of a particular CSV field. +CSVFIELD is a percent sign followed by the field\[aq]s name or column +number, like \f[C]%date\f[R] or \f[C]%1\f[R]. +.PP +A single matcher can be written on the same line as the \[dq]if\[dq]; or +multiple matchers can be written on the following lines, non-indented. +Multiple matchers are OR\[aq]d (any one of them can match). +.PP After the patterns there should be one or more rules to apply, all indented by at least one space. Three kinds of rule are allowed in conditional blocks: diff --git a/hledger-lib/hledger_csv.info b/hledger-lib/hledger_csv.info index aa0c97535..e31358ffb 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.7 from stdin.  File: hledger_csv.info, Node: Top, Next: EXAMPLES, Up: (dir) -hledger_csv(5) hledger 1.16.99 -****************************** +hledger_csv(5) hledger 1.17 +*************************** CSV - how hledger reads CSV data, and the CSV rules file format @@ -190,10 +190,7 @@ amount2 %amzamount #include categorisation.rules # add a third posting for fees, but only if they are non-zero. -# Commas in the data makes counting fields hard, so count from the right instead. -# (Regex translation: "a field containing a non-zero dollar amount, -# immediately before the 1 right-most fields") -if ,\$[1-9][.0-9]+(,[^,]*){1}$ +if %fees [1-9] account3 expenses:fees amount3 %fees @@ -255,13 +252,11 @@ description %description_ %itemtitle comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ # convert to short currency symbols -# Note: in conditional block regexps, the line of csv being matched is -# a synthetic one: the unquoted field values, with commas between them. -if ,USD, +if %currency USD currency $ -if ,EUR, +if %currency EUR currency E -if ,GBP, +if %currency GBP currency P # generate postings @@ -275,9 +270,8 @@ amount1 %netamount # (account2 is set below) amount2 -%grossamount -# if there's a fee (9th field), add a third posting for the money taken by paypal. -# TODO: This regexp fails when fields contain a comma (generates a third posting with zero amount) -if ^([^,]+,){8}[^0] +# if there's a fee, add a third posting for the money taken by paypal. +if %feeamount [1-9] account3 expenses:banking:paypal amount3 -%feeamount comment3 business: @@ -285,11 +279,11 @@ if ^([^,]+,){8}[^0] # choose an account for the second posting # override the default account names: -# if amount (8th field) is positive, it's income (a debit) -if ^([^,]+,){7}[0-9] +# if the amount is positive, it's income (a debit) +if %grossamount ^[^-] account2 income:unknown # if negative, it's an expense (a credit) -if ^([^,]+,){7}- +if %grossamount ^- account2 expenses:unknown # apply common rules for setting account2 & other tweaks @@ -537,13 +531,13 @@ File: hledger_csv.info, Node: if, Next: end, Prev: separator, Up: CSV RULES 2.5 'if' ======== -if PATTERN +if MATCHER RULE if -PATTERN -PATTERN -PATTERN +MATCHER +MATCHER +MATCHER RULE RULE @@ -552,21 +546,30 @@ applied only to CSV records which match certain patterns. They are often used for customising account names based on transaction descriptions. - A single pattern can be written on the same line as the "if"; or -multiple patterns can be written on the following lines, non-indented. -Multiple patterns are OR'd (any one of them can match). Patterns are -case-insensitive regular expressions which try to match anywhere within -the whole CSV record (POSIX extended regular expressions with some -additions, see https://hledger.org/hledger.html#regular-expressions). -Note the CSV record they see is close to, but not identical to, the one -in the CSV file; enclosing double quotes will be removed, and the -separator character is always comma. + Each MATCHER can be a record matcher, which looks like this: - It's not yet easy to match within a specific field. If the data does -not contain commas, you can hack it with a regular expression like: +REGEX -# match "foo" in the fourth field -if ^([^,]*,){3}foo + REGEX is a case-insensitive regular expression which tries to match +anywhere within the CSV record. It is a POSIX extended regular +expressions with some additions (see Regular expressions in the hledger +manual). Note: the "CSV record" it is matched against is not the +original record, but a synthetic one, with enclosing double quotes or +whitespace removed, and always comma-separated. (Eg, an SSV record +'2020-01-01; "Acme, Inc."; 1,000' appears to REGEX as '2020-01-01,Acme, +Inc.,1,000'). + + Or, MATCHER can be a field matcher, like this: + +%CSVFIELD REGEX + + which matches just the content of a particular CSV field. CSVFIELD +is a percent sign followed by the field's name or column number, like +'%date' or '%1'. + + A single matcher can be written on the same line as the "if"; or +multiple matchers can be written on the following lines, non-indented. +Multiple matchers are OR'd (any one of them can match). After the patterns there should be one or more rules to apply, all indented by at least one space. Three kinds of rule are allowed in @@ -968,64 +971,64 @@ command the user specified.  Tag Table: Node: Top72 -Node: EXAMPLES2099 -Ref: #examples2205 -Node: Basic2413 -Ref: #basic2513 -Node: Bank of Ireland3055 -Ref: #bank-of-ireland3190 -Node: Amazon4652 -Ref: #amazon4770 -Node: Paypal6702 -Ref: #paypal6796 -Node: CSV RULES14675 -Ref: #csv-rules14784 -Node: skip15060 -Ref: #skip15153 -Node: fields15528 -Ref: #fields15650 -Node: Transaction field names16815 -Ref: #transaction-field-names16975 -Node: Posting field names17086 -Ref: #posting-field-names17238 -Node: field assignment18529 -Ref: #field-assignment18672 -Node: separator19490 -Ref: #separator19619 -Node: if20030 -Ref: #if20132 -Node: end21848 -Ref: #end21954 -Node: date-format22178 -Ref: #date-format22310 -Node: newest-first23059 -Ref: #newest-first23197 -Node: include23880 -Ref: #include24009 -Node: balance-type24453 -Ref: #balance-type24573 -Node: TIPS25273 -Ref: #tips25355 -Node: Rapid feedback25611 -Ref: #rapid-feedback25728 -Node: Valid CSV26188 -Ref: #valid-csv26318 -Node: File Extension26510 -Ref: #file-extension26662 -Node: Reading multiple CSV files27072 -Ref: #reading-multiple-csv-files27257 -Node: Valid transactions27498 -Ref: #valid-transactions27676 -Node: Deduplicating importing28304 -Ref: #deduplicating-importing28483 -Node: Setting amounts29516 -Ref: #setting-amounts29685 -Node: Setting currency/commodity30671 -Ref: #setting-currencycommodity30863 -Node: Referencing other fields31666 -Ref: #referencing-other-fields31866 -Node: How CSV rules are evaluated32763 -Ref: #how-csv-rules-are-evaluated32936 +Node: EXAMPLES2093 +Ref: #examples2199 +Node: Basic2407 +Ref: #basic2507 +Node: Bank of Ireland3049 +Ref: #bank-of-ireland3184 +Node: Amazon4646 +Ref: #amazon4764 +Node: Paypal6483 +Ref: #paypal6577 +Node: CSV RULES14221 +Ref: #csv-rules14330 +Node: skip14606 +Ref: #skip14699 +Node: fields15074 +Ref: #fields15196 +Node: Transaction field names16361 +Ref: #transaction-field-names16521 +Node: Posting field names16632 +Ref: #posting-field-names16784 +Node: field assignment18075 +Ref: #field-assignment18218 +Node: separator19036 +Ref: #separator19165 +Node: if19576 +Ref: #if19678 +Node: end21597 +Ref: #end21703 +Node: date-format21927 +Ref: #date-format22059 +Node: newest-first22808 +Ref: #newest-first22946 +Node: include23629 +Ref: #include23758 +Node: balance-type24202 +Ref: #balance-type24322 +Node: TIPS25022 +Ref: #tips25104 +Node: Rapid feedback25360 +Ref: #rapid-feedback25477 +Node: Valid CSV25937 +Ref: #valid-csv26067 +Node: File Extension26259 +Ref: #file-extension26411 +Node: Reading multiple CSV files26821 +Ref: #reading-multiple-csv-files27006 +Node: Valid transactions27247 +Ref: #valid-transactions27425 +Node: Deduplicating importing28053 +Ref: #deduplicating-importing28232 +Node: Setting amounts29265 +Ref: #setting-amounts29434 +Node: Setting currency/commodity30420 +Ref: #setting-currencycommodity30612 +Node: Referencing other fields31415 +Ref: #referencing-other-fields31615 +Node: How CSV rules are evaluated32512 +Ref: #how-csv-rules-are-evaluated32685  End Tag Table diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index 212ddb71a..e6d79e66f 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -163,10 +163,7 @@ EXAMPLES #include categorisation.rules # add a third posting for fees, but only if they are non-zero. - # Commas in the data makes counting fields hard, so count from the right instead. - # (Regex translation: "a field containing a non-zero dollar amount, - # immediately before the 1 right-most fields") - if ,\$[1-9][.0-9]+(,[^,]*){1}$ + if %fees [1-9] account3 expenses:fees amount3 %fees @@ -223,13 +220,11 @@ EXAMPLES comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ # convert to short currency symbols - # Note: in conditional block regexps, the line of csv being matched is - # a synthetic one: the unquoted field values, with commas between them. - if ,USD, + if %currency USD currency $ - if ,EUR, + if %currency EUR currency E - if ,GBP, + if %currency GBP currency P # generate postings @@ -243,9 +238,8 @@ EXAMPLES # (account2 is set below) amount2 -%grossamount - # if there's a fee (9th field), add a third posting for the money taken by paypal. - # TODO: This regexp fails when fields contain a comma (generates a third posting with zero amount) - if ^([^,]+,){8}[^0] + # if there's a fee, add a third posting for the money taken by paypal. + if %feeamount [1-9] account3 expenses:banking:paypal amount3 -%feeamount comment3 business: @@ -253,11 +247,11 @@ EXAMPLES # choose an account for the second posting # override the default account names: - # if amount (8th field) is positive, it's income (a debit) - if ^([^,]+,){7}[0-9] + # if the amount is positive, it's income (a debit) + if %grossamount ^[^-] account2 income:unknown # if negative, it's an expense (a credit) - if ^([^,]+,){7}- + if %grossamount ^- account2 expenses:unknown # apply common rules for setting account2 & other tweaks @@ -446,13 +440,13 @@ CSV RULES See also: File Extension. if - if PATTERN + if MATCHER RULE if - PATTERN - PATTERN - PATTERN + MATCHER + MATCHER + MATCHER RULE RULE @@ -460,24 +454,32 @@ CSV RULES only to CSV records which match certain patterns. They are often used for customising account names based on transaction descriptions. - A single pattern can be written on the same line as the "if"; or multi- - ple patterns can be written on the following lines, non-indented. Mul- - tiple patterns are OR'd (any one of them can match). Patterns are - case-insensitive regular expressions which try to match anywhere within - the whole CSV record (POSIX extended regular expressions with some ad- - ditions, see https://hledger.org/hledger.html#regular-expressions). - Note the CSV record they see is close to, but not identical to, the one - in the CSV file; enclosing double quotes will be removed, and the sepa- - rator character is always comma. + Each MATCHER can be a record matcher, which looks like this: - It's not yet easy to match within a specific field. If the data does - not contain commas, you can hack it with a regular expression like: + REGEX - # match "foo" in the fourth field - if ^([^,]*,){3}foo + REGEX is a case-insensitive regular expression which tries to match + anywhere within the CSV record. It is a POSIX extended regular expres- + sions with some additions (see Regular expressions in the hledger man- + ual). Note: the "CSV record" it is matched against is not the original + record, but a synthetic one, with enclosing double quotes or whitespace + removed, and always comma-separated. (Eg, an SSV record 2020-01-01; + "Acme, Inc."; 1,000 appears to REGEX as 2020-01-01,Acme, Inc.,1,000). - After the patterns there should be one or more rules to apply, all in- - dented by at least one space. Three kinds of rule are allowed in con- + Or, MATCHER can be a field matcher, like this: + + %CSVFIELD REGEX + + which matches just the content of a particular CSV field. CSVFIELD is + a percent sign followed by the field's name or column number, like + %date or %1. + + A single matcher can be written on the same line as the "if"; or multi- + ple matchers can be written on the following lines, non-indented. Mul- + tiple matchers are OR'd (any one of them can match). + + After the patterns there should be one or more rules to apply, all in- + dented by at least one space. Three kinds of rule are allowed in con- ditional blocks: o field assignments (to set a hledger field) @@ -501,7 +503,7 @@ CSV RULES comment XXX deductible ? check it end - This rule can be used inside if blocks (only), to make hledger stop + This rule can be used inside if blocks (only), to make hledger stop reading this CSV file and move on to the next input file, or to command execution. Eg: @@ -512,10 +514,10 @@ CSV RULES date-format date-format DATEFMT - This is a helper for the date (and date2) fields. If your CSV dates - are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll - need to add a date-format rule describing them with a strptime date - parsing pattern, which must parse the CSV date value completely. Some + This is a helper for the date (and date2) fields. If your CSV dates + are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll + need to add a date-format rule describing them with a strptime date + parsing pattern, which must parse the CSV date value completely. Some examples: # MM/DD/YY @@ -537,15 +539,15 @@ CSV RULES mat.html#v:formatTime newest-first - hledger always sorts the generated transactions by date. Transactions - on the same date should appear in the same order as their CSV records, - as hledger can usually auto-detect whether the CSV's normal order is + hledger always sorts the generated transactions by date. Transactions + on the same date should appear in the same order as their CSV records, + as hledger can usually auto-detect whether the CSV's normal order is oldest first or newest first. But if all of the following are true: - o the CSV might sometimes contain just one day of data (all records + o the CSV might sometimes contain just one day of data (all records having the same date) - o the CSV records are normally in reverse chronological order (newest + o the CSV records are normally in reverse chronological order (newest at the top) o and you care about preserving the order of same-day transactions @@ -558,9 +560,9 @@ CSV RULES include include RULESFILE - This includes the contents of another CSV rules file at this point. - RULESFILE is an absolute file path or a path relative to the current - file's directory. This can be useful for sharing common rules between + This includes the contents of another CSV rules file at this point. + RULESFILE is an absolute file path or a path relative to the current + file's directory. This can be useful for sharing common rules between several rules files, eg: # someaccount.csv.rules @@ -575,10 +577,10 @@ CSV RULES balance-type Balance assertions generated by assigning to balanceN are of the simple - = type by default, which is a single-commodity, subaccount-excluding + = type by default, which is a single-commodity, subaccount-excluding assertion. You may find the subaccount-including variants more useful, - eg if you have created some virtual subaccounts of checking to help - with budgeting. You can select a different type of assertion with the + eg if you have created some virtual subaccounts of checking to help + with budgeting. You can select a different type of assertion with the balance-type rule: # balance assertions will consider all commodities and all subaccounts @@ -593,19 +595,19 @@ CSV RULES TIPS Rapid feedback - It's a good idea to get rapid feedback while creating/troubleshooting + It's a good idea to get rapid feedback while creating/troubleshooting CSV rules. Here's a good way, using entr from http://eradman.com/entr- project : $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' - A desc: query (eg) is used to select just one, or a few, transactions - of interest. "bash -c" is used to run multiple commands, so we can - echo a separator each time the command re-runs, making it easier to + A desc: query (eg) is used to select just one, or a few, transactions + of interest. "bash -c" is used to run multiple commands, so we can + echo a separator each time the command re-runs, making it easier to read the output. Valid CSV - hledger accepts CSV conforming to RFC 4180. When CSV values are en- + hledger accepts CSV conforming to RFC 4180. When CSV values are en- closed in quotes, note: o they must be double quotes (not single quotes) @@ -613,9 +615,9 @@ TIPS o spaces outside the quotes are not allowed File Extension - CSV ("Character Separated Values") files should be named with one of - these filename extensions: .csv, .ssv, .tsv. Or, the file path should - be prefixed with one of csv:, ssv:, tsv:. This helps hledger identify + CSV ("Character Separated Values") files should be named with one of + these filename extensions: .csv, .ssv, .tsv. Or, the file path should + be prefixed with one of csv:, ssv:, tsv:. This helps hledger identify the format and show the right error messages. For example: $ hledger -f foo.ssv print @@ -627,44 +629,44 @@ TIPS More about this: Input files in the hledger manual. Reading multiple CSV files - If you use multiple -f options to read multiple CSV files at once, - hledger will look for a correspondingly-named rules file for each CSV - file. But if you use the --rules-file option, that rules file will be + If you use multiple -f options to read multiple CSV files at once, + hledger will look for a correspondingly-named rules file for each CSV + file. But if you use the --rules-file option, that rules file will be used for all the CSV files. Valid transactions After reading a CSV file, hledger post-processes and validates the gen- erated journal entries as it would for a journal file - balancing them, - applying balance assignments, and canonicalising amount styles. Any - errors at this stage will be reported in the usual way, displaying the + applying balance assignments, and canonicalising amount styles. Any + errors at this stage will be reported in the usual way, displaying the problem entry. There is one exception: balance assertions, if you have generated them, - will not be checked, since normally these will work only when the CSV - data is part of the main journal. If you do need to check balance as- + will not be checked, since normally these will work only when the CSV + data is part of the main journal. If you do need to check balance as- sertions generated from CSV right away, pipe into another hledger: $ hledger -f file.csv print | hledger -f- print Deduplicating, importing - When you download a CSV file periodically, eg to get your latest bank - transactions, the new file may overlap with the old one, containing + When you download a CSV file periodically, eg to get your latest bank + transactions, the new file may overlap with the old one, containing some of the same records. The import command will (a) detect the new transactions, and (b) append just those transactions to your main journal. It is idempotent, so you - don't have to remember how many times you ran it or with which version - of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This + don't have to remember how many times you ran it or with which version + of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This is the easiest way to import CSV data. Eg: # download the latest CSV files, then run this command. # Note, no -f flags needed here. $ hledger import *.csv [--dry] - This method works for most CSV files. (Where records have a stable + This method works for most CSV files. (Where records have a stable chronological order, and new records appear only at the new end.) - A number of other tools and workflows, hledger-specific and otherwise, + A number of other tools and workflows, hledger-specific and otherwise, exist for converting, deduplicating, classifying and managing CSV data. See: @@ -675,43 +677,43 @@ TIPS Setting amounts A posting amount can be set in one of these ways: - o by assigning (with a fields list or field assigment) to amountN + o by assigning (with a fields list or field assigment) to amountN (posting N's amount) or amount (posting 1's amount) - o by assigning to amountN-in and amountN-out (or amount-in and amount- - out). For each CSV record, whichever of these has a non-zero value - will be used, with appropriate sign. If both contain a non-zero + o by assigning to amountN-in and amountN-out (or amount-in and amount- + out). For each CSV record, whichever of these has a non-zero value + will be used, with appropriate sign. If both contain a non-zero value, this may not work. - o by assigning to balanceN (or balance) instead of the above, setting - the amount indirectly via a balance assignment. If you do this the + o by assigning to balanceN (or balance) instead of the above, setting + the amount indirectly via a balance assignment. If you do this the default account name may be wrong, so you should set that explicitly. There is some special handling for an amount's sign: - o If an amount value is parenthesised, it will be de-parenthesised and + o If an amount value is parenthesised, it will be de-parenthesised and sign-flipped. - o If an amount value begins with a double minus sign, those cancel out + o If an amount value begins with a double minus sign, those cancel out and are removed. o If an amount value begins with a plus sign, that will be removed Setting currency/commodity - If the currency/commodity symbol is included in the CSV's amount + If the currency/commodity symbol is included in the CSV's amount field(s), you don't have to do anything special. If the currency is provided as a separate CSV field, you can either: - o assign that to currency, which adds it to all posting amounts. The - symbol will prepended to the amount quantity (on the left side). If - you write a trailing space after the symbol, there will be a space - between symbol and amount (an exception to the usual whitespace + o assign that to currency, which adds it to all posting amounts. The + symbol will prepended to the amount quantity (on the left side). If + you write a trailing space after the symbol, there will be a space + between symbol and amount (an exception to the usual whitespace stripping). o or assign it to currencyN which adds it to posting N's amount only. - o or for more control, construct the amount from symbol and quantity + o or for more control, construct the amount from symbol and quantity using field assignment, eg: fields date,description,currency,quantity @@ -719,9 +721,9 @@ TIPS amount %quantity %currency Referencing other fields - In field assignments, you can interpolate only CSV fields, not hledger - fields. In the example below, there's both a CSV field and a hledger - field named amount1, but %amount1 always means the CSV field, not the + In field assignments, you can interpolate only CSV fields, not hledger + fields. In the example below, there's both a CSV field and a hledger + field named amount1, but %amount1 always means the CSV field, not the hledger field: # Name the third CSV field "amount1" @@ -733,7 +735,7 @@ TIPS # Set comment to the CSV amount1 (not the amount1 assigned above) comment %amount1 - Here, since there's no CSV amount1 field, %amount1 will produce a lit- + Here, since there's no CSV amount1 field, %amount1 will produce a lit- eral "amount1": fields date,description,csvamount @@ -741,7 +743,7 @@ TIPS # Can't interpolate amount1 here comment %amount1 - When there are multiple field assignments to the same hledger field, + When there are multiple field assignments to the same hledger field, only the last one takes effect. Here, comment's value will be be B, or C if "something" is matched, but never A: @@ -751,14 +753,14 @@ TIPS comment C How CSV rules are evaluated - Here's how to think of CSV rules being evaluated (if you really need + Here's how to think of CSV rules being evaluated (if you really need to). First, - o include - all includes are inlined, from top to bottom, depth first. - (At each include point the file is inlined and scanned for further + o include - all includes are inlined, from top to bottom, depth first. + (At each include point the file is inlined and scanned for further includes, recursively, before proceeding.) - Then "global" rules are evaluated, top to bottom. If a rule is re- + Then "global" rules are evaluated, top to bottom. If a rule is re- peated, the last one wins: o skip (at top level) @@ -772,30 +774,30 @@ TIPS Then for each CSV record in turn: - o test all if blocks. If any of them contain a end rule, skip all re- - maining CSV records. Otherwise if any of them contain a skip rule, - skip that many CSV records. If there are multiple matched skip + o test all if blocks. If any of them contain a end rule, skip all re- + maining CSV records. Otherwise if any of them contain a skip rule, + skip that many CSV records. If there are multiple matched skip rules, the first one wins. - o collect all field assignments at top level and in matched if blocks. - When there are multiple assignments for a field, keep only the last + o collect all field assignments at top level and in matched if blocks. + When there are multiple assignments for a field, keep only the last one. - o compute a value for each hledger field - either the one that was as- + o compute a value for each hledger field - either the one that was as- signed to it (and interpolate the %CSVFIELDNAME references), or a de- fault o generate a synthetic hledger transaction from these values. - This is all part of the CSV reader, one of several readers hledger can - use to parse input files. When all files have been read successfully, - the transactions are passed as input to whichever hledger command the + This is all part of the CSV reader, one of several readers hledger can + use to parse input files. When all files have been read successfully, + the transactions are passed as input to whichever hledger command the user specified. REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -809,7 +811,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) @@ -817,4 +819,4 @@ SEE ALSO -hledger 1.16.99 February 2020 hledger_csv(5) +hledger 1.17 March 2020 hledger_csv(5) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 2c31428d3..b4757fd0d 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -1,6 +1,6 @@ .\"t -.TH "hledger_journal" "5" "February 2020" "hledger 1.16.99" "hledger User Manuals" +.TH "hledger_journal" "5" "March 2020" "hledger 1.17" "hledger User Manuals" diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 677ff908a..bc45147f8 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -4,8 +4,8 @@ stdin.  File: hledger_journal.info, Node: Top, Up: (dir) -hledger_journal(5) hledger 1.16.99 -********************************** +hledger_journal(5) hledger 1.17 +******************************* Journal - hledger's default file format, representing a General Journal @@ -1735,116 +1735,116 @@ rules will have these tags added:  Tag Table: Node: Top76 -Node: Transactions1875 -Ref: #transactions1967 -Node: Dates3156 -Ref: #dates3255 -Node: Simple dates3320 -Ref: #simple-dates3446 -Node: Secondary dates3955 -Ref: #secondary-dates4109 -Node: Posting dates5445 -Ref: #posting-dates5574 -Node: Status6946 -Ref: #status7067 -Node: Description8775 -Ref: #description8909 -Node: Payee and note9229 -Ref: #payee-and-note9343 -Node: Comments9678 -Ref: #comments9804 -Node: Tags10998 -Ref: #tags11113 -Node: Postings12506 -Ref: #postings12634 -Node: Virtual Postings13660 -Ref: #virtual-postings13777 -Node: Account names15082 -Ref: #account-names15223 -Node: Amounts15710 -Ref: #amounts15849 -Node: Digit group marks16781 -Ref: #digit-group-marks16929 -Node: Amount display style17867 -Ref: #amount-display-style18021 -Node: Transaction prices19182 -Ref: #transaction-prices19348 -Node: Balance Assertions21614 -Ref: #balance-assertions21794 -Node: Assertions and ordering22827 -Ref: #assertions-and-ordering23015 -Node: Assertions and included files23715 -Ref: #assertions-and-included-files23958 -Node: Assertions and multiple -f options24291 -Ref: #assertions-and-multiple--f-options24547 -Node: Assertions and commodities24679 -Ref: #assertions-and-commodities24911 -Node: Assertions and prices26068 -Ref: #assertions-and-prices26282 -Node: Assertions and subaccounts26722 -Ref: #assertions-and-subaccounts26951 -Node: Assertions and virtual postings27275 -Ref: #assertions-and-virtual-postings27517 -Node: Assertions and precision27659 -Ref: #assertions-and-precision27852 -Node: Balance Assignments28119 -Ref: #balance-assignments28293 -Node: Balance assignments and prices29457 -Ref: #balance-assignments-and-prices29629 -Node: Directives29853 -Ref: #directives30012 -Node: Comment blocks35660 -Ref: #comment-blocks35805 -Node: Including other files35981 -Ref: #including-other-files36161 -Node: Default year36569 -Ref: #default-year36738 -Node: Declaring commodities37145 -Ref: #declaring-commodities37328 -Node: Default commodity39001 -Ref: #default-commodity39177 -Node: Market prices40066 -Ref: #market-prices40231 -Node: Declaring accounts41072 -Ref: #declaring-accounts41248 -Node: Account comments42173 -Ref: #account-comments42336 -Node: Account subdirectives42760 -Ref: #account-subdirectives42955 -Node: Account types43268 -Ref: #account-types43452 -Node: Account display order45091 -Ref: #account-display-order45261 -Node: Rewriting accounts46412 -Ref: #rewriting-accounts46597 -Node: Basic aliases47323 -Ref: #basic-aliases47469 -Node: Regex aliases48173 -Ref: #regex-aliases48345 -Node: Combining aliases49063 -Ref: #combining-aliases49241 -Node: end aliases50517 -Ref: #end-aliases50665 -Node: Default parent account50766 -Ref: #default-parent-account50932 -Node: Periodic transactions51816 -Ref: #periodic-transactions52015 -Node: Periodic rule syntax53887 -Ref: #periodic-rule-syntax54093 -Node: Two spaces between period expression and description!54797 -Ref: #two-spaces-between-period-expression-and-description55116 -Node: Forecasting with periodic transactions55800 -Ref: #forecasting-with-periodic-transactions56105 -Node: Budgeting with periodic transactions58131 -Ref: #budgeting-with-periodic-transactions58370 -Node: Auto postings / transaction modifiers58819 -Ref: #auto-postings-transaction-modifiers59031 -Node: Auto postings and dates61527 -Ref: #auto-postings-and-dates61784 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions61959 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62334 -Node: Auto posting tags62712 -Ref: #auto-posting-tags62951 +Node: Transactions1869 +Ref: #transactions1961 +Node: Dates3150 +Ref: #dates3249 +Node: Simple dates3314 +Ref: #simple-dates3440 +Node: Secondary dates3949 +Ref: #secondary-dates4103 +Node: Posting dates5439 +Ref: #posting-dates5568 +Node: Status6940 +Ref: #status7061 +Node: Description8769 +Ref: #description8903 +Node: Payee and note9223 +Ref: #payee-and-note9337 +Node: Comments9672 +Ref: #comments9798 +Node: Tags10992 +Ref: #tags11107 +Node: Postings12500 +Ref: #postings12628 +Node: Virtual Postings13654 +Ref: #virtual-postings13771 +Node: Account names15076 +Ref: #account-names15217 +Node: Amounts15704 +Ref: #amounts15843 +Node: Digit group marks16775 +Ref: #digit-group-marks16923 +Node: Amount display style17861 +Ref: #amount-display-style18015 +Node: Transaction prices19176 +Ref: #transaction-prices19342 +Node: Balance Assertions21608 +Ref: #balance-assertions21788 +Node: Assertions and ordering22821 +Ref: #assertions-and-ordering23009 +Node: Assertions and included files23709 +Ref: #assertions-and-included-files23952 +Node: Assertions and multiple -f options24285 +Ref: #assertions-and-multiple--f-options24541 +Node: Assertions and commodities24673 +Ref: #assertions-and-commodities24905 +Node: Assertions and prices26062 +Ref: #assertions-and-prices26276 +Node: Assertions and subaccounts26716 +Ref: #assertions-and-subaccounts26945 +Node: Assertions and virtual postings27269 +Ref: #assertions-and-virtual-postings27511 +Node: Assertions and precision27653 +Ref: #assertions-and-precision27846 +Node: Balance Assignments28113 +Ref: #balance-assignments28287 +Node: Balance assignments and prices29451 +Ref: #balance-assignments-and-prices29623 +Node: Directives29847 +Ref: #directives30006 +Node: Comment blocks35654 +Ref: #comment-blocks35799 +Node: Including other files35975 +Ref: #including-other-files36155 +Node: Default year36563 +Ref: #default-year36732 +Node: Declaring commodities37139 +Ref: #declaring-commodities37322 +Node: Default commodity38995 +Ref: #default-commodity39171 +Node: Market prices40060 +Ref: #market-prices40225 +Node: Declaring accounts41066 +Ref: #declaring-accounts41242 +Node: Account comments42167 +Ref: #account-comments42330 +Node: Account subdirectives42754 +Ref: #account-subdirectives42949 +Node: Account types43262 +Ref: #account-types43446 +Node: Account display order45085 +Ref: #account-display-order45255 +Node: Rewriting accounts46406 +Ref: #rewriting-accounts46591 +Node: Basic aliases47317 +Ref: #basic-aliases47463 +Node: Regex aliases48167 +Ref: #regex-aliases48339 +Node: Combining aliases49057 +Ref: #combining-aliases49235 +Node: end aliases50511 +Ref: #end-aliases50659 +Node: Default parent account50760 +Ref: #default-parent-account50926 +Node: Periodic transactions51810 +Ref: #periodic-transactions52009 +Node: Periodic rule syntax53881 +Ref: #periodic-rule-syntax54087 +Node: Two spaces between period expression and description!54791 +Ref: #two-spaces-between-period-expression-and-description55110 +Node: Forecasting with periodic transactions55794 +Ref: #forecasting-with-periodic-transactions56099 +Node: Budgeting with periodic transactions58125 +Ref: #budgeting-with-periodic-transactions58364 +Node: Auto postings / transaction modifiers58813 +Ref: #auto-postings-transaction-modifiers59025 +Node: Auto postings and dates61521 +Ref: #auto-postings-and-dates61778 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions61953 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62328 +Node: Auto posting tags62706 +Ref: #auto-posting-tags62945  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 723df75de..6116f2522 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -1415,4 +1415,4 @@ SEE ALSO -hledger 1.16.99 February 2020 hledger_journal(5) +hledger 1.17 March 2020 hledger_journal(5) diff --git a/hledger-lib/hledger_timeclock.5 b/hledger-lib/hledger_timeclock.5 index 87d919497..5d680bdfe 100644 --- a/hledger-lib/hledger_timeclock.5 +++ b/hledger-lib/hledger_timeclock.5 @@ -1,5 +1,5 @@ -.TH "hledger_timeclock" "5" "February 2020" "hledger 1.16.99" "hledger User Manuals" +.TH "hledger_timeclock" "5" "March 2020" "hledger 1.17" "hledger User Manuals" diff --git a/hledger-lib/hledger_timeclock.info b/hledger-lib/hledger_timeclock.info index 50cf76ff3..3d3e6044b 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.16.99 -************************************ +hledger_timeclock(5) hledger 1.17 +********************************* Timeclock - the time logging format of timeclock.el, as read by hledger diff --git a/hledger-lib/hledger_timeclock.txt b/hledger-lib/hledger_timeclock.txt index f0fe1f87f..1f45ae7c3 100644 --- a/hledger-lib/hledger_timeclock.txt +++ b/hledger-lib/hledger_timeclock.txt @@ -78,4 +78,4 @@ SEE ALSO -hledger 1.16.99 February 2020 hledger_timeclock(5) +hledger 1.17 March 2020 hledger_timeclock(5) diff --git a/hledger-lib/hledger_timedot.5 b/hledger-lib/hledger_timedot.5 index b0233eb67..2c2945a72 100644 --- a/hledger-lib/hledger_timedot.5 +++ b/hledger-lib/hledger_timedot.5 @@ -1,5 +1,5 @@ -.TH "hledger_timedot" "5" "February 2020" "hledger 1.16.99" "hledger User Manuals" +.TH "hledger_timedot" "5" "March 2020" "hledger 1.17" "hledger User Manuals" @@ -22,17 +22,21 @@ quantities other than time. In the docs below we\[aq]ll assume it\[aq]s time. .PP A timedot file contains a series of day entries. -A day entry begins with a date, and is followed by category/quantity -pairs, one per line. -Dates are hledger-style simple dates (see hledger_journal(5)). -Categories are hledger-style account names, optionally indented. -As in a hledger journal, there must be at least two spaces between the -category (account name) and the quantity. +A day entry begins with a non-indented hledger-style simple date (Y-M-D, +Y/M/D, Y.M.D..) Any additional text on the same line is used as a +transaction description for this day. +.PP +This is followed by optionally-indented timelog items for that day, one +per line. +Each timelog item is a note, usually a hledger:style:account:name +representing a time category, followed by two or more spaces, and a +quantity. +Each timelog item generates a hledger transaction. .PP Quantities can be written as: .IP \[bu] 2 -a sequence of dots (.) representing quarter hours. -Spaces may optionally be used for grouping and readability. +dots: a sequence of dots (.) representing quarter hours. +Spaces may optionally be used for grouping. Eg: .... \&.. .IP \[bu] 2 @@ -47,8 +51,25 @@ Eg: 90m. The following equivalencies are assumed, currently: 1m = 60s, 1h = 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. .PP -Blank lines and lines beginning with #, ; or * are ignored. -An example: +There is some flexibility allowing notes and todo lists to be kept right +in the time log, if needed: +.IP \[bu] 2 +Blank lines and lines beginning with \f[C]#\f[R] or \f[C];\f[R] are +ignored. +.IP \[bu] 2 +Lines not ending with a double-space and quantity are parsed as items +taking no time, which will not appear in balance reports by default. +(Add -E to see them.) +.IP \[bu] 2 +Org mode headlines (lines beginning with one or more \f[C]*\f[R] +followed by a space) can be used as date lines or timelog items (the +stars are ignored). +Also all org headlines before the first date line are ignored. +This means org users can manage their timelog as an org outline (eg +using org-mode/orgstruct-mode in Emacs), for organisation, faster +navigation, controlling visibility etc. +.PP +Examples: .IP .nf \f[C] @@ -63,8 +84,6 @@ inc:client1 .... .... biz:research . \f[R] .fi -.PP -Or with numbers: .IP .nf \f[C] @@ -74,6 +93,35 @@ fos:hledger 3 biz:research 1 \f[R] .fi +.IP +.nf +\f[C] +* Time log +** 2020-01-01 +*** adm:time . +*** adm:finance . +\f[R] +.fi +.IP +.nf +\f[C] +* 2020 Work Diary +** Q1 +*** 2020-02-29 +**** DONE +0700 yoga +**** UNPLANNED +**** BEGUN +hom:chores + cleaning ... + water plants + outdoor - one full watering can + indoor - light watering +**** TODO +adm:planning: trip +*** LATER +\f[R] +.fi .PP Reporting: .IP diff --git a/hledger-lib/hledger_timedot.info b/hledger-lib/hledger_timedot.info index 97b237999..f6df78a6f 100644 --- a/hledger-lib/hledger_timedot.info +++ b/hledger-lib/hledger_timedot.info @@ -4,8 +4,8 @@ stdin.  File: hledger_timedot.info, Node: Top, Up: (dir) -hledger_timedot(5) hledger 1.16.99 -********************************** +hledger_timedot(5) hledger 1.17 +******************************* Timedot - hledger's human-friendly time logging format @@ -21,16 +21,20 @@ commodityless quantities, so it could be used to represent dated quantities other than time. In the docs below we'll assume it's time. A timedot file contains a series of day entries. A day entry begins -with a date, and is followed by category/quantity pairs, one per line. -Dates are hledger-style simple dates (see hledger_journal(5)). -Categories are hledger-style account names, optionally indented. As in -a hledger journal, there must be at least two spaces between the -category (account name) and the quantity. +with a non-indented hledger-style simple date (Y-M-D, Y/M/D, Y.M.D..) +Any additional text on the same line is used as a transaction +description for this day. + + This is followed by optionally-indented timelog items for that day, +one per line. Each timelog item is a note, usually a +hledger:style:account:name representing a time category, followed by two +or more spaces, and a quantity. Each timelog item generates a hledger +transaction. Quantities can be written as: - * a sequence of dots (.) representing quarter hours. Spaces may - optionally be used for grouping and readability. Eg: .... .. + * dots: a sequence of dots (.) representing quarter hours. Spaces + may optionally be used for grouping. Eg: .... .. * an integral or decimal number, representing hours. Eg: 1.5 @@ -40,8 +44,23 @@ category (account name) and the quantity. The following equivalencies are assumed, currently: 1m = 60s, 1h = 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. - Blank lines and lines beginning with #, ; or * are ignored. An -example: + There is some flexibility allowing notes and todo lists to be kept +right in the time log, if needed: + + * Blank lines and lines beginning with '#' or ';' are ignored. + + * Lines not ending with a double-space and quantity are parsed as + items taking no time, which will not appear in balance reports by + default. (Add -E to see them.) + + * Org mode headlines (lines beginning with one or more '*' followed + by a space) can be used as date lines or timelog items (the stars + are ignored). Also all org headlines before the first date line + are ignored. This means org users can manage their timelog as an + org outline (eg using org-mode/orgstruct-mode in Emacs), for + organisation, faster navigation, controlling visibility etc. + + Examples: # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. 2016/2/1 @@ -53,13 +72,32 @@ biz:research . inc:client1 .... .... biz:research . - Or with numbers: - 2016/2/3 inc:client1 4 fos:hledger 3 biz:research 1 +* Time log +** 2020-01-01 +*** adm:time . +*** adm:finance . + +* 2020 Work Diary +** Q1 +*** 2020-02-29 +**** DONE +0700 yoga +**** UNPLANNED +**** BEGUN +hom:chores + cleaning ... + water plants + outdoor - one full watering can + indoor - light watering +**** TODO +adm:planning: trip +*** LATER + Reporting: $ hledger -f t.timedot print date:2016/2/2 diff --git a/hledger-lib/hledger_timedot.txt b/hledger-lib/hledger_timedot.txt index ca090d276..829965e21 100644 --- a/hledger-lib/hledger_timedot.txt +++ b/hledger-lib/hledger_timedot.txt @@ -19,16 +19,20 @@ DESCRIPTION other than time. In the docs below we'll assume it's time. A timedot file contains a series of day entries. A day entry begins - with a date, and is followed by category/quantity pairs, one per line. - Dates are hledger-style simple dates (see hledger_journal(5)). Cate- - gories are hledger-style account names, optionally indented. As in a - hledger journal, there must be at least two spaces between the category - (account name) and the quantity. + with a non-indented hledger-style simple date (Y-M-D, Y/M/D, Y.M.D..) + Any additional text on the same line is used as a transaction descrip- + tion for this day. + + This is followed by optionally-indented timelog items for that day, one + per line. Each timelog item is a note, usually a hledger:style:ac- + count:name representing a time category, followed by two or more spa- + ces, and a quantity. Each timelog item generates a hledger transac- + tion. Quantities can be written as: - o a sequence of dots (.) representing quarter hours. Spaces may op- - tionally be used for grouping and readability. Eg: .... .. + o dots: a sequence of dots (.) representing quarter hours. Spaces may + optionally be used for grouping. Eg: .... .. o an integral or decimal number, representing hours. Eg: 1.5 @@ -38,8 +42,23 @@ DESCRIPTION lencies are assumed, currently: 1m = 60s, 1h = 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. - Blank lines and lines beginning with #, ; or * are ignored. An exam- - ple: + There is some flexibility allowing notes and todo lists to be kept + right in the time log, if needed: + + o Blank lines and lines beginning with # or ; are ignored. + + o Lines not ending with a double-space and quantity are parsed as items + taking no time, which will not appear in balance reports by default. + (Add -E to see them.) + + o Org mode headlines (lines beginning with one or more * followed by a + space) can be used as date lines or timelog items (the stars are ig- + nored). Also all org headlines before the first date line are ig- + nored. This means org users can manage their timelog as an org out- + line (eg using org-mode/orgstruct-mode in Emacs), for organisation, + faster navigation, controlling visibility etc. + + Examples: # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. 2016/2/1 @@ -51,13 +70,32 @@ DESCRIPTION inc:client1 .... .... biz:research . - Or with numbers: - 2016/2/3 inc:client1 4 fos:hledger 3 biz:research 1 + * Time log + ** 2020-01-01 + *** adm:time . + *** adm:finance . + + * 2020 Work Diary + ** Q1 + *** 2020-02-29 + **** DONE + 0700 yoga + **** UNPLANNED + **** BEGUN + hom:chores + cleaning ... + water plants + outdoor - one full watering can + indoor - light watering + **** TODO + adm:planning: trip + *** LATER + Reporting: $ hledger -f t.timedot print date:2016/2/2 @@ -82,7 +120,7 @@ DESCRIPTION ------------++---------------------------------------- || 7.75 2.25 8.00 - I prefer to use period for separating account components. We can make + I prefer to use period for separating account components. We can make this work with an account alias: 2016/2/4 @@ -101,7 +139,7 @@ DESCRIPTION REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -115,7 +153,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) @@ -123,4 +161,4 @@ SEE ALSO -hledger 1.16.99 February 2020 hledger_timedot(5) +hledger 1.17 March 2020 hledger_timedot(5) diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index ccc6b580f..1fc2efa38 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "hledger-ui" "1" "February 2020" "hledger-ui 1.16.99" "hledger User Manuals" +.TH "hledger-ui" "1" "March 2020" "hledger-ui 1.17" "hledger User Manuals" diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index c3fdbdc61..e3c13b781 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.7 from stdin.  File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-ui(1) hledger-ui 1.16.99 -******************************** +hledger-ui(1) hledger-ui 1.17 +***************************** hledger-ui - terminal interface for the hledger accounting tool @@ -499,26 +499,26 @@ program is restarted.  Tag Table: Node: Top71 -Node: OPTIONS1476 -Ref: #options1573 -Node: KEYS5004 -Ref: #keys5099 -Node: SCREENS9375 -Ref: #screens9480 -Node: Accounts screen9570 -Ref: #accounts-screen9698 -Node: Register screen11914 -Ref: #register-screen12069 -Node: Transaction screen14066 -Ref: #transaction-screen14224 -Node: Error screen15094 -Ref: #error-screen15216 -Node: ENVIRONMENT15460 -Ref: #environment15574 -Node: FILES16381 -Ref: #files16480 -Node: BUGS16693 -Ref: #bugs16770 +Node: OPTIONS1470 +Ref: #options1567 +Node: KEYS4998 +Ref: #keys5093 +Node: SCREENS9369 +Ref: #screens9474 +Node: Accounts screen9564 +Ref: #accounts-screen9692 +Node: Register screen11908 +Ref: #register-screen12063 +Node: Transaction screen14060 +Ref: #transaction-screen14218 +Node: Error screen15088 +Ref: #error-screen15210 +Node: ENVIRONMENT15454 +Ref: #environment15568 +Node: FILES16375 +Ref: #files16474 +Node: BUGS16687 +Ref: #bugs16764  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 1bbc30655..79ce0bcb0 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -441,4 +441,4 @@ SEE ALSO -hledger-ui 1.16.99 February 2020 hledger-ui(1) +hledger-ui 1.17 March 2020 hledger-ui(1) diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 78cfbb5fd..2fd6b81c9 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "hledger-web" "1" "February 2020" "hledger-web 1.16.99" "hledger User Manuals" +.TH "hledger-web" "1" "March 2020" "hledger-web 1.17" "hledger User Manuals" @@ -343,8 +343,8 @@ what you get from \f[C]/transactions\f[R] or .PP Another way to generate test data is with the \f[C]readJsonFile\f[R]/\f[C]writeJsonFile\f[R] helpers in -Hledger.Web.Json, which read or write any of hledger\[aq]s JSON-capable -types from or to a file. +Hledger.Web.Json, which can write or read most of hledger\[aq]s data +types to or from a file. Eg here we write the first transaction of a sample journal: .IP .nf diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index 3956591b9..4d776fff9 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.7 from stdin.  File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-web(1) hledger-web 1.16.99 -********************************** +hledger-web(1) hledger-web 1.17 +******************************* hledger-web - web interface for the hledger accounting tool @@ -350,8 +350,8 @@ form, hledger-web must be started with the 'add' capability for this what you get from '/transactions' or '/accounttransactions'. Another way to generate test data is with the -'readJsonFile'/'writeJsonFile' helpers in Hledger.Web.Json, which read -or write any of hledger's JSON-capable types from or to a file. Eg here +'readJsonFile'/'writeJsonFile' helpers in Hledger.Web.Json, which can +write or read most of hledger's data types to or from a file. Eg here we write the first transaction of a sample journal: $ make ghci-web @@ -427,22 +427,22 @@ awkward.  Tag Table: Node: Top72 -Node: OPTIONS1752 -Ref: #options1857 -Node: PERMISSIONS8201 -Ref: #permissions8340 -Node: EDITING UPLOADING DOWNLOADING9552 -Ref: #editing-uploading-downloading9733 -Node: RELOADING10567 -Ref: #reloading10701 -Node: JSON API11134 -Ref: #json-api11248 -Node: ENVIRONMENT12689 -Ref: #environment12805 -Node: FILES13538 -Ref: #files13638 -Node: BUGS13851 -Ref: #bugs13929 +Node: OPTIONS1746 +Ref: #options1851 +Node: PERMISSIONS8195 +Ref: #permissions8334 +Node: EDITING UPLOADING DOWNLOADING9546 +Ref: #editing-uploading-downloading9727 +Node: RELOADING10561 +Ref: #reloading10695 +Node: JSON API11128 +Ref: #json-api11242 +Node: ENVIRONMENT12680 +Ref: #environment12796 +Node: FILES13529 +Ref: #files13629 +Node: BUGS13842 +Ref: #bugs13920  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index ed21ec333..41302edd7 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -309,8 +309,8 @@ JSON API what you get from /transactions or /accounttransactions. Another way to generate test data is with the readJsonFile/writeJson- - File helpers in Hledger.Web.Json, which read or write any of hledger's - JSON-capable types from or to a file. Eg here we write the first + File helpers in Hledger.Web.Json, which can write or read most of + hledger's data types to or from a file. Eg here we write the first transaction of a sample journal: $ make ghci-web @@ -392,4 +392,4 @@ SEE ALSO -hledger-web 1.16.99 February 2020 hledger-web(1) +hledger-web 1.17 March 2020 hledger-web(1) diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index b16229cb7..34afb7d82 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -499,5 +499,6 @@ Budget performance in 2019/01: Output format -The balance command supports output destination and output format -selection. +This command also supports the output destination and output format +options The output formats supported are txt, csv, (multicolumn +non-budget reports only) html, and (experimental) json. diff --git a/hledger/Hledger/Cli/Commands/Balancesheet.txt b/hledger/Hledger/Cli/Commands/Balancesheet.txt index 9d7557edd..422716f95 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheet.txt +++ b/hledger/Hledger/Cli/Commands/Balancesheet.txt @@ -39,5 +39,6 @@ for a balance sheet; note this means it ignores report begin dates (and -T/--row-total, since summing end balances generally does not make sense). Instead of absolute values percentages can be displayed with -%. -This command also supports output destination and output format -selection. +This command also supports the output destination and output format +options The output formats supported are txt, csv, html, and +(experimental) json. diff --git a/hledger/Hledger/Cli/Commands/Balancesheetequity.txt b/hledger/Hledger/Cli/Commands/Balancesheetequity.txt index ae8418c06..ea0746b2e 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheetequity.txt +++ b/hledger/Hledger/Cli/Commands/Balancesheetequity.txt @@ -29,3 +29,7 @@ Equity: Total: -------------------- 0 + +This command also supports the output destination and output format +options The output formats supported are txt, csv, html, and +(experimental) json. diff --git a/hledger/Hledger/Cli/Commands/Cashflow.txt b/hledger/Hledger/Cli/Commands/Cashflow.txt index 773cc409c..2d58c5f0f 100644 --- a/hledger/Hledger/Cli/Commands/Cashflow.txt +++ b/hledger/Hledger/Cli/Commands/Cashflow.txt @@ -30,5 +30,6 @@ though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. Instead of absolute values percentages can be displayed with -%. -This command also supports output destination and output format -selection. +This command also supports the output destination and output format +options The output formats supported are txt, csv, html, and +(experimental) json. diff --git a/hledger/Hledger/Cli/Commands/Incomestatement.txt b/hledger/Hledger/Cli/Commands/Incomestatement.txt index 41a546cd1..5758bf04f 100644 --- a/hledger/Hledger/Cli/Commands/Incomestatement.txt +++ b/hledger/Hledger/Cli/Commands/Incomestatement.txt @@ -39,5 +39,6 @@ period, though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. Instead of absolute values percentages can be displayed with -%. -This command also supports output destination and output format -selection. +This command also supports the output destination and output format +options The output formats supported are txt, csv, html, and +(experimental) json. diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index bcf298a48..ec521a26e 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -70,8 +70,11 @@ This assumes that transactions added to FILE always have same or increasing dates, and that transactions on the same day do not get reordered. See also the import command. -This command also supports output destination and output format -selection. Here's an example of print's CSV output: +This command also supports the output destination and output format +options The output formats supported are txt, csv, and (experimental) +json. + +Here's an example of print's CSV output: $ hledger print -Ocsv "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" diff --git a/hledger/Hledger/Cli/Commands/Register.txt b/hledger/Hledger/Cli/Commands/Register.txt index a9ad4f771..0d0ab9d3e 100644 --- a/hledger/Hledger/Cli/Commands/Register.txt +++ b/hledger/Hledger/Cli/Commands/Register.txt @@ -103,5 +103,6 @@ $ export COLUMNS=100; hledger reg # set till session end (or window resize) $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 -This command also supports output destination and output format -selection. +This command also supports the output destination and output format +options The output formats supported are txt, csv, and (experimental) +json. diff --git a/hledger/hledger.1 b/hledger/hledger.1 index c5e036344..4248647e5 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "hledger" "1" "February 2020" "hledger 1.16.99" "hledger User Manuals" +.TH "hledger" "1" "March 2020" "hledger 1.17" "hledger User Manuals" @@ -1037,31 +1037,90 @@ If you need those, either use the include directive, or concatenate the files, eg: \f[C]cat a.journal b.journal | hledger -f- CMD\f[R]. .SS Output destination .PP -Some commands (print, register, stats, the balance commands) can write -their output to a destination other than the console. -This is controlled by the \f[C]-o/--output-file\f[R] option. +hledger commands send their output to the terminal by default. +You can of course redirect this, eg into a file, using standard shell +syntax: .IP .nf \f[C] -$ hledger balance -o - # write to stdout (the default) -$ hledger balance -o FILE # write to FILE +$ hledger print > foo.txt +\f[R] +.fi +.PP +Some commands (print, register, stats, the balance commands) also +provide the \f[C]-o/--output-file\f[R] option, which does the same thing +without needing the shell. +Eg: +.IP +.nf +\f[C] +$ hledger print -o foo.txt +$ hledger print -o - # write to stdout (the default) \f[R] .fi .SS Output format .PP -Some commands can write their output in other formats. -Eg print and register can output CSV, and the balance commands can -output CSV or HTML. -This is controlled by the \f[C]-O/--output-format\f[R] option, or by -specifying a \f[C].csv\f[R] or \f[C].html\f[R] file extension with -\f[C]-o/--output-file\f[R]. +Some commands (print, register, the balance commands) offer a choice of +output format. +In addition to the usual plain text format (\f[C]txt\f[R]), there are +CSV (\f[C]csv\f[R]), HTML (\f[C]html\f[R]) and JSON (\f[C]json\f[R]). +This is controlled by the \f[C]-O/--output-format\f[R] option: .IP .nf \f[C] -$ hledger balance -O csv # write CSV to stdout -$ hledger balance -o FILE.csv # write CSV to FILE.csv +$ hledger print -O csv \f[R] .fi +.PP +or, by a file extension specified with \f[C]-o/--output-file\f[R]: +.IP +.nf +\f[C] +$ hledger balancesheet -o foo.html # write HTML to foo.html +\f[R] +.fi +.PP +The \f[C]-O\f[R] option can be used to override the file extension if +needed: +.IP +.nf +\f[C] +$ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt +\f[R] +.fi +.PP +Some notes about JSON output: +.IP \[bu] 2 +This feature is marked experimental, and not yet much used; you should +expect our JSON to evolve. +Real-world feedback is welcome. +.IP \[bu] 2 +Our JSON is rather large and verbose, as it is quite a faithful +representation of hledger\[aq]s internal data types. +To understand the JSON, read the Haskell type definitions, which are +mostly in +https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. +.IP \[bu] 2 +The JSON output from hledger commands is essentially the same as the +JSON served by hledger-web\[aq]s JSON API, but pretty printed, using +line breaks and indentation. +Our pretty printer has the ability to elide data in certain cases - +rendering non-strings as if they were strings, or displaying +\[dq]FOO..\[dq] instead of FOO\[aq]s full details. +This should never happen in hledger\[aq]s JSON output; if you see +otherwise, please report as a bug. +.IP \[bu] 2 +hledger represents quantities as Decimal values storing up to 255 +significant digits, eg for repeating decimals. +Such numbers can arise in practice (from automatically-calculated +transaction prices), and would break most JSON consumers. +So in JSON, we show quantities as simple Numbers with at most 10 decimal +places. +We don\[aq]t limit the number of integer digits, but that part is under +your control. +We hope this approach will not cause problems in practice; if you find +otherwise, please let us know. +(Cf #1195) .SS Regular expressions .PP hledger uses regular expressions in a number of places: @@ -2955,8 +3014,10 @@ Budget performance in 2019/01: .fi .SS Output format .PP -The balance command supports output destination and output format -selection. +This command also supports the output destination and output format +options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R], +(multicolumn non-budget reports only) \f[C]html\f[R], and (experimental) +\f[C]json\f[R]. .SS balancesheet .PP balancesheet, bs @@ -3010,8 +3071,9 @@ generally does not make sense). Instead of absolute values percentages can be displayed with \f[C]-%\f[R]. .PP -This command also supports output destination and output format -selection. +This command also supports the output destination and output format +options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R], +\f[C]html\f[R], and (experimental) \f[C]json\f[R]. .SS balancesheetequity .PP balancesheetequity, bse @@ -3050,6 +3112,10 @@ Total: 0 \f[R] .fi +.PP +This command also supports the output destination and output format +options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R], +\f[C]html\f[R], and (experimental) \f[C]json\f[R]. .SS cashflow .PP cashflow, cf @@ -3093,8 +3159,9 @@ multicolumn balance reports you can alter the report mode with Instead of absolute values percentages can be displayed with \f[C]-%\f[R]. .PP -This command also supports output destination and output format -selection. +This command also supports the output destination and output format +options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R], +\f[C]html\f[R], and (experimental) \f[C]json\f[R]. .SS check-dates .PP check-dates @@ -3461,8 +3528,9 @@ with multicolumn balance reports you can alter the report mode with Instead of absolute values percentages can be displayed with \f[C]-%\f[R]. .PP -This command also supports output destination and output format -selection. +This command also supports the output destination and output format +options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R], +\f[C]html\f[R], and (experimental) \f[C]json\f[R]. .SS notes .PP notes Show notes. @@ -3602,8 +3670,10 @@ increasing dates, and that transactions on the same day do not get reordered. See also the import command. .PP -This command also supports output destination and output format -selection. +This command also supports the output destination and output format +options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R], +and (experimental) \f[C]json\f[R]. +.PP Here\[aq]s an example of print\[aq]s CSV output: .IP .nf @@ -3812,8 +3882,9 @@ $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 \f[R] .fi .PP -This command also supports output destination and output format -selection. +This command also supports the output destination and output format +options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R], +and (experimental) \f[C]json\f[R]. .SS register-match .PP register-match diff --git a/hledger/hledger.info b/hledger/hledger.info index a8bcb5739..9bc132e14 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -3,8 +3,8 @@ This is hledger.info, produced by makeinfo version 6.7 from stdin.  File: hledger.info, Node: Top, Next: COMMON TASKS, Up: (dir) -hledger(1) hledger 1.16.99 -************************** +hledger(1) hledger 1.17 +*********************** hledger - a command-line accounting tool @@ -978,12 +978,17 @@ File: hledger.info, Node: Output destination, Next: Output format, Prev: Inpu 2.8 Output destination ====================== -Some commands (print, register, stats, the balance commands) can write -their output to a destination other than the console. This is -controlled by the '-o/--output-file' option. +hledger commands send their output to the terminal by default. You can +of course redirect this, eg into a file, using standard shell syntax: -$ hledger balance -o - # write to stdout (the default) -$ hledger balance -o FILE # write to FILE +$ hledger print > foo.txt + + Some commands (print, register, stats, the balance commands) also +provide the '-o/--output-file' option, which does the same thing without +needing the shell. Eg: + +$ hledger print -o foo.txt +$ hledger print -o - # write to stdout (the default)  File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Output destination, Up: OPTIONS @@ -991,13 +996,47 @@ File: hledger.info, Node: Output format, Next: Regular expressions, Prev: Out 2.9 Output format ================= -Some commands can write their output in other formats. Eg print and -register can output CSV, and the balance commands can output CSV or -HTML. This is controlled by the '-O/--output-format' option, or by -specifying a '.csv' or '.html' file extension with '-o/--output-file'. +Some commands (print, register, the balance commands) offer a choice of +output format. In addition to the usual plain text format ('txt'), +there are CSV ('csv'), HTML ('html') and JSON ('json'). This is +controlled by the '-O/--output-format' option: -$ hledger balance -O csv # write CSV to stdout -$ hledger balance -o FILE.csv # write CSV to FILE.csv +$ hledger print -O csv + + or, by a file extension specified with '-o/--output-file': + +$ hledger balancesheet -o foo.html # write HTML to foo.html + + The '-O' option can be used to override the file extension if needed: + +$ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt + + Some notes about JSON output: + + * This feature is marked experimental, and not yet much used; you + should expect our JSON to evolve. Real-world feedback is welcome. + + * Our JSON is rather large and verbose, as it is quite a faithful + representation of hledger's internal data types. To understand the + JSON, read the Haskell type definitions, which are mostly in + https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. + + * The JSON output from hledger commands is essentially the same as + the JSON served by hledger-web's JSON API, but pretty printed, + using line breaks and indentation. Our pretty printer has the + ability to elide data in certain cases - rendering non-strings as + if they were strings, or displaying "FOO.." instead of FOO's full + details. This should never happen in hledger's JSON output; if you + see otherwise, please report as a bug. + + * hledger represents quantities as Decimal values storing up to 255 + significant digits, eg for repeating decimals. Such numbers can + arise in practice (from automatically-calculated transaction + prices), and would break most JSON consumers. So in JSON, we show + quantities as simple Numbers with at most 10 decimal places. We + don't limit the number of integer digits, but that part is under + your control. We hope this approach will not cause problems in + practice; if you find otherwise, please let us know. (Cf #1195)  File: hledger.info, Node: Regular expressions, Next: Smart dates, Prev: Output format, Up: OPTIONS @@ -2437,8 +2476,9 @@ Budget performance in 2019/01: 3.4.9 Output format ------------------- -The balance command supports output destination and output format -selection. +This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', (multicolumn +non-budget reports only) 'html', and (experimental) 'json'.  File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS @@ -2486,8 +2526,9 @@ for a balance sheet; note this means it ignores report begin dates (and sense). Instead of absolute values percentages can be displayed with '-%'. - This command also supports output destination and output format -selection. + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'html', and +(experimental) 'json'.  File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS @@ -2525,6 +2566,10 @@ Total: -------------------- 0 + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'html', and +(experimental) 'json'. +  File: hledger.info, Node: cashflow, Next: check-dates, Prev: balancesheetequity, Up: COMMANDS @@ -2561,8 +2606,9 @@ period, though as with multicolumn balance reports you can alter the report mode with '--change'/'--cumulative'/'--historical'. Instead of absolute values percentages can be displayed with '-%'. - This command also supports output destination and output format -selection. + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'html', and +(experimental) 'json'.  File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS @@ -2904,8 +2950,9 @@ per period, though as with multicolumn balance reports you can alter the report mode with '--change'/'--cumulative'/'--historical'. Instead of absolute values percentages can be displayed with '-%'. - This command also supports output destination and output format -selection. + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'html', and +(experimental) 'json'.  File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: COMMANDS @@ -3029,8 +3076,11 @@ $ hledger -f bank1.csv print --new increasing dates, and that transactions on the same day do not get reordered. See also the import command. - This command also supports output destination and output format -selection. Here's an example of print's CSV output: + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', and +(experimental) 'json'. + + Here's an example of print's CSV output: $ hledger print -Ocsv "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" @@ -3198,8 +3248,9 @@ $ export COLUMNS=100; hledger reg # set till session end (or window resize) $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 - This command also supports output destination and output format -selection. + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', and +(experimental) 'json'.  File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS @@ -3683,187 +3734,187 @@ $ LANG=fr_FR.utf8 hledger -f my.journal print  Tag Table: Node: Top68 -Node: COMMON TASKS2321 -Ref: #common-tasks2433 -Node: Getting help2840 -Ref: #getting-help2972 -Node: Constructing command lines3525 -Ref: #constructing-command-lines3717 -Node: Starting a journal file4414 -Ref: #starting-a-journal-file4612 -Node: Setting opening balances5800 -Ref: #setting-opening-balances5996 -Node: Recording transactions9137 -Ref: #recording-transactions9317 -Node: Reconciling9873 -Ref: #reconciling10016 -Node: Reporting12273 -Ref: #reporting12413 -Node: Migrating to a new file16412 -Ref: #migrating-to-a-new-file16560 -Node: OPTIONS16859 -Ref: #options16966 -Node: General options17336 -Ref: #general-options17461 -Node: Command options20231 -Ref: #command-options20382 -Node: Command arguments20780 -Ref: #command-arguments20927 -Node: Queries21807 -Ref: #queries21962 -Node: Special characters in arguments and queries25924 -Ref: #special-characters-in-arguments-and-queries26152 -Node: More escaping26603 -Ref: #more-escaping26765 -Node: Even more escaping27061 -Ref: #even-more-escaping27255 -Node: Less escaping27926 -Ref: #less-escaping28088 -Node: Unicode characters28333 -Ref: #unicode-characters28515 -Node: Input files29927 -Ref: #input-files30070 -Node: Output destination31999 -Ref: #output-destination32151 -Node: Output format32434 -Ref: #output-format32584 -Node: Regular expressions32969 -Ref: #regular-expressions33126 -Node: Smart dates34487 -Ref: #smart-dates34638 -Node: Report start & end date35999 -Ref: #report-start-end-date36171 -Node: Report intervals37609 -Ref: #report-intervals37774 -Node: Period expressions38164 -Ref: #period-expressions38324 -Node: Depth limiting42450 -Ref: #depth-limiting42594 -Node: Pivoting42936 -Ref: #pivoting43059 -Node: Valuation44735 -Ref: #valuation44837 -Node: -B Cost45017 -Ref: #b-cost45128 -Node: -V Market value45326 -Ref: #v-market-value45500 -Node: -X Market value in specified commodity46932 -Ref: #x-market-value-in-specified-commodity47171 -Node: --value Flexible valuation47347 -Ref: #value-flexible-valuation47573 -Node: Effect of --value on reports52078 -Ref: #effect-of---value-on-reports52294 -Node: Combining -B -V -X --value57840 -Ref: #combining--b--v--x---value58023 -Node: COMMANDS58059 -Ref: #commands58167 -Node: accounts59251 -Ref: #accounts59349 -Node: activity60048 -Ref: #activity60158 -Node: add60541 -Ref: #add60640 -Node: balance63379 -Ref: #balance63490 -Node: Classic balance report64948 -Ref: #classic-balance-report65121 -Node: Customising the classic balance report66490 -Ref: #customising-the-classic-balance-report66718 -Node: Colour support68794 -Ref: #colour-support68961 -Node: Flat mode69134 -Ref: #flat-mode69282 -Node: Depth limited balance reports69695 -Ref: #depth-limited-balance-reports69880 -Node: Percentages70336 -Ref: #percentages70502 -Node: Multicolumn balance report71639 -Ref: #multicolumn-balance-report71819 -Node: Budget report77081 -Ref: #budget-report77224 -Node: Nested budgets82426 -Ref: #nested-budgets82538 -Ref: #output-format-186019 -Node: balancesheet86097 -Ref: #balancesheet86233 -Node: balancesheetequity87616 -Ref: #balancesheetequity87765 -Node: cashflow88326 -Ref: #cashflow88454 -Node: check-dates89550 -Ref: #check-dates89677 -Node: check-dupes89956 -Ref: #check-dupes90080 -Node: close90373 -Ref: #close90487 -Node: close usage92009 -Ref: #close-usage92102 -Node: commodities94915 -Ref: #commodities95042 -Node: descriptions95124 -Ref: #descriptions95252 -Node: diff95433 -Ref: #diff95539 -Node: files96586 -Ref: #files96686 -Node: help96833 -Ref: #help96933 -Node: import98014 -Ref: #import98128 -Node: Importing balance assignments99021 -Ref: #importing-balance-assignments99169 -Node: incomestatement99818 -Ref: #incomestatement99951 -Node: notes101355 -Ref: #notes101468 -Node: payees101594 -Ref: #payees101700 -Node: prices101858 -Ref: #prices101964 -Node: print102305 -Ref: #print102415 -Node: print-unique107123 -Ref: #print-unique107249 -Node: register107534 -Ref: #register107661 -Node: Custom register output111833 -Ref: #custom-register-output111962 -Node: register-match113224 -Ref: #register-match113358 -Node: rewrite113709 -Ref: #rewrite113824 -Node: Re-write rules in a file115679 -Ref: #re-write-rules-in-a-file115813 -Node: Diff output format117023 -Ref: #diff-output-format117192 -Node: rewrite vs print --auto118284 -Ref: #rewrite-vs.-print---auto118463 -Node: roi119019 -Ref: #roi119117 -Node: stats120129 -Ref: #stats120228 -Node: tags121016 -Ref: #tags121114 -Node: test121408 -Ref: #test121516 -Node: Add-on Commands122263 -Ref: #add-on-commands122380 -Node: ui123723 -Ref: #ui123811 -Node: web123865 -Ref: #web123968 -Node: iadd124084 -Ref: #iadd124195 -Node: interest124277 -Ref: #interest124384 -Node: ENVIRONMENT124624 -Ref: #environment124736 -Node: FILES125565 -Ref: #files-1125668 -Node: LIMITATIONS125881 -Ref: #limitations126000 -Node: TROUBLESHOOTING126742 -Ref: #troubleshooting126855 +Node: COMMON TASKS2315 +Ref: #common-tasks2427 +Node: Getting help2834 +Ref: #getting-help2966 +Node: Constructing command lines3519 +Ref: #constructing-command-lines3711 +Node: Starting a journal file4408 +Ref: #starting-a-journal-file4606 +Node: Setting opening balances5794 +Ref: #setting-opening-balances5990 +Node: Recording transactions9131 +Ref: #recording-transactions9311 +Node: Reconciling9867 +Ref: #reconciling10010 +Node: Reporting12267 +Ref: #reporting12407 +Node: Migrating to a new file16406 +Ref: #migrating-to-a-new-file16554 +Node: OPTIONS16853 +Ref: #options16960 +Node: General options17330 +Ref: #general-options17455 +Node: Command options20225 +Ref: #command-options20376 +Node: Command arguments20774 +Ref: #command-arguments20921 +Node: Queries21801 +Ref: #queries21956 +Node: Special characters in arguments and queries25918 +Ref: #special-characters-in-arguments-and-queries26146 +Node: More escaping26597 +Ref: #more-escaping26759 +Node: Even more escaping27055 +Ref: #even-more-escaping27249 +Node: Less escaping27920 +Ref: #less-escaping28082 +Node: Unicode characters28327 +Ref: #unicode-characters28509 +Node: Input files29921 +Ref: #input-files30064 +Node: Output destination31993 +Ref: #output-destination32145 +Node: Output format32570 +Ref: #output-format32720 +Node: Regular expressions34768 +Ref: #regular-expressions34925 +Node: Smart dates36286 +Ref: #smart-dates36437 +Node: Report start & end date37798 +Ref: #report-start-end-date37970 +Node: Report intervals39408 +Ref: #report-intervals39573 +Node: Period expressions39963 +Ref: #period-expressions40123 +Node: Depth limiting44249 +Ref: #depth-limiting44393 +Node: Pivoting44735 +Ref: #pivoting44858 +Node: Valuation46534 +Ref: #valuation46636 +Node: -B Cost46816 +Ref: #b-cost46927 +Node: -V Market value47125 +Ref: #v-market-value47299 +Node: -X Market value in specified commodity48731 +Ref: #x-market-value-in-specified-commodity48970 +Node: --value Flexible valuation49146 +Ref: #value-flexible-valuation49372 +Node: Effect of --value on reports53877 +Ref: #effect-of---value-on-reports54093 +Node: Combining -B -V -X --value59639 +Ref: #combining--b--v--x---value59822 +Node: COMMANDS59858 +Ref: #commands59966 +Node: accounts61050 +Ref: #accounts61148 +Node: activity61847 +Ref: #activity61957 +Node: add62340 +Ref: #add62439 +Node: balance65178 +Ref: #balance65289 +Node: Classic balance report66747 +Ref: #classic-balance-report66920 +Node: Customising the classic balance report68289 +Ref: #customising-the-classic-balance-report68517 +Node: Colour support70593 +Ref: #colour-support70760 +Node: Flat mode70933 +Ref: #flat-mode71081 +Node: Depth limited balance reports71494 +Ref: #depth-limited-balance-reports71679 +Node: Percentages72135 +Ref: #percentages72301 +Node: Multicolumn balance report73438 +Ref: #multicolumn-balance-report73618 +Node: Budget report78880 +Ref: #budget-report79023 +Node: Nested budgets84225 +Ref: #nested-budgets84337 +Ref: #output-format-187818 +Node: balancesheet88015 +Ref: #balancesheet88151 +Node: balancesheetequity89617 +Ref: #balancesheetequity89766 +Node: cashflow90489 +Ref: #cashflow90617 +Node: check-dates91796 +Ref: #check-dates91923 +Node: check-dupes92202 +Ref: #check-dupes92326 +Node: close92619 +Ref: #close92733 +Node: close usage94255 +Ref: #close-usage94348 +Node: commodities97161 +Ref: #commodities97288 +Node: descriptions97370 +Ref: #descriptions97498 +Node: diff97679 +Ref: #diff97785 +Node: files98832 +Ref: #files98932 +Node: help99079 +Ref: #help99179 +Node: import100260 +Ref: #import100374 +Node: Importing balance assignments101267 +Ref: #importing-balance-assignments101415 +Node: incomestatement102064 +Ref: #incomestatement102197 +Node: notes103684 +Ref: #notes103797 +Node: payees103923 +Ref: #payees104029 +Node: prices104187 +Ref: #prices104293 +Node: print104634 +Ref: #print104744 +Node: print-unique109530 +Ref: #print-unique109656 +Node: register109941 +Ref: #register110068 +Node: Custom register output114240 +Ref: #custom-register-output114369 +Node: register-match115706 +Ref: #register-match115840 +Node: rewrite116191 +Ref: #rewrite116306 +Node: Re-write rules in a file118161 +Ref: #re-write-rules-in-a-file118295 +Node: Diff output format119505 +Ref: #diff-output-format119674 +Node: rewrite vs print --auto120766 +Ref: #rewrite-vs.-print---auto120945 +Node: roi121501 +Ref: #roi121599 +Node: stats122611 +Ref: #stats122710 +Node: tags123498 +Ref: #tags123596 +Node: test123890 +Ref: #test123998 +Node: Add-on Commands124745 +Ref: #add-on-commands124862 +Node: ui126205 +Ref: #ui126293 +Node: web126347 +Ref: #web126450 +Node: iadd126566 +Ref: #iadd126677 +Node: interest126759 +Ref: #interest126866 +Node: ENVIRONMENT127106 +Ref: #environment127218 +Node: FILES128047 +Ref: #files-1128150 +Node: LIMITATIONS128363 +Ref: #limitations128482 +Node: TROUBLESHOOTING129224 +Ref: #troubleshooting129337  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index f240d12b8..e8f6981b2 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -829,73 +829,113 @@ OPTIONS files, eg: cat a.journal b.journal | hledger -f- CMD. Output destination - Some commands (print, register, stats, the balance commands) can write - their output to a destination other than the console. This is con- - trolled by the -o/--output-file option. + hledger commands send their output to the terminal by default. You can + of course redirect this, eg into a file, using standard shell syntax: - $ hledger balance -o - # write to stdout (the default) - $ hledger balance -o FILE # write to FILE + $ hledger print > foo.txt + + Some commands (print, register, stats, the balance commands) also pro- + vide the -o/--output-file option, which does the same thing without + needing the shell. Eg: + + $ hledger print -o foo.txt + $ hledger print -o - # write to stdout (the default) Output format - Some commands can write their output in other formats. Eg print and - register can output CSV, and the balance commands can output CSV or - HTML. This is controlled by the -O/--output-format option, or by spec- - ifying a .csv or .html file extension with -o/--output-file. + Some commands (print, register, the balance commands) offer a choice of + output format. In addition to the usual plain text format (txt), there + are CSV (csv), HTML (html) and JSON (json). This is controlled by the + -O/--output-format option: - $ hledger balance -O csv # write CSV to stdout - $ hledger balance -o FILE.csv # write CSV to FILE.csv + $ hledger print -O csv + + or, by a file extension specified with -o/--output-file: + + $ hledger balancesheet -o foo.html # write HTML to foo.html + + The -O option can be used to override the file extension if needed: + + $ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt + + Some notes about JSON output: + + o This feature is marked experimental, and not yet much used; you + should expect our JSON to evolve. Real-world feedback is welcome. + + o Our JSON is rather large and verbose, as it is quite a faithful rep- + resentation of hledger's internal data types. To understand the + JSON, read the Haskell type definitions, which are mostly in + https://github.com/simonmichael/hledger/blob/master/hledger- + lib/Hledger/Data/Types.hs. + + o The JSON output from hledger commands is essentially the same as the + JSON served by hledger-web's JSON API, but pretty printed, using line + breaks and indentation. Our pretty printer has the ability to elide + data in certain cases - rendering non-strings as if they were + strings, or displaying "FOO.." instead of FOO's full details. This + should never happen in hledger's JSON output; if you see otherwise, + please report as a bug. + + o hledger represents quantities as Decimal values storing up to 255 + significant digits, eg for repeating decimals. Such numbers can + arise in practice (from automatically-calculated transaction prices), + and would break most JSON consumers. So in JSON, we show quantities + as simple Numbers with at most 10 decimal places. We don't limit the + number of integer digits, but that part is under your control. We + hope this approach will not cause problems in practice; if you find + otherwise, please let us know. (Cf #1195) Regular expressions hledger uses regular expressions in a number of places: - o query terms, on the command line and in the hledger-web search form: + o query terms, on the command line and in the hledger-web search form: REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX o CSV rules conditional blocks: if REGEX ... - o account alias directives and options: alias /REGEX/ = REPLACEMENT, + o account alias directives and options: alias /REGEX/ = REPLACEMENT, --alias /REGEX/=REPLACEMENT - hledger's regular expressions come from the regex-tdfa library. In + hledger's regular expressions come from the regex-tdfa library. In general they: o are case insensitive - o are infix matching (do not need to match the entire thing being + o are infix matching (do not need to match the entire thing being matched) o are POSIX extended regular expressions o also support GNU word boundaries (\<, \>, \b, \B) - o and parenthesised capturing groups and numeric backreferences in re- + o and parenthesised capturing groups and numeric backreferences in re- placement strings o do not support mode modifiers like (?s) Some things to note: - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, these are not required. - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts with the dollar sign in hledger-web, write cur:\$. - o On the command line, some metacharacters like $ have a special mean- + o On the command line, some metacharacters like $ have a special mean- ing to the shell and so must be escaped at least once more. See Spe- cial characters. Smart dates hledger's user interfaces accept a flexible "smart date" syntax (unlike - dates in the journal file). Smart dates allow some english words, can - be relative to today's date, and can have less-significant date parts + dates in the journal file). Smart dates allow some english words, can + be relative to today's date, and can have less-significant date parts omitted (defaulting to 1). Examples: - 2004/10/1, 2004-01-01, exact date, several separators allowed. Year + 2004/10/1, 2004-01-01, exact date, several separators allowed. Year 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 2004 start of year 2004/10 start of month @@ -910,44 +950,44 @@ OPTIONS 20181201 8 digit YYYYMMDD with valid year month and day 201812 6 digit YYYYMM with valid year and month - Counterexamples - malformed digit sequences might give surprising re- + Counterexamples - malformed digit sequences might give surprising re- sults: - 201813 6 digits with an invalid month is parsed as start of + 201813 6 digits with an invalid month is parsed as start of 6-digit year - 20181301 8 digits with an invalid month is parsed as start of + 20181301 8 digits with an invalid month is parsed as start of 8-digit year 20181232 8 digits with an invalid day gives an error 201801012 9+ digits beginning with a valid YYYYMMDD gives an error Report start & end date - Most hledger reports show the full span of time represented by the + Most hledger reports show the full span of time represented by the journal data, by default. So, the effective report start and end dates - will be the earliest and latest transaction or posting dates found in + will be the earliest and latest transaction or posting dates found in the journal. - Often you will want to see a shorter time span, such as the current - month. You can specify a start and/or end date using -b/--begin, + Often you will want to see a shorter time span, such as the current + month. You can specify a start and/or end date using -b/--begin, -e/--end, -p/--period or a date: query (described below). All of these accept the smart date syntax. Some notes: - o As in Ledger, end dates are exclusive, so you need to write the date + o As in Ledger, end dates are exclusive, so you need to write the date after the last day you want to include. - o As noted in reporting options: among start/end dates specified with + o As noted in reporting options: among start/end dates specified with options, the last (i.e. right-most) option takes precedence. - o The effective report start and end dates are the intersection of the - start/end dates from options and that from date: queries. That is, - date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the + o The effective report start and end dates are the intersection of the + start/end dates from options and that from date: queries. That is, + date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the smallest common time span. Examples: -b 2016/3/17 begin on St. Patrick's day 2016 - -e 12/1 end at the start of december 1st of the current year + -e 12/1 end at the start of december 1st of the current year (11/30 will be the last date included) -b thismonth all transactions on or after the 1st of the current month -p thismonth all transactions in the current month @@ -958,31 +998,31 @@ OPTIONS Report intervals A report interval can be specified so that commands like register, bal- - ance and activity will divide their reports into multiple subperiods. - The basic intervals can be selected with one of -D/--daily, - -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- - plex intervals may be specified with a period expression. Report in- + ance and activity will divide their reports into multiple subperiods. + The basic intervals can be selected with one of -D/--daily, + -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- + plex intervals may be specified with a period expression. Report in- tervals can not be specified with a query. Period expressions - The -p/--period option accepts period expressions, a shorthand way of + The -p/--period option accepts period expressions, a shorthand way of expressing a start date, end date, and/or report interval all at once. - Here's a basic period expression specifying the first quarter of 2009. - Note, hledger always treats start dates as inclusive and end dates as + Here's a basic period expression specifying the first quarter of 2009. + Note, hledger always treats start dates as inclusive and end dates as exclusive: -p "from 2009/1/1 to 2009/4/1" - Keywords like "from" and "to" are optional, and so are the spaces, as - long as you don't run two dates together. "to" can also be written as + Keywords like "from" and "to" are optional, and so are the spaces, as + long as you don't run two dates together. "to" can also be written as "-". These are equivalent to the above: -p "2009/1/1 2009/4/1" -p2009/1/1to2009/4/1 -p2009/1/1-2009/4/1 - Dates are smart dates, so if the current year is 2009, the above can + Dates are smart dates, so if the current year is 2009, the above can also be written as: -p "1/1 4/1" @@ -996,63 +1036,64 @@ OPTIONS 1, 2009 -p "from 2009/1" the same -p "from 2009" the same - -p "to 2009" everything before january + -p "to 2009" everything before january 1, 2009 - A single date with no "from" or "to" defines both the start and end + A single date with no "from" or "to" defines both the start and end date like so: - -p "2009" the year 2009; equivalent + -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of jan; equiva- + -p "2009/1" the month of jan; equiva- lent to "2009/1/1 to 2009/2/1" - - -p "2009/1/1" just that day; equivalent + -p "2009/1/1" just that day; equivalent to "2009/1/1 to 2009/1/2" - The argument of -p can also begin with, or be, a report interval ex- + The argument of -p can also begin with, or be, a report interval ex- pression. The basic report intervals are daily, weekly, monthly, quar- - terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y - flags. Between report interval and start/end dates (if any), the word + terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y + flags. Between report interval and start/end dates (if any), the word in is optional. Examples: -p "weekly from 2009/1/1 to 2009/4/1" -p "monthly in 2008" -p "quarterly" - Note that weekly, monthly, quarterly and yearly intervals will always + Note that weekly, monthly, quarterly and yearly intervals will always start on the first day on week, month, quarter or year accordingly, and - will end on the last day of same period, even if associated period ex- + will end on the last day of same period, even if associated period ex- pression specifies different explicit start and end date. For example: - -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- + -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- to 2009/4/1" day - -p "monthly in starts on 2018/11/01 + + + -p "monthly in starts on 2018/11/01 2008/11/25" - -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, + -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009 -p "yearly from starts on 2009/01/01, first day of 2009 2009-12-29" - The following more complex report intervals are also supported: bi- + The following more complex report intervals are also supported: bi- weekly, bimonthly, every day|week|month|quarter|year, every N days|weeks|months|quarters|years. - All of these will start on the first day of the requested period and + All of these will start on the first day of the requested period and end on the last one, as described above. Examples: - -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, + -p "bimonthly from 2008" periods will have boundaries on 2008/01/01, 2008/03/01, ... -p "every 2 weeks" starts on closest preceding Monday - -p "every 5 month from periods will have boundaries on 2009/03/01, + -p "every 5 month from periods will have boundaries on 2009/03/01, 2009/03" 2009/08/01, ... - If you want intervals that start on arbitrary day of your choosing and + If you want intervals that start on arbitrary day of your choosing and span a week, month or year, you need to use any of the following: every Nth day of week, every , every Nth day [of month], every @@ -1064,42 +1105,42 @@ OPTIONS -p "every 2nd day of periods will go from Tue to Tue week" -p "every Tue" same - -p "every 15th day" period boundaries will be on 15th of each + -p "every 15th day" period boundaries will be on 15th of each month - -p "every 2nd Monday" period boundaries will be on second Monday of + -p "every 2nd Monday" period boundaries will be on second Monday of each month -p "every 11/05" yearly periods with boundaries on 5th of Nov -p "every 5th Nov" same -p "every Nov 5th" same - Show historical balances at end of 15th each month (N is exclusive end + Show historical balances at end of 15th each month (N is exclusive end date): hledger balance -H -p "every 16th day" - Group postings from start of wednesday to end of next tuesday (N is + Group postings from start of wednesday to end of next tuesday (N is start date and exclusive end date): hledger register checking -p "every 3rd day of week" Depth limiting With the --depth N option (short form: -N), commands like account, bal- - ance and register will show only the uppermost accounts in the account - tree, down to level N. Use this when you want a summary with less de- + ance and register will show only the uppermost accounts in the account + tree, down to level N. Use this when you want a summary with less de- tail. This flag has the same effect as a depth: query argument (so -2, --depth=2 or depth:2 are basically equivalent). Pivoting Normally hledger sums amounts, and organizes them in a hierarchy, based - on account name. The --pivot FIELD option causes it to sum and orga- - nize hierarchy based on the value of some other field instead. FIELD + on account name. The --pivot FIELD option causes it to sum and orga- + nize hierarchy based on the value of some other field instead. FIELD can be: code, description, payee, note, or the full name (case insensi- tive) of any tag. As with account names, values containing colon:sepa- rated:parts will be displayed hierarchically in reports. - --pivot is a general option affecting all reports; you can think of + --pivot is a general option affecting all reports; you can think of hledger transforming the journal before any other processing, replacing - every posting's account name with the value of the specified field on + every posting's account name with the value of the specified field on that posting, inheriting it from the transaction or using a blank value if it's not present. @@ -1125,7 +1166,7 @@ OPTIONS -------------------- 0 - One way to show only amounts with a member: value (using a query, de- + One way to show only amounts with a member: value (using a query, de- scribed below): $ hledger balance --pivot member tag:member=. @@ -1133,7 +1174,7 @@ OPTIONS -------------------- -2 EUR - Another way (the acct: query matches against the pivoted "account + Another way (the acct: query matches against the pivoted "account name"): $ hledger balance --pivot member acct:. @@ -1144,23 +1185,23 @@ OPTIONS Valuation -B: Cost The -B/--cost flag converts amounts to their cost (or selling price) at - transaction time, if they have a transaction price specified. This + transaction time, if they have a transaction price specified. This flag is equivalent to --value=cost, described below. -V: Market value The -V/--market flag converts reported amounts to their market value in - a default valuation commodity, using the market prices in effect on a - default valuation date. For single period reports, the valuation date - is today (equivalent to --value=now); for multiperiod reports, it is + a default valuation commodity, using the market prices in effect on a + default valuation date. For single period reports, the valuation date + is today (equivalent to --value=now); for multiperiod reports, it is the last day of each subperiod (equivalent to --value=end). The default valuation commodity is the one referenced in the latest ap- - plicable market price dated on or before the valuation date. If most - of your P declarations lead to a single home currency, this will usu- + plicable market price dated on or before the valuation date. If most + of your P declarations lead to a single home currency, this will usu- ally be what you want. (To specify the commodity, see -X below.) Note that in hledger, market prices are always declared explicitly with - P directives; we do not infer them from transaction prices as Ledger + P directives; we do not infer them from transaction prices as Ledger does. Here's a quick example of -V: @@ -1186,15 +1227,15 @@ OPTIONS $ hledger -f t.j bal -N euros -V -e 2016/11/4 $110.00 assets:euros - What are they worth after 2016/12/21 ? (no report end date specified, + What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) $ hledger -f t.j bal -N euros -V $103.00 assets:euros -X: Market value in specified commodity - The -X/--exchange option is like -V, except it specifies the target - commodity you would like to convert to. It is equivalent to + The -X/--exchange option is like -V, except it specifies the target + commodity you would like to convert to. It is equivalent to --value=now,COMM or --value=end,COMM. --value: Flexible valuation @@ -1215,48 +1256,48 @@ OPTIONS valuation date: --value=cost - Convert amounts to cost, using the prices recorded in transac- + Convert amounts to cost, using the prices recorded in transac- tions. --value=then Convert amounts to their value in a default valuation commodity, - using market prices on each posting's date. This is currently + using market prices on each posting's date. This is currently supported only by the print and register commands. --value=end Convert amounts to their value in a default valuation commodity, - using market prices on the last day of the report period (or if + using market prices on the last day of the report period (or if unspecified, the journal's end date); or in multiperiod reports, market prices on the last day of each subperiod. --value=now - Convert amounts to their value in default valuation commodity + Convert amounts to their value in default valuation commodity using current market prices (as of when report is generated). --value=YYYY-MM-DD - Convert amounts to their value in default valuation commodity + Convert amounts to their value in default valuation commodity using market prices on this date. - The default valuation commodity is the commodity mentioned in the most + The default valuation commodity is the commodity mentioned in the most recent applicable market price declaration. When all your price decla- - rations lead to a single home currency, this will usually do what you + rations lead to a single home currency, this will usually do what you want. To select a different valuation commodity, add the optional ,COMM part: - a comma, then the target commodity's symbol. Eg: --value=now,EUR. + a comma, then the target commodity's symbol. Eg: --value=now,EUR. hledger will do its best to convert amounts to this commodity, using: o declared prices (from source commodity to valuation commodity) - o reverse prices (declared prices from valuation to source commodity, + o reverse prices (declared prices from valuation to source commodity, inverted) - o indirect prices (prices calculated from the shortest chain of de- + o indirect prices (prices calculated from the shortest chain of de- clared or reverse prices from source to valuation commodity) in that order. - Here are some examples showing the effect of --value as seen with + Here are some examples showing the effect of --value as seen with print: P 2000-01-01 A 1 B @@ -1294,7 +1335,7 @@ OPTIONS 2000-02-01 (a) 2 B - With no report period specified, that shows the value as of the last + With no report period specified, that shows the value as of the last day of the journal (2000-03-01): $ hledger -f- print --value=end @@ -1331,7 +1372,7 @@ OPTIONS 2000-03-01 (a) 1 B - You may need to explicitly set a commodity's display style, when re- + You may need to explicitly set a commodity's display style, when re- verse prices are used. Eg this output might be surprising: P 2000-01-01 A 2B @@ -1345,10 +1386,10 @@ OPTIONS a 0 b 0 - Explanation: because there's no amount or commodity directive specify- - ing a display style for A, 0.5A gets the default style, which shows no + Explanation: because there's no amount or commodity directive specify- + ing a display style for A, 0.5A gets the default style, which shows no decimal digits. Because the displayed amount looks like zero, the com- - modity symbol and minus sign are not displayed either. Adding a com- + modity symbol and minus sign are not displayed either. Adding a com- modity directive sets a more useful display style for A: P 2000-01-01 A 2B @@ -1364,18 +1405,19 @@ OPTIONS b -0.50A Effect of --value on reports - Here is a reference for how --value currently affects each part of - hledger's reports. It's work in progress, but may be useful for trou- - bleshooting or reporting bugs. See also the definitions and notes be- - low. If you find problems, please report them, ideally with a repro- + Here is a reference for how --value currently affects each part of + hledger's reports. It's work in progress, but may be useful for trou- + bleshooting or reporting bugs. See also the definitions and notes be- + low. If you find problems, please report them, ideally with a repro- ducible example. Related: #329, #1083. Report type -B, -V, -X --value=then --value=end --value=DATE, --value=cost --value=now ------------------------------------------------------------------------------------------ + print posting cost value at re- value at value at re- value at - amounts port end or posting date port or DATE/today + amounts port end or posting date port or DATE/today today journal end balance as- unchanged unchanged unchanged unchanged unchanged sertions / @@ -1388,10 +1430,10 @@ OPTIONS journal journal start start posting cost value at re- value at value at re- value at - amounts (no port end or posting date port or DATE/today + amounts (no port end or posting date port or DATE/today report in- today journal end terval) - summary summarised value at pe- sum of post- value at pe- value at + summary summarised value at pe- sum of post- value at pe- value at posting cost riod ends ings in in- riod ends DATE/today amounts terval, val- (with report ued at inter- @@ -1404,7 +1446,7 @@ OPTIONS bse, cf, is..) balances (no sums of value at re- not supported value at re- value at - report in- costs port end or port or DATE/today of + report in- costs port end or port or DATE/today of terval) today of journal end sums of post- sums of of sums of ings postings postings @@ -1420,7 +1462,7 @@ OPTIONS budget like bal- like bal- not supported like bal- like balances amounts with ances ances ances --budget - grand total sum of dis- sum of dis- not supported sum of dis- sum of dis- + grand total sum of dis- sum of dis- not supported sum of dis- sum of dis- (no report played val- played val- played val- played values interval) ues ues ues row to- sums/aver- sums/aver- not supported sums/aver- sums/averages @@ -1428,7 +1470,7 @@ OPTIONS ages (with played val- played val- played val- values report in- ues ues ues terval) - column to- sums of dis- sums of dis- not supported sums of dis- sums of dis- + column to- sums of dis- sums of dis- not supported sums of dis- sums of dis- tals played val- played val- played val- played values ues ues ues grand to- sum/average sum/average not supported sum/average sum/average @@ -1440,29 +1482,29 @@ OPTIONS cost calculated using price(s) recorded in the transaction(s). - value market value using available market price declarations, or the + value market value using available market price declarations, or the unchanged amount if no conversion rate can be found. report start - the first day of the report period specified with -b or -p or + the first day of the report period specified with -b or -p or date:, otherwise today. report or journal start - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, otherwise today. report end - the last day of the report period specified with -e or -p or + the last day of the report period specified with -e or -p or date:, otherwise today. report or journal end - the last day of the report period specified with -e or -p or - date:, otherwise the latest transaction date in the journal, + the last day of the report period specified with -e or -p or + date:, otherwise the latest transaction date in the journal, otherwise today. report interval - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report's multi-period mode (whether showing one or many subperi- ods). @@ -1470,33 +1512,33 @@ OPTIONS The rightmost of these flags wins. COMMANDS - hledger provides a number of subcommands; hledger with no arguments + hledger provides a number of subcommands; hledger with no arguments shows a list. If you install additional hledger-* packages, or if you put programs or - scripts named hledger-NAME in your PATH, these will also be listed as + scripts named hledger-NAME in your PATH, these will also be listed as subcommands. - Run a subcommand by writing its name as first argument (eg hledger in- - comestatement). You can also write one of the standard short aliases - displayed in parentheses in the command list (hledger b), or any any + Run a subcommand by writing its name as first argument (eg hledger in- + comestatement). You can also write one of the standard short aliases + displayed in parentheses in the command list (hledger b), or any any unambiguous prefix of a command name (hledger inc). - Here are all the builtin commands in alphabetical order. See also - hledger for a more organised command list, and hledger CMD -h for de- + Here are all the builtin commands in alphabetical order. See also + hledger for a more organised command list, and hledger CMD -h for de- tailed command help. accounts accounts, a Show account names. - This command lists account names, either declared with account direc- - tives (--declared), posted to (--used), or both (the default). With - query arguments, only matched account names and account names refer- - enced by matched postings are shown. It shows a flat list by default. - With --tree, it uses indentation to show the account hierarchy. In - flat mode you can add --drop N to omit the first few account name com- - ponents. Account names can be depth-clipped with depth:N or --depth N + This command lists account names, either declared with account direc- + tives (--declared), posted to (--used), or both (the default). With + query arguments, only matched account names and account names refer- + enced by matched postings are shown. It shows a flat list by default. + With --tree, it uses indentation to show the account hierarchy. In + flat mode you can add --drop N to omit the first few account name com- + ponents. Account names can be depth-clipped with depth:N or --depth N or -N. Examples: @@ -1515,8 +1557,8 @@ COMMANDS activity Show an ascii barchart of posting counts per interval. - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the default). With query arguments, it counts only matched transactions. Examples: @@ -1531,22 +1573,22 @@ COMMANDS add Prompt for transactions and add them to the journal. - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- actions, and appends them to the journal file (if there are multiple -f - FILE options, the first file is used.) Existing transactions are not - changed. This is the only hledger command that writes to the journal + FILE options, the first file is used.) Existing transactions are not + changed. This is the only hledger command that writes to the journal file. To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar (by de- - scription) recent transaction (filtered by the query, if any) as a + o add tries to provide useful defaults, using the most similar (by de- + scription) recent transaction (filtered by the query, if any) as a template. o You can also set the initial defaults with command line arguments. @@ -1554,10 +1596,10 @@ COMMANDS o Readline-style edit keys can be used during data entry. o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is + tions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. - o If the journal defines a default commodity, it will be added to any + o If the journal defines a default commodity, it will be added to any bare numbers entered. o A parenthesised transaction code may be entered following a date. @@ -1566,7 +1608,7 @@ COMMANDS o If you make a mistake, enter < at any prompt to go one step backward. - o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Example (see the tutorial for a detailed explanation): @@ -1596,8 +1638,8 @@ COMMANDS Starting the next transaction (. or ctrl-D/ctrl-C to quit) Date [2015/05/22]: $ - On Microsoft Windows, the add command makes sure that no part of the - file path ends with a period, as it can cause data loss on that plat- + On Microsoft Windows, the add command makes sure that no part of the + file path ends with a period, as it can cause data loss on that plat- form (cf #1056). balance @@ -1605,29 +1647,29 @@ COMMANDS Show accounts and their balances. The balance command is hledger's most versatile command. Note, despite - the name, it is not always used for showing real-world account bal- - ances; the more accounting-aware balancesheet and incomestatement may + the name, it is not always used for showing real-world account bal- + ances; the more accounting-aware balancesheet and incomestatement may be more convenient for that. By default, it displays all accounts, and each account's change in bal- ance during the entire period of the journal. Balance changes are cal- - culated by adding up the postings in each account. You can limit the - postings matched, by a query, to see fewer accounts, changes over a + culated by adding up the postings in each account. You can limit the + postings matched, by a query, to see fewer accounts, changes over a different time period, changes from only cleared transactions, etc. If you include an account's complete history of postings in the report, - the balance change is equivalent to the account's current ending bal- - ance. For a real-world account, typically you won't have all transac- + the balance change is equivalent to the account's current ending bal- + ance. For a real-world account, typically you won't have all transac- tions in the journal; instead you'll have all transactions after a cer- - tain date, and an "opening balances" transaction setting the correct - starting balance on that date. Then the balance command will show + tain date, and an "opening balances" transaction setting the correct + starting balance on that date. Then the balance command will show real-world account balances. In some cases the -H/--historical flag is used to ensure this (more below). The balance command can produce several styles of report: Classic balance report - This is the original balance report, as found in Ledger. It usually + This is the original balance report, as found in Ledger. It usually looks like this: $ hledger balance @@ -1645,22 +1687,22 @@ COMMANDS 0 By default, accounts are displayed hierarchically, with subaccounts in- - dented below their parent. At each level of the tree, accounts are - sorted by account code if any, then by account name. Or with + dented below their parent. At each level of the tree, accounts are + sorted by account code if any, then by account name. Or with -S/--sort-amount, by their balance amount. "Boring" accounts, which contain a single interesting subaccount and no - balance of their own, are elided into the following line for more com- - pact output. (Eg above, the "liabilities" account.) Use --no-elide to + balance of their own, are elided into the following line for more com- + pact output. (Eg above, the "liabilities" account.) Use --no-elide to prevent this. - Account balances are "inclusive" - they include the balances of any + Account balances are "inclusive" - they include the balances of any subaccounts. - Accounts which have zero balance (and no non-zero subaccounts) are + Accounts which have zero balance (and no non-zero subaccounts) are omitted. Use -E/--empty to show them. - A final total is displayed by default; use -N/--no-total to suppress + A final total is displayed by default; use -N/--no-total to suppress it, eg: $ hledger balance -p 2008/6 expenses --no-total @@ -1669,7 +1711,7 @@ COMMANDS $1 supplies Customising the classic balance report - You can customise the layout of classic balance reports with --format + You can customise the layout of classic balance reports with --format FMT: $ hledger balance --format "%20(account) %12(total)" @@ -1687,7 +1729,7 @@ COMMANDS 0 The FMT format string (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with + to each account/balance pair. It may contain any suitable text, with data fields interpolated like so: %[MIN][.MAX](FIELDNAME) @@ -1698,14 +1740,14 @@ COMMANDS o FIELDNAME must be enclosed in parentheses, and can be one of: - o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. o account - the account's name o total - the account's balance/posted total, right justified - Also, FMT can begin with an optional prefix to control how multi-com- + Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: o %_ - render on multiple lines, bottom-aligned (the default) @@ -1722,14 +1764,14 @@ COMMANDS o %(total) - the account's total - o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on one line - o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report Colour support @@ -1740,9 +1782,9 @@ COMMANDS o the output is not being redirected or piped anywhere Flat mode - To see a flat list instead of the default hierarchical display, use - --flat. In this mode, accounts (unless depth-clipped) show their full - names and "exclusive" balance, excluding any subaccount balances. In + To see a flat list instead of the default hierarchical display, use + --flat. In this mode, accounts (unless depth-clipped) show their full + names and "exclusive" balance, excluding any subaccount balances. In this mode, you can also use --drop N to omit the first few account name components. @@ -1751,8 +1793,8 @@ COMMANDS $1 supplies Depth limited balance reports - With --depth N or depth:N or just -N, balance reports show accounts - only to the specified numeric depth. This is very useful to summarise + With --depth N or depth:N or just -N, balance reports show accounts + only to the specified numeric depth. This is very useful to summarise a complex set of accounts and get an overview. $ hledger balance -N -1 @@ -1765,9 +1807,9 @@ COMMANDS inclusive balances at the depth limit. Percentages - With -% or --percent, balance reports show each account's value ex- - pressed as a percentage of the column's total. This is useful to get - an overview of the relative sizes of account balances. For example to + With -% or --percent, balance reports show each account's value ex- + pressed as a percentage of the column's total. This is useful to get + an overview of the relative sizes of account balances. For example to obtain an overview of expenses: $ hledger balance expenses -% @@ -1777,32 +1819,32 @@ COMMANDS -------------------- 100.0 % - Note that --tree does not have an effect on -%. The percentages are - always relative to the total sum of each column, they are never rela- + Note that --tree does not have an effect on -%. The percentages are + always relative to the total sum of each column, they are never rela- tive to the parent account. - Since the percentages are relative to the columns sum, it is usually - not useful to calculate percentages if the signs of the amounts are - mixed. Although the results are technically correct, they are most - likely useless. Especially in a balance report that sums up to zero + Since the percentages are relative to the columns sum, it is usually + not useful to calculate percentages if the signs of the amounts are + mixed. Although the results are technically correct, they are most + likely useless. Especially in a balance report that sums up to zero (eg hledger balance -B) all percentage values will be zero. - This flag does not work if the report contains any mixed commodity ac- + This flag does not work if the report contains any mixed commodity ac- counts. If there are mixed commodity accounts in the report be sure to use -V or -B to coerce the report into using a single commodity. Multicolumn balance report - Multicolumn or tabular balance reports are a very useful hledger fea- - ture, and usually the preferred style. They share many of the above - features, but they show the report as a table, with columns represent- - ing time periods. This mode is activated by providing a reporting in- + Multicolumn or tabular balance reports are a very useful hledger fea- + ture, and usually the preferred style. They share many of the above + features, but they show the report as a table, with columns represent- + ing time periods. This mode is activated by providing a reporting in- terval. - There are three types of multicolumn balance report, showing different + There are three types of multicolumn balance report, showing different information: 1. By default: each column shows the sum of postings in that period, ie - the account's change of balance in that period. This is useful eg + the account's change of balance in that period. This is useful eg for a monthly income statement: $ hledger balance --quarterly income expenses -E @@ -1818,7 +1860,7 @@ COMMANDS || $-1 $1 0 0 2. With --cumulative: each column shows the ending balance for that pe- - riod, accumulating the changes across periods, starting from 0 at + riod, accumulating the changes across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative @@ -1834,8 +1876,8 @@ COMMANDS || $-1 0 0 0 3. With --historical/-H: each column shows the actual historical ending - balance for that period, accumulating the changes across periods, - starting from the actual balance at the report start date. This is + balance for that period, accumulating the changes across periods, + starting from the actual balance at the report start date. This is useful eg for a multi-period balance sheet, and when you are showing only the data after a certain start date: @@ -1854,26 +1896,26 @@ COMMANDS Note that --cumulative or --historical/-H disable --row-total/-T, since summing end balances generally does not make sense. - Multicolumn balance reports display accounts in flat mode by default; + Multicolumn balance reports display accounts in flat mode by default; to see the hierarchy, use --tree. - With a reporting interval (like --quarterly above), the report - start/end dates will be adjusted if necessary so that they encompass + With a reporting interval (like --quarterly above), the report + start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last peri- ods will be "full" and comparable to the others. - The -E/--empty flag does two things in multicolumn balance reports: + The -E/--empty flag does two things in multicolumn balance reports: first, the report will show all columns within the specified report pe- - riod (without -E, leading and trailing columns with all zeroes are not - shown). Second, all accounts which existed at the report start date - will be considered, not just the ones with activity during the report - period (use -E to include low-activity accounts which would otherwise + riod (without -E, leading and trailing columns with all zeroes are not + shown). Second, all accounts which existed at the report start date + will be considered, not just the ones with activity during the report + period (use -E to include low-activity accounts which would otherwise would be omitted). The -T/--row-total flag adds an additional column showing the total for each row. - The -A/--average flag adds a column showing the average value in each + The -A/--average flag adds a column showing the average value in each row. Here's an example of all three: @@ -1894,21 +1936,21 @@ COMMANDS (Average is rounded to the dollar here since all journal amounts are) - A limitation of multicolumn balance reports: eliding of boring parent - accounts in tree mode, as in the classic balance report, is not yet + A limitation of multicolumn balance reports: eliding of boring parent + accounts in tree mode, as in the classic balance report, is not yet supported. - The --transpose flag can be used to exchange the rows and columns of a + The --transpose flag can be used to exchange the rows and columns of a multicolumn report. Budget report - With --budget, extra columns are displayed showing budget goals for - each account and period, if any. Budget goals are defined by periodic + With --budget, extra columns are displayed showing budget goals for + each account and period, if any. Budget goals are defined by periodic transactions. This is very useful for comparing planned and actual in- - come, expenses, time usage, etc. --budget is most often combined with + come, expenses, time usage, etc. --budget is most often combined with a report interval. - For example, you can take average monthly expenses in the common ex- + For example, you can take average monthly expenses in the common ex- pense categories to construct a minimal monthly budget: ;; Budget @@ -1955,25 +1997,25 @@ COMMANDS Note this is different from a normal balance report in several ways: - o Only accounts with budget goals during the report period are shown, + o Only accounts with budget goals during the report period are shown, by default. - o In each column, in square brackets after the actual amount, budgeted + o In each column, in square brackets after the actual amount, budgeted amounts are shown, along with the percentage of budget used. - o All parent accounts are always shown, even in flat mode. Eg assets, + o All parent accounts are always shown, even in flat mode. Eg assets, assets:bank, and expenses above. - o Amounts always include all subaccounts, budgeted or unbudgeted, even + o Amounts always include all subaccounts, budgeted or unbudgeted, even in flat mode. This means that the numbers displayed will not always add up! Eg above, - the expenses actual amount includes the gifts and supplies transac- - tions, but the expenses:gifts and expenses:supplies accounts are not + the expenses actual amount includes the gifts and supplies transac- + tions, but the expenses:gifts and expenses:supplies accounts are not shown, as they have no budget amounts declared. - This can be confusing. When you need to make things clearer, use the - -E/--empty flag, which will reveal all accounts including unbudgeted + This can be confusing. When you need to make things clearer, use the + -E/--empty flag, which will reveal all accounts including unbudgeted ones, giving the full picture. Eg: $ hledger balance -M --budget --empty @@ -2015,12 +2057,12 @@ COMMANDS For more examples, see Budgeting and Forecasting. Nested budgets - You can add budgets to any account in your account hierarchy. If you + You can add budgets to any account in your account hierarchy. If you have budgets on both parent account and some of its children, then bud- - get(s) of the child account(s) would be added to the budget of their + get(s) of the child account(s) would be added to the budget of their parent, much like account balances behave. - In the most simple case this means that once you add a budget to any + In the most simple case this means that once you add a budget to any account, all its parents would have budget as well. To illustrate this, consider the following budget: @@ -2030,13 +2072,13 @@ COMMANDS expenses:personal:electronics $100.00 liabilities - With this, monthly budget for electronics is defined to be $100 and - budget for personal expenses is an additional $1000, which implicitly + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which implicitly means that budget for both expenses:personal and expenses is $1100. - Transactions in expenses:personal:electronics will be counted both to- + Transactions in expenses:personal:electronics will be counted both to- wards its $100 budget and $1100 of expenses:personal , and transactions - in any other subaccount of expenses:personal would be counted towards + in any other subaccount of expenses:personal would be counted towards only towards the budget of expenses:personal. For example, let's consider these transactions: @@ -2062,9 +2104,9 @@ COMMANDS expenses:personal $30.00 liabilities - As you can see, we have transactions in expenses:personal:electron- - ics:upgrades and expenses:personal:train tickets, and since both of - these accounts are without explicitly defined budget, these transac- + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- tions would be counted towards budgets of expenses:personal:electronics and expenses:personal accordingly: @@ -2080,7 +2122,7 @@ COMMANDS -------------------------------++------------------------------- || 0 [ 0] - And with --empty, we can get a better picture of budget allocation and + And with --empty, we can get a better picture of budget allocation and consumption: $ hledger balance --budget -M --empty @@ -2098,8 +2140,9 @@ COMMANDS || 0 [ 0] Output format - The balance command supports output destination and output format se- - lection. + This command also supports the output destination and output format op- + tions The output formats supported are txt, csv, (multicolumn non-bud- + get reports only) html, and (experimental) json. balancesheet balancesheet, bs @@ -2142,12 +2185,13 @@ COMMANDS sense). Instead of absolute values percentages can be displayed with -%. - This command also supports output destination and output format selec- - tion. + This command also supports the output destination and output format op- + tions The output formats supported are txt, csv, html, and (experimen- + tal) json. balancesheetequity balancesheetequity, bse - Just like balancesheet, but also reports Equity (which it assumes is + Just like balancesheet, but also reports Equity (which it assumes is under a top-level equity account). Example: @@ -2176,12 +2220,16 @@ COMMANDS -------------------- 0 + This command also supports the output destination and output format op- + tions The output formats supported are txt, csv, html, and (experimen- + tal) json. + cashflow cashflow, cf - This command displays a simple cashflow statement, showing changes in - "cash" accounts. It assumes that these accounts are under a top-level - asset account (case insensitive, plural forms also allowed) and do not - contain receivable or A/R in their name. Note this report shows all + This command displays a simple cashflow statement, showing changes in + "cash" accounts. It assumes that these accounts are under a top-level + asset account (case insensitive, plural forms also allowed) and do not + contain receivable or A/R in their name. Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). @@ -2202,13 +2250,14 @@ COMMANDS $-1 With a reporting interval, multiple columns will be shown, one for each - report period. Normally cashflow shows changes in assets per period, - though as with multicolumn balance reports you can alter the report + report period. Normally cashflow shows changes in assets per period, + though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. Instead of absolute val- ues percentages can be displayed with -%. - This command also supports output destination and output format selec- - tion. + This command also supports the output destination and output format op- + tions The output formats supported are txt, csv, html, and (experimen- + tal) json. check-dates check-dates @@ -2480,8 +2529,9 @@ COMMANDS report mode with --change/--cumulative/--historical. Instead of abso- lute values percentages can be displayed with -%. - This command also supports output destination and output format selec- - tion. + This command also supports the output destination and output format op- + tions The output formats supported are txt, csv, html, and (experimen- + tal) json. notes notes Show notes. @@ -2508,10 +2558,10 @@ COMMANDS prices prices - Print market price directives from the journal. With --costs, also - print synthetic market prices based on transaction prices. With --in- - verted-costs, also print inverse prices based on transaction prices. - Prices (and postings providing prices) can be filtered by a query. + Print market price directives from the journal. With --costs, also + print synthetic market prices based on transaction prices. With --in- + verted-costs, also print inverse prices based on transaction prices. + Prices (and postings providing prices) can be filtered by a query. Price amounts are always displayed with their full precision. print @@ -2519,11 +2569,11 @@ COMMANDS Show transaction journal entries, sorted by date. The print command displays full journal entries (transactions) from the - journal file in date order, tidily formatted. With --date2, transac- + journal file in date order, tidily formatted. With --date2, transac- tions are sorted by secondary date instead. print's output is always a valid hledger journal. - It preserves all transaction information, but it does not preserve di- + It preserves all transaction information, but it does not preserve di- rectives or inter-transaction comments $ hledger print @@ -2550,43 +2600,46 @@ COMMANDS Normally, the journal entry's explicit or implicit amount style is pre- served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, when a transaction price is im- - plied but not written, it will not appear in the output. You can use - the -x/--explicit flag to make all amounts and transaction prices ex- - plicit, which can be useful for troubleshooting or for making your + not appear in the output. Similarly, when a transaction price is im- + plied but not written, it will not appear in the output. You can use + the -x/--explicit flag to make all amounts and transaction prices ex- + plicit, which can be useful for troubleshooting or for making your journal more readable and robust against data entry errors. -x is also implied by using any of -B,-V,-X,--value. - Note, -x/--explicit will cause postings with a multi-commodity amount - (these can arise when a multi-commodity transaction has an implicit - amount) to be split into multiple single-commodity postings, keeping + Note, -x/--explicit will cause postings with a multi-commodity amount + (these can arise when a multi-commodity transaction has an implicit + amount) to be split into multiple single-commodity postings, keeping the output parseable. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost using that price. This can be used for troubleshooting. - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is no similar-enough match, no transaction will be shown. With --new, for each FILE being read, hledger reads (and writes) a spe- - cial state file (.latest.FILE in the same directory), containing the - latest transaction date(s) that were seen last time FILE was read. - When this file is found, only transactions with newer dates (and new - transactions on the latest date) are printed. This is useful for ig- - noring already-seen entries in import data, such as downloaded CSV + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for ig- + noring already-seen entries in import data, such as downloaded CSV files. Eg: $ hledger -f bank1.csv print --new (shows transactions added since last print --new on this file) - This assumes that transactions added to FILE always have same or in- - creasing dates, and that transactions on the same day do not get re- + This assumes that transactions added to FILE always have same or in- + creasing dates, and that transactions on the same day do not get re- ordered. See also the import command. - This command also supports output destination and output format selec- - tion. Here's an example of print's CSV output: + This command also supports the output destination and output format op- + tions The output formats supported are txt, csv, and (experimental) + json. + + Here's an example of print's CSV output: $ hledger print -Ocsv "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" @@ -2737,27 +2790,28 @@ COMMANDS $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 - This command also supports output destination and output format selec- - tion. + This command also supports the output destination and output format op- + tions The output formats supported are txt, csv, and (experimental) + json. register-match register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. If there are multiple equally - good matches, it shows the most recent. Query options (options, not - arguments) can be used to restrict the search space. Helps ledger-au- + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps ledger-au- tosync detect already-seen transactions when importing. rewrite rewrite Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print + For now the only rewrite available is adding new postings, like print --auto. This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds + the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- + posting amounts can be fixed, or a multiplier of the existing transac- tion's first posting amount. Examples: @@ -2773,7 +2827,7 @@ COMMANDS (reserve:grocery) *0.25 ; reserve 25% for grocery (reserve:) *0.25 ; reserve 25% for grocery - Note the single quotes to protect the dollar sign from bash, and the + Note the single quotes to protect the dollar sign from bash, and the two spaces between account and amount. More: @@ -2783,16 +2837,16 @@ COMMANDS $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - Argument for --add-posting option is a usual posting of transaction - with an exception for amount specification. More precisely, you can + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can use '*' (star symbol) before the amount to indicate that that this is a - factor for an amount of original matched posting. If the amount in- + factor for an amount of original matched posting. If the amount in- cludes a commodity name, the new posting amount will be in the new com- - modity; otherwise, it will be in the matched posting amount's commod- + modity; otherwise, it will be in the matched posting amount's commod- ity. Re-write rules in a file - During the run this tool will execute so called "Automated Transac- + During the run this tool will execute so called "Automated Transac- tions" found in any journal it process. I.e instead of specifying this operations in command line you can put them in a journal file. @@ -2807,7 +2861,7 @@ COMMANDS budget:gifts *-1 assets:budget *1 - Note that '=' (equality symbol) that is used instead of date in trans- + Note that '=' (equality symbol) that is used instead of date in trans- actions you usually write. It indicates the query by which you want to match the posting to add new ones. @@ -2820,12 +2874,12 @@ COMMANDS --add-posting 'assets:budget *1' \ > rewritten-tidy-output.journal - It is important to understand that relative order of such entries in - journal is important. You can re-use result of previously added post- + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- ings. Diff output format - To use this tool for batch modification of your journal files you may + To use this tool for batch modification of your journal files you may find useful output in form of unified diff. $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' @@ -2849,10 +2903,10 @@ COMMANDS If you'll pass this through patch tool you'll get transactions contain- ing the posting that matches your query be updated. Note that multiple - files might be update according to list of input files specified via + files might be update according to list of input files specified via --file options and include directives inside of these files. - Be careful. Whole transaction being re-formatted in a style of output + Be careful. Whole transaction being re-formatted in a style of output from hledger print. See also: @@ -2860,48 +2914,48 @@ COMMANDS https://github.com/simonmichael/hledger/issues/99 rewrite vs. print --auto - This command predates print --auto, and currently does much the same + This command predates print --auto, and currently does much the same thing, but with these differences: - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect only child files. - o rewrite's query limits which transactions can be rewritten; all are + o rewrite's query limits which transactions can be rewritten; all are printed. print --auto's query limits which transactions are printed. - o rewrite applies rules specified on command line or in the journal. + o rewrite applies rules specified on command line or in the journal. print --auto applies rules specified in the journal. roi roi - Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. - This command assumes that you have account(s) that hold nothing but + This command assumes that you have account(s) that hold nothing but your investments and whenever you record current appraisal/valuation of these investments you offset unrealized profit and loss into account(s) that, again, hold nothing but unrealized profit and loss. - Any transactions affecting balance of investment account(s) and not - originating from unrealized profit and loss account(s) are assumed to + Any transactions affecting balance of investment account(s) and not + originating from unrealized profit and loss account(s) are assumed to be your investments or withdrawals. - At a minimum, you need to supply a query (which could be just an ac- + At a minimum, you need to supply a query (which could be just an ac- count name) to select your investments with --inv, and another query to identify your profit and loss transactions with --pnl. - It will compute and display the internalized rate of return (IRR) and - time-weighted rate of return (TWR) for your investments for the time - period requested. Both rates of return are annualized before display, + It will compute and display the internalized rate of return (IRR) and + time-weighted rate of return (TWR) for your investments for the time + period requested. Both rates of return are annualized before display, regardless of the length of reporting interval. stats stats Show some journal statistics. - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report for each report period. Example: @@ -2919,14 +2973,14 @@ COMMANDS Commodities : 1 ($) Market prices : 12 ($) - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. tags tags - List all the tag names used in the journal. With a TAGREGEX argument, - only tag names matching the regular expression (case insensitive) are - shown. With QUERY arguments, only transactions matching the query are + List all the tag names used in the journal. With a TAGREGEX argument, + only tag names matching the regular expression (case insensitive) are + shown. With QUERY arguments, only transactions matching the query are considered. With --values flag, the tags' unique values are listed in- stead. @@ -2934,13 +2988,13 @@ COMMANDS test Run built-in unit tests. - This command runs the unit tests built in to hledger and hledger-lib, - printing the results on stdout. If any test fails, the exit code will + This command runs the unit tests built in to hledger and hledger-lib, + printing the results on stdout. If any test fails, the exit code will be non-zero. - This is mainly used by hledger developers, but you can also use it to - sanity-check the installed hledger executable on your platform. All - tests are expected to pass - if you ever see a failure, please report + This is mainly used by hledger developers, but you can also use it to + sanity-check the installed hledger executable on your platform. All + tests are expected to pass - if you ever see a failure, please report as a bug! This command also accepts tasty test runner options, written after a -- @@ -2949,35 +3003,35 @@ COMMANDS $ hledger test -- -pData.Amount --color=never - For help on these, see https://github.com/feuerbach/tasty#options (-- + For help on these, see https://github.com/feuerbach/tasty#options (-- --help currently doesn't show them). Add-on Commands - hledger also searches for external add-on commands, and will include + hledger also searches for external add-on commands, and will include these in the commands list. These are programs or scripts in your PATH - whose name starts with hledger- and ends with a recognised file exten- + whose name starts with hledger- and ends with a recognised file exten- sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). - Add-ons can be invoked like any hledger command, but there are a few + Add-ons can be invoked like any hledger command, but there are a few things to be aware of. Eg if the hledger-web add-on is installed, - o hledger -h web shows hledger's help, while hledger web -h shows + o hledger -h web shows hledger's help, while hledger web -h shows hledger-web's help. - o Flags specific to the add-on must have a preceding -- to hide them - from hledger. So hledger web --serve --port 9000 will be rejected; + o Flags specific to the add-on must have a preceding -- to hide them + from hledger. So hledger web --serve --port 9000 will be rejected; you must use hledger web -- --serve --port 9000. o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger (and - haskell) library functions that built-in commands do, for command-line + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger (and + haskell) library functions that built-in commands do, for command-line options, journal parsing, reporting, etc. - Two important add-ons are the hledger-ui and hledger-web user inter- + Two important add-ons are the hledger-ui and hledger-web user inter- faces. These are maintained and released along with hledger: ui @@ -2996,23 +3050,23 @@ COMMANDS hledger-interest generates interest transactions for an account accord- ing to various schemes. - A few more experimental or old add-ons can be found in hledger's bin/ + A few more experimental or old add-ons can be found in hledger's bin/ directory. These are typically prototypes and not guaranteed to work. ENVIRONMENT - COLUMNS The screen width used by the register command. Default: the + COLUMNS The screen width used by the register command. Default: the full terminal width. LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). - A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- - trolled finance directory and YYYY is the current year. Or ~/DIR/cur- + A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- + trolled finance directory and YYYY is the current year. Or ~/DIR/cur- rent.journal, where current.journal is a symbolic link to YYYY.journal. On Mac computers, you can set this and other environment variables in a - more thorough way that also affects applications started from the GUI + more thorough way that also affects applications started from the GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en- vironment.plist file containing @@ -3023,13 +3077,13 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). LIMITATIONS - The need to precede addon command options with -- when invoked from + The need to precede addon command options with -- when invoked from hledger is awkward. When input data contains non-ascii characters, a suitable system locale @@ -3045,33 +3099,33 @@ LIMITATIONS In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. - Not all of Ledger's journal file syntax is supported. See file format + Not all of Ledger's journal file syntax is supported. See file format differences. - On large data files, hledger is slower and uses more memory than + On large data files, hledger is slower and uses more memory than Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and re- - member you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and re- + member you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command 'hledger' found" stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, + be added to your PATH environment variable. Eg on unix-like systems, that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors In order to handle non-ascii letters and symbols (like ), hledger needs an appropriate locale. This is usually configured system-wide; you can also configure it temporarily. The locale may need to be one that sup- - ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, I'm not sure yet). Here's an example of setting the locale temporarily, on ubuntu @@ -3090,7 +3144,7 @@ TROUBLESHOOTING $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ bash --login - If we preferred to use eg fr_FR.utf8, we might have to install that + If we preferred to use eg fr_FR.utf8, we might have to install that first: $ apt-get install language-pack-fr @@ -3111,7 +3165,7 @@ TROUBLESHOOTING REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -3125,7 +3179,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) @@ -3133,4 +3187,4 @@ SEE ALSO -hledger 1.16.99 February 2020 hledger(1) +hledger 1.17 March 2020 hledger(1)