diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index f9ccc0396..d0850fed5 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -112,15 +112,15 @@ Examples: .IP .nf \f[C] -#\ for\ dates\ like\ "6/11/2013": -date\-format\ %\-d/%\-m/%Y +#\ for\ dates\ like\ "11/06/2013": +date\-format\ %m/%d/%Y \f[] .fi .IP .nf \f[C] -#\ for\ dates\ like\ "11/06/2013": -date\-format\ %m/%d/%Y +#\ for\ dates\ like\ "6/11/2013"\ (note\ the\ \-\ to\ make\ leading\ zeros\ optional): +date\-format\ %\-d/%\-m/%Y \f[] .fi .IP diff --git a/hledger-lib/hledger_csv.info b/hledger-lib/hledger_csv.info index bcc8d5a54..215bc89c9 100644 --- a/hledger-lib/hledger_csv.info +++ b/hledger-lib/hledger_csv.info @@ -113,12 +113,12 @@ File: hledger_csv.info, Node: date-format, Next: field list, Prev: skip, Up: DATEFMT is a strptime-like date parsing pattern, which must parse the date field values completely. Examples: -# for dates like "6/11/2013": -date-format %-d/%-m/%Y - # for dates like "11/06/2013": date-format %m/%d/%Y +# for dates like "6/11/2013" (note the - to make leading zeros optional): +date-format %-d/%-m/%Y + # for dates like "2013-Nov-06": date-format %Y-%h-%d @@ -323,27 +323,27 @@ Node: skip2539 Ref: #skip2633 Node: date-format2805 Ref: #date-format2932 -Node: field list3438 -Ref: #field-list3575 -Node: field assignment4280 -Ref: #field-assignment4435 -Node: conditional block4939 -Ref: #conditional-block5093 -Node: include5989 -Ref: #include6119 -Node: newest-first6350 -Ref: #newest-first6464 -Node: CSV TIPS6875 -Ref: #csv-tips6969 -Node: CSV ordering7087 -Ref: #csv-ordering7205 -Node: CSV accounts7386 -Ref: #csv-accounts7524 -Node: CSV amounts7778 -Ref: #csv-amounts7924 -Node: CSV balance assertions8699 -Ref: #csv-balance-assertions8881 -Node: Reading multiple CSV files9086 -Ref: #reading-multiple-csv-files9256 +Node: field list3482 +Ref: #field-list3619 +Node: field assignment4324 +Ref: #field-assignment4479 +Node: conditional block4983 +Ref: #conditional-block5137 +Node: include6033 +Ref: #include6163 +Node: newest-first6394 +Ref: #newest-first6508 +Node: CSV TIPS6919 +Ref: #csv-tips7013 +Node: CSV ordering7131 +Ref: #csv-ordering7249 +Node: CSV accounts7430 +Ref: #csv-accounts7568 +Node: CSV amounts7822 +Ref: #csv-amounts7968 +Node: CSV balance assertions8743 +Ref: #csv-balance-assertions8925 +Node: Reading multiple CSV files9130 +Ref: #reading-multiple-csv-files9300  End Tag Table diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index 7f7c7dfbd..52a7f5406 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -88,12 +88,12 @@ CSV RULES is a strptime-like date parsing pattern, which must parse the date field values completely. Examples: - # for dates like "6/11/2013": - date-format %-d/%-m/%Y - # for dates like "11/06/2013": date-format %m/%d/%Y + # for dates like "6/11/2013" (note the - to make leading zeros optional): + date-format %-d/%-m/%Y + # for dates like "2013-Nov-06": date-format %Y-%h-%d diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 1de9cf14f..d0d0c1e99 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -635,6 +635,13 @@ Balance assertions are checked against all postings, both real and virtual. They are not affected by the \f[C]\-\-real/\-R\f[] flag or \f[C]real:\f[] query. +.SS Assertions and precision +.PP +Balance assertions compare the exactly calculated amounts, which are not +always what is shown by reports. +Eg a commodity directive may limit the display precision, but this will +not affect balance assertions. +Balance assertion failure messages show exact amounts. .SS Balance Assignments .PP Ledger\-style balance assignments are also supported. @@ -1514,21 +1521,20 @@ 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. +.SS Two spaces after the period expression .PP -Period expressions must be terminated by \f[B]two or more spaces\f[] if -followed by additional fields. -For example, the periodic transaction given below includes a transaction -description \[lq]paycheck\[rq], which is separated from the period -expression by a double space. -If not for the second space, hledger would attempt (and fail) to parse -\[lq]paycheck\[rq] as a part of the period expression. +If the period expression is followed by a transaction description, these +must be separated by \f[B]two or more spaces\f[]. +This helps hledger know where the period expression ends, so that +descriptions can not accidentally alter their meaning, as in this +example: .IP .nf \f[C] -;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ or\ more\ spaces -;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ || -;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv -~\ every\ 2\ weeks\ from\ 2018/6/4\ to\ 2018/9\ \ paycheck +;\ 2\ or\ more\ spaces\ needed\ here,\ so\ the\ period\ is\ not\ understood\ as\ "every\ 2\ months\ in\ 2020" +;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ || +;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv +~\ every\ 2\ months\ \ in\ 2020,\ we\ will\ review \ \ \ \ assets:bank:checking\ \ \ $1500 \ \ \ \ income:acme\ inc \f[] diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 4325ca423..2ffba36e2 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -476,6 +476,7 @@ or for reading Ledger files. * Assertions and prices:: * Assertions and subaccounts:: * Assertions and virtual postings:: +* Assertions and precision::  File: hledger_journal.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance Assertions @@ -599,7 +600,7 @@ $ hledger bal checking --flat 2  -File: hledger_journal.info, Node: Assertions and virtual postings, Prev: Assertions and subaccounts, Up: Balance Assertions +File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance Assertions 1.9.7 Assertions and virtual postings ------------------------------------- @@ -608,6 +609,17 @@ Balance assertions are checked against all postings, both real and virtual. They are not affected by the '--real/-R' flag or 'real:' query. + +File: hledger_journal.info, Node: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance Assertions + +1.9.8 Assertions and precision +------------------------------ + +Balance assertions compare the exactly calculated amounts, which are not +always what is shown by reports. Eg a commodity directive may limit the +display precision, but this will not affect balance assertions. Balance +assertion failure messages show exact amounts. +  File: hledger_journal.info, Node: Balance Assignments, Next: Transaction prices, Prev: Balance Assertions, Up: FILE FORMAT @@ -1342,30 +1354,34 @@ date must fall on a natural boundary of the interval. Eg 'monthly from 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. - - Period expressions must be terminated by *two or more spaces* if -followed by additional fields. For example, the periodic transaction -given below includes a transaction description "paycheck", which is -separated from the period expression by a double space. If not for the -second space, hledger would attempt (and fail) to parse "paycheck" as a -part of the period expression. - -; 2 or more spaces -; || -; vv -~ every 2 weeks from 2018/6/4 to 2018/9 paycheck - assets:bank:checking $1500 - income:acme inc - * Menu: +* Two spaces after the period expression:: * Forecasting with periodic transactions:: * Budgeting with periodic transactions::  -File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Up: Periodic transactions +File: hledger_journal.info, Node: Two spaces after the period expression, Next: Forecasting with periodic transactions, Up: Periodic transactions -1.15.1 Forecasting with periodic transactions +1.15.1 Two spaces after the period expression +--------------------------------------------- + +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 +accidentally alter their meaning, as in this example: + +; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020" +; || +; vv +~ every 2 months in 2020, we will review + assets:bank:checking $1500 + income:acme inc + + +File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces after the period expression, Up: Periodic transactions + +1.15.2 Forecasting with periodic transactions --------------------------------------------- With the '--forecast' flag, each periodic transaction rule generates @@ -1408,7 +1424,7 @@ disables forecast transactions on previous dates.)  File: hledger_journal.info, Node: Budgeting with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions -1.15.2 Budgeting with periodic transactions +1.15.3 Budgeting with periodic transactions ------------------------------------------- With the '--budget' flag, currently supported by the balance command, @@ -1549,71 +1565,75 @@ Node: Virtual Postings15032 Ref: #virtual-postings15191 Node: Balance Assertions16411 Ref: #balance-assertions16586 -Node: Assertions and ordering17508 -Ref: #assertions-and-ordering17694 -Node: Assertions and included files18394 -Ref: #assertions-and-included-files18635 -Node: Assertions and multiple -f options18968 -Ref: #assertions-and-multiple--f-options19222 -Node: Assertions and commodities19354 -Ref: #assertions-and-commodities19584 -Node: Assertions and prices20772 -Ref: #assertions-and-prices20984 -Node: Assertions and subaccounts21093 -Ref: #assertions-and-subaccounts21320 -Node: Assertions and virtual postings21841 -Ref: #assertions-and-virtual-postings22048 -Node: Balance Assignments22190 -Ref: #balance-assignments22371 -Node: Transaction prices23491 -Ref: #transaction-prices23660 -Node: Comments25928 -Ref: #comments26062 -Node: Tags27232 -Ref: #tags27350 -Node: Directives28752 -Ref: #directives28895 -Node: Comment blocks34502 -Ref: #comment-blocks34647 -Node: Including other files34823 -Ref: #including-other-files35003 -Node: Default year35411 -Ref: #default-year35580 -Node: Declaring commodities36003 -Ref: #declaring-commodities36186 -Node: Default commodity37413 -Ref: #default-commodity37589 -Node: Market prices38225 -Ref: #market-prices38390 -Node: Declaring accounts39231 -Ref: #declaring-accounts39407 -Node: Account types40364 -Ref: #account-types40513 -Node: Account comments41587 -Ref: #account-comments41772 -Node: Account display order42093 -Ref: #account-display-order42266 -Node: Rewriting accounts43388 -Ref: #rewriting-accounts43573 -Node: Basic aliases44307 -Ref: #basic-aliases44453 -Node: Regex aliases45157 -Ref: #regex-aliases45328 -Node: Multiple aliases46046 -Ref: #multiple-aliases46221 -Node: end aliases46719 -Ref: #end-aliases46866 -Node: Default parent account46967 -Ref: #default-parent-account47133 -Node: Periodic transactions48017 -Ref: #periodic-transactions48199 -Node: Forecasting with periodic transactions49902 -Ref: #forecasting-with-periodic-transactions50145 -Node: Budgeting with periodic transactions51832 -Ref: #budgeting-with-periodic-transactions52071 -Node: Transaction Modifiers52530 -Ref: #transaction-modifiers52693 -Node: EDITOR SUPPORT54674 -Ref: #editor-support54792 +Node: Assertions and ordering17537 +Ref: #assertions-and-ordering17723 +Node: Assertions and included files18423 +Ref: #assertions-and-included-files18664 +Node: Assertions and multiple -f options18997 +Ref: #assertions-and-multiple--f-options19251 +Node: Assertions and commodities19383 +Ref: #assertions-and-commodities19613 +Node: Assertions and prices20801 +Ref: #assertions-and-prices21013 +Node: Assertions and subaccounts21122 +Ref: #assertions-and-subaccounts21349 +Node: Assertions and virtual postings21870 +Ref: #assertions-and-virtual-postings22110 +Node: Assertions and precision22252 +Ref: #assertions-and-precision22443 +Node: Balance Assignments22710 +Ref: #balance-assignments22891 +Node: Transaction prices24011 +Ref: #transaction-prices24180 +Node: Comments26448 +Ref: #comments26582 +Node: Tags27752 +Ref: #tags27870 +Node: Directives29272 +Ref: #directives29415 +Node: Comment blocks35022 +Ref: #comment-blocks35167 +Node: Including other files35343 +Ref: #including-other-files35523 +Node: Default year35931 +Ref: #default-year36100 +Node: Declaring commodities36523 +Ref: #declaring-commodities36706 +Node: Default commodity37933 +Ref: #default-commodity38109 +Node: Market prices38745 +Ref: #market-prices38910 +Node: Declaring accounts39751 +Ref: #declaring-accounts39927 +Node: Account types40884 +Ref: #account-types41033 +Node: Account comments42107 +Ref: #account-comments42292 +Node: Account display order42613 +Ref: #account-display-order42786 +Node: Rewriting accounts43908 +Ref: #rewriting-accounts44093 +Node: Basic aliases44827 +Ref: #basic-aliases44973 +Node: Regex aliases45677 +Ref: #regex-aliases45848 +Node: Multiple aliases46566 +Ref: #multiple-aliases46741 +Node: end aliases47239 +Ref: #end-aliases47386 +Node: Default parent account47487 +Ref: #default-parent-account47653 +Node: Periodic transactions48537 +Ref: #periodic-transactions48719 +Node: Two spaces after the period expression49844 +Ref: #two-spaces-after-the-period-expression50089 +Node: Forecasting with periodic transactions50574 +Ref: #forecasting-with-periodic-transactions50864 +Node: Budgeting with periodic transactions52551 +Ref: #budgeting-with-periodic-transactions52790 +Node: Transaction Modifiers53249 +Ref: #transaction-modifiers53412 +Node: EDITOR SUPPORT55393 +Ref: #editor-support55511  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 8dae3ce9a..88d751e35 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -472,11 +472,17 @@ FILE FORMAT Balance assertions are checked against all postings, both real and vir- tual. They are not affected by the --real/-R flag or real: query. + Assertions and precision + Balance assertions compare the exactly calculated amounts, which are + not always what is shown by reports. Eg a commodity directive may + limit the display precision, but this will not affect balance asser- + tions. Balance assertion failure messages show exact amounts. + Balance Assignments - Ledger-style balance assignments are also supported. These are like - balance assertions, but with no posting amount on the left side of the - equals sign; instead it is calculated automatically so as to satisfy - the assertion. This can be a convenience during data entry, eg when + Ledger-style balance assignments are also supported. These are like + balance assertions, but with no posting amount on the left side of the + equals sign; instead it is calculated automatically so as to satisfy + the assertion. This can be a convenience during data entry, eg when setting opening balances: ; starting a new journal, set asset account balances @@ -494,17 +500,17 @@ FILE FORMAT expenses:misc The calculated amount depends on the account's balance in the commodity - at that point (which depends on the previously-dated postings of the - commodity to that account since the last balance assertion or assign- + at that point (which depends on the previously-dated postings of the + commodity to that account since the last balance assertion or assign- ment). Note that using balance assignments makes your journal a little less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it. Transaction prices Within a transaction, you can note an amount's price in another commod- - ity. This can be used to document the cost (in a purchase) or selling - price (in a sale). For example, transaction prices are useful to - record purchases of a foreign currency. Note transaction prices are + ity. This can be used to document the cost (in a purchase) or selling + price (in a sale). For example, transaction prices are useful to + record purchases of a foreign currency. Note transaction prices are fixed at the time of the transaction, and do not change over time. See also market prices, which represent prevailing exchange rates on a cer- tain date. @@ -533,7 +539,7 @@ FILE FORMAT (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- PRICE}, which hledger currently ignores). - Use the -B/--cost flag to convert amounts to their transaction price's + Use the -B/--cost flag to convert amounts to their transaction price's commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). Eg here is how -B affects the balance report for the example above: @@ -544,8 +550,8 @@ FILE FORMAT $-135 assets:dollars $135 assets:euros # <- the euros' cost - Note -B is sensitive to the order of postings when a transaction price - is inferred: the inferred price will be in the commodity of the last + Note -B is sensitive to the order of postings when a transaction price + is inferred: the inferred price will be in the commodity of the last amount. So if example 3's postings are reversed, while the transaction is equivalent, -B shows something different: @@ -559,14 +565,14 @@ FILE FORMAT Comments Lines in the journal beginning with a semicolon (;) or hash (#) or star - (*) are comments, and will be ignored. (Star comments cause org-mode - nodes to be ignored, allowing emacs users to fold and navigate their + (*) are comments, and will be ignored. (Star comments cause org-mode + nodes to be ignored, allowing emacs users to fold and navigate their journals with org-mode or orgstruct-mode.) - You can attach comments to a transaction by writing them after the - description and/or indented on the following lines (before the post- - ings). Similarly, you can attach comments to an individual posting by - writing them after the amount and/or indented on the following lines. + You can attach comments to a transaction by writing them after the + description and/or indented on the following lines (before the post- + ings). Similarly, you can attach comments to an individual posting by + writing them after the amount and/or indented on the following lines. Transaction and posting comments must begin with a semicolon (;). Some examples: @@ -590,24 +596,24 @@ FILE FORMAT ; another comment line for posting 2 ; a file comment (because not indented) - You can also comment larger regions of a file using comment and + You can also comment larger regions of a file using comment and end comment directives. Tags - Tags are a way to add extra labels or labelled data to postings and + Tags are a way to add extra labels or labelled data to postings and transactions, which you can then search or pivot on. - A simple tag is a word (which may contain hyphens) followed by a full + A simple tag is a word (which may contain hyphens) followed by a full colon, written inside a transaction or posting comment line: 2017/1/16 bought groceries ; sometag: - Tags can have a value, which is the text after the colon, up to the + Tags can have a value, which is the text after the colon, up to the next comma or end of line, with leading/trailing whitespace removed: expenses:food $10 ; a-posting-tag: the tag value - Note this means hledger's tag values can not contain commas or new- + Note this means hledger's tag values can not contain commas or new- lines. Ending at commas means you can write multiple short tags on one line, comma separated: @@ -621,74 +627,68 @@ FILE FORMAT o "tag2" is another tag, whose value is "some value ..." - Tags in a transaction comment affect the transaction and all of its - postings, while tags in a posting comment affect only that posting. - For example, the following transaction has three tags (A, TAG2, + Tags in a transaction comment affect the transaction and all of its + postings, while tags in a posting comment affect only that posting. + For example, the following transaction has three tags (A, TAG2, third-tag) and the posting has four (those plus posting-tag): 1/1 a transaction ; A:, TAG2: ; third-tag: a third transaction tag, <- with a value (a) $1 ; posting-tag: - Tags are like Ledger's metadata feature, except hledger's tag values + Tags are like Ledger's metadata feature, except hledger's tag values are simple strings. Directives - A directive is a line in the journal beginning with a special keyword, + A directive is a line in the journal beginning with a special keyword, that influences how the journal is processed. hledger's directives are based on a subset of Ledger's, but there are many differences (and also some differences between hledger versions). Directives' behaviour and interactions can get a little bit complex, so - here is a table summarising the directives and their effects, with + here is a table summarising the directives and their effects, with links to more detailed docs. - direc- end subdi- purpose can affect (as of + direc- end subdi- purpose can affect (as of tive directive rec- 2018/06) tives ------------------------------------------------------------------------------------------------- - account any document account names, all entries in all - text declare account types & dis- files, before or + account any document account names, all entries in all + text declare account types & dis- files, before or play order after alias end aliases rewrite account names following inline/included entries until end - of current file or + of current file or end directive - apply account end apply account prepend a common parent to following + apply account end apply account prepend a common parent to following account names inline/included entries until end - of current file or + of current file or end directive comment end comment ignore part of journal following inline/included entries until end - of current file or + of current file or end directive - commodity format declare a commodity and its number notation: + commodity format declare a commodity and its number notation: number notation & display following entries style in that commodity - in all files; dis- + in all files; dis- play style: amounts of that commodity in reports - - - - - - - D declare a commodity, number commodity: all com- + D declare a commodity, number commodity: all com- notation & display style for modityless entries - commodityless amounts in all files; num- - ber notation: fol- + commodityless amounts in all files; num- + ber notation: fol- lowing commodity- - less entries and + less entries and entries in that - commodity in all + commodity in all files; display style: amounts of that commodity in @@ -699,7 +699,7 @@ FILE FORMAT commodity commodity in reports, when -V is used - Y declare a year for yearless following + Y declare a year for yearless following dates inline/included entries until end of current file @@ -709,9 +709,9 @@ FILE FORMAT 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) @@ -719,37 +719,37 @@ FILE FORMAT scope are affected by a directive As you can see, directives vary in which journal entries and files they - affect, and whether they are focussed on input (parsing) or output + affect, and whether they are focussed on input (parsing) or output (reports). 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 + The include directive can only be used in journal files. It can include 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 @@ -769,8 +769,8 @@ FILE FORMAT assets Declaring commodities - The commodity directive declares commodities which may be used in the - journal (though currently we do not enforce this). It may be written + The commodity directive declares commodities which may be used in the + journal (though currently we do not enforce this). It may be written on a single line, like this: ; commodity EXAMPLEAMOUNT @@ -780,8 +780,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 @@ -793,19 +793,19 @@ FILE FORMAT commodity INR format INR 9,99,99,999.00 - Commodity directives have a second purpose: they define the standard + Commodity directives have a second purpose: they define the standard display format for amounts in the commodity. Normally the display for- - mat is inferred from journal entries, but this can be unpredictable; - declaring it with a commodity directive overrides this and removes - ambiguity. Towards this end, amounts in commodity directives must - always be written with a decimal point (a period or comma, followed by + mat is inferred from journal entries, but this can be unpredictable; + declaring it with a commodity directive overrides this and removes + ambiguity. Towards this end, amounts in commodity directives must + always be written with a decimal point (a period or 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 @@ -820,9 +820,9 @@ FILE FORMAT a decimal point. Market prices - The P directive declares a market price, which is an exchange rate + The P directive declares a market price, which is an exchange rate between two commodities on a certain date. (In Ledger, they are called - "historical prices".) These are often obtained from a stock exchange, + "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. Here is the format: @@ -833,36 +833,36 @@ 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 $1.35 P 2010/1/1 $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 - account directives can be used to pre-declare some or all accounts. + account directives can be used to pre-declare some or all accounts. Though not required, they can provide several benefits: 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, + o They help with account name completion in the add command, hledger-iadd, hledger-web, ledger-mode etc. Here is the full syntax: @@ -875,15 +875,15 @@ FILE FORMAT account assets:bank:checking Account types - hledger recognises five types of account: asset, liability, equity, + hledger recognises five types of account: asset, liability, equity, revenue, expense. This is useful for certain accounting-aware reports, in particular balancesheet, incomestatement and cashflow. 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. - More generally, you can declare an account's type by adding one of the + More generally, you can declare an account's type by adding one of the letters ALERX to its account directive, separated from the account name by two or more spaces. Eg: @@ -893,8 +893,8 @@ FILE FORMAT account revenues R account expenses X - Note: if you ever override the types of those auto-detected english - account names mentioned above, you might need to help the reports a + Note: if you ever override the types of those auto-detected english + account names mentioned above, you might need to help the reports a bit: ; make "liabilities" not have the liability type, who knows why @@ -907,22 +907,22 @@ FILE FORMAT ) Account comments - An account directive can also have indented comments on following + An account directive can also have indented comments on following lines, eg: account assets:bank:checking ; acctno:12345 ; a comment - We also allow (and ignore) Ledger-style subdirectives, with no leading + We also allow (and ignore) Ledger-style subdirectives, with no leading semicolon, for compatibility. - Tags in account comments, like acctno above, currently have no effect. + Tags in account comments, like acctno above, currently have no effect. Account display order - Account directives also set the order in which accounts are displayed - in reports, the hledger-ui accounts screen, the hledger-web sidebar, - etc. Normally accounts are listed in alphabetical order, but if you + Account directives also set the order in which accounts are displayed + in reports, the hledger-ui accounts screen, the hledger-web sidebar, + etc. Normally accounts are listed in alphabetical order, but if you have eg these account directives in the journal: account assets @@ -931,7 +931,7 @@ FILE FORMAT account revenues account expenses - you'll see those accounts listed in declaration order, not alphabeti- + you'll see those accounts listed in declaration order, not alphabeti- cally: $ hledger accounts -1 @@ -943,16 +943,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). @@ -971,14 +971,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 + do not affect account names being entered via hledger add or hledger-web. See also Cookbook: 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 @@ -986,54 +986,54 @@ 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 - replace any occurrence of the old account name with the new one. Sub- + OLD and NEW are case sensitive full account names. hledger will + replace any occurrence of the old account name with the new one. Sub- accounts 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. 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 Default parent account - 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 @@ -1050,7 +1050,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 @@ -1059,18 +1059,18 @@ 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 + Periodic transaction rules describe transactions that recur. They allow you to generate future transactions for forecasting, without hav- - ing to write them out explicitly in the journal (with --forecast). + ing to write them out explicitly in the journal (with --forecast). Secondly, they also can be used to define budget goals (with --budget). A periodic transaction rule looks like a normal journal entry, with the @@ -1081,89 +1081,88 @@ 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 + 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. - Period expressions must be terminated by two or more spaces if followed - by additional fields. For example, the periodic transaction given - below includes a transaction description "paycheck", which is separated - from the period expression by a double space. If not for the second - space, hledger would attempt (and fail) to parse "paycheck" as a part - of the period expression. + Two spaces after the period expression + 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: - ; 2 or more spaces - ; || - ; vv - ~ every 2 weeks from 2018/6/4 to 2018/9 paycheck + ; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020" + ; || + ; vv + ~ every 2 months in 2020, we will review assets:bank:checking $1500 income:acme inc Forecasting with periodic transactions - With the --forecast flag, each periodic transaction rule generates + With the --forecast flag, each periodic transaction rule generates future 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 named recur, whose value is + saved in the journal, but appear in all reports. They will look like + normal transactions, but with an extra tag named recur, whose value is the generating period expression. - 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 Cookbook: Budgeting + For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. Transaction Modifiers - Transaction modifier rules describe changes that should be applied - automatically to certain transactions. Currently, this means adding + Transaction modifier rules describe changes that should be applied + automatically to certain transactions. Currently, this means adding extra postings (also known as "automated postings"). Transaction modi- fiers are enabled by the --auto flag. - A transaction modifier rule looks quite like a normal transaction, - except the first line is an equals sign followed by a query that - matches certain postings (mnemonic: = suggests matching). And each + A transaction modifier rule looks quite like a normal transaction, + except the first line is an equals sign followed by a query that + matches certain postings (mnemonic: = suggests matching). And each "posting" is actually a posting-generating rule: = QUERY @@ -1174,17 +1173,17 @@ FILE FORMAT The posting rules look just 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. @@ -1220,16 +1219,16 @@ FILE FORMAT assets:checking $20 Postings added by transaction modifiers participate in transaction bal- - ancing, missing amount inference and balance assertions, like regular + ancing, missing amount inference and balance assertions, like regular postings. 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: @@ -1248,7 +1247,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) @@ -1262,7 +1261,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)