From 65efdea4c04913caa83f765da1f68d4157d9430d Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Tue, 7 Jan 2020 16:24:51 -0800 Subject: [PATCH] ;doc: regen some manuals [ci skip] --- hledger-lib/hledger_csv.5 | 51 ++--- hledger-lib/hledger_csv.info | 191 +++++++++--------- hledger-lib/hledger_csv.txt | 178 ++++++++-------- hledger-lib/hledger_journal.5 | 10 +- hledger-lib/hledger_journal.info | 133 ++++++------ hledger-lib/hledger_journal.txt | 334 +++++++++++++++---------------- 6 files changed, 450 insertions(+), 447 deletions(-) diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index 2db4fbe85..cf9b7c549 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -52,6 +52,11 @@ T}@T{ assign a value to one hledger field, with interpolation T} T{ +\f[B]\f[CB]separator\f[B]\f[R] +T}@T{ +a custom field separator +T} +T{ \f[B]\f[CB]if\f[B]\f[R] T}@T{ apply some rules to matched CSV records @@ -547,6 +552,29 @@ comment note: %somefield - %anotherfield, date: %1 Interpolation strips outer whitespace (so a CSV value like \f[C]\[dq] 1 \[dq]\f[R] becomes \f[C]1\f[R] when interpolated) (#1051). See TIPS below for more about referencing other fields. +.SS \f[C]separator\f[R] +.PP +You can use the \f[C]separator\f[R] directive to read other kinds of +character-separated data. +Eg to read SSV (Semicolon Separated Values), use: +.IP +.nf +\f[C] +separator ; +\f[R] +.fi +.PP +The separator directive accepts exactly one single byte character as a +separator. +To specify whitespace characters, you may use the special words +\f[C]TAB\f[R] or \f[C]SPACE\f[R]. +Eg to read TSV (Tab Separated Values), use: +.IP +.nf +\f[C] +separator TAB +\f[R] +.fi .SS \f[C]if\f[R] .IP .nf @@ -791,29 +819,6 @@ When CSV values are enclosed in quotes, note: they must be double quotes (not single quotes) .IP \[bu] 2 spaces outside the quotes are not allowed -.SS Other separator characters -.PP -You can use the \f[C]--separator \[aq]CHAR\[aq]\f[R] command line option -(experimental) to read other kinds of character-separated data. -Eg to read SSV (Semicolon Separated Values), use: -.IP -.nf -\f[C] -$ hledger -f foo.tsv --separator \[aq];\[aq] print -\f[R] -.fi -.PP -Note the semicolon is quoted because it\[aq]s a special shell character. -.PP -To read TSV (Tab Separated Values), use: -.IP -.nf -\f[C] -$ hledger -f foo.tsv --separator \[aq] \[aq] print -\f[R] -.fi -.PP -Note, that\[aq]s a real tab character in quotes, not \f[C]\[rs]t\f[R]. .SS Reading multiple CSV files .PP If you use multiple \f[C]-f\f[R] options to read multiple CSV files at diff --git a/hledger-lib/hledger_csv.info b/hledger-lib/hledger_csv.info index 3af7e3bae..ffcb95990 100644 --- a/hledger-lib/hledger_csv.info +++ b/hledger-lib/hledger_csv.info @@ -30,6 +30,7 @@ after the examples: *'fields'* name CSV fields, assign them to hledger fields *field assign a value to one hledger field, with interpolation assignment* +*'separator'* a custom field separator *'if'* apply some rules to matched CSV records *'end'* skip the remaining CSV records *'date-format'* describe the format of CSV dates @@ -371,6 +372,7 @@ Blank lines and lines beginning with '#' or ';' are ignored. * skip:: * fields:: * field assignment:: +* separator:: * if:: * end:: * date-format:: @@ -479,7 +481,7 @@ also contain tags, as usual. See TIPS below for more about setting amounts and currency.  -File: hledger_csv.info, Node: field assignment, Next: if, Prev: fields, Up: CSV RULES +File: hledger_csv.info, Node: field assignment, Next: separator, Prev: fields, Up: CSV RULES 2.3 field assignment ==================== @@ -504,9 +506,27 @@ becomes '1' when interpolated) (#1051). See TIPS below for more about referencing other fields.  -File: hledger_csv.info, Node: if, Next: end, Prev: field assignment, Up: CSV RULES +File: hledger_csv.info, Node: separator, Next: if, Prev: field assignment, Up: CSV RULES -2.4 'if' +2.4 'separator' +=============== + +You can use the 'separator' directive to read other kinds of +character-separated data. Eg to read SSV (Semicolon Separated Values), +use: + +separator ; + + The separator directive accepts exactly one single byte character as +a separator. To specify whitespace characters, you may use the special +words 'TAB' or 'SPACE'. Eg to read TSV (Tab Separated Values), use: + +separator TAB + + +File: hledger_csv.info, Node: if, Next: end, Prev: separator, Up: CSV RULES + +2.5 'if' ======== if PATTERN @@ -565,7 +585,7 @@ banking thru software  File: hledger_csv.info, Node: end, Next: date-format, Prev: if, Up: CSV RULES -2.5 'end' +2.6 'end' ========= This rule can be used inside if blocks (only), to make hledger stop @@ -579,7 +599,7 @@ if ,,,,  File: hledger_csv.info, Node: date-format, Next: newest-first, Prev: end, Up: CSV RULES -2.6 'date-format' +2.7 'date-format' ================= date-format DATEFMT @@ -610,7 +630,7 @@ https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime  File: hledger_csv.info, Node: newest-first, Next: include, Prev: date-format, Up: CSV RULES -2.7 'newest-first' +2.8 'newest-first' ================== hledger always sorts the generated transactions by date. Transactions @@ -632,7 +652,7 @@ newest-first  File: hledger_csv.info, Node: include, Next: balance-type, Prev: newest-first, Up: CSV RULES -2.8 'include' +2.9 'include' ============= include RULESFILE @@ -655,8 +675,8 @@ include categorisation.rules  File: hledger_csv.info, Node: balance-type, Prev: include, Up: CSV RULES -2.9 'balance-type' -================== +2.10 'balance-type' +=================== Balance assertions generated by assigning to balanceN are of the simple '=' type by default, which is a single-commodity, subaccount-excluding @@ -685,7 +705,6 @@ File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top * Rapid feedback:: * Valid CSV:: -* Other separator characters:: * Reading multiple CSV files:: * Valid transactions:: * Deduplicating importing:: @@ -712,7 +731,7 @@ a separator each time the command re-runs, making it easier to read the output.  -File: hledger_csv.info, Node: Valid CSV, Next: Other separator characters, Prev: Rapid feedback, Up: TIPS +File: hledger_csv.info, Node: Valid CSV, Next: Reading multiple CSV files, Prev: Rapid feedback, Up: TIPS 3.2 Valid CSV ============= @@ -724,29 +743,9 @@ enclosed in quotes, note: * spaces outside the quotes are not allowed  -File: hledger_csv.info, Node: Other separator characters, Next: Reading multiple CSV files, Prev: Valid CSV, Up: TIPS +File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Valid CSV, Up: TIPS -3.3 Other separator characters -============================== - -You can use the '--separator 'CHAR'' command line option (experimental) -to read other kinds of character-separated data. Eg to read SSV -(Semicolon Separated Values), use: - -$ hledger -f foo.tsv --separator ';' print - - Note the semicolon is quoted because it's a special shell character. - - To read TSV (Tab Separated Values), use: - -$ hledger -f foo.tsv --separator ' ' print - - Note, that's a real tab character in quotes, not '\t'. - - -File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Other separator characters, Up: TIPS - -3.4 Reading multiple CSV files +3.3 Reading multiple CSV files ============================== If you use multiple '-f' options to read multiple CSV files at once, @@ -757,7 +756,7 @@ used for all the CSV files.  File: hledger_csv.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: TIPS -3.5 Valid transactions +3.4 Valid transactions ====================== After reading a CSV file, hledger post-processes and validates the @@ -776,7 +775,7 @@ $ hledger -f file.csv print | hledger -f- print  File: hledger_csv.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: TIPS -3.6 Deduplicating, importing +3.5 Deduplicating, importing ============================ When you download a CSV file periodically, eg to get your latest bank @@ -806,7 +805,7 @@ CSV data. See:  File: hledger_csv.info, Node: Setting amounts, Next: Setting currency/commodity, Prev: Deduplicating importing, Up: TIPS -3.7 Setting amounts +3.6 Setting amounts =================== A posting amount can be set in one of these ways: @@ -835,7 +834,7 @@ A posting amount can be set in one of these ways:  File: hledger_csv.info, Node: Setting currency/commodity, Next: Referencing other fields, Prev: Setting amounts, Up: TIPS -3.8 Setting currency/commodity +3.7 Setting currency/commodity ============================== If the currency/commodity symbol is included in the CSV's amount @@ -862,7 +861,7 @@ field(s), you don't have to do anything special.  File: hledger_csv.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Setting currency/commodity, Up: TIPS -3.9 Referencing other fields +3.8 Referencing other fields ============================ In field assignments, you can interpolate only CSV fields, not hledger @@ -899,8 +898,8 @@ if something  File: hledger_csv.info, Node: How CSV rules are evaluated, Prev: Referencing other fields, Up: TIPS -3.10 How CSV rules are evaluated -================================ +3.9 How CSV rules are evaluated +=============================== Here's how to think of CSV rules being evaluated (if you really need to). First, @@ -940,62 +939,62 @@ command the user specified.  Tag Table: Node: Top72 -Node: EXAMPLES1835 -Ref: #examples1941 -Node: Basic2149 -Ref: #basic2249 -Node: Bank of Ireland2791 -Ref: #bank-of-ireland2926 -Node: Amazon4389 -Ref: #amazon4507 -Node: Paypal6440 -Ref: #paypal6534 -Node: CSV RULES14417 -Ref: #csv-rules14526 -Node: skip14788 -Ref: #skip14881 -Node: fields15256 -Ref: #fields15378 -Node: Transaction field names16543 -Ref: #transaction-field-names16703 -Node: Posting field names16814 -Ref: #posting-field-names16966 -Node: field assignment18257 -Ref: #field-assignment18393 -Node: if19211 -Ref: #if19320 -Node: end21036 -Ref: #end21142 -Node: date-format21366 -Ref: #date-format21498 -Node: newest-first22247 -Ref: #newest-first22385 -Node: include23068 -Ref: #include23197 -Node: balance-type23641 -Ref: #balance-type23759 -Node: TIPS24459 -Ref: #tips24541 -Node: Rapid feedback24809 -Ref: #rapid-feedback24926 -Node: Valid CSV25386 -Ref: #valid-csv25528 -Node: Other separator characters25720 -Ref: #other-separator-characters25908 -Node: Reading multiple CSV files26347 -Ref: #reading-multiple-csv-files26544 -Node: Valid transactions26785 -Ref: #valid-transactions26963 -Node: Deduplicating importing27591 -Ref: #deduplicating-importing27770 -Node: Setting amounts28803 -Ref: #setting-amounts28972 -Node: Setting currency/commodity29958 -Ref: #setting-currencycommodity30150 -Node: Referencing other fields30953 -Ref: #referencing-other-fields31153 -Node: How CSV rules are evaluated32050 -Ref: #how-csv-rules-are-evaluated32223 +Node: EXAMPLES1879 +Ref: #examples1985 +Node: Basic2193 +Ref: #basic2293 +Node: Bank of Ireland2835 +Ref: #bank-of-ireland2970 +Node: Amazon4433 +Ref: #amazon4551 +Node: Paypal6484 +Ref: #paypal6578 +Node: CSV RULES14461 +Ref: #csv-rules14570 +Node: skip14846 +Ref: #skip14939 +Node: fields15314 +Ref: #fields15436 +Node: Transaction field names16601 +Ref: #transaction-field-names16761 +Node: Posting field names16872 +Ref: #posting-field-names17024 +Node: field assignment18315 +Ref: #field-assignment18458 +Node: separator19276 +Ref: #separator19405 +Node: if19786 +Ref: #if19888 +Node: end21604 +Ref: #end21710 +Node: date-format21934 +Ref: #date-format22066 +Node: newest-first22815 +Ref: #newest-first22953 +Node: include23636 +Ref: #include23765 +Node: balance-type24209 +Ref: #balance-type24329 +Node: TIPS25029 +Ref: #tips25111 +Node: Rapid feedback25348 +Ref: #rapid-feedback25465 +Node: Valid CSV25925 +Ref: #valid-csv26067 +Node: Reading multiple CSV files26259 +Ref: #reading-multiple-csv-files26439 +Node: Valid transactions26680 +Ref: #valid-transactions26858 +Node: Deduplicating importing27486 +Ref: #deduplicating-importing27665 +Node: Setting amounts28698 +Ref: #setting-amounts28867 +Node: Setting currency/commodity29853 +Ref: #setting-currencycommodity30045 +Node: Referencing other fields30848 +Ref: #referencing-other-fields31048 +Node: How CSV rules are evaluated31945 +Ref: #how-csv-rules-are-evaluated32116  End Tag Table diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index 44dc369f9..3d4e6b1d4 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -34,6 +34,7 @@ DESCRIPTION field assignment assign a value to one hledger field, with inter- polation + separator a custom field separator if apply some rules to matched CSV records end skip the remaining CSV @@ -427,6 +428,18 @@ CSV RULES comes 1 when interpolated) (#1051). See TIPS below for more about ref- erencing other fields. + separator + You can use the separator directive to read other kinds of character- + separated data. Eg to read SSV (Semicolon Separated Values), use: + + separator ; + + The separator directive accepts exactly one single byte character as a + separator. To specify whitespace characters, you may use the special + words TAB or SPACE. Eg to read TSV (Tab Separated Values), use: + + separator TAB + if if PATTERN RULE @@ -438,28 +451,28 @@ CSV RULES RULE RULE - Conditional blocks ("if blocks") are a block of rules that are applied - only to CSV records which match certain patterns. They are often used + Conditional blocks ("if blocks") are a block of rules that are applied + only to CSV records which match certain patterns. They are often used for customising account names based on transaction descriptions. A single pattern can be written on the same line as the "if"; or multi- ple patterns can be written on the following lines, non-indented. Mul- - tiple patterns are OR'd (any one of them can match). Patterns are + tiple patterns are OR'd (any one of them can match). Patterns are case-insensitive regular expressions which try to match anywhere within - the whole CSV record (POSIX extended regular expressions with some ad- + the whole CSV record (POSIX extended regular expressions with some ad- ditions, see https://hledger.org/hledger.html#regular-expressions). Note the CSV record they see is close to, but not identical to, the one in the CSV file; enclosing double quotes will be removed, and the sepa- rator character is always comma. - It's not yet easy to match within a specific field. If the data does + It's not yet easy to match within a specific field. If the data does not contain commas, you can hack it with a regular expression like: # match "foo" in the fourth field if ^([^,]*,){3}foo - After the patterns there should be one or more rules to apply, all in- - dented by at least one space. Three kinds of rule are allowed in con- + After the patterns there should be one or more rules to apply, all in- + dented by at least one space. Three kinds of rule are allowed in con- ditional blocks: o field assignments (to set a hledger field) @@ -483,7 +496,7 @@ CSV RULES comment XXX deductible ? check it end - This rule can be used inside if blocks (only), to make hledger stop + This rule can be used inside if blocks (only), to make hledger stop reading this CSV file and move on to the next input file, or to command execution. Eg: @@ -494,10 +507,10 @@ CSV RULES date-format date-format DATEFMT - This is a helper for the date (and date2) fields. If your CSV dates - are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll - need to add a date-format rule describing them with a strptime date - parsing pattern, which must parse the CSV date value completely. Some + This is a helper for the date (and date2) fields. If your CSV dates + are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll + need to add a date-format rule describing them with a strptime date + parsing pattern, which must parse the CSV date value completely. Some examples: # MM/DD/YY @@ -519,15 +532,15 @@ CSV RULES mat.html#v:formatTime newest-first - hledger always sorts the generated transactions by date. Transactions - on the same date should appear in the same order as their CSV records, - as hledger can usually auto-detect whether the CSV's normal order is + hledger always sorts the generated transactions by date. Transactions + on the same date should appear in the same order as their CSV records, + as hledger can usually auto-detect whether the CSV's normal order is oldest first or newest first. But if all of the following are true: - o the CSV might sometimes contain just one day of data (all records + o the CSV might sometimes contain just one day of data (all records having the same date) - o the CSV records are normally in reverse chronological order (newest + o the CSV records are normally in reverse chronological order (newest at the top) o and you care about preserving the order of same-day transactions @@ -540,9 +553,9 @@ CSV RULES include include RULESFILE - This includes the contents of another CSV rules file at this point. - RULESFILE is an absolute file path or a path relative to the current - file's directory. This can be useful for sharing common rules between + This includes the contents of another CSV rules file at this point. + RULESFILE is an absolute file path or a path relative to the current + file's directory. This can be useful for sharing common rules between several rules files, eg: # someaccount.csv.rules @@ -557,10 +570,10 @@ CSV RULES balance-type Balance assertions generated by assigning to balanceN are of the simple - = type by default, which is a single-commodity, subaccount-excluding + = type by default, which is a single-commodity, subaccount-excluding assertion. You may find the subaccount-including variants more useful, - eg if you have created some virtual subaccounts of checking to help - with budgeting. You can select a different type of assertion with the + eg if you have created some virtual subaccounts of checking to help + with budgeting. You can select a different type of assertion with the balance-type rule: # balance assertions will consider all commodities and all subaccounts @@ -575,79 +588,64 @@ CSV RULES TIPS Rapid feedback - It's a good idea to get rapid feedback while creating/troubleshooting + It's a good idea to get rapid feedback while creating/troubleshooting CSV rules. Here's a good way, using entr from http://eradman.com/entr- project : $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' - A desc: query (eg) is used to select just one, or a few, transactions - of interest. "bash -c" is used to run multiple commands, so we can - echo a separator each time the command re-runs, making it easier to + A desc: query (eg) is used to select just one, or a few, transactions + of interest. "bash -c" is used to run multiple commands, so we can + echo a separator each time the command re-runs, making it easier to read the output. Valid CSV - hledger accepts CSV conforming to RFC 4180. When CSV values are en- + hledger accepts CSV conforming to RFC 4180. When CSV values are en- closed in quotes, note: o they must be double quotes (not single quotes) o spaces outside the quotes are not allowed - Other separator characters - You can use the --separator 'CHAR' command line option (experimental) - to read other kinds of character-separated data. Eg to read SSV (Semi- - colon Separated Values), use: - - $ hledger -f foo.tsv --separator ';' print - - Note the semicolon is quoted because it's a special shell character. - - To read TSV (Tab Separated Values), use: - - $ hledger -f foo.tsv --separator ' ' print - - Note, that's a real tab character in quotes, not \t. - Reading multiple CSV files - If you use multiple -f options to read multiple CSV files at once, - hledger will look for a correspondingly-named rules file for each CSV - file. But if you use the --rules-file option, that rules file will be + If you use multiple -f options to read multiple CSV files at once, + hledger will look for a correspondingly-named rules file for each CSV + file. But if you use the --rules-file option, that rules file will be used for all the CSV files. Valid transactions After reading a CSV file, hledger post-processes and validates the gen- erated journal entries as it would for a journal file - balancing them, - applying balance assignments, and canonicalising amount styles. Any - errors at this stage will be reported in the usual way, displaying the + applying balance assignments, and canonicalising amount styles. Any + errors at this stage will be reported in the usual way, displaying the problem entry. There is one exception: balance assertions, if you have generated them, - will not be checked, since normally these will work only when the CSV - data is part of the main journal. If you do need to check balance as- + will not be checked, since normally these will work only when the CSV + data is part of the main journal. If you do need to check balance as- sertions generated from CSV right away, pipe into another hledger: $ hledger -f file.csv print | hledger -f- print Deduplicating, importing - When you download a CSV file periodically, eg to get your latest bank - transactions, the new file may overlap with the old one, containing + When you download a CSV file periodically, eg to get your latest bank + transactions, the new file may overlap with the old one, containing some of the same records. The import command will (a) detect the new transactions, and (b) append just those transactions to your main journal. It is idempotent, so you - don't have to remember how many times you ran it or with which version - of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This + don't have to remember how many times you ran it or with which version + of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This is the easiest way to import CSV data. Eg: # download the latest CSV files, then run this command. # Note, no -f flags needed here. $ hledger import *.csv [--dry] - This method works for most CSV files. (Where records have a stable + This method works for most CSV files. (Where records have a stable chronological order, and new records appear only at the new end.) - A number of other tools and workflows, hledger-specific and otherwise, + A number of other tools and workflows, hledger-specific and otherwise, exist for converting, deduplicating, classifying and managing CSV data. See: @@ -658,43 +656,43 @@ TIPS Setting amounts A posting amount can be set in one of these ways: - o by assigning (with a fields list or field assigment) to amountN + o by assigning (with a fields list or field assigment) to amountN (posting N's amount) or amount (posting 1's amount) - o by assigning to amountN-in and amountN-out (or amount-in and amount- - out). For each CSV record, whichever of these has a non-zero value - will be used, with appropriate sign. If both contain a non-zero + o by assigning to amountN-in and amountN-out (or amount-in and amount- + out). For each CSV record, whichever of these has a non-zero value + will be used, with appropriate sign. If both contain a non-zero value, this may not work. - o by assigning to balanceN (or balance) instead of the above, setting - the amount indirectly via a balance assignment. If you do this the + o by assigning to balanceN (or balance) instead of the above, setting + the amount indirectly via a balance assignment. If you do this the default account name may be wrong, so you should set that explicitly. There is some special handling for an amount's sign: - o If an amount value is parenthesised, it will be de-parenthesised and + o If an amount value is parenthesised, it will be de-parenthesised and sign-flipped. - o If an amount value begins with a double minus sign, those cancel out + o If an amount value begins with a double minus sign, those cancel out and are removed. o If an amount value begins with a plus sign, that will be removed Setting currency/commodity - If the currency/commodity symbol is included in the CSV's amount + If the currency/commodity symbol is included in the CSV's amount field(s), you don't have to do anything special. If the currency is provided as a separate CSV field, you can either: - o assign that to currency, which adds it to all posting amounts. The - symbol will prepended to the amount quantity (on the left side). If - you write a trailing space after the symbol, there will be a space - between symbol and amount (an exception to the usual whitespace + o assign that to currency, which adds it to all posting amounts. The + symbol will prepended to the amount quantity (on the left side). If + you write a trailing space after the symbol, there will be a space + between symbol and amount (an exception to the usual whitespace stripping). o or assign it to currencyN which adds it to posting N's amount only. - o or for more control, construct the amount from symbol and quantity + o or for more control, construct the amount from symbol and quantity using field assignment, eg: fields date,description,currency,quantity @@ -702,9 +700,9 @@ TIPS amount %quantity %currency Referencing other fields - In field assignments, you can interpolate only CSV fields, not hledger - fields. In the example below, there's both a CSV field and a hledger - field named amount1, but %amount1 always means the CSV field, not the + In field assignments, you can interpolate only CSV fields, not hledger + fields. In the example below, there's both a CSV field and a hledger + field named amount1, but %amount1 always means the CSV field, not the hledger field: # Name the third CSV field "amount1" @@ -716,7 +714,7 @@ TIPS # Set comment to the CSV amount1 (not the amount1 assigned above) comment %amount1 - Here, since there's no CSV amount1 field, %amount1 will produce a lit- + Here, since there's no CSV amount1 field, %amount1 will produce a lit- eral "amount1": fields date,description,csvamount @@ -724,7 +722,7 @@ TIPS # Can't interpolate amount1 here comment %amount1 - When there are multiple field assignments to the same hledger field, + When there are multiple field assignments to the same hledger field, only the last one takes effect. Here, comment's value will be be B, or C if "something" is matched, but never A: @@ -734,14 +732,14 @@ TIPS comment C How CSV rules are evaluated - Here's how to think of CSV rules being evaluated (if you really need + Here's how to think of CSV rules being evaluated (if you really need to). First, - o include - all includes are inlined, from top to bottom, depth first. - (At each include point the file is inlined and scanned for further + o include - all includes are inlined, from top to bottom, depth first. + (At each include point the file is inlined and scanned for further includes, recursively, before proceeding.) - Then "global" rules are evaluated, top to bottom. If a rule is re- + Then "global" rules are evaluated, top to bottom. If a rule is re- peated, the last one wins: o skip (at top level) @@ -755,30 +753,30 @@ TIPS Then for each CSV record in turn: - o test all if blocks. If any of them contain a end rule, skip all re- - maining CSV records. Otherwise if any of them contain a skip rule, - skip that many CSV records. If there are multiple matched skip + o test all if blocks. If any of them contain a end rule, skip all re- + maining CSV records. Otherwise if any of them contain a skip rule, + skip that many CSV records. If there are multiple matched skip rules, the first one wins. - o collect all field assignments at top level and in matched if blocks. - When there are multiple assignments for a field, keep only the last + o collect all field assignments at top level and in matched if blocks. + When there are multiple assignments for a field, keep only the last one. - o compute a value for each hledger field - either the one that was as- + o compute a value for each hledger field - either the one that was as- signed to it (and interpolate the %CSVFIELDNAME references), or a de- fault o generate a synthetic hledger transaction from these values. - This is all part of the CSV reader, one of several readers hledger can - use to parse input files. When all files have been read successfully, - the transactions are passed as input to whichever hledger command the + This is all part of the CSV reader, one of several readers hledger can + use to parse input files. When all files have been read successfully, + the transactions are passed as input to whichever hledger command the user specified. REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -792,7 +790,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/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 9833063c6..ff246573f 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -1002,12 +1002,12 @@ T{ T}@T{ T}@T{ T}@T{ -declare a commodity, number notation & display style for commodityless -amounts +declare a commodity to be used for commodityless amounts, and its number +notation & display style T}@T{ -commodity: all commodityless entries in all files; number notation: -following commodityless entries and entries in that commodity in all -files; display style: amounts of that commodity in reports +default commodity: following commodityless entries until end of current +file; number notation: following entries in that commodity until end of +current file; display style: amounts of that commodity in reports T} T{ \f[C]include\f[R] diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 9a682b48b..d4f8f865c 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -903,19 +903,20 @@ account' apply account names inline/included amounts of that commodity in reports -'D' declare a commodity, number commodity: all +'D' declare a commodity to be default + used for commodityless commodity: + amounts, and its number following notation & display style commodityless - for commodityless amounts entries in all - files; number - notation: - following - commodityless - entries and - entries in that - commodity in all - files; display - style: amounts of - that commodity in + entries until end + of current file; + number notation: + following entries + in that commodity + until end of + current file; + display style: + amounts of that + commodity in reports 'include' include entries/directives what the included from another file directives affect @@ -1808,60 +1809,60 @@ Node: Tags28648 Ref: #tags28766 Node: Directives30159 Ref: #directives30302 -Node: Comment blocks35910 -Ref: #comment-blocks36055 -Node: Including other files36231 -Ref: #including-other-files36411 -Node: Default year36819 -Ref: #default-year36988 -Node: Declaring commodities37395 -Ref: #declaring-commodities37578 -Node: Default commodity39239 -Ref: #default-commodity39415 -Node: Market prices40049 -Ref: #market-prices40214 -Node: Declaring accounts41055 -Ref: #declaring-accounts41231 -Node: Account comments42156 -Ref: #account-comments42319 -Node: Account subdirectives42714 -Ref: #account-subdirectives42909 -Node: Account types43222 -Ref: #account-types43406 -Node: Account display order45048 -Ref: #account-display-order45218 -Node: Rewriting accounts46347 -Ref: #rewriting-accounts46532 -Node: Basic aliases47258 -Ref: #basic-aliases47404 -Node: Regex aliases48108 -Ref: #regex-aliases48280 -Node: Combining aliases48998 -Ref: #combining-aliases49176 -Node: end aliases50452 -Ref: #end-aliases50600 -Node: Default parent account50701 -Ref: #default-parent-account50867 -Node: Periodic transactions51751 -Ref: #periodic-transactions51949 -Node: Periodic rule syntax53821 -Ref: #periodic-rule-syntax54027 -Node: Two spaces between period expression and description!54731 -Ref: #two-spaces-between-period-expression-and-description55050 -Node: Forecasting with periodic transactions55734 -Ref: #forecasting-with-periodic-transactions56039 -Node: Budgeting with periodic transactions58065 -Ref: #budgeting-with-periodic-transactions58304 -Node: Auto postings / transaction modifiers58753 -Ref: #auto-postings-transaction-modifiers58964 -Node: Auto postings and dates61193 -Ref: #auto-postings-and-dates61450 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions61625 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62000 -Node: Auto posting tags62378 -Ref: #auto-posting-tags62617 -Node: EDITOR SUPPORT63282 -Ref: #editor-support63400 +Node: Comment blocks35981 +Ref: #comment-blocks36126 +Node: Including other files36302 +Ref: #including-other-files36482 +Node: Default year36890 +Ref: #default-year37059 +Node: Declaring commodities37466 +Ref: #declaring-commodities37649 +Node: Default commodity39310 +Ref: #default-commodity39486 +Node: Market prices40120 +Ref: #market-prices40285 +Node: Declaring accounts41126 +Ref: #declaring-accounts41302 +Node: Account comments42227 +Ref: #account-comments42390 +Node: Account subdirectives42785 +Ref: #account-subdirectives42980 +Node: Account types43293 +Ref: #account-types43477 +Node: Account display order45119 +Ref: #account-display-order45289 +Node: Rewriting accounts46418 +Ref: #rewriting-accounts46603 +Node: Basic aliases47329 +Ref: #basic-aliases47475 +Node: Regex aliases48179 +Ref: #regex-aliases48351 +Node: Combining aliases49069 +Ref: #combining-aliases49247 +Node: end aliases50523 +Ref: #end-aliases50671 +Node: Default parent account50772 +Ref: #default-parent-account50938 +Node: Periodic transactions51822 +Ref: #periodic-transactions52020 +Node: Periodic rule syntax53892 +Ref: #periodic-rule-syntax54098 +Node: Two spaces between period expression and description!54802 +Ref: #two-spaces-between-period-expression-and-description55121 +Node: Forecasting with periodic transactions55805 +Ref: #forecasting-with-periodic-transactions56110 +Node: Budgeting with periodic transactions58136 +Ref: #budgeting-with-periodic-transactions58375 +Node: Auto postings / transaction modifiers58824 +Ref: #auto-postings-transaction-modifiers59035 +Node: Auto postings and dates61264 +Ref: #auto-postings-and-dates61521 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions61696 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62071 +Node: Auto posting tags62449 +Ref: #auto-posting-tags62688 +Node: EDITOR SUPPORT63353 +Ref: #editor-support63471  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 98bf47582..e6c7d7b10 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -700,36 +700,36 @@ FILE FORMAT play style: amounts of that commodity in reports - D declare a commodity, number commodity: all com- - notation & display style for modityless entries - commodityless amounts in all files; num- - ber notation: fol- - lowing commodity- - less entries and - entries in that - commodity in all - files; display - style: amounts of - that commodity in - reports + D declare a commodity to be default commodity: + used for commodityless following commod- + amounts, and its number no- ityless entries un- + tation & display style til end of current + file; number nota- + tion: following en- + tries in that com- + modity until end of + current file; dis- + play style: amounts + of that commodity + in reports include include entries/directives what the included from another file directives affect P declare a market price for a amounts of that - commodity commodity in re- - ports, when -V is + commodity commodity in re- + ports, when -V is used - Y declare a year for yearless following in- + Y declare a year for yearless following in- dates line/included en- - tries until end of + tries until end of current file And some definitions: subdirec- optional indented directive line immediately following a par- tive ent directive - number how to interpret numbers when parsing journal entries (the - notation identity of the decimal separator character). (Currently - each commodity can have its own notation, even in the same + number how to interpret numbers when parsing journal entries (the + notation identity of the decimal separator character). (Currently + each commodity can have its own notation, even in the same file.) display how to display amounts of a commodity in reports (symbol side style and spacing, digit groups, decimal separator, decimal places) @@ -740,34 +740,34 @@ FILE FORMAT affect, and whether they are focussed on input (parsing) or output (re- ports). Some directives have multiple effects. - If you have a journal made up of multiple files, or pass multiple -f - options on the command line, note that directives which affect input - typically last only until the end of their defining file. This pro- + If you have a journal made up of multiple files, or pass multiple -f + options on the command line, note that directives which affect input + typically last only until the end of their defining file. This pro- vides more simplicity and predictability, eg reports are not changed by - writing file options in a different order. It can be surprising at + writing file options in a different order. It can be surprising at times though. Comment blocks - A line containing just comment starts a commented region of the file, + A line containing just comment starts a commented region of the file, and a line containing just end comment (or the end of the current file) ends it. See also comments. Including other files - You can pull in the content of additional files by writing an include + You can pull in the content of additional 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 - file. The include file path may contain common glob patterns (e.g. + If the path does not begin with a slash, it is relative to the current + file. The include file path may contain common glob patterns (e.g. *). - The include directive can only be used in journal files. It can in- + The include directive can only be used in journal files. It can in- clude journal, timeclock or timedot files, but not CSV files. 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 @@ -789,18 +789,18 @@ FILE FORMAT Declaring commodities The commodity directive has several functions: - 1. It declares commodities which may be used in the journal. This is + 1. It declares commodities which may be used in the journal. This is currently not enforced, but can serve as documentation. 2. It declares what decimal mark character to expect when parsing input - - useful to disambiguate international number formats in your data. + - useful to disambiguate international number formats in your data. (Without this, hledger will parse both 1,000 and 1.000 as 1). 3. It declares the amount display format to use in output - decimal and digit group marks, number of decimal places, symbol placement etc. - You are likely to run into one of the problems solved by commodity di- - rectives, sooner or later, so it's a good idea to just always use them + You are likely to run into one of the problems solved by commodity di- + rectives, sooner or later, so it's a good idea to just always use them to declare your commodities. A commodity directive is just the word commodity followed by an amount. @@ -813,8 +813,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 @@ -827,14 +827,14 @@ FILE FORMAT format INR 1,00,00,000.00 The quantity of the amount does not matter; only the format is signifi- - cant. The number must include a decimal mark: either a period or a + cant. The number must include a decimal mark: either a period or a comma, followed by 0 or more decimal digits. 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 @@ -849,9 +849,9 @@ FILE FORMAT a decimal point. Market prices - The P directive declares a market price, which is an exchange rate be- - tween two commodities on a certain date. (In Ledger, they are called - "historical prices".) These are often obtained from a stock exchange, + The P directive declares a market price, which is an exchange rate be- + tween two commodities on a certain date. (In Ledger, they are called + "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. Here is the format: @@ -862,16 +862,16 @@ FILE FORMAT o COMMODITYA is the symbol of the commodity being priced - o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- + o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- modity, giving the price in commodity B of one unit of commodity A. - These two market price directives say that one euro was worth 1.35 US + These two market price directives say that one euro was worth 1.35 US dollars during 2009, and $1.40 from 2010 onward: P 2009/1/1 EUR $1.35 P 2010/1/1 EUR $1.40 - The -V/--value flag can be used to convert reported amounts to another + The -V/--value flag can be used to convert reported amounts to another commodity using these prices. Declaring accounts @@ -881,20 +881,20 @@ FILE FORMAT o They can document your intended chart of accounts, providing a refer- ence. - o They can store extra information about accounts (account numbers, + o They can store extra information about accounts (account numbers, notes, etc.) - o They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), useful for reports like balancesheet and + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), useful for reports like balancesheet and incomestatement. - o They control account display order in reports, allowing non-alpha- + o They control account display order in reports, allowing non-alpha- betic sorting (eg Revenues to appear above Expenses). - o They help with account name completion in the add command, hledger- + o They help with account name completion in the add command, hledger- iadd, hledger-web, ledger-mode etc. - The simplest form is just the word account followed by a hledger-style + The simplest form is just the word account followed by a hledger-style account name, eg: account assets:bank:checking @@ -912,7 +912,7 @@ FILE FORMAT the next line instead. Account subdirectives - We also allow (and ignore) Ledger-style indented subdirectives, just + We also allow (and ignore) Ledger-style indented subdirectives, just for compatibility.: account assets:bank:checking @@ -925,18 +925,18 @@ FILE FORMAT [LEDGER-STYLE SUBDIRECTIVES, IGNORED] Account types - hledger recognises five types (or classes) of account: Asset, Liabil- - ity, Equity, Revenue, Expense. This is used by a few accounting-aware + hledger recognises five types (or classes) of account: Asset, Liabil- + ity, Equity, Revenue, Expense. This is used by a few accounting-aware reports such as balancesheet, incomestatement and cashflow. Auto-detected account types If you name your top-level accounts with some variation of assets, lia- - bilities/debts, equity, revenues/income, or expenses, their types are + bilities/debts, equity, revenues/income, or expenses, their types are detected automatically. Account types declared with tags - More generally, you can declare an account's type with an account di- - rective, by writing a type: tag in a comment, followed by one of the + More generally, you can declare an account's type with an account di- + rective, by writing a type: tag in a comment, followed by one of the words Asset, Liability, Equity, Revenue, Expense, or one of the letters ALERX (case insensitive): @@ -947,8 +947,8 @@ FILE FORMAT account expenses ; type:Expenses Account types declared with account type codes - Or, you can write one of those letters separated from the account name - by two or more spaces, but this should probably be considered depre- + Or, you can write one of those letters separated from the account name + by two or more spaces, but this should probably be considered depre- cated as of hledger 1.13: account assets A @@ -958,7 +958,7 @@ FILE FORMAT account expenses X Overriding auto-detected types - If you ever override the types of those auto-detected english account + If you ever override the types of those auto-detected english account names mentioned above, you might need to help the reports a bit. Eg: ; make "liabilities" not have the liability type - who knows why @@ -969,8 +969,8 @@ FILE FORMAT account - ; type:L Account display order - Account directives also set the order in which accounts are displayed, - eg in reports, the hledger-ui accounts screen, and the hledger-web + Account directives also set the order in which accounts are displayed, + eg in reports, the hledger-ui accounts screen, and the hledger-web sidebar. By default accounts are listed in alphabetical order. But if you have these account directives in the journal: @@ -992,16 +992,16 @@ FILE FORMAT Undeclared accounts, if any, are displayed last, in alphabetical order. - Note that sorting is done at each level of the account tree (within - each group of sibling accounts under the same parent). And currently, + Note that sorting is done at each level of the account tree (within + each group of sibling accounts under the same parent). And currently, this directive: account other:zoo - would influence the position of zoo among other's subaccounts, but not - the position of other among the top-level accounts. This means: - you - will sometimes declare parent accounts (eg account other above) that - you don't intend to post to, just to customize their display order - + would influence the position of zoo among other's subaccounts, but not + the position of other among the top-level accounts. This means: - you + will sometimes declare parent accounts (eg account other above) that + you don't intend to post to, just to customize their display order - sibling accounts stay together (you couldn't display x:y in between a:b and a:c). @@ -1020,14 +1020,14 @@ FILE FORMAT o customising reports Account aliases also rewrite account names in account directives. They - do not affect account names being entered via hledger add or hledger- + do not affect account names being entered via hledger add or hledger- web. See also Rewrite account names. Basic aliases - To set an account alias, use the alias directive in your journal file. - This affects all subsequent journal entries in the current file or its + To set an account alias, use the alias directive in your journal file. + This affects all subsequent journal entries in the current file or its included files. The spaces around the = are optional: alias OLD = NEW @@ -1035,49 +1035,49 @@ FILE FORMAT Or, you can use the --alias 'OLD=NEW' option on the command line. This affects all entries. It's useful for trying out aliases interactively. - OLD and NEW are case sensitive full account names. hledger will re- - place any occurrence of the old account name with the new one. Subac- + OLD and NEW are case sensitive full account names. hledger will re- + place any occurrence of the old account name with the new one. Subac- counts are also affected. Eg: alias checking = assets:bank:wells fargo:checking ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" Regex aliases - There is also a more powerful variant that uses a regular expression, + There is also a more powerful variant that uses a regular expression, 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. Eg: alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 ; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - Also note that REPLACEMENT continues to the end of line (or on command - line, to end of option argument), so it can contain trailing white- + Also note that REPLACEMENT continues to the end of line (or on command + line, to end of option argument), so it can contain trailing white- space. Combining aliases - You can define as many aliases as you like, using journal directives + You can define as many aliases as you like, using journal directives and/or command line options. - Recursive aliases - where an account name is rewritten by one alias, - then by another alias, and so on - are allowed. Each alias sees the + Recursive aliases - where an account name is rewritten by one alias, + then by another alias, and so on - are allowed. Each alias sees the effect of previously applied aliases. - In such cases it can be important to understand which aliases will be - applied and in which order. For (each account name in) each journal + In such cases it can be important to understand which aliases will be + applied and in which order. For (each account name in) each journal entry, we apply: - 1. alias directives preceding the journal entry, most recently parsed + 1. alias directives preceding the journal entry, most recently parsed first (ie, reading upward from the journal entry, bottom to top) - 2. --alias options, in the order they appeared on the command line + 2. --alias options, in the order they appeared on the command line (left to right). In other words, for (an account name in) a given journal entry: @@ -1088,22 +1088,22 @@ FILE FORMAT o aliases defined after/below the entry do not affect it. - This gives nearby aliases precedence over distant ones, and helps pro- - vide semantic stability - aliases will keep working the same way inde- + This gives nearby aliases precedence over distant ones, and helps pro- + vide semantic stability - aliases will keep working the same way inde- pendent of which files are being read and in which order. - In case of trouble, adding --debug=6 to the command line will show + In case of trouble, adding --debug=6 to the command line will show which aliases are being applied when. end aliases - You can clear (forget) all currently defined aliases with the end + You can clear (forget) all currently defined aliases with the end aliases directive: end aliases Default parent account - You can specify a parent account which will be prepended to all ac- - counts within a section of the journal. Use the apply account and end + You can specify a parent account which will be prepended to all ac- + counts within a section of the journal. Use the apply account and end apply account directives like so: apply account home @@ -1120,7 +1120,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 @@ -1129,50 +1129,50 @@ 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. - A default parent account also affects account directives. It does not - affect account names being entered via hledger add or hledger-web. If - account aliases are present, they are applied after the default parent + A default parent account also affects account directives. It does not + affect account names being entered via hledger add or hledger-web. If + account aliases are present, they are applied after the default parent account. Periodic transactions - Periodic transaction rules describe transactions that recur. They al- - low hledger to generate temporary future transactions to help with - forecasting, so you don't have to write out each one in the journal, - and it's easy to try out different forecasts. Secondly, they are also + Periodic transaction rules describe transactions that recur. They al- + low hledger to generate temporary future transactions to help with + forecasting, so you don't have to write out each one in the journal, + and it's easy to try out different forecasts. Secondly, they are also used to define the budgets shown in budget reports. - Periodic transactions can be a little tricky, so before you use them, + Periodic transactions can be a little tricky, so before you use them, read this whole section - or at least these tips: - 1. Two spaces accidentally added or omitted will cause you trouble - + 1. Two spaces accidentally added or omitted will cause you trouble - read about this below. - 2. For troubleshooting, show the generated transactions with hledger - print --forecast tag:generated or hledger register --forecast + 2. For troubleshooting, show the generated transactions with hledger + print --forecast tag:generated or hledger register --forecast tag:generated. - 3. Forecasted transactions will begin only after the last non-fore- + 3. Forecasted transactions will begin only after the last non-fore- casted transaction's date. - 4. Forecasted transactions will end 6 months from today, by default. + 4. Forecasted transactions will end 6 months from today, by default. See below for the exact start/end rules. - 5. period expressions can be tricky. Their documentation needs im- + 5. period expressions can be tricky. Their documentation needs im- provement, but is worth studying. - 6. Some period expressions with a repeating interval must begin on a - natural boundary of that interval. Eg in weekly from DATE, DATE - must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an + 6. Some period expressions with a repeating interval must begin on a + natural boundary of that interval. Eg in weekly from DATE, DATE + must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an error. 7. Other period expressions with an interval are automatically expanded - to cover a whole number of that interval. (This is done to improve + to cover a whole number of that interval. (This is done to improve reports, but it also affects periodic transactions. Yes, it's a bit - inconsistent with the above.) Eg: ~ every 10th day of month from - 2020/01, which is equivalent to ~ every 10th day of month from + inconsistent with the above.) Eg: ~ every 10th day of month from + 2020/01, which is equivalent to ~ every 10th day of month from 2020/01/01, will be adjusted to start on 2019/12/10. Periodic rule syntax @@ -1184,17 +1184,17 @@ FILE FORMAT expenses:rent $2000 assets:bank:checking - There is an additional constraint on the period expression: the start - date must fall on a natural boundary of the interval. Eg monthly from + There is an additional constraint on the period expression: the start + date must fall on a natural boundary of the interval. Eg monthly from 2018/1/1 is valid, but monthly from 2018/1/15 is not. - Partial or relative dates (M/D, D, tomorrow, last week) in the period - expression can work (useful or not). They will be relative to today's - date, unless a Y default year directive is in effect, in which case + Partial or relative dates (M/D, D, tomorrow, last week) in the period + expression can work (useful or not). They will be relative to today's + date, unless a Y default year directive is in effect, in which case they will be relative to Y/1/1. Two spaces between period expression and description! - If the period expression is followed by a transaction description, + If the period expression is followed by a transaction description, these must be separated by two or more spaces. This helps hledger know where the period expression ends, so that descriptions can not acciden- tally alter their meaning, as in this example: @@ -1208,82 +1208,82 @@ FILE FORMAT So, - o Do write two spaces between your period expression and your transac- + o Do write two spaces between your period expression and your transac- tion description, if any. - o Don't accidentally write two spaces in the middle of your period ex- + o Don't accidentally write two spaces in the middle of your period ex- pression. Forecasting with periodic transactions - With the --forecast flag, each periodic transaction rule generates fu- - ture transactions recurring at the specified interval. These are not - saved in the journal, but appear in all reports. They will look like + With the --forecast flag, each periodic transaction rule generates fu- + ture transactions recurring at the specified interval. These are not + saved in the journal, but appear in all reports. They will look like normal transactions, but with an extra tag: - o generated-transaction:~ PERIODICEXPR - shows that this was generated + o generated-transaction:~ PERIODICEXPR - shows that this was generated by a periodic transaction rule, and the period - There is also a hidden tag, with an underscore prefix, which does not + There is also a hidden tag, with an underscore prefix, which does not appear in hledger's output: o _generated-transaction:~ PERIODICEXPR - This can be used to match transactions generated "just now", rather + This can be used to match transactions generated "just now", rather than generated in the past and saved to the journal. - Forecast transactions start on the first occurrence, and end on the - last occurrence, of their interval within the forecast period. The + Forecast transactions start on the first occurrence, and end on the + last occurrence, of their interval within the forecast period. The forecast period: o begins on the later of o the report start date if specified with -b/-p/date: - o the day after the latest normal (non-periodic) transaction in the + o the day after the latest normal (non-periodic) transaction in the journal, or today if there are no normal transactions. - o ends on the report end date if specified with -e/-p/date:, or 180 + o ends on the report end date if specified with -e/-p/date:, or 180 days from today. - where "today" means the current date at report time. The "later of" - rule ensures that forecast transactions do not overlap normal transac- + where "today" means the current date at report time. The "later of" + rule ensures that forecast transactions do not overlap normal transac- tions in time; they will begin only after normal transactions end. - Forecasting can be useful for estimating balances into the future, and - experimenting with different scenarios. Note the start date logic + Forecasting can be useful for estimating balances into the future, and + experimenting with different scenarios. Note the start date logic means that forecasted transactions are automatically replaced by normal transactions as you add those. Forecasting can also help with data entry: describe most of your trans- - actions with periodic rules, and every so often copy the output of + actions with periodic rules, and every so often copy the output of print --forecast to the journal. You can generate one-time transactions too: just write a period expres- - sion specifying a date with no report interval. (You could also write - a normal transaction with a future date, but remember this disables + sion specifying a date with no report interval. (You could also write + a normal transaction with a future date, but remember this disables forecast transactions on previous dates.) Budgeting with periodic transactions - With the --budget flag, currently supported by the balance command, - each periodic transaction rule declares recurring budget goals for the - specified accounts. Eg the first example above declares a goal of - spending $2000 on rent (and also, a goal of depositing $2000 into - checking) every month. Goals and actual performance can then be com- + With the --budget flag, currently supported by the balance command, + each periodic transaction rule declares recurring budget goals for the + specified accounts. Eg the first example above declares a goal of + spending $2000 on rent (and also, a goal of depositing $2000 into + checking) every month. Goals and actual performance can then be com- pared in budget reports. - For more details, see: balance: Budget report and Budgeting and Fore- + For more details, see: balance: Budget report and Budgeting and Fore- casting. Auto postings / transaction modifiers Transaction modifier rules, AKA auto posting rules, describe changes to - be applied automatically to certain matched transactions. Currently - just one kind of change is possible - adding extra postings, which we - call "automated postings" or just "auto postings". These rules become + be applied automatically to certain matched transactions. Currently + just one kind of change is possible - adding extra postings, which we + call "automated postings" or just "auto postings". These rules become active when you use the --auto flag. A transaction modifier rule looks much like a normal transaction except - the first line is an equals sign followed by a query that matches cer- - tain postings (mnemonic: = suggests matching). And each "posting" is + the first line is an equals sign followed by a query that matches cer- + tain postings (mnemonic: = suggests matching). And each "posting" is actually a posting-generating rule: = QUERY @@ -1291,20 +1291,20 @@ FILE FORMAT ACCT [AMT] ... - These posting-generating rules look like normal postings, except the + These posting-generating rules look like normal postings, except the amount can be: - o a normal amount with a commodity symbol, eg $2. This will be used + o a normal amount with a commodity symbol, eg $2. This will be used as-is. o a number, eg 2. The commodity symbol (if any) from the matched post- ing will be added to this. - o a numeric multiplier, eg *2 (a star followed by a number N). The + o a numeric multiplier, eg *2 (a star followed by a number N). The matched posting's amount (and total price, if any) will be multiplied by N. - o a multiplier with a commodity symbol, eg *$2 (a star, number N, and + o a multiplier with a commodity symbol, eg *$2 (a star, number N, and symbol S). The matched posting's amount will be multiplied by N, and its commodity symbol will be replaced with S. @@ -1344,20 +1344,20 @@ FILE FORMAT assets:checking $20 Auto postings and dates - A posting date (or secondary date) in the matched posting, or (taking - precedence) a posting date in the auto posting rule itself, will also + A posting date (or secondary date) in the matched posting, or (taking + precedence) a posting date in the auto posting rule itself, will also be used in the generated posting. Auto postings and transaction balancing / inferred amounts / balance asser- tions Currently, transaction modifiers are applied / auto postings are added: - o after missing amounts are inferred, and transactions are checked for + o after missing amounts are inferred, and transactions are checked for balancedness, o but before balance assertions are checked. - Note this means that journal entries must be balanced both before and + Note this means that journal entries must be balanced both before and after auto postings are added. This changed in hledger 1.12+; see #893 for background. @@ -1367,11 +1367,11 @@ FILE FORMAT o generated-posting:= QUERY - shows this was generated by an auto post- ing rule, and the query - o _generated-posting:= QUERY - a hidden tag, which does not appear in + o _generated-posting:= QUERY - a hidden tag, which does not appear in hledger's output. This can be used to match postings generated "just now", rather than generated in the past and saved to the journal. - Also, any transaction that has been changed by transaction modifier + Also, any transaction that has been changed by transaction modifier rules will have these tags added: o modified: - this transaction was modified @@ -1380,18 +1380,18 @@ FILE FORMAT tion was modified "just now". EDITOR SUPPORT - Helper modes exist for popular text editors, which make working with + Helper modes exist for popular text editors, which make working with journal files easier. They add colour, formatting, tab completion, and - helpful commands, and are quite recommended if you edit your journal - with a text editor. They include ledger-mode or hledger-mode for - Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and + helpful commands, and are quite recommended if you edit your journal + with a text editor. They include ledger-mode or hledger-mode for + Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and others. See the Editor configuration at hledger.org for the latest in- formation. 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) @@ -1405,7 +1405,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)