From c8fefef7e852b239137c0a436770f6740abfbfb5 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 18 Nov 2016 13:26:15 -0800 Subject: [PATCH] doc: document file reading, and some options cleanups --- hledger-lib/doc/hledger_journal.5 | 6 +- hledger-lib/doc/hledger_journal.5.info | 106 ++++----- hledger-lib/doc/hledger_journal.5.m4.md | 3 +- hledger-lib/doc/hledger_journal.5.txt | 6 +- hledger/doc/hledger.1 | 99 +++++++- hledger/doc/hledger.1.info | 293 ++++++++++++++---------- hledger/doc/hledger.1.txt | 61 ++++- hledger/doc/options.m4.md | 64 +++++- 8 files changed, 425 insertions(+), 213 deletions(-) diff --git a/hledger-lib/doc/hledger_journal.5 b/hledger-lib/doc/hledger_journal.5 index b83aac4ac..963fbe2dd 100644 --- a/hledger-lib/doc/hledger_journal.5 +++ b/hledger-lib/doc/hledger_journal.5 @@ -250,8 +250,10 @@ As you can see, the amount format is somewhat flexible: amounts are a number (the "quantity") and optionally a currency symbol/commodity name (the "commodity"). .IP \[bu] 2 -the commodity is a symbol, word, or double\-quoted phrase, on the left -or right, with or without a separating space +the commodity is a symbol, word, or phrase, on the left or right, with +or without a separating space. +If the commodity contains numbers, spaces or non\-word punctuation it +must be enclosed in double quotes. .IP \[bu] 2 negative amounts with a commodity on the left can have the minus sign before or after it diff --git a/hledger-lib/doc/hledger_journal.5.info b/hledger-lib/doc/hledger_journal.5.info index 6d0aba5bd..363eec497 100644 --- a/hledger-lib/doc/hledger_journal.5.info +++ b/hledger-lib/doc/hledger_journal.5.info @@ -257,8 +257,10 @@ commodity name. Some examples: * amounts are a number (the "quantity") and optionally a currency symbol/commodity name (the "commodity"). - * the commodity is a symbol, word, or double-quoted phrase, on the - left or right, with or without a separating space + * the commodity is a symbol, word, or phrase, on the left or right, + with or without a separating space. If the commodity contains + numbers, spaces or non-word punctuation it must be enclosed in + double quotes. * negative amounts with a commodity on the left can have the minus sign before or after it @@ -941,55 +943,55 @@ Node: Account names7535 Ref: #account-names7674 Node: Amounts8159 Ref: #amounts8297 -Node: Virtual Postings10295 -Ref: #virtual-postings10456 -Node: Balance Assertions11676 -Ref: #balance-assertions11840 -Node: Assertions and ordering12662 -Ref: #assertions-and-ordering12847 -Node: Assertions and commodities13878 -Ref: #assertions-and-commodities14104 -Node: Assertions and subaccounts14796 -Ref: #assertions-and-subaccounts15030 -Node: Assertions and virtual postings15552 -Ref: #assertions-and-virtual-postings15761 -Node: Prices15902 -Ref: #prices16034 -Node: Transaction prices16085 -Ref: #transaction-prices16230 -Node: Market prices17837 -Ref: #market-prices17972 -Node: Comments18860 -Ref: #comments18982 -Node: Tags20094 -Ref: #tags20212 -Node: Directives21135 -Ref: #directives21250 -Node: Account aliases21443 -Ref: #account-aliases21589 -Node: Basic aliases22191 -Ref: #basic-aliases22336 -Node: Regex aliases23024 -Ref: #regex-aliases23194 -Node: Multiple aliases23964 -Ref: #multiple-aliases24138 -Node: end aliases24634 -Ref: #end-aliases24776 -Node: account directive24878 -Ref: #account-directive25060 -Node: apply account directive25356 -Ref: #apply-account-directive25554 -Node: Multi-line comments26214 -Ref: #multi-line-comments26406 -Node: commodity directive26533 -Ref: #commodity-directive26719 -Node: Default commodity27592 -Ref: #default-commodity27767 -Node: Default year28303 -Ref: #default-year28470 -Node: Including other files28893 -Ref: #including-other-files29052 -Node: EDITOR SUPPORT29448 -Ref: #editor-support29568 +Node: Virtual Postings10396 +Ref: #virtual-postings10557 +Node: Balance Assertions11777 +Ref: #balance-assertions11941 +Node: Assertions and ordering12763 +Ref: #assertions-and-ordering12948 +Node: Assertions and commodities13979 +Ref: #assertions-and-commodities14205 +Node: Assertions and subaccounts14897 +Ref: #assertions-and-subaccounts15131 +Node: Assertions and virtual postings15653 +Ref: #assertions-and-virtual-postings15862 +Node: Prices16003 +Ref: #prices16135 +Node: Transaction prices16186 +Ref: #transaction-prices16331 +Node: Market prices17938 +Ref: #market-prices18073 +Node: Comments18961 +Ref: #comments19083 +Node: Tags20195 +Ref: #tags20313 +Node: Directives21236 +Ref: #directives21351 +Node: Account aliases21544 +Ref: #account-aliases21690 +Node: Basic aliases22292 +Ref: #basic-aliases22437 +Node: Regex aliases23125 +Ref: #regex-aliases23295 +Node: Multiple aliases24065 +Ref: #multiple-aliases24239 +Node: end aliases24735 +Ref: #end-aliases24877 +Node: account directive24979 +Ref: #account-directive25161 +Node: apply account directive25457 +Ref: #apply-account-directive25655 +Node: Multi-line comments26315 +Ref: #multi-line-comments26507 +Node: commodity directive26634 +Ref: #commodity-directive26820 +Node: Default commodity27693 +Ref: #default-commodity27868 +Node: Default year28404 +Ref: #default-year28571 +Node: Including other files28994 +Ref: #including-other-files29153 +Node: EDITOR SUPPORT29549 +Ref: #editor-support29669  End Tag Table diff --git a/hledger-lib/doc/hledger_journal.5.m4.md b/hledger-lib/doc/hledger_journal.5.m4.md index df2729df0..bb79805c0 100644 --- a/hledger-lib/doc/hledger_journal.5.m4.md +++ b/hledger-lib/doc/hledger_journal.5.m4.md @@ -207,7 +207,8 @@ Amounts consist of a number and (usually) a currency symbol or commodity name. S As you can see, the amount format is somewhat flexible: - amounts are a number (the "quantity") and optionally a currency symbol/commodity name (the "commodity"). -- the commodity is a symbol, word, or double-quoted phrase, on the left or right, with or without a separating space +- the commodity is a symbol, word, or phrase, on the left or right, with or without a separating space. + If the commodity contains numbers, spaces or non-word punctuation it must be enclosed in double quotes. - negative amounts with a commodity on the left can have the minus sign before or after it - digit groups (thousands, or any other grouping) can be separated by commas (in which case period is used for decimal point) or periods (in which case comma is used for decimal point) diff --git a/hledger-lib/doc/hledger_journal.5.txt b/hledger-lib/doc/hledger_journal.5.txt index 48a805c45..a2fe5df0a 100644 --- a/hledger-lib/doc/hledger_journal.5.txt +++ b/hledger-lib/doc/hledger_journal.5.txt @@ -187,8 +187,10 @@ FILE FORMAT o amounts are a number (the "quantity") and optionally a currency sym- bol/commodity name (the "commodity"). - o the commodity is a symbol, word, or double-quoted phrase, on the left - or right, with or without a separating space + o the commodity is a symbol, word, or phrase, on the left or right, + with or without a separating space. If the commodity contains num- + bers, spaces or non-word punctuation it must be enclosed in double + quotes. o negative amounts with a commodity on the left can have the minus sign before or after it diff --git a/hledger/doc/hledger.1 b/hledger/doc/hledger.1 index 18289befb..bda0df4c4 100644 --- a/hledger/doc/hledger.1 +++ b/hledger/doc/hledger.1 @@ -237,8 +237,9 @@ run add\-on executables directly .PP If you\[aq]re really curious, add \f[C]\-\-debug=2\f[] for troubleshooting. +.SS General options .PP -\f[B]General options:\f[] +Always available, can be written before or after COMMAND. .TP .B \f[C]\-h\f[] show general usage (or after COMMAND, the command\[aq]s usage) @@ -291,8 +292,9 @@ display accounts named OLD as NEW ignore any failing balance assertions in the journal .RS .RE +.SS Reporting options .PP -\f[B]Common reporting options:\f[] +Common reporting options, must be written after COMMAND. .TP .B \f[C]\-b\ \-\-begin=DATE\f[] include postings/txns on or after this date @@ -393,18 +395,91 @@ be "TAG:multi:level:account:name". show anonymized accounts and payees .RS .RE -.SS Multiple files .PP -You can specify multiple \f[C]\-f/\-\-file\ FILE\f[] options. -This is like combining all the files into one, except they can have -different formats. -Also directives and aliases in one file do not affect subsequent files -(if you need that, use the include directive instead). -.SS Repeated options -.PP -Otherwise, if a reporting option is repeated, the last one takes -precedence. +If a reporting option occurs more than once on the command line, the +last one takes precedence. Eg \-p jan \-p feb is equivalent to \-p feb. +.SS Input files +.PP +hledger reads transactions from a data file (and the add command writes +to it). +Usually this is in hledger\[aq]s journal format, but it can also be one +of the other supported file types, such as timeclock, timedot, CSV, or a +C++ Ledger journal (partial support). +.PP +By default this file is \f[C]$HOME/.hledger.journal\f[] (or on Windows, +something like \f[C]C:/Users/USER/.hledger.journal\f[]). +You can override this with the \f[C]$LEDGER_FILE\f[] environment +variable: +.IP +.nf +\f[C] +$\ setenv\ LEDGER_FILE\ ~/finance/2016.journal +$\ hledger\ stats +\f[] +.fi +.PP +or with the \f[C]\-f/\-\-file\f[] option: +.IP +.nf +\f[C] +$\ hledger\ \-f\ some/file.ext\ stats +\f[] +.fi +.PP +hledger tries to identify the file format based on the file extension, +as follows: +.PP +.TS +tab(@); +l l. +T{ +File extension: +T}@T{ +Use format: +T} +_ +T{ +\f[C]\&.journal\f[], \f[C]\&.j\f[], \f[C]\&.hledger\f[], +\f[C]\&.ledger\f[] +T}@T{ +journal +T} +T{ +\f[C]\&.timeclock\f[] +T}@T{ +timeclock +T} +T{ +\f[C]\&.timedot\f[] +T}@T{ +timedot +T} +T{ +\f[C]\&.csv\f[] +T}@T{ +CSV +T} +.TE +.PP +If the file name has some other extension, or none, hledger tries each +of these formats in turn. +(Plus one more: the experimental "ledger" format, an alternate parser +for C++ Ledger journals, which we try only as a last resort as it\[aq]s +new and hledger\[aq]s journal parser works better for now.) +.PP +The file name \f[C]\-\f[] (hyphen) means standard input, as usual: +.IP +.nf +\f[C] +$\ cat\ some.journal\ |\ hledger\ \-f\- +\f[] +.fi +.PP +You can specify multiple \f[C]\-f\f[] options, to read multiple files as +one big journal. +Directives in one file will not affect subsequent files in this case (if +you need that, use the include directive instead). .SS Depth limiting .PP With the \f[C]\-\-depth\ N\f[] option, commands like account, balance diff --git a/hledger/doc/hledger.1.info b/hledger/doc/hledger.1.info index 5e2eb5537..52d4a76e0 100644 --- a/hledger/doc/hledger.1.info +++ b/hledger/doc/hledger.1.info @@ -195,7 +195,24 @@ cur:\\\\$'. If you're really curious, add `--debug=2' for troubleshooting. - *General options:* +* Menu: + +* General options:: +* Reporting options:: +* Input files:: +* Depth limiting:: +* Smart dates:: +* Report intervals:: +* Period expressions:: +* Regular expressions:: + + +File: hledger.1.info, Node: General options, Next: Reporting options, Up: OPTIONS + +2.1 General options +=================== + +Always available, can be written before or after COMMAND. `-h' show general usage (or after COMMAND, the command's usage) @@ -228,7 +245,13 @@ cur:\\\\$'. `-I --ignore-assertions' ignore any failing balance assertions in the journal - *Common reporting options:* + +File: hledger.1.info, Node: Reporting options, Next: Input files, Prev: General options, Up: OPTIONS + +2.2 Reporting options +===================== + +Common reporting options, must be written after COMMAND. `-b --begin=DATE' include postings/txns on or after this date @@ -291,40 +314,62 @@ cur:\\\\$'. `--anon' show anonymized accounts and payees -* Menu: - -* Multiple files:: -* Repeated options:: -* Depth limiting:: -* Smart dates:: -* Report intervals:: -* Period expressions:: -* Regular expressions:: + If a reporting option occurs more than once on the command line, the +last one takes precedence. Eg -p jan -p feb is equivalent to -p feb.  -File: hledger.1.info, Node: Multiple files, Next: Repeated options, Up: OPTIONS +File: hledger.1.info, Node: Input files, Next: Depth limiting, Prev: Reporting options, Up: OPTIONS -2.1 Multiple files -================== +2.3 Input files +=============== -You can specify multiple `-f/--file FILE' options. This is like -combining all the files into one, except they can have different -formats. Also directives and aliases in one file do not affect -subsequent files (if you need that, use the include directive instead). +hledger reads transactions from a data file (and the add command writes +to it). Usually this is in hledger's journal format, but it can also be +one of the other supported file types, such as timeclock, timedot, CSV, +or a C++ Ledger journal (partial support). + + By default this file is `$HOME/.hledger.journal' (or on Windows, +something like `C:/Users/USER/.hledger.journal'). You can override this +with the `$LEDGER_FILE' environment variable: + + +$ setenv LEDGER_FILE ~/finance/2016.journal +$ hledger stats + + or with the `-f/--file' option: + + +$ hledger -f some/file.ext stats + + hledger tries to identify the file format based on the file +extension, as follows: + +File extension: Use format: +-------------------------------------------------------- +`.journal', `.j', `.hledger', `.ledger' journal +`.timeclock' timeclock +`.timedot' timedot +`.csv' CSV + + If the file name has some other extension, or none, hledger tries +each of these formats in turn. (Plus one more: the experimental "ledger" +format, an alternate parser for C++ Ledger journals, which we try only +as a last resort as it's new and hledger's journal parser works better +for now.) + + The file name `-' (hyphen) means standard input, as usual: + + +$ cat some.journal | hledger -f- + + You can specify multiple `-f' options, to read multiple files as one +big journal. Directives in one file will not affect subsequent files in +this case (if you need that, use the include directive instead).  -File: hledger.1.info, Node: Repeated options, Next: Depth limiting, Prev: Multiple files, Up: OPTIONS +File: hledger.1.info, Node: Depth limiting, Next: Smart dates, Prev: Input files, Up: OPTIONS -2.2 Repeated options -==================== - -Otherwise, if a reporting option is repeated, the last one takes -precedence. Eg -p jan -p feb is equivalent to -p feb. - - -File: hledger.1.info, Node: Depth limiting, Next: Smart dates, Prev: Repeated options, Up: OPTIONS - -2.3 Depth limiting +2.4 Depth limiting ================== With the `--depth N' option, commands like account, balance and @@ -334,7 +379,7 @@ to level N. Use this when you want a summary with less detail.  File: hledger.1.info, Node: Smart dates, Next: Report intervals, Prev: Depth limiting, Up: OPTIONS -2.4 Smart dates +2.5 Smart dates =============== hledger's user interfaces accept a flexible "smart date" syntax (unlike @@ -357,7 +402,7 @@ omitted (defaulting to 1).  File: hledger.1.info, Node: Report intervals, Next: Period expressions, Prev: Smart dates, Up: OPTIONS -2.5 Report intervals +2.6 Report intervals ==================== A report interval can be specified so that commands like register, @@ -369,7 +414,7 @@ complex intervals may be specified with a period expression.  File: hledger.1.info, Node: Period expressions, Next: Regular expressions, Prev: Report intervals, Up: OPTIONS -2.6 Period expressions +2.7 Period expressions ====================== The `-p/--period' option accepts period expressions, a shorthand way of @@ -444,7 +489,7 @@ start date and exclusive end date):  File: hledger.1.info, Node: Regular expressions, Prev: Period expressions, Up: OPTIONS -2.7 Regular expressions +2.8 Regular expressions ======================= hledger uses regular expressions in a number of places: @@ -2114,95 +2159,97 @@ Node: EXAMPLES1873 Ref: #examples1975 Node: OPTIONS3979 Ref: #options4083 -Node: Multiple files9008 -Ref: #multiple-files9133 -Node: Repeated options9398 -Ref: #repeated-options9550 -Node: Depth limiting9670 -Ref: #depth-limiting9815 -Node: Smart dates10016 -Ref: #smart-dates10155 -Node: Report intervals11152 -Ref: #report-intervals11305 -Node: Period expressions11641 -Ref: #period-expressions11806 -Node: Regular expressions14141 -Ref: #regular-expressions14283 -Node: QUERIES15766 -Ref: #queries15870 -Node: COMMANDS19509 -Ref: #commands19623 -Node: accounts20296 -Ref: #accounts20396 -Node: activity21378 -Ref: #activity21490 -Node: add21849 -Ref: #add21950 -Node: balance24609 -Ref: #balance24722 -Node: Flat mode27695 -Ref: #flat-mode27822 -Node: Depth limited balance reports28241 -Ref: #depth-limited-balance-reports28444 -Node: Multicolumn balance reports28865 -Ref: #multicolumn-balance-reports29067 -Node: Market value33716 -Ref: #market-value33880 -Node: Custom balance output34373 -Ref: #custom-balance-output34546 -Node: Output destination36650 -Ref: #output-destination36815 -Node: CSV output37085 -Ref: #csv-output37204 -Node: balancesheet37601 -Ref: #balancesheet37729 -Node: cashflow38381 -Ref: #cashflow38498 -Node: help39188 -Ref: #help39300 -Node: incomestatement40137 -Ref: #incomestatement40267 -Node: info40994 -Ref: #info41101 -Node: man41463 -Ref: #man41560 -Node: print41963 -Ref: #print42068 -Node: register43414 -Ref: #register43527 -Node: Custom register output48019 -Ref: #custom-register-output48150 -Node: stats49447 -Ref: #stats49553 -Node: test50429 -Ref: #test50516 -Node: ADD-ON COMMANDS50883 -Ref: #add-on-commands51019 -Node: api52307 -Ref: #api52399 -Node: autosync52433 -Ref: #autosync52548 -Node: diff54863 -Ref: #diff54973 -Node: equity55637 -Ref: #equity55751 -Node: interest57079 -Ref: #interest57196 -Node: irr60280 -Ref: #irr60393 -Node: print-unique62768 -Ref: #print-unique62898 -Node: rewrite63156 -Ref: #rewrite63275 -Node: ui63804 -Ref: #ui63904 -Node: web63945 -Ref: #web64033 -Node: TROUBLESHOOTING64066 -Ref: #troubleshooting64185 -Node: Run-time problems64239 -Ref: #run-time-problems64382 -Node: Known limitations66326 -Ref: #known-limitations66469 +Node: General options6683 +Ref: #general-options6812 +Node: Reporting options7583 +Ref: #reporting-options7736 +Node: Input files9512 +Ref: #input-files9652 +Node: Depth limiting11233 +Ref: #depth-limiting11373 +Node: Smart dates11574 +Ref: #smart-dates11713 +Node: Report intervals12710 +Ref: #report-intervals12863 +Node: Period expressions13199 +Ref: #period-expressions13364 +Node: Regular expressions15699 +Ref: #regular-expressions15841 +Node: QUERIES17324 +Ref: #queries17428 +Node: COMMANDS21067 +Ref: #commands21181 +Node: accounts21854 +Ref: #accounts21954 +Node: activity22936 +Ref: #activity23048 +Node: add23407 +Ref: #add23508 +Node: balance26167 +Ref: #balance26280 +Node: Flat mode29253 +Ref: #flat-mode29380 +Node: Depth limited balance reports29799 +Ref: #depth-limited-balance-reports30002 +Node: Multicolumn balance reports30423 +Ref: #multicolumn-balance-reports30625 +Node: Market value35274 +Ref: #market-value35438 +Node: Custom balance output35931 +Ref: #custom-balance-output36104 +Node: Output destination38208 +Ref: #output-destination38373 +Node: CSV output38643 +Ref: #csv-output38762 +Node: balancesheet39159 +Ref: #balancesheet39287 +Node: cashflow39939 +Ref: #cashflow40056 +Node: help40746 +Ref: #help40858 +Node: incomestatement41695 +Ref: #incomestatement41825 +Node: info42552 +Ref: #info42659 +Node: man43021 +Ref: #man43118 +Node: print43521 +Ref: #print43626 +Node: register44972 +Ref: #register45085 +Node: Custom register output49577 +Ref: #custom-register-output49708 +Node: stats51005 +Ref: #stats51111 +Node: test51987 +Ref: #test52074 +Node: ADD-ON COMMANDS52441 +Ref: #add-on-commands52577 +Node: api53865 +Ref: #api53957 +Node: autosync53991 +Ref: #autosync54106 +Node: diff56421 +Ref: #diff56531 +Node: equity57195 +Ref: #equity57309 +Node: interest58637 +Ref: #interest58754 +Node: irr61838 +Ref: #irr61951 +Node: print-unique64326 +Ref: #print-unique64456 +Node: rewrite64714 +Ref: #rewrite64833 +Node: ui65362 +Ref: #ui65462 +Node: web65503 +Ref: #web65591 +Node: TROUBLESHOOTING65624 +Ref: #troubleshooting65743 +Node: Run-time problems65797 +Ref: #run-time-problems65940 +Node: Known limitations67884 +Ref: #known-limitations68027  End Tag Table diff --git a/hledger/doc/hledger.1.txt b/hledger/doc/hledger.1.txt index bcbabab9d..8a5370a5f 100644 --- a/hledger/doc/hledger.1.txt +++ b/hledger/doc/hledger.1.txt @@ -177,7 +177,8 @@ OPTIONS If you're really curious, add --debug=2 for troubleshooting. - General options: + General options + Always available, can be written before or after COMMAND. -h show general usage (or after COMMAND, the command's usage) @@ -207,7 +208,8 @@ OPTIONS -I --ignore-assertions ignore any failing balance assertions in the journal - Common reporting options: + Reporting options + Common reporting options, must be written after COMMAND. -b --begin=DATE include postings/txns on or after this date @@ -269,15 +271,51 @@ OPTIONS --anon show anonymized accounts and payees - Multiple files - You can specify multiple -f/--file FILE options. This is like combin- - ing all the files into one, except they can have different formats. - Also directives and aliases in one file do not affect subsequent files - (if you need that, use the include directive instead). + If a reporting option occurs more than once on the command line, the + last one takes precedence. Eg -p jan -p feb is equivalent to -p feb. - Repeated options - Otherwise, if a reporting option is repeated, the last one takes prece- - dence. Eg -p jan -p feb is equivalent to -p feb. + Input files + hledger reads transactions from a data file (and the add command writes + to it). Usually this is in hledger's journal format, but it can also + be one of the other supported file types, such as timeclock, timedot, + CSV, or a C++ Ledger journal (partial support). + + By default this file is $HOME/.hledger.journal (or on Windows, some- + thing like C:/Users/USER/.hledger.journal). You can override this with + the $LEDGER_FILE environment variable: + + $ setenv LEDGER_FILE ~/finance/2016.journal + $ hledger stats + + or with the -f/--file option: + + $ hledger -f some/file.ext stats + + hledger tries to identify the file format based on the file extension, + as follows: + + + File extension: Use format: + ----------------------------------------- + .journal, .j, .hledger, journal + .ledger + .timeclock timeclock + .timedot timedot + .csv CSV + + If the file name has some other extension, or none, hledger tries each + of these formats in turn. (Plus one more: the experimental "ledger" + format, an alternate parser for C++ Ledger journals, which we try only + as a last resort as it's new and hledger's journal parser works better + for now.) + + The file name - (hyphen) means standard input, as usual: + + $ cat some.journal | hledger -f- + + You can specify multiple -f options, to read multiple files as one big + journal. Directives in one file will not affect subsequent files in + this case (if you need that, use the include directive instead). Depth limiting With the --depth N option, commands like account, balance and register @@ -293,6 +331,7 @@ OPTIONS Examples: + 2009/1/1, 2009/01/01, simple dates, several sep- 2009-1-1, 2009.1.1 arators allowed 2009/1, 2009 same as above - a missing @@ -358,6 +397,8 @@ OPTIONS date like so: + + -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" -p "2009/1" the month of jan; equiva- diff --git a/hledger/doc/options.m4.md b/hledger/doc/options.m4.md index 2525952ce..f7d4490b1 100644 --- a/hledger/doc/options.m4.md +++ b/hledger/doc/options.m4.md @@ -56,26 +56,68 @@ If in doubt, keep things simple: If you're really curious, add `--debug=2` for troubleshooting. -**General options:** +## General options + +Always available, can be written before or after COMMAND. _generaloptions_ -**Common reporting options:** +## Reporting options + +Common reporting options, must be written after COMMAND. _reportingoptions_ -## Multiple files +If a reporting option occurs more than once on the command line, +the last one takes precedence. +Eg -p jan -p feb is equivalent to -p feb. -You can specify multiple `-f/--file FILE` options. This is like -combining all the files into one, except they can have different formats. -Also directives and aliases in one file do not affect subsequent files -(if you need that, use the [include directive](#including-other-files) -instead). +## Input files -## Repeated options +hledger reads transactions from a data file (and the add command writes to it). +Usually this is in hledger's journal format, +but it can also be one of the other supported file types, such as +timeclock, +timedot, +CSV, +or a C++ Ledger journal (partial support). -Otherwise, if a reporting option is repeated, the last one takes precedence. Eg -p jan -p -feb is equivalent to -p feb. +By default this file is `$HOME/.hledger.journal` +(or on Windows, something like `C:/Users/USER/.hledger.journal`). +You can override this with the `$LEDGER_FILE` environment variable: +```bash +$ setenv LEDGER_FILE ~/finance/2016.journal +$ hledger stats +``` +or with the `-f/--file` option: +```bash +$ hledger -f some/file.ext stats +``` + +hledger tries to identify the file format based on the file extension, +as follows: + +| File extension: | Use format: +|-------------------------------------------|---------------- +| `.journal`, `.j`, `.hledger`, `.ledger` | journal +| `.timeclock` | timeclock +| `.timedot` | timedot +| `.csv` | CSV + +If the file name has some other extension, or none, +hledger tries each of these formats in turn. +(Plus one more: the experimental "ledger" format, an alternate + parser for C++ Ledger journals, which we try only as a last resort + as it's new and hledger's journal parser works better for now.) + +The file name `-` (hyphen) means standard input, as usual: +```bash +$ cat some.journal | hledger -f- +``` + +You can specify multiple `-f` options, to read multiple files as one big journal. +Directives in one file will not affect subsequent files in this case (if you need that, +use the [include directive](#including-other-files) instead). ## Depth limiting