From 2ac77338f84be2b75157b9941d2230f598289212 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 19 Apr 2017 08:58:51 -0700 Subject: [PATCH] doc: csv tweaks --- hledger-lib/doc/hledger_csv.5 | 11 ++-- hledger-lib/doc/hledger_csv.5.info | 52 ++++++++++--------- hledger-lib/doc/hledger_csv.5.m4.md | 10 ++-- hledger-lib/doc/hledger_csv.5.txt | 21 +++++--- hledger-lib/doc/hledger_journal.5 | 3 +- hledger-lib/doc/hledger_journal.5.info | 43 ++++++++-------- hledger-lib/doc/hledger_journal.5.txt | 69 +++++++++++++------------- site/csv-import.md | 2 + 8 files changed, 115 insertions(+), 96 deletions(-) diff --git a/hledger-lib/doc/hledger_csv.5 b/hledger-lib/doc/hledger_csv.5 index 4cfeb43e9..4b0dac17e 100644 --- a/hledger-lib/doc/hledger_csv.5 +++ b/hledger-lib/doc/hledger_csv.5 @@ -18,7 +18,7 @@ hledger will create it if necessary, with some default rules which you\[aq]ll need to adjust. At minimum, the rules file must specify the \f[C]date\f[] and \f[C]amount\f[] fields. -For an example, see How to read CSV files. +For an example, see Cookbook: convert CSV files. .PP To learn about \f[I]exporting\f[] CSV, see CSV output. .SH CSV RULES @@ -90,7 +90,7 @@ to journal entry fields if you use any of these standard field names: \f[C]date\f[], \f[C]date2\f[], \f[C]status\f[], \f[C]code\f[], \f[C]description\f[], \f[C]comment\f[], \f[C]account1\f[], \f[C]account2\f[], \f[C]amount\f[], \f[C]amount\-in\f[], -\f[C]amount\-out\f[], \f[C]currency\f[]. +\f[C]amount\-out\f[], \f[C]currency\f[], \f[C]balance\f[]. Eg: .IP .nf @@ -195,7 +195,7 @@ Eg: include\ common.rules \f[] .fi -.SH TIPS +.SH CSV TIPS .PP Each generated journal entry will have two postings, to \f[C]account1\f[] and \f[C]account2\f[] respectively. @@ -211,6 +211,11 @@ If the CSV has the currency in a separate field, assign that to the the amount. (Or you can do the same thing with a field assignment.) .PP +If the CSV includes a running balance, you can assign that to the +\f[C]balance\f[] pseudo field to generate a balance assertion on +\f[C]account1\f[] whenever the balance field is non\-empty. +(Eg to double\-check your bank\[aq]s balance calculation.) +.PP If an amount value is parenthesised, it will be de\-parenthesised and sign\-flipped automatically. .PP diff --git a/hledger-lib/doc/hledger_csv.5.info b/hledger-lib/doc/hledger_csv.5.info index d6743bf10..f0ac01403 100644 --- a/hledger-lib/doc/hledger_csv.5.info +++ b/hledger-lib/doc/hledger_csv.5.info @@ -13,16 +13,16 @@ file". This file should be named like the CSV file with an additional with '--rules-file PATH'. hledger will create it if necessary, with some default rules which you'll need to adjust. At minimum, the rules file must specify the 'date' and 'amount' fields. For an example, see -How to read CSV files. +Cookbook: convert CSV files. To learn about _exporting_ CSV, see CSV output. * Menu: * CSV RULES:: -* TIPS:: +* CSV TIPS::  -File: hledger_csv.5.info, Node: CSV RULES, Next: TIPS, Prev: Top, Up: Top +File: hledger_csv.5.info, Node: CSV RULES, Next: CSV TIPS, Prev: Top, Up: Top 1 CSV RULES *********** @@ -89,7 +89,8 @@ File: hledger_csv.5.info, Node: field list, Next: field assignment, Prev: dat whitespace; 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'. Eg: +'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance'. +Eg: # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, # and give the 7th and 8th fields meaningful names for later reference: @@ -170,10 +171,10 @@ Eg: include common.rules  -File: hledger_csv.5.info, Node: TIPS, Prev: CSV RULES, Up: Top +File: hledger_csv.5.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top -2 TIPS -****** +2 CSV TIPS +********** Each generated journal entry will have two postings, to 'account1' and 'account2' respectively. Currently it's not possible to generate @@ -186,6 +187,11 @@ entries with more than two postings. 'currency' pseudo field which will be automatically prepended to the amount. (Or you can do the same thing with a field assignment.) + If the CSV includes a running balance, you can assign that to the +'balance' pseudo field to generate a balance assertion on 'account1' +whenever the balance field is non-empty. (Eg to double-check your +bank's balance calculation.) + If an amount value is parenthesised, it will be de-parenthesised and sign-flipped automatically. @@ -195,21 +201,21 @@ order of same-day entries will be preserved, usually.  Tag Table: Node: Top74 -Node: CSV RULES800 -Ref: #csv-rules906 -Node: skip1149 -Ref: #skip1245 -Node: date-format1417 -Ref: #date-format1546 -Node: field list2052 -Ref: #field-list2191 -Node: field assignment2886 -Ref: #field-assignment3043 -Node: conditional block3547 -Ref: #conditional-block3703 -Node: include4599 -Ref: #include4710 -Node: TIPS4941 -Ref: #tips5025 +Node: CSV RULES810 +Ref: #csv-rules920 +Node: skip1163 +Ref: #skip1259 +Node: date-format1431 +Ref: #date-format1560 +Node: field list2066 +Ref: #field-list2205 +Node: field assignment2910 +Ref: #field-assignment3067 +Node: conditional block3571 +Ref: #conditional-block3727 +Node: include4623 +Ref: #include4734 +Node: CSV TIPS4965 +Ref: #csv-tips5061  End Tag Table diff --git a/hledger-lib/doc/hledger_csv.5.m4.md b/hledger-lib/doc/hledger_csv.5.m4.md index cd556cdf3..d5736d730 100644 --- a/hledger-lib/doc/hledger_csv.5.m4.md +++ b/hledger-lib/doc/hledger_csv.5.m4.md @@ -24,7 +24,7 @@ This file should be named like the CSV file with an additional `.rules` suffix ( or, you can specify the file with `--rules-file PATH`. hledger will create it if necessary, with some default rules which you'll need to adjust. At minimum, the rules file must specify the `date` and `amount` fields. -For an example, see [How to read CSV files](how-to-read-csv-files.html). +For an example, see [Cookbook: convert CSV files](csv-import.html). To learn about *exporting* CSV, see [CSV output](hledger.html#csv-output). @@ -157,7 +157,7 @@ a path relative to the current file's directory. Eg: include common.rules ``` -# TIPS +# CSV TIPS Each generated journal entry will have two postings, to `account1` and `account2` respectively. Currently it's not possible to generate entries with more than two postings. @@ -167,10 +167,14 @@ If the CSV has debit/credit amounts in separate fields, assign to the `amount-in If the CSV has the currency in a separate field, assign that to the `currency` pseudo field which will be automatically prepended to the amount. (Or you can do the same thing with a field assignment.) +If the CSV includes a running balance, you can assign that to the `balance` pseudo field +to generate a [balance assertion](/journal.html#balance-assertoins) on `account1` +whenever the balance field is non-empty. +(Eg to double-check your bank's balance calculation.) + If an amount value is parenthesised, it will be de-parenthesised and sign-flipped automatically. The generated journal entries will be sorted by date. The original order of same-day entries will be preserved, usually. -If you assign anything to the `balance` pseudo field, it would become an assertion of the balance of `account1`. If you assign empty string to it, no assertion will be generated (this can be used to omit balance assertions on some transactions). diff --git a/hledger-lib/doc/hledger_csv.5.txt b/hledger-lib/doc/hledger_csv.5.txt index da26fd383..d70f6c1ef 100644 --- a/hledger-lib/doc/hledger_csv.5.txt +++ b/hledger-lib/doc/hledger_csv.5.txt @@ -13,8 +13,8 @@ DESCRIPTION .rules suffix (eg: mybank.csv.rules); or, you can specify the file with --rules-file PATH. hledger will create it if necessary, with some default rules which you'll need to adjust. At minimum, the rules file - must specify the date and amount fields. For an example, see How to - read CSV files. + must specify the date and amount fields. For an example, see Cookbook: + convert CSV files. To learn about exporting CSV, see CSV output. @@ -58,7 +58,7 @@ CSV RULES 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. Eg: + amount, amount-in, amount-out, currency, balance. Eg: # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, # and give the 7th and 8th fields meaningful names for later reference: @@ -123,7 +123,7 @@ CSV RULES # rules reused with several CSV files include common.rules -TIPS +CSV TIPS Each generated journal entry will have two postings, to account1 and account2 respectively. Currently it's not possible to generate entries with more than two postings. @@ -135,16 +135,21 @@ TIPS currency pseudo field which will be automatically prepended to the amount. (Or you can do the same thing with a field assignment.) - If an amount value is parenthesised, it will be de-parenthesised and + If the CSV includes a running balance, you can assign that to the bal- + ance pseudo field to generate a balance assertion on account1 whenever + the balance field is non-empty. (Eg to double-check your bank's bal- + ance calculation.) + + If an amount value is parenthesised, it will be de-parenthesised and sign-flipped automatically. - The generated journal entries will be sorted by date. The original + The generated journal entries will be sorted by date. The original order of same-day entries will be preserved, usually. 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) @@ -158,7 +163,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-lib/doc/hledger_journal.5 b/hledger-lib/doc/hledger_journal.5 index acdc0a206..e1ef686f4 100644 --- a/hledger-lib/doc/hledger_journal.5 +++ b/hledger-lib/doc/hledger_journal.5 @@ -739,8 +739,7 @@ alias\ checking\ =\ assets:bank:wells\ fargo:checking .SS Regex aliases .PP There is also a more powerful variant that uses a regular expression, -indicated by the forward slashes. -(This was the default behaviour in hledger 0.24\-0.25): +indicated by the forward slashes: .IP .nf \f[C] diff --git a/hledger-lib/doc/hledger_journal.5.info b/hledger-lib/doc/hledger_journal.5.info index 3e434f03f..96989bad4 100644 --- a/hledger-lib/doc/hledger_journal.5.info +++ b/hledger-lib/doc/hledger_journal.5.info @@ -736,8 +736,7 @@ File: hledger_journal.5.info, Node: Regex aliases, Next: Multiple aliases, Pr ...................... There is also a more powerful variant that uses a regular expression, -indicated by the forward slashes. (This was the default behaviour in -hledger 0.24-0.25): +indicated by the forward slashes: alias /REGEX/ = REPLACEMENT @@ -1018,25 +1017,25 @@ Node: Basic aliases25540 Ref: #basic-aliases25685 Node: Regex aliases26375 Ref: #regex-aliases26545 -Node: Multiple aliases27316 -Ref: #multiple-aliases27490 -Node: end aliases27988 -Ref: #end-aliases28130 -Node: account directive28231 -Ref: #account-directive28413 -Node: apply account directive28709 -Ref: #apply-account-directive28907 -Node: Multi-line comments29566 -Ref: #multi-line-comments29758 -Node: commodity directive29886 -Ref: #commodity-directive30072 -Node: Default commodity30944 -Ref: #default-commodity31119 -Node: Default year31656 -Ref: #default-year31823 -Node: Including other files32246 -Ref: #including-other-files32405 -Node: EDITOR SUPPORT32802 -Ref: #editor-support32922 +Node: Multiple aliases27260 +Ref: #multiple-aliases27434 +Node: end aliases27932 +Ref: #end-aliases28074 +Node: account directive28175 +Ref: #account-directive28357 +Node: apply account directive28653 +Ref: #apply-account-directive28851 +Node: Multi-line comments29510 +Ref: #multi-line-comments29702 +Node: commodity directive29830 +Ref: #commodity-directive30016 +Node: Default commodity30888 +Ref: #default-commodity31063 +Node: Default year31600 +Ref: #default-year31767 +Node: Including other files32190 +Ref: #including-other-files32349 +Node: EDITOR SUPPORT32746 +Ref: #editor-support32866  End Tag Table diff --git a/hledger-lib/doc/hledger_journal.5.txt b/hledger-lib/doc/hledger_journal.5.txt index f0051c608..24e62bcf1 100644 --- a/hledger-lib/doc/hledger_journal.5.txt +++ b/hledger-lib/doc/hledger_journal.5.txt @@ -559,44 +559,43 @@ FILE FORMAT Regex aliases There is also a more powerful variant that uses a regular expression, - indicated by the forward slashes. (This was the default behaviour in - hledger 0.24-0.25): + indicated by the forward slashes: alias /REGEX/ = REPLACEMENT or --alias '/REGEX/=REPLACEMENT'. - REGEX is a case-insensitive regular expression. Anywhere it matches - inside an account name, the matched part will be replaced by REPLACE- - MENT. If REGEX contains parenthesised match groups, these can be ref- + REGEX is a case-insensitive regular expression. Anywhere it matches + inside an account name, the matched part will be replaced by REPLACE- + MENT. If REGEX contains parenthesised match groups, these can be ref- erenced by the usual numeric backreferences in REPLACEMENT. Note, cur- - rently regular expression aliases may cause noticeable slow-downs. + rently regular expression aliases may cause noticeable slow-downs. (And if you use Ledger on your hledger file, they will be ignored.) Eg: alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" Multiple aliases - You can define as many aliases as you like using directives or com- - mand-line options. Aliases are recursive - each alias sees the result - of applying previous ones. (This is different from Ledger, where + You can define as many aliases as you like using directives or com- + mand-line options. Aliases are recursive - each alias sees the result + of applying previous ones. (This is different from Ledger, where aliases are non-recursive by default). Aliases are applied in the fol- lowing order: - 1. alias directives, most recently seen first (recent directives take + 1. alias directives, most recently seen first (recent directives take precedence over earlier ones; directives not yet seen are ignored) 2. alias options, in the order they appear on the command line end aliases - You can clear (forget) all currently defined aliases with the + You can clear (forget) all currently defined aliases with the end aliases directive: end aliases account directive - The account directive predefines account names, as in Ledger and Bean- - count. This may be useful for your own documentation; hledger doesn't + The account directive predefines account names, as in Ledger and Bean- + count. This may be useful for your own documentation; hledger doesn't make use of it yet. ; account ACCT @@ -611,8 +610,8 @@ FILE FORMAT ; etc. apply account directive - You can specify a parent account which will be prepended to all - accounts within a section of the journal. Use the apply account and + You can specify a parent account which will be prepended to all + accounts within a section of the journal. Use the apply account and end apply account directives like so: apply account home @@ -629,7 +628,7 @@ FILE FORMAT home:food $10 home:cash $-10 - If end apply account is omitted, the effect lasts to the end of the + If end apply account is omitted, the effect lasts to the end of the file. Included files are also affected, eg: apply account business @@ -638,16 +637,16 @@ FILE FORMAT apply account personal include personal.journal - Prior to hledger 1.0, legacy account and end spellings were also sup- + Prior to hledger 1.0, legacy account and end spellings were also sup- ported. Multi-line comments - A line containing just comment starts a multi-line comment, and a line + A line containing just comment starts a multi-line comment, and a line containing just end comment ends it. See comments. commodity directive - The commodity directive predefines commodities (currently this is just - informational), and also it may define the display format for amounts + The commodity directive predefines commodities (currently this is just + informational), and also it may define the display format for amounts in this commodity (overriding the automatically inferred format). It may be written on a single line, like this: @@ -659,8 +658,8 @@ FILE FORMAT ; separating thousands with comma. commodity 1,000.0000 AAAA - or on multiple lines, using the "format" subdirective. In this case - the commodity symbol appears twice and should be the same in both + or on multiple lines, using the "format" subdirective. In this case + the commodity symbol appears twice and should be the same in both places: ; commodity SYMBOL @@ -673,10 +672,10 @@ FILE FORMAT format INR 9,99,99,999.00 Default commodity - The D directive sets a default commodity (and display format), to be + The D directive sets a default commodity (and display format), to be used for amounts without a commodity symbol (ie, plain numbers). (Note - this differs from Ledger's default commodity directive.) The commodity - and display format will be applied to all subsequent commodity-less + this differs from Ledger's default commodity directive.) The commodity + and display format will be applied to all subsequent commodity-less amounts, or until the next D directive. # commodity-less amounts should be treated as dollars @@ -688,8 +687,8 @@ FILE FORMAT b Default year - You can set a default year to be used for subsequent dates which don't - specify a year. This is a line beginning with Y followed by the year. + You can set a default year to be used for subsequent dates which don't + specify a year. This is a line beginning with Y followed by the year. Eg: Y2009 ; set default year to 2009 @@ -709,24 +708,24 @@ FILE FORMAT assets Including other files - You can pull in the content of additional journal files by writing an + You can pull in the content of additional journal files by writing an include directive, like this: include path/to/file.journal - If the path does not begin with a slash, it is relative to the current + If the path does not begin with a slash, it is relative to the current file. Glob patterns (*) are not currently supported. - The include directive can only be used in journal files. It can + The include directive can only be used in journal files. It can include journal, timeclock or timedot files, but not CSV files. EDITOR SUPPORT Add-on modes exist for various text editors, to make working with jour- - nal files easier. They add colour, navigation aids and helpful com- - mands. For hledger users who edit the journal file directly (the + nal files easier. They add colour, navigation aids and helpful com- + mands. For hledger users who edit the journal file directly (the majority), using one of these modes is quite recommended. - These were written with Ledger in mind, but also work with hledger + These were written with Ledger in mind, but also work with hledger files: @@ -743,7 +742,7 @@ EDITOR SUPPORT 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) @@ -757,7 +756,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/site/csv-import.md b/site/csv-import.md index be594aa8b..71b2e513e 100644 --- a/site/csv-import.md +++ b/site/csv-import.md @@ -55,3 +55,5 @@ using conversion rules file checking.csv.rules -------------------- 0 ``` + +Here are more [CSV rules examples](http://code.hledger.org/tree/master/examples/csv).