diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index 157abeb49..45f6b889e 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -88,8 +88,9 @@ ignored. .PP \f[C]skip\f[R]\f[I]\f[CI]N\f[I]\f[R] .PP -Skip this number of CSV records at the beginning. -You\[aq]ll need this whenever your CSV data contains header lines. +Skip this many non-empty lines preceding the CSV data. +(Empty/blank lines are skipped automatically.) You\[aq]ll need this +whenever your CSV data contains header lines. Eg: .IP .nf diff --git a/hledger-lib/hledger_csv.info b/hledger-lib/hledger_csv.info index 03db26f67..8e288f965 100644 --- a/hledger-lib/hledger_csv.info +++ b/hledger-lib/hledger_csv.info @@ -96,8 +96,9 @@ File: hledger_csv.info, Node: skip, Next: date-format, Up: CSV RULES 'skip'_'N'_ - Skip this number of CSV records at the beginning. You'll need this -whenever your CSV data contains header lines. Eg: + Skip this many non-empty lines preceding the CSV data. (Empty/blank +lines are skipped automatically.) You'll need this whenever your CSV +data contains header lines. Eg: # ignore the first CSV line skip 1 @@ -354,31 +355,31 @@ Node: CSV RULES2167 Ref: #csv-rules2275 Node: skip2538 Ref: #skip2632 -Node: date-format2804 -Ref: #date-format2931 -Node: field list3481 -Ref: #field-list3618 -Node: field assignment4348 -Ref: #field-assignment4503 -Node: conditional block5127 -Ref: #conditional-block5281 -Node: include6177 -Ref: #include6307 -Node: newest-first6538 -Ref: #newest-first6652 -Node: CSV TIPS7063 -Ref: #csv-tips7157 -Node: CSV ordering7301 -Ref: #csv-ordering7419 -Node: CSV accounts7600 -Ref: #csv-accounts7738 -Node: CSV amounts7992 -Ref: #csv-amounts8150 -Node: CSV balance assertions/assignments9230 -Ref: #csv-balance-assertionsassignments9448 -Node: Reading multiple CSV files9769 -Ref: #reading-multiple-csv-files9969 -Node: Valid CSV10243 -Ref: #valid-csv10366 +Node: date-format2857 +Ref: #date-format2984 +Node: field list3534 +Ref: #field-list3671 +Node: field assignment4401 +Ref: #field-assignment4556 +Node: conditional block5180 +Ref: #conditional-block5334 +Node: include6230 +Ref: #include6360 +Node: newest-first6591 +Ref: #newest-first6705 +Node: CSV TIPS7116 +Ref: #csv-tips7210 +Node: CSV ordering7354 +Ref: #csv-ordering7472 +Node: CSV accounts7653 +Ref: #csv-accounts7791 +Node: CSV amounts8045 +Ref: #csv-amounts8203 +Node: CSV balance assertions/assignments9283 +Ref: #csv-balance-assertionsassignments9501 +Node: Reading multiple CSV files9822 +Ref: #reading-multiple-csv-files10022 +Node: Valid CSV10296 +Ref: #valid-csv10419  End Tag Table diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index 680a444ee..d2d1e594a 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -74,8 +74,9 @@ CSV RULES skip skipN - Skip this number of CSV records at the beginning. You'll need this - whenever your CSV data contains header lines. Eg: + Skip this many non-empty lines preceding the CSV data. (Empty/blank + lines are skipped automatically.) You'll need this whenever your CSV + data contains header lines. Eg: # ignore the first CSV line skip 1 @@ -83,9 +84,9 @@ CSV RULES date-format date-formatDATEFMT - When your CSV date fields are not formatted like YYYY/MM/DD (or YYYY- - MM-DD or YYYY.MM.DD), you'll need to specify the format. DATEFMT is a - strptime-like date parsing pattern, which must parse the date field + When your CSV date fields are not formatted like YYYY/MM/DD (or YYYY- + MM-DD or YYYY.MM.DD), you'll need to specify the format. DATEFMT is a + strptime-like date parsing pattern, which must parse the date field values completely. Examples: # for dates like "11/06/2013": @@ -103,11 +104,11 @@ CSV RULES field list fieldsFIELDNAME1, FIELDNAME2... - This (a) names the CSV fields, in order (names may not contain white- - space; uninteresting names may be left blank), and (b) assigns them to - journal entry fields if you use any of these standard field names: - date, date2, status, code, description, comment, account1, account2, - amount, amount-in, amount-out, currency, balance, balance1, balance2. + This (a) names the CSV fields, in order (names may not contain white- + space; uninteresting names may be left blank), and (b) assigns them to + journal entry fields if you use any of these standard field names: + date, date2, status, code, description, comment, account1, account2, + amount, amount-in, amount-out, currency, balance, balance1, balance2. Eg: # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, @@ -121,8 +122,8 @@ CSV RULES field assignment ENTRYFIELDNAME FIELDVALUE - This sets a journal entry field (one of the standard names above) to - the given text value, which can include CSV field values interpolated + This sets a journal entry field (one of the standard names above) to + the given text value, which can include CSV field values interpolated by name (%CSVFIELDNAME) or 1-based position (%N). Eg: # set the amount to the 4th CSV field with "USD " prepended @@ -131,10 +132,10 @@ CSV RULES # combine three fields to make a comment (containing two tags) comment note: %somefield - %anotherfield, date: %1 - Field assignments can be used instead of or in addition to a field + Field assignments can be used instead of or in addition to a field list. - Note, interpolation strips any outer whitespace, so a CSV value like " + Note, interpolation strips any outer whitespace, so a CSV value like " 1 " becomes 1 when interpolated (#1051). conditional block @@ -146,12 +147,12 @@ CSV RULES PATTERN... FIELDASSIGNMENTS... - This applies one or more field assignments, only to those CSV records + This applies one or more field assignments, only to those CSV records matched by one of the PATTERNs. The patterns are case-insensitive reg- ular expressions which match anywhere within the whole CSV record (it's - not yet possible to match within a specific field). When there are - multiple patterns they can be written on separate lines, unindented. - The field assignments are on separate lines indented by at least one + not yet possible to match within a specific field). When there are + multiple patterns they can be written on separate lines, unindented. + The field assignments are on separate lines indented by at least one space. Examples: # if the CSV record contains "groceries", set account2 to "expenses:groceries" @@ -178,33 +179,33 @@ CSV RULES newest-first newest-first - Consider adding this rule if all of the following are true: you might - be processing just one day of data, your CSV records are in reverse - chronological order (newest first), and you care about preserving the - order of same-day transactions. It usually isn't needed, because - hledger autodetects the CSV order, but when all CSV records have the + Consider adding this rule if all of the following are true: you might + be processing just one day of data, your CSV records are in reverse + chronological order (newest first), and you care about preserving the + order of same-day transactions. It usually isn't needed, because + hledger autodetects the CSV order, but when all CSV records have the same date it will assume they are oldest first. CSV TIPS CSV ordering - The generated journal entries will be sorted by date. The order of - same-day entries will be preserved (except in the special case where + The generated journal entries will be sorted by date. The order of + same-day entries will be preserved (except in the special case where you might need newest-first, see above). CSV accounts Each journal entry will have two postings, to account1 and account2 re- - spectively. It's not yet possible to generate entries with more than - two postings. It's conventional and recommended to use account1 for + spectively. It's not yet possible to generate entries with more than + two postings. It's conventional and recommended to use account1 for the account whose CSV we are reading. CSV amounts A transaction amount must be set, in one of these ways: - o with an amount field assignment, which sets the first posting's + o with an amount field assignment, which sets the first posting's amount o (When the CSV has debit and credit amounts in separate fields:) - with field assignments for the amount-in and amount-out pseudo fields + with field assignments for the amount-in and amount-out pseudo fields (both of them). Whichever one has a value will be used, with appropri- ate sign. If both contain a value, it might not work so well. @@ -212,30 +213,30 @@ CSV TIPS There is some special handling for sign in amounts: - 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 will cancel out and be removed. - If the currency/commodity symbol is provided as a separate CSV field, + If the currency/commodity symbol is provided as a separate CSV field, assign it to the currency pseudo field; the symbol will be prepended to - the amount (TODO: when there is an amount). Or, you can use an amount + the amount (TODO: when there is an amount). Or, you can use an amount field assignment for more control, eg: fields date,description,currency,amount amount %amount %currency CSV balance assertions/assignments - If the CSV includes a running balance, you can assign that to one of - the pseudo fields balance (or balance1) or balance2. This will gener- - ate a balance assertion (or if the amount is left empty, a balance as- + If the CSV includes a running balance, you can assign that to one of + the pseudo fields balance (or balance1) or balance2. This will gener- + ate a balance assertion (or if the amount is left empty, a balance as- signment), on the first or second posting, whenever the running balance field is non-empty. (TODO: #1000) Reading multiple CSV files - You can read multiple CSV files at once using multiple -f arguments on - the command line, and hledger will look for a correspondingly-named + You can read multiple CSV files at once using multiple -f arguments on + the command line, and hledger will look for a correspondingly-named rules file for each. Note if you use the --rules-file option, this one rules file will be used for all the CSV files being read. @@ -254,7 +255,7 @@ CSV TIPS 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) @@ -268,7 +269,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) diff --git a/hledger/Hledger/Cli/Commands/Prices.txt b/hledger/Hledger/Cli/Commands/Prices.txt index 46c17358e..0e4227e38 100644 --- a/hledger/Hledger/Cli/Commands/Prices.txt +++ b/hledger/Hledger/Cli/Commands/Prices.txt @@ -2,6 +2,7 @@ prices Print market price directives from the journal. With --costs, also print synthetic market prices based on transaction prices. With --inverted-costs, also print inverse prices based on transaction prices. -Prices (and postings providing prices) can be filtered by a query. +Prices (and postings providing prices) can be filtered by a query. Price +amounts are always displayed with their full precision. _FLAGS_ diff --git a/hledger/hledger.1 b/hledger/hledger.1 index f989ce19a..8a467115b 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -2988,6 +2988,7 @@ prices. With --inverted-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. .SS print .PP print, txns, p diff --git a/hledger/hledger.info b/hledger/hledger.info index 1624039dc..4561d5b3b 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -2477,6 +2477,7 @@ Print market price directives from the journal. With -costs, also print synthetic market prices based on transaction prices. With -inverted-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.  File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS @@ -3272,56 +3273,56 @@ Node: payees85096 Ref: #payees85202 Node: prices85360 Ref: #prices85466 -Node: print85745 -Ref: #print85855 -Node: print-unique90348 -Ref: #print-unique90474 -Node: register90759 -Ref: #register90886 -Node: Custom register output95058 -Ref: #custom-register-output95187 -Node: register-match96449 -Ref: #register-match96583 -Node: rewrite96934 -Ref: #rewrite97049 -Node: Re-write rules in a file98904 -Ref: #re-write-rules-in-a-file99038 -Node: Diff output format100248 -Ref: #diff-output-format100417 -Node: rewrite vs print --auto101509 -Ref: #rewrite-vs.-print---auto101688 -Node: roi102244 -Ref: #roi102342 -Node: stats103354 -Ref: #stats103453 -Node: tags104241 -Ref: #tags104339 -Node: test104633 -Ref: #test104717 -Node: ADD-ON COMMANDS105478 -Ref: #add-on-commands105588 -Node: Official add-ons106876 -Ref: #official-add-ons107016 -Node: ui107096 -Ref: #ui107183 -Node: web107237 -Ref: #web107326 -Node: Third party add-ons107372 -Ref: #third-party-add-ons107547 -Ref: #diff-1107706 -Node: iadd107805 -Ref: #iadd107915 -Node: interest107997 -Ref: #interest108118 -Node: irr108213 -Ref: #irr108311 -Node: Experimental add-ons108442 -Ref: #experimental-add-ons108594 -Node: autosync108842 -Ref: #autosync108953 -Node: chart109192 -Ref: #chart109311 -Node: check109382 -Ref: #check109484 +Node: print85807 +Ref: #print85917 +Node: print-unique90410 +Ref: #print-unique90536 +Node: register90821 +Ref: #register90948 +Node: Custom register output95120 +Ref: #custom-register-output95249 +Node: register-match96511 +Ref: #register-match96645 +Node: rewrite96996 +Ref: #rewrite97111 +Node: Re-write rules in a file98966 +Ref: #re-write-rules-in-a-file99100 +Node: Diff output format100310 +Ref: #diff-output-format100479 +Node: rewrite vs print --auto101571 +Ref: #rewrite-vs.-print---auto101750 +Node: roi102306 +Ref: #roi102404 +Node: stats103416 +Ref: #stats103515 +Node: tags104303 +Ref: #tags104401 +Node: test104695 +Ref: #test104779 +Node: ADD-ON COMMANDS105540 +Ref: #add-on-commands105650 +Node: Official add-ons106938 +Ref: #official-add-ons107078 +Node: ui107158 +Ref: #ui107245 +Node: web107299 +Ref: #web107388 +Node: Third party add-ons107434 +Ref: #third-party-add-ons107609 +Ref: #diff-1107768 +Node: iadd107867 +Ref: #iadd107977 +Node: interest108059 +Ref: #interest108180 +Node: irr108275 +Ref: #irr108373 +Node: Experimental add-ons108504 +Ref: #experimental-add-ons108656 +Node: autosync108904 +Ref: #autosync109015 +Node: chart109254 +Ref: #chart109373 +Node: check109444 +Ref: #check109546  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index f8906f8f1..3174c9396 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -2160,18 +2160,19 @@ COMMANDS 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. + Prices (and postings providing prices) can be filtered by a query. + Price amounts are always displayed with their full precision. print print, txns, p 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 @@ -2197,39 +2198,39 @@ COMMANDS assets:bank:checking $-1 Normally, the journal entry's explicit or implicit amount style is pre- - served. Ie when an amount is omitted in the journal, it will be omit- - ted in the output. You can use the -x/--explicit flag to make all + served. Ie when an amount is omitted in the journal, it will be omit- + ted in the output. You can use the -x/--explicit flag to make all amounts explicit, which can be useful for troubleshooting or for making your journal more readable and robust against data entry errors. Note, - -x will cause postings with a multi-commodity amount (these can arise - when a multi-commodity transaction has an implicit amount) will be - split into multiple single-commodity postings, for valid journal out- + -x will cause postings with a multi-commodity amount (these can arise + when a multi-commodity transaction has an implicit amount) will be + split into multiple single-commodity postings, for valid journal out- put. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost using that price. This can be used for troubleshooting. - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is no similar-enough match, no transaction will be shown. With --new, for each FILE being read, hledger reads (and writes) a spe- - cial state file (.latest.FILE in the same directory), containing the - latest transaction date(s) that were seen last time FILE was read. - When this file is found, only transactions with newer dates (and new - transactions on the latest date) are printed. This is useful for ig- - noring already-seen entries in import data, such as downloaded CSV + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for ig- + noring already-seen entries in import data, such as downloaded CSV files. Eg: $ hledger -f bank1.csv print --new # shows transactions added since last print --new on this file - This assumes that transactions added to FILE always have same or in- - creasing dates, and that transactions on the same day do not get re- + This assumes that transactions added to FILE always have same or in- + creasing dates, and that transactions on the same day do not get re- ordered. See also the import command. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -2246,20 +2247,20 @@ COMMANDS "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) print-unique @@ -2283,7 +2284,7 @@ COMMANDS Show postings and their running total. The register command displays postings in date order, one per line, and - their running total. This is typically used with a query selecting a + their running total. This is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -2294,8 +2295,8 @@ COMMANDS With --date2, it shows and sorts by secondary date instead. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -2305,18 +2306,18 @@ COMMANDS The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one ac- + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- count and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account to- + bers. It's also useful to show postings on the checking account to- gether with the related account: $ hledger register --related --invert assets:checking @@ -2328,7 +2329,7 @@ COMMANDS 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -2345,7 +2346,7 @@ COMMANDS 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth op- + Often, you'll want to see just one line per interval. The --depth op- tion helps with this, causing subaccounts to be aggregated: $ hledger register --monthly assets --depth 1h @@ -2353,17 +2354,17 @@ COMMANDS 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of in- - tervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of in- + tervals. This ensures that the first and last intervals are full length and comparable to the others in the report. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not a bash shell variable) or by using the --width/-w option. - The description and account columns normally share the space equally + The description and account columns normally share the space equally (about half of (width - 40) each). You can adjust this by adding a de- scription width as part of --width's argument, comma-separated: --width W,D . Here's a diagram (won't display correctly in --help): @@ -2381,27 +2382,27 @@ COMMANDS $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. register-match register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. If there are multiple equally - good matches, it shows the most recent. Query options (options, not - arguments) can be used to restrict the search space. Helps ledger-au- + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps ledger-au- tosync detect already-seen transactions when importing. rewrite rewrite Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print + For now the only rewrite available is adding new postings, like print --auto. This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds + the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- + posting amounts can be fixed, or a multiplier of the existing transac- tion's first posting amount. Examples: @@ -2417,7 +2418,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: @@ -2427,16 +2428,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. @@ -2451,7 +2452,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. @@ -2464,12 +2465,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' @@ -2493,10 +2494,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: @@ -2504,48 +2505,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: @@ -2563,14 +2564,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. @@ -2578,46 +2579,46 @@ COMMANDS test Run built-in unit tests. - This command runs the unit tests built in to hledger-lib and hledger, + This command runs the unit tests built in to hledger-lib and hledger, printing test names and results on stdout. If any test fails, the exit code will be non-zero. - Test names include a group prefix. If a (exact, case sensitive) group - prefix, or a full test name is provided as the first argument, only + Test names include a group prefix. If a (exact, case sensitive) group + prefix, or a full test name is provided as the first argument, only that group or test is run. - If a numeric second argument is provided, it will set the randomness - seed, for repeatable results from tests using randomness (currently + If a numeric second argument is provided, it will set the randomness + seed, for repeatable results from tests using randomness (currently none of them). - This is mainly used by developers, but it's nice to be able to sanity- + This is mainly used by developers, but it's nice to be able to sanity- check your installed hledger executable at any time. All tests are ex- - pected to pass - if you ever see otherwise, something has gone wrong, + pected to pass - if you ever see otherwise, something has gone wrong, please report a bug! 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. Here are some hledger add-ons available: @@ -2632,7 +2633,7 @@ ADD-ON COMMANDS hledger-web provides a simple web interface. Third party add-ons - These are maintained separately, and usually updated shortly after a + These are maintained separately, and usually updated shortly after a hledger release. diff @@ -2652,14 +2653,14 @@ ADD-ON COMMANDS count, but it's superseded now by the built-in roi command. Experimental add-ons - These are available in source form in the hledger repo's bin/ direc- - tory. They may be less mature and documented than built-in commands. + These are available in source form in the hledger repo's bin/ direc- + tory. They may be less mature and documented than built-in commands. Reading and tweaking these is a good way to start making your own! autosync hledger-autosync is a symbolic link for easily running ledger-autosync, - if installed. ledger-autosync does deduplicating conversion of OFX - data and some CSV formats, and can also download the data if your bank + if installed. ledger-autosync does deduplicating conversion of OFX + data and some CSV formats, and can also download the data if your bank offers OFX Direct Connect. chart @@ -2669,21 +2670,21 @@ ADD-ON COMMANDS hledger-check.hs checks more powerful account balance assertions. 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). 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 @@ -2699,33 +2700,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 @@ -2744,7 +2745,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 @@ -2765,7 +2766,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) @@ -2779,7 +2780,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)