diff --git a/hledger/hledger.1 b/hledger/hledger.1 index d16dd7cb6..c96db9260 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -987,6 +987,33 @@ directives, not transaction prices (unlike Ledger). Using \-B/\[en]cost and \-V/\[en]value together is currently allowed, but the results are probably not meaningful. Let us know if you find a use for this. +.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[] option. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-o\ \-\ \ \ \ \ #\ write\ to\ stdout\ (the\ default) +$\ hledger\ balance\ \-o\ FILE\ \ #\ write\ to\ FILE +\f[] +.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[] option, or by +specifying a \f[C]\&.csv\f[] or \f[C]\&.html\f[] file extension with +\f[C]\-o/\-\-output\-file\f[]. +.IP +.nf +\f[C] +$\ hledger\ balance\ \-O\ csv\ \ \ \ \ \ \ #\ write\ CSV\ to\ stdout +$\ hledger\ balance\ \-o\ FILE.csv\ \ #\ write\ CSV\ to\ FILE.csv +\f[] +.fi .SS Regular expressions .PP hledger uses regular expressions in a number of places: @@ -1448,7 +1475,7 @@ in single\-column balance reports: use this custom line format .TP .B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] select the output format. -Supported formats: txt, csv. +Supported formats: txt, csv, html. .RS .RE .TP @@ -1798,8 +1825,8 @@ Balance\ changes\ in\ 2017/11/01\-2017/12/31: For more examples and details, see Budgeting and Forecasting. .SS Custom balance output .PP -In simple (non\-multi\-column) balance reports, you can customise the -output with \f[C]\-\-format\ FMT\f[]: +You can customise the layout of simple (non\-tabular) balance reports +with \f[C]\-\-format\ FMT\f[]: .IP .nf \f[C] @@ -1867,6 +1894,8 @@ rendered on one line .IP \[bu] 2 \f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default format for the single\-column balance report +.PP +This command also supports output destination and output formats. .SS Colour support .PP The balance command shows negative amounts in red, if: @@ -1874,33 +1903,6 @@ The balance command shows negative amounts in red, if: the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[] .IP \[bu] 2 the output is not being redirected or piped anywhere -.SS Output destination -.PP -The balance, print, register and stats commands can write their output -to a destination other than the console. -This is controlled by the \f[C]\-o/\-\-output\-file\f[] option. -.IP -.nf -\f[C] -$\ hledger\ balance\ \-o\ \-\ \ \ \ \ #\ write\ to\ stdout\ (the\ default) -$\ hledger\ balance\ \-o\ FILE\ \ #\ write\ to\ FILE -\f[] -.fi -.SS CSV output -.PP -The balance, print and register commands can write their output as CSV. -This is useful for exporting data to other applications, eg to make -charts in a spreadsheet. -This is controlled by the \f[C]\-O/\-\-output\-format\f[] option, or by -specifying a \f[C]\&.csv\f[] file extension with -\f[C]\-o/\-\-output\-file\f[]. -.IP -.nf -\f[C] -$\ hledger\ balance\ \-O\ csv\ \ \ \ \ \ \ #\ write\ CSV\ to\ stdout -$\ hledger\ balance\ \-o\ FILE.csv\ \ #\ write\ CSV\ to\ FILE.csv -\f[] -.fi .SS balancesheet .PP This command displays a simple balance sheet, showing historical ending @@ -2011,6 +2013,8 @@ As with multicolumn balance reports, you can alter the report mode with Normally balancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates. +.PP +This command also supports output destination and output formats. .SS balancesheetequity .PP Just like balancesheet, but also reports Equity (which it assumes is @@ -2146,6 +2150,8 @@ report period. Normally cashflow shows changes in assets per period, though as with multicolumn balance reports you can alter the report mode with \f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +.PP +This command also supports output destination and output formats. .SS check\-dates .PP Check that transactions are sorted by increasing date. @@ -2343,6 +2349,8 @@ report period. Normally incomestatement shows revenues/expenses per period, though as with multicolumn balance reports you can alter the report mode with \f[C]\-\-change\f[]/\f[C]\-\-cumulative\f[]/\f[C]\-\-historical\f[]. +.PP +This command also supports output destination and output formats. .SS prices .PP Print all market prices from the journal. @@ -2455,7 +2463,7 @@ increasing dates, and that transactions on the same day do not get reordered. See also the import command. .PP -The print command also supports output destination and CSV output. +This command also supports output destination and output formats. Here's an example of print's CSV output: .IP .nf @@ -2667,9 +2675,7 @@ $\ hledger\ reg\ \-w\ $COLUMNS,40\ \ \ \ \ \ #\ use\ terminal\ width,\ and\ set\ \f[] .fi .PP -The register command also supports the \f[C]\-o/\-\-output\-file\f[] and -\f[C]\-O/\-\-output\-format\f[] options for controlling output -destination and CSV output. +This command also supports output destination and output formats. .SS register\-match .PP Print the one posting whose transaction description is closest to DESC, @@ -2708,8 +2714,7 @@ 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. .PP -The stats command also supports \f[C]\-o/\-\-output\-file\f[] for -controlling output destination. +This command also supports output destination and output formats. .SS tags .PP List all the tag names used in the journal. diff --git a/hledger/hledger.info b/hledger/hledger.info index 206e90e4d..38f6e0857 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -681,6 +681,37 @@ File: hledger.info, Node: Combining -B and -V, Next: Regular expressions, Pre Using -B/-cost and -V/-value together is currently allowed, but the results are probably not meaningful. Let us know if you find a use for this. +* Menu: + +* Output destination:: +* Output format:: + + +File: hledger.info, Node: Output destination, Next: Output format, Up: Combining -B and -V + +2.15.1 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 balance -o - # write to stdout (the default) +$ hledger balance -o FILE # write to FILE + + +File: hledger.info, Node: Output format, Prev: Output destination, Up: Combining -B and -V + +2.15.2 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'. + +$ hledger balance -O csv # write CSV to stdout +$ hledger balance -o FILE.csv # write CSV to FILE.csv  File: hledger.info, Node: Regular expressions, Prev: Combining -B and -V, Up: OPTIONS @@ -1084,7 +1115,7 @@ Show accounts and their balances. Aliases: b, bal. in single-column balance reports: use this custom line format '-O FMT --output-format=FMT' - select the output format. Supported formats: txt, csv. + select the output format. Supported formats: txt, csv, html. '-o FILE --output-file=FILE' write output to FILE. A file extension matching one of the above @@ -1159,8 +1190,6 @@ $ hledger balance -p 2008/6 expenses --no-total * Budgets:: * Custom balance output:: * Colour support:: -* Output destination:: -* CSV output::  File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Up: balance @@ -1393,8 +1422,8 @@ File: hledger.info, Node: Custom balance output, Next: Colour support, Prev: 4.4.5 Custom balance output --------------------------- -In simple (non-multi-column) balance reports, you can customise the -output with '--format FMT': +You can customise the layout of simple (non-tabular) balance reports +with '--format FMT': $ hledger balance --format "%20(account) %12(total)" assets $-1 @@ -1447,8 +1476,10 @@ may be needed to get pleasing results. * '%20(total) %2(depth_spacer)%-(account)' - the default format for the single-column balance report + This command also supports output destination and output formats. +  -File: hledger.info, Node: Colour support, Next: Output destination, Prev: Custom balance output, Up: balance +File: hledger.info, Node: Colour support, Prev: Custom balance output, Up: balance 4.4.6 Colour support -------------------- @@ -1458,34 +1489,6 @@ The balance command shows negative amounts in red, if: * the 'TERM' environment variable is not set to 'dumb' * the output is not being redirected or piped anywhere - -File: hledger.info, Node: Output destination, Next: CSV output, Prev: Colour support, Up: balance - -4.4.7 Output destination ------------------------- - -The balance, print, register and stats commands can write their output -to a destination other than the console. This is controlled by the -'-o/--output-file' option. - -$ hledger balance -o - # write to stdout (the default) -$ hledger balance -o FILE # write to FILE - - -File: hledger.info, Node: CSV output, Prev: Output destination, Up: balance - -4.4.8 CSV output ----------------- - -The balance, print and register commands can write their output as CSV. -This is useful for exporting data to other applications, eg to make -charts in a spreadsheet. This is controlled by the '-O/--output-format' -option, or by specifying a '.csv' file extension with -'-o/--output-file'. - -$ hledger balance -O csv # write CSV to stdout -$ hledger balance -o FILE.csv # write CSV to FILE.csv -  File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS @@ -1569,6 +1572,8 @@ the report mode with '--change'/'--cumulative'/'--historical'. Normally balancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates. + This command also supports output destination and output formats. +  File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: COMMANDS @@ -1679,6 +1684,8 @@ each 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'. + This command also supports output destination and output formats. +  File: hledger.info, Node: check-dates, Next: check-dupes, Prev: cashflow, Up: COMMANDS @@ -1856,6 +1863,8 @@ each report period. Normally incomestatement shows revenues/expenses per period, though as with multicolumn balance reports you can alter the report mode with '--change'/'--cumulative'/'--historical'. + This command also supports output destination and output formats. +  File: hledger.info, Node: prices, Next: print, Prev: incomestatement, Up: COMMANDS @@ -1951,7 +1960,7 @@ $ hledger -f bank1.csv print --new increasing dates, and that transactions on the same day do not get reordered. See also the import command. - The print command also supports output destination and CSV output. + This command also supports output destination and output formats. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -2122,9 +2131,7 @@ $ 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, and set description width - The register command also supports the '-o/--output-file' and -'-O/--output-format' options for controlling output destination and CSV -output. + This command also supports output destination and output formats.  File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS @@ -2173,8 +2180,7 @@ Commodities : 1 ($) or a matched part of it. With a reporting interval, it shows a report for each report period. - The stats command also supports '-o/--output-file' for controlling -output destination. + This command also supports output destination and output formats.  File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS @@ -2418,103 +2424,103 @@ Node: Market value21197 Ref: #market-value21332 Node: Combining -B and -V22515 Ref: #combining--b-and--v22679 -Node: Regular expressions22826 -Ref: #regular-expressions22969 -Node: QUERIES24330 -Ref: #queries24432 -Node: COMMANDS28399 -Ref: #commands28511 -Node: accounts29493 -Ref: #accounts29591 -Node: activity30837 -Ref: #activity30947 -Node: add31307 -Ref: #add31406 -Node: balance34067 -Ref: #balance34178 -Node: Flat mode37658 -Ref: #flat-mode37783 -Node: Depth limited balance reports38203 -Ref: #depth-limited-balance-reports38404 -Node: Multicolumn balance reports38824 -Ref: #multicolumn-balance-reports39019 -Node: Budgets43708 -Ref: #budgets43855 -Node: Custom balance output47686 -Ref: #custom-balance-output47848 -Node: Colour support49941 -Ref: #colour-support50100 -Node: Output destination50273 -Ref: #output-destination50429 -Node: CSV output50699 -Ref: #csv-output50816 -Node: balancesheet51213 -Ref: #balancesheet51349 -Node: balancesheetequity53581 -Ref: #balancesheetequity53730 -Node: cashflow54267 -Ref: #cashflow54395 -Node: check-dates56439 -Ref: #check-dates56566 -Node: check-dupes56683 -Ref: #check-dupes56807 -Node: close56944 -Ref: #close57051 -Node: help57381 -Ref: #help57481 -Node: import58555 -Ref: #import58669 -Node: incomestatement59399 -Ref: #incomestatement59533 -Node: prices61858 -Ref: #prices61973 -Node: print62016 -Ref: #print62126 -Node: print-unique67011 -Ref: #print-unique67137 -Node: register67205 -Ref: #register67332 -Node: Custom register output71833 -Ref: #custom-register-output71962 -Node: register-match73259 -Ref: #register-match73393 -Node: rewrite73576 -Ref: #rewrite73693 -Node: stats73762 -Ref: #stats73865 -Node: tags74747 -Ref: #tags74845 -Node: test75081 -Ref: #test75165 -Node: ADD-ON COMMANDS75533 -Ref: #add-on-commands75643 -Node: Official add-ons76930 -Ref: #official-add-ons77070 -Node: api77157 -Ref: #api77246 -Node: ui77298 -Ref: #ui77397 -Node: web77455 -Ref: #web77544 -Node: Third party add-ons77590 -Ref: #third-party-add-ons77765 -Node: diff77900 -Ref: #diff77997 -Node: iadd78096 -Ref: #iadd78210 -Node: interest78293 -Ref: #interest78414 -Node: irr78509 -Ref: #irr78607 -Node: Experimental add-ons78685 -Ref: #experimental-add-ons78837 -Node: autosync79128 -Ref: #autosync79240 -Node: budget79479 -Ref: #budget79601 -Node: chart79667 -Ref: #chart79784 -Node: check79855 -Ref: #check79957 +Node: Output destination22876 +Ref: #output-destination23026 +Node: Output format23309 +Ref: #output-format23449 +Node: Regular expressions23834 +Ref: #regular-expressions23977 +Node: QUERIES25338 +Ref: #queries25440 +Node: COMMANDS29407 +Ref: #commands29519 +Node: accounts30501 +Ref: #accounts30599 +Node: activity31845 +Ref: #activity31955 +Node: add32315 +Ref: #add32414 +Node: balance35075 +Ref: #balance35186 +Node: Flat mode38634 +Ref: #flat-mode38759 +Node: Depth limited balance reports39179 +Ref: #depth-limited-balance-reports39380 +Node: Multicolumn balance reports39800 +Ref: #multicolumn-balance-reports39995 +Node: Budgets44684 +Ref: #budgets44831 +Node: Custom balance output48662 +Ref: #custom-balance-output48824 +Node: Colour support50981 +Ref: #colour-support51113 +Node: balancesheet51286 +Ref: #balancesheet51422 +Node: balancesheetequity53724 +Ref: #balancesheetequity53873 +Node: cashflow54410 +Ref: #cashflow54538 +Node: check-dates56652 +Ref: #check-dates56779 +Node: check-dupes56896 +Ref: #check-dupes57020 +Node: close57157 +Ref: #close57264 +Node: help57594 +Ref: #help57694 +Node: import58768 +Ref: #import58882 +Node: incomestatement59612 +Ref: #incomestatement59746 +Node: prices62141 +Ref: #prices62256 +Node: print62299 +Ref: #print62409 +Node: print-unique67293 +Ref: #print-unique67419 +Node: register67487 +Ref: #register67614 +Node: Custom register output72115 +Ref: #custom-register-output72244 +Node: register-match73465 +Ref: #register-match73599 +Node: rewrite73782 +Ref: #rewrite73899 +Node: stats73968 +Ref: #stats74071 +Node: tags74932 +Ref: #tags75030 +Node: test75266 +Ref: #test75350 +Node: ADD-ON COMMANDS75718 +Ref: #add-on-commands75828 +Node: Official add-ons77115 +Ref: #official-add-ons77255 +Node: api77342 +Ref: #api77431 +Node: ui77483 +Ref: #ui77582 +Node: web77640 +Ref: #web77729 +Node: Third party add-ons77775 +Ref: #third-party-add-ons77950 +Node: diff78085 +Ref: #diff78182 +Node: iadd78281 +Ref: #iadd78395 +Node: interest78478 +Ref: #interest78599 +Node: irr78694 +Ref: #irr78792 +Node: Experimental add-ons78870 +Ref: #experimental-add-ons79022 +Node: autosync79313 +Ref: #autosync79425 +Node: budget79664 +Ref: #budget79786 +Node: chart79852 +Ref: #chart79969 +Node: check80040 +Ref: #check80142  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 29b4b7632..5cf6d6ebf 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -635,59 +635,76 @@ OPTIONS results are probably not meaningful. Let us know if you find a use for this. + 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 balance -o - # write to stdout (the default) + $ hledger balance -o FILE # write to FILE + + Output format + Some commands can write their output in other formats. Eg print and + register can output CSV, and the balance commands can output CSV or + HTML. This is controlled by the -O/--output-format option, or by spec- + ifying a .csv or .html file extension with -o/--output-file. + + $ hledger balance -O csv # write CSV to stdout + $ hledger balance -o FILE.csv # write CSV to FILE.csv + 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 + o and parenthesised capturing groups and numeric backreferences in replacement 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. QUERIES - One of hledger's strengths is being able to quickly report on precise - subsets of your data. Most commands accept an optional query expres- - sion, written as arguments after the command name, to filter the data - by date, account name or other criteria. The syntax is similar to a + One of hledger's strengths is being able to quickly report on precise + subsets of your data. Most commands accept an optional query expres- + sion, written as arguments after the command name, to filter the data + by date, account name or other criteria. The syntax is similar to a web search: one or more space-separated search terms, quotes to enclose - whitespace, prefixes to match specific fields, a not: prefix to negate + whitespace, prefixes to match specific fields, a not: prefix to negate the match. - We do not yet support arbitrary boolean combinations of search terms; - instead most commands show transactions/postings/accounts which match + We do not yet support arbitrary boolean combinations of search terms; + instead most commands show transactions/postings/accounts which match (or negatively match): o any of the description terms AND @@ -708,32 +725,32 @@ QUERIES o match all the other terms. - The following kinds of search terms can be used. Remember these can + The following kinds of search terms can be used. Remember these can also be prefixed with not:, eg to exclude a particular subaccount. - REGEX match account names by this regular expression. (No prefix is + REGEX match account names by this regular expression. (No prefix is equivalent to acct:). acct:REGEX same as above amt:N, amt:N, amt:>=N - match postings with a single-commodity amount that is equal to, - less than, or greater than N. (Multi-commodity amounts are not + match postings with a single-commodity amount that is equal to, + less than, or greater than N. (Multi-commodity amounts are not tested, and will always match.) The comparison has two modes: if N is preceded by a + or - sign (or is 0), the two signed numbers - are compared. Otherwise, the absolute magnitudes are compared, + are compared. Otherwise, the absolute magnitudes are compared, ignoring sign. code:REGEX match by transaction code (eg check number) cur:REGEX - match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a par- + match postings or transactions including any amounts whose cur- + rency/commodity symbol is fully matched by REGEX. (For a par- tial match, use .*REGEX.*). Note, to match characters which are regex-significant, like the dollar sign ($), you need to prepend - \. And when using the command line you need to add one more + \. And when using the command line you need to add one more level of quoting to hide it from the shell, so eg do: hledger print cur:'\$' or hledger print cur:\\$. @@ -742,20 +759,20 @@ QUERIES date:PERIODEXPR match dates within the specified period. PERIODEXPR is a period - expression (with no report interval). Examples: date:2016, - date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the - --date2 command line flag is present, this matches secondary + expression (with no report interval). Examples: date:2016, + date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the + --date2 command line flag is present, this matches secondary dates instead. date2:PERIODEXPR match secondary dates within the specified period. depth:N - match (or display, depending on command) accounts at or above + match (or display, depending on command) accounts at or above this depth note:REGEX - match transaction notes (part of description right of |, or + match transaction notes (part of description right of |, or whole description when there's no |) payee:REGEX @@ -769,38 +786,38 @@ QUERIES match unmarked, pending, or cleared transactions respectively tag:REGEX[=REGEX] - match by tag name, and optionally also by tag value. Note a - tag: query is considered to match a transaction if it matches - any of the postings. Also remember that postings inherit the + match by tag name, and optionally also by tag value. Note a + tag: query is considered to match a transaction if it matches + any of the postings. Also remember that postings inherit the tags of their parent transaction. The following special search term is used automatically in hledger-web, only: inacct:ACCTNAME - tells hledger-web to show the transaction register for this + tells hledger-web to show the transaction register for this account. Can be filtered further with acct etc. Some of these can also be expressed as command-line options (eg depth:2 - is equivalent to --depth 2). Generally you can mix options and query - arguments, and the resulting query will be their intersection (perhaps + is equivalent to --depth 2). Generally you can mix options and query + arguments, and the resulting query will be their intersection (perhaps excluding the -p/--period option). 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 + Run a subcommand by writing its name as first argument (eg hledger incomestatement). You can also write one of the standard short - aliases displayed in parentheses in the command list (hledger b), or + 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 + Here are all the builtin commands in alphabetical order. See also + hledger for a more organised command list, and hledger CMD -h for detailed command help. accounts @@ -818,12 +835,12 @@ COMMANDS --drop=N in flat mode: omit N leading account name parts - This command lists account names, either declared with account direc- - tives (-declared), posted to (-used), or both (default). With query - arguments, only matched account names and account names referenced 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 compo- + This command lists account names, either declared with account direc- + tives (-declared), posted to (-used), or both (default). With query + arguments, only matched account names and account names referenced 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 compo- nents. Account names can be depth-clipped with --depth N or depth:N. Examples: @@ -866,8 +883,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. $ hledger activity --quarterly @@ -880,24 +897,24 @@ COMMANDS Prompt for transactions and add them to the journal. --no-new-accounts - don't allow creating new accounts; helps prevent typos when + don't allow creating new accounts; helps prevent typos when entering account names - 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 + 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 + 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 recent + o add tries to provide useful defaults, using the most similar recent transaction (by description) as a template. o You can also set the initial defaults with command line arguments. @@ -905,20 +922,20 @@ 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. o Comments and tags may be entered following a description or amount. - o If you make a mistake, enter < at any prompt to restart the transac- + o If you make a mistake, enter < at any prompt to restart the transac- tion. - 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): @@ -955,7 +972,7 @@ COMMANDS show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports) -H --historical @@ -987,28 +1004,28 @@ COMMANDS in single-column balance reports: use this custom line format -O FMT --output-format=FMT - select the output format. Supported formats: txt, csv. + select the output format. Supported formats: txt, csv, html. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. --pretty-tables use unicode to display prettier tables. --sort-amount - sort by amount instead of account code/name (in flat mode). + sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed. --budget - show performance compared to budget goals defined by periodic + show performance compared to budget goals defined by periodic transactions --show-unbudgeted with -budget, show unbudgeted accounts also - The balance command displays accounts and balances. It is hledger's + The balance command displays accounts and balances. It is hledger's most featureful and versatile command. $ hledger balance @@ -1025,28 +1042,28 @@ COMMANDS -------------------- 0 - More precisely, the balance command shows the change to each account's + More precisely, the balance command shows the change to each account's balance caused by all (matched) postings. In the common case where you - do not filter by date and your journal sets the correct opening bal- + do not filter by date and your journal sets the correct opening bal- ances, this is the same as the account's ending balance. - By default, accounts are displayed hierarchically, with subaccounts - indented below their parent. At each level of the tree, accounts are - sorted by account code if any, then by account name. Or with + By default, accounts are displayed hierarchically, with subaccounts + indented 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- + balance of their own, are elided into the following line for more com- pact output. (Not yet supported in tabular reports.) 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: $ hledger balance -p 2008/6 expenses --no-total @@ -1056,9 +1073,9 @@ COMMANDS Flat mode To see a flat list of full account names instead of the default hierar- - chical display, use --flat. In this mode, accounts (unless + chical display, use --flat. In this mode, accounts (unless depth-clipped) show their "exclusive" balance, excluding any subaccount - balances. In this mode, you can also use --drop N to omit the first + balances. In this mode, you can also use --drop N to omit the first few account name components. $ hledger balance -p 2008/6 expenses -N --flat --drop 1 @@ -1066,9 +1083,9 @@ COMMANDS $1 supplies Depth limited balance reports - With --depth N, balance shows accounts only to the specified depth. - This is very useful to show a complex charts of accounts in less - detail. In flat mode, balances from accounts below the depth limit + With --depth N, balance shows accounts only to the specified depth. + This is very useful to show a complex charts of accounts in less + detail. In flat mode, balances from accounts below the depth limit will be shown as part of a parent account at the depth limit. $ hledger balance -N --depth 1 @@ -1078,12 +1095,12 @@ COMMANDS $1 liabilities Multicolumn balance reports - With a reporting interval, multiple balance columns will be shown, one - for each report period. There are three types of multi-column balance + With a reporting interval, multiple balance columns will be shown, one + for each report period. There are three types of multi-column 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 @@ -1098,8 +1115,8 @@ COMMANDS -------------------++--------------------------------- || $-1 $1 0 0 - 2. With --cumulative: each column shows the ending balance for that - period, accumulating the changes across periods, starting from 0 at + 2. With --cumulative: each column shows the ending balance for that + period, accumulating the changes across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative @@ -1115,8 +1132,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: @@ -1132,26 +1149,26 @@ COMMANDS ----------------------++------------------------------------- || 0 0 0 - Multi-column balance reports display accounts in flat mode by default; + Multi-column 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: - first, the report will show all columns within the specified report - period (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 + The -E/--empty flag does two things in multicolumn balance reports: + first, the report will show all columns within the specified report + period (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 oth- erwise 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: @@ -1173,13 +1190,13 @@ COMMANDS # Average is rounded to the dollar here since all journal amounts are Budgets - With --budget and a report interval, all periodic transactions in your - journal with that interval, active during the requested report period, - are interpreted as recurring budget goals for the specified accounts - (and subaccounts), and the report will show the difference between + With --budget and a report interval, all periodic transactions in your + journal with that interval, active during the requested report period, + are interpreted as recurring budget goals for the specified accounts + (and subaccounts), and the report will show the difference between actual and budgeted balances. - For example, you can take average monthly expenses in the common + For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: ;; Budget @@ -1238,8 +1255,8 @@ COMMANDS -----------------------++------------------------------------------------- || 0 0 - Accounts with no budget goals (not mentioned in the periodic transac- - tions) will be aggregated under , unless you add the + Accounts with no budget goals (not mentioned in the periodic transac- + tions) will be aggregated under , unless you add the --show-unbudgeted flag to display them normally: $ hledger balance --budget --show-unbudgeted @@ -1260,8 +1277,8 @@ COMMANDS For more examples and details, see Budgeting and Forecasting. Custom balance output - In simple (non-multi-column) balance reports, you can customise the - output with --format FMT: + You can customise the layout of simple (non-tabular) balance reports + with --format FMT: $ hledger balance --format "%20(account) %12(total)" assets $-1 @@ -1278,7 +1295,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) @@ -1289,14 +1306,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) @@ -1305,7 +1322,7 @@ COMMANDS o %, - render on one line, comma-separated - There are some quirks. Eg in one-line mode, %(depth_spacer) has no + There are some quirks. Eg in one-line mode, %(depth_spacer) has no effect, instead %(account) has indentation built in. Experimentation may be needed to get pleasing results. @@ -1313,16 +1330,18 @@ 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 + This command also supports output destination and output formats. + Colour support The balance command shows negative amounts in red, if: @@ -1330,23 +1349,6 @@ COMMANDS o the output is not being redirected or piped anywhere - Output destination - The balance, print, register and stats commands can write their output - to a destination other than the console. This is controlled by the - -o/--output-file option. - - $ hledger balance -o - # write to stdout (the default) - $ hledger balance -o FILE # write to FILE - - CSV output - The balance, print and register commands can write their output as CSV. - This is useful for exporting data to other applications, eg to make - charts in a spreadsheet. This is controlled by the -O/--output-format - option, or by specifying a .csv file extension with -o/--output-file. - - $ hledger balance -O csv # write CSV to stdout - $ hledger balance -o FILE.csv # write CSV to FILE.csv - balancesheet This command displays a simple balance sheet, showing historical ending balances of asset and liability accounts (ignoring any report begin @@ -1422,6 +1424,8 @@ COMMANDS ancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates. + This command also supports output destination and output formats. + balancesheetequity Just like balancesheet, but also reports Equity (which it assumes is under a top-level equity account). @@ -1519,6 +1523,8 @@ COMMANDS though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. + This command also supports output destination and output formats. + check-dates Check that transactions are sorted by increasing date. With a query, only matched transactions' dates are checked. @@ -1662,6 +1668,8 @@ COMMANDS period, though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. + This command also supports output destination and output formats. + prices Print all market prices from the journal. @@ -1745,7 +1753,7 @@ COMMANDS increasing dates, and that transactions on the same day do not get reordered. See also the import command. - The print command also supports output destination and CSV output. + This command also supports output destination and output formats. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -1899,12 +1907,11 @@ COMMANDS $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - The register command also supports the -o/--output-file and -O/--out- - put-format options for controlling output destination and CSV output. + This command also supports output destination and output formats. register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. Helps ledger-autosync detect + in the style of the register command. Helps ledger-autosync detect already-seen transactions when importing. rewrite @@ -1914,7 +1921,7 @@ COMMANDS Show some journal statistics. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger stats @@ -1929,12 +1936,11 @@ COMMANDS Accounts : 8 (depth 3) Commodities : 1 ($) - 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. - The stats command also supports -o/--output-file for controlling output - destination. + This command also supports output destination and output formats. tags List all the tag names used in the journal. With a TAGREGEX argument, diff --git a/hledger/hledger_balance.m4.md b/hledger/hledger_balance.m4.md index 2bf6493ef..7dae7f926 100644 --- a/hledger/hledger_balance.m4.md +++ b/hledger/hledger_balance.m4.md @@ -36,7 +36,7 @@ Show accounts and their balances. Aliases: b, bal. `-O FMT --output-format=FMT ` : select the output format. Supported formats: -txt, csv. +txt, csv, html. `-o FILE --output-file=FILE` : write output to FILE. A file extension matching one of the above formats selects that format. @@ -336,8 +336,7 @@ For more examples and details, see [Budgeting and Forecasting](budgeting-and-for ### Custom balance output -In simple (non-multi-column) balance reports, you can customise the -output with `--format FMT`: +You can customise the layout of simple (non-tabular) balance reports with `--format FMT`: ```shell $ hledger balance --format "%20(account) %12(total)" @@ -391,6 +390,8 @@ Some example formats: - `%,%-50(account) %25(total)` - account name padded to 50 characters, total padded to 20 characters, with multiple commodities rendered on one line - `%20(total) %2(depth_spacer)%-(account)` - the default format for the single-column balance report +This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats). + ### Colour support The balance command shows negative amounts in red, if: @@ -398,27 +399,4 @@ The balance command shows negative amounts in red, if: - the `TERM` environment variable is not set to `dumb` - the output is not being redirected or piped anywhere -### Output destination - -The balance, print, register and stats commands can write their output to a -destination other than the console. This is controlled by the -`-o/--output-file` option. - -```shell -$ hledger balance -o - # write to stdout (the default) -$ hledger balance -o FILE # write to FILE -``` - -### CSV output - -The balance, print and register commands can write their output as -CSV. This is useful for exporting data to other applications, eg to -make charts in a spreadsheet. This is controlled by the -`-O/--output-format` option, or by specifying a `.csv` file extension -with `-o/--output-file`. - -```shell -$ hledger balance -O csv # write CSV to stdout -$ hledger balance -o FILE.csv # write CSV to FILE.csv -``` diff --git a/hledger/hledger_commands.m4.md b/hledger/hledger_commands.m4.md index e308c9468..86573e016 100644 --- a/hledger/hledger_commands.m4.md +++ b/hledger/hledger_commands.m4.md @@ -250,6 +250,8 @@ Normally balancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates. +This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats). + ## balancesheetequity Just like [balancesheet](#balancesheet), but also reports Equity (which it assumes is under a top-level `equity` account). @@ -349,6 +351,8 @@ Normally cashflow shows changes in assets per period, though as with [multicolumn balance reports](#multicolumn-balance-reports) you can alter the report mode with `--change`/`--cumulative`/`--historical`. +This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats). + ## check-dates Check that transactions are sorted by increasing date. With a query, only matched transactions' dates are checked. @@ -499,6 +503,8 @@ Normally incomestatement shows revenues/expenses per period, though as with [multicolumn balance reports](#multicolumn-balance-reports) you can alter the report mode with `--change`/`--cumulative`/`--historical`. +This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats). + ## prices Print all [market prices](/manual#market-prices) from the journal. @@ -579,10 +585,7 @@ This assumes that transactions added to FILE always have same or increasing date and that transactions on the same day do not get reordered. See also the [import](#import) command. -The print command also supports -[output destination](#output-destination) -and -[CSV output](#csv-output). +This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats). Here's an example of print's CSV output: ```shell $ hledger print -Ocsv @@ -737,9 +740,7 @@ $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width ``` -The register command also supports the -`-o/--output-file` and `-O/--output-format` options for controlling -[output destination](#output-destination) and [CSV output](#csv-output). +This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats). ## register-match Print the one posting whose transaction description is closest to DESC, @@ -773,8 +774,7 @@ The stats command displays summary information for the whole journal, or a matched part of it. With a [reporting interval](#reporting-interval), it shows a report for each report period. -The stats command also supports `-o/--output-file` -for controlling [output destination](#output-destination). +This command also supports [output destination](/manual.html#output-destination) and [output formats](/manual.html#output-formats). ## tags List all the tag names used in the journal. With a TAGREGEX argument, diff --git a/hledger/hledger_options.m4.md b/hledger/hledger_options.m4.md index dfa58f09b..582dc0049 100644 --- a/hledger/hledger_options.m4.md +++ b/hledger/hledger_options.m4.md @@ -414,6 +414,28 @@ not [transaction prices](journal.html#transaction-prices) (unlike Ledger). Using -B/--cost and -V/--value together is currently allowed, but the results are probably not meaningful. Let us know if you find a use for this. +### 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. + +```shell +$ hledger balance -o - # write to stdout (the default) +$ hledger balance -o FILE # write to FILE +``` + +### Output format + +Some commands can write their output in other formats. +Eg print and register can output CSV, and the balance commands can output CSV or HTML. +This is controlled by the `-O/--output-format` option, or by specifying a `.csv` or `.html` file extension with `-o/--output-file`. + +```shell +$ hledger balance -O csv # write CSV to stdout +$ hledger balance -o FILE.csv # write CSV to FILE.csv +``` + ## Regular expressions hledger uses [regular expressions](http://www.regular-expressions.info) in a number of places: