diff --git a/CHANGES.md b/CHANGES.md --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,11 @@ Internal/api/developer-ish changes in the hledger-lib (and hledger) packages. For user-visible changes, see the hledger package changelog. +# 1.20.1 2020-12-15 + +- renamed: updateReportSpecFromOpts -> updateReportSpec[With] + + # 1.20 2020-12-05 diff --git a/Hledger/Data/Account.hs b/Hledger/Data/Account.hs --- a/Hledger/Data/Account.hs +++ b/Hledger/Data/Account.hs @@ -203,8 +203,9 @@ sortAccountTreeByAmount normalsign = mapAccounts $ \a -> a{asubs=sortSubs $ asubs a} where sortSubs = case normalsign of - NormallyPositive -> sortOn (Down . normaliseMixedAmountSquashPricesForDisplay . aibalance) - NormallyNegative -> sortOn ( normaliseMixedAmountSquashPricesForDisplay . aibalance) + NormallyPositive -> sortOn (\a -> (Down $ amt a, aname a)) + NormallyNegative -> sortOn (\a -> (amt a, aname a)) + amt = normaliseMixedAmountSquashPricesForDisplay . aibalance -- | Add extra info for this account derived from the Journal's -- account directives, if any (comment, tags, declaration order..). diff --git a/Hledger/Reports/MultiBalanceReport.hs b/Hledger/Reports/MultiBalanceReport.hs --- a/Hledger/Reports/MultiBalanceReport.hs +++ b/Hledger/Reports/MultiBalanceReport.hs @@ -434,19 +434,20 @@ report = reportPercent ropts $ PeriodicReport colspans sortedrows totalsrow -- | Build the report rows. --- -- One row per account, with account name info, row amounts, row total and row average. +-- Rows are unsorted. buildReportRows :: ReportOpts -> HashMap AccountName DisplayName -> HashMap AccountName (Map DateSpan Account) -> [MultiBalanceReportRow] -buildReportRows ropts displaynames = toList . HM.mapMaybeWithKey mkRow +buildReportRows ropts displaynames = + toList . HM.mapMaybeWithKey mkRow -- toList of HashMap's Foldable instance - does not sort consistently where mkRow name accts = do displayname <- HM.lookup name displaynames return $ PeriodicReportRow displayname rowbals rowtot rowavg where - rowbals = map balance $ toList accts + rowbals = map balance $ toList accts -- toList of Map's Foldable instance - does sort by key -- The total and average for the row. -- These are always simply the sum/average of the displayed row amounts. -- Total for a cumulative/historical report is always the last column. @@ -526,11 +527,11 @@ sortedaccounttree = sortAccountTreeByAmount (fromMaybe NormallyPositive $ normalbalance_ ropts) accounttreewithbals sortedanames = map aname $ drop 1 $ flattenAccounts sortedaccounttree - -- Sort the report rows, representing a flat account list, by row total. + -- Sort the report rows, representing a flat account list, by row total (and then account name). sortFlatMBRByAmount :: [MultiBalanceReportRow] -> [MultiBalanceReportRow] - sortFlatMBRByAmount = case normalbalance_ ropts of - Just NormallyNegative -> sortOn amt - _ -> sortOn (Down . amt) + sortFlatMBRByAmount = case fromMaybe NormallyPositive $ normalbalance_ ropts of + NormallyPositive -> sortOn (\r -> (Down $ amt r, prrFullName r)) + NormallyNegative -> sortOn (\r -> (amt r, prrFullName r)) where amt = normaliseMixedAmountSquashPricesForDisplay . prrTotal -- Sort the report rows by account declaration order then account name. diff --git a/Hledger/Reports/ReportOptions.hs b/Hledger/Reports/ReportOptions.hs --- a/Hledger/Reports/ReportOptions.hs +++ b/Hledger/Reports/ReportOptions.hs @@ -18,7 +18,8 @@ rawOptsToReportOpts, defreportspec, reportOptsToSpec, - updateReportSpecFromOpts, + updateReportSpec, + updateReportSpecWith, rawOptsToReportSpec, flat_, tree_, @@ -245,12 +246,16 @@ , rsQueryOpts = queryopts } --- | Regenerate a ReportSpec after updating ReportOpts, or return an error --- message if there is a problem such as missing or unparseable options data. --- This helps keep the ReportSpec, its underlying ReportOpts, and the ReportOpts' --- data fields like querystring_ all in sync. -updateReportSpecFromOpts :: (ReportOpts -> ReportOpts) -> ReportSpec -> Either String ReportSpec -updateReportSpecFromOpts f rspec = reportOptsToSpec (rsToday rspec) . f $ rsOpts rspec +-- | Update the ReportOpts and the fields derived from it in a ReportSpec, +-- or return an error message if there is a problem such as missing or +-- unparseable options data. This is the safe way to change a ReportSpec, +-- ensuring that all fields (rsQuery, rsOpts, querystring_, etc.) are in sync. +updateReportSpec :: ReportOpts -> ReportSpec -> Either String ReportSpec +updateReportSpec ropts rspec = reportOptsToSpec (rsToday rspec) ropts + +-- | Like updateReportSpec, but takes a ReportOpts-modifying function. +updateReportSpecWith :: (ReportOpts -> ReportOpts) -> ReportSpec -> Either String ReportSpec +updateReportSpecWith f rspec = reportOptsToSpec (rsToday rspec) . f $ rsOpts rspec -- | Generate a ReportSpec from RawOpts and the current date. rawOptsToReportSpec :: RawOpts -> IO ReportSpec diff --git a/Hledger/Utils/Debug.hs b/Hledger/Utils/Debug.hs --- a/Hledger/Utils/Debug.hs +++ b/Hledger/Utils/Debug.hs @@ -1,31 +1,19 @@ {-# LANGUAGE FlexibleContexts, TypeFamilies #-} -{- | Debugging helpers. +{- | -You can enable increasingly verbose debug output by adding --debug [1-9] -to a hledger command line. --debug with no argument means --debug 1. -This is implemented by calling dbgN or similar helpers, defined below. -These calls can be found throughout hledger code; they have been added -organically where it seemed likely they would be needed again. -The choice of debug level has not been very systematic. -202006 Here's a start at some guidelines, not yet applied project-wide: +Helpers for debug output and pretty-printing +(using pretty-simple, with which there may be some overlap). +This module also exports Debug.Trace. -Debug level: What to show: ------------- --------------------------------------------------------- -0 normal command output only (no warnings, eg) -1 (--debug) useful warnings, most common troubleshooting info, eg valuation -2 common troubleshooting info, more detail -3 report options selection -4 report generation -5 report generation, more detail -6 input file reading -7 input file reading, more detail -8 command line parsing -9 any other rarely needed / more in-depth info +@dbg0@-@dbg9@ will pretty-print values to stderr +if the program was run with a sufficiently high @--debug=N@ argument. +(@--debug@ with no argument means @--debug=1@; @dbg0@ always prints). -Tip: when debugging with GHCI, the first run after loading Debug.hs sets the -debug level. If you need to change it, you must touch Debug.hs, :reload in GHCI, -then run the command with a new --debug value. Or, often it's more convenient -to add a temporary dbg0 and :reload (dbg0 always prints). +The @debugLevel@ global is set once at startup using unsafePerformIO. +In GHCI, this happens only on the first run of :main, so if you want +to change the debug level without restarting GHCI, +save a dummy change in Debug.hs and do a :reload. +(Sometimes it's more convenient to temporarily add dbg0's and :reload.) -} @@ -36,15 +24,20 @@ -- http://hackage.haskell.org/packages/archive/traced/2009.7.20/doc/html/Debug-Traced.html module Hledger.Utils.Debug ( + -- * Pretty printing pprint ,pshow - ,ptrace + -- * Tracing ,traceWith + -- * Pretty tracing + ,ptrace + -- ** Debug-level-aware tracing + ,debugLevel ,traceAt ,traceAtWith - ,debugLevel ,ptraceAt ,ptraceAtWith + -- ** Easiest form (recommended) ,dbg0 ,dbg1 ,dbg2 @@ -55,6 +48,8 @@ ,dbg7 ,dbg8 ,dbg9 + ,dbgExit + -- ** More control ,dbg0With ,dbg1With ,dbg2With @@ -65,7 +60,7 @@ ,dbg7With ,dbg8With ,dbg9With - ,dbgExit + -- ** For standalone lines in IO blocks ,ptraceAtIO ,dbg0IO ,dbg1IO @@ -77,8 +72,10 @@ ,dbg7IO ,dbg8IO ,dbg9IO + -- ** Trace to a file ,plog ,plogAt + -- ** Trace the state of hledger parsers ,traceParse ,dbgparse ,module Debug.Trace @@ -134,8 +131,6 @@ -- unsafePerformIO and can be accessed from anywhere and before normal -- command-line processing. When running with :main in GHCI, you must -- touch and reload this module to see the effect of a new --debug option. --- After command-line processing, it is also available as the @debug_@ --- field of 'Hledger.Cli.CliOptions.CliOpts'. -- {-# OPTIONS_GHC -fno-cse #-} -- {-# NOINLINE debugLevel #-} debugLevel :: Int @@ -223,6 +218,10 @@ dbg9 :: Show a => String -> a -> a dbg9 = ptraceAt 9 +-- | Like dbg0, but also exit the program. Uses unsafePerformIO. +dbgExit :: Show a => String -> a -> a +dbgExit msg = const (unsafePerformIO exitFailure) . dbg0 msg + -- | Like dbg0, but takes a custom show function instead of a label. dbg0With :: Show a => (a -> String) -> a -> a dbg0With = ptraceAtWith 0 @@ -254,10 +253,6 @@ dbg9With :: Show a => (a -> String) -> a -> a dbg9With = ptraceAtWith 9 --- | Like dbg0, but also exit the program. Uses unsafePerformIO. -dbgExit :: Show a => String -> a -> a -dbgExit msg = const (unsafePerformIO exitFailure) . dbg0 msg - -- | Like ptraceAt, but convenient to insert in an IO monad and -- enforces monadic sequencing (plus convenience aliases). -- XXX These have a bug; they should use @@ -308,8 +303,8 @@ -- | Log a label and a pretty-printed showable value to ./debug.log, -- if the global debug level is at or above the specified level. -- At level 0, always logs. Otherwise, uses unsafePerformIO. --- Tends to fail if called more than once, at least when built with -threaded --- (Exception: debug.log: openFile: resource busy (file is locked)). +-- Tends to fail if called more than once too quickly, at least when built with -threaded +-- ("Exception: debug.log: openFile: resource busy (file is locked)"). plogAt :: Show a => Int -> String -> a -> a plogAt lvl | lvl > 0 && debugLevel < lvl = flip const @@ -332,7 +327,7 @@ -- `seq` a -- | Print the provided label (if non-null) and current parser state --- (position and next input) to the console. (See also megaparsec's dbg.) +-- (position and next input) to the console. See also megaparsec's dbg. traceParse :: String -> TextParser m () traceParse msg = do pos <- getSourcePos diff --git a/hledger-lib.cabal b/hledger-lib.cabal --- a/hledger-lib.cabal +++ b/hledger-lib.cabal @@ -4,10 +4,10 @@ -- -- see: https://github.com/sol/hpack -- --- hash: 496cff1a1bc952e36c246f175d8efcb4c6cab6e9adc79c17b2d1e8b71ddaa2e5 +-- hash: ca5acbb51137f6a05e911a261649e99feab3663ce6e1c4616d29245938828f40 name: hledger-lib -version: 1.20 +version: 1.20.1 synopsis: A reusable library providing the core functionality of hledger description: A reusable library containing hledger's core functionality. This is used by most hledger* packages so that they support the same diff --git a/hledger_csv.5 b/hledger_csv.5 --- a/hledger_csv.5 +++ b/hledger_csv.5 @@ -1,6 +1,6 @@ .\"t -.TH "hledger_csv" "5" "November 2020" "hledger 1.20" "hledger User Manuals" +.TH "hledger_csv" "5" "December 2020" "hledger 1.20.1" "hledger User Manuals" @@ -1290,13 +1290,11 @@ .SH COPYRIGHT -Copyright (C) 2007-2019 Simon Michael. +Copyright (C) 2007-2020 Simon Michael. .br Released under GNU GPL v3 or later. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger(1), hledger\-ui(1), hledger\-web(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) - -http://hledger.org diff --git a/hledger_csv.info b/hledger_csv.info --- a/hledger_csv.info +++ b/hledger_csv.info @@ -3,8 +3,8 @@  File: hledger_csv.info, Node: Top, Next: EXAMPLES, Up: (dir) -hledger_csv(5) hledger 1.20 -*************************** +hledger_csv(5) hledger 1.20.1 +***************************** CSV - how hledger reads CSV data, and the CSV rules file format @@ -60,11 +60,37 @@ * Menu: * EXAMPLES:: +* Basic:: +* Bank of Ireland:: +* Amazon:: +* Paypal:: * CSV RULES:: +* skip:: +* fields:: +* field assignment:: +* separator:: +* if block:: +* if table:: +* end:: +* date-format:: +* decimal-mark:: +* newest-first:: +* include:: +* balance-type:: * TIPS:: +* Rapid feedback:: +* Valid CSV:: +* File Extension:: +* Reading multiple CSV files:: +* Valid transactions:: +* Deduplicating importing:: +* Setting amounts:: +* Setting currency/commodity:: +* Referencing other fields:: +* How CSV rules are evaluated::  -File: hledger_csv.info, Node: EXAMPLES, Next: CSV RULES, Prev: Top, Up: Top +File: hledger_csv.info, Node: EXAMPLES, Next: Basic, Prev: Top, Up: Top 1 EXAMPLES ********** @@ -73,18 +99,11 @@ collection at: https://github.com/simonmichael/hledger/tree/master/examples/csv -* Menu: - -* Basic:: -* Bank of Ireland:: -* Amazon:: -* Paypal:: -  -File: hledger_csv.info, Node: Basic, Next: Bank of Ireland, Up: EXAMPLES +File: hledger_csv.info, Node: Basic, Next: Bank of Ireland, Prev: EXAMPLES, Up: Top -1.1 Basic -========= +2 Basic +******* At minimum, the rules file must identify the date and amount fields, and often it also specifies the date format and how many header lines there @@ -106,10 +125,10 @@ Default account names are chosen, since we didn't set them.  -File: hledger_csv.info, Node: Bank of Ireland, Next: Amazon, Prev: Basic, Up: EXAMPLES +File: hledger_csv.info, Node: Bank of Ireland, Next: Amazon, Prev: Basic, Up: Top -1.2 Bank of Ireland -=================== +3 Bank of Ireland +***************** Here's a CSV with two amount fields (Debit and Credit), and a balance field, which we can use to add balance assertions, which is not @@ -159,10 +178,10 @@ imported into a journal file.  -File: hledger_csv.info, Node: Amazon, Next: Paypal, Prev: Bank of Ireland, Up: EXAMPLES +File: hledger_csv.info, Node: Amazon, Next: Paypal, Prev: Bank of Ireland, Up: Top -1.3 Amazon -========== +4 Amazon +******** Here we convert amazon.com order history, and use an if block to generate a third posting if there's a fee. (In practice you'd probably @@ -217,10 +236,10 @@ expenses:fees $1.00  -File: hledger_csv.info, Node: Paypal, Prev: Amazon, Up: EXAMPLES +File: hledger_csv.info, Node: Paypal, Next: CSV RULES, Prev: Amazon, Up: Top -1.4 Paypal -========== +5 Paypal +******** Here's a real-world rules file for (customised) Paypal CSV, with some Paypal-specific rules, and a second rules file included: @@ -371,34 +390,19 @@ expenses:banking:paypal $0.59 ; business:  -File: hledger_csv.info, Node: CSV RULES, Next: TIPS, Prev: EXAMPLES, Up: Top +File: hledger_csv.info, Node: CSV RULES, Next: skip, Prev: Paypal, Up: Top -2 CSV RULES +6 CSV RULES *********** The following kinds of rule can appear in the rules file, in any order. Blank lines and lines beginning with '#' or ';' are ignored. -* Menu: - -* skip:: -* fields:: -* field assignment:: -* separator:: -* if block:: -* if table:: -* end:: -* date-format:: -* decimal-mark:: -* newest-first:: -* include:: -* balance-type:: -  -File: hledger_csv.info, Node: skip, Next: fields, Up: CSV RULES +File: hledger_csv.info, Node: skip, Next: fields, Prev: CSV RULES, Up: Top -2.1 'skip' -========== +7 'skip' +******** skip N @@ -411,10 +415,10 @@ ignore certain CSV records (described below).  -File: hledger_csv.info, Node: fields, Next: field assignment, Prev: skip, Up: CSV RULES +File: hledger_csv.info, Node: fields, Next: field assignment, Prev: skip, Up: Top -2.2 'fields' -============ +8 'fields' +********** fields FIELDNAME1, FIELDNAME2, ... @@ -453,8 +457,8 @@  File: hledger_csv.info, Node: Transaction field names, Next: Posting field names, Up: fields -2.2.1 Transaction field names ------------------------------ +8.1 Transaction field names +=========================== 'date', 'date2', 'status', 'code', 'description', 'comment' can be used to form the transaction's first line. @@ -462,8 +466,8 @@  File: hledger_csv.info, Node: Posting field names, Prev: Transaction field names, Up: fields -2.2.2 Posting field names -------------------------- +8.2 Posting field names +======================= * Menu: @@ -476,8 +480,8 @@  File: hledger_csv.info, Node: account, Next: amount, Up: Posting field names -2.2.2.1 account -............... +8.2.1 account +------------- 'accountN', where N is 1 to 99, causes a posting to be generated, with that account name. @@ -494,8 +498,8 @@  File: hledger_csv.info, Node: amount, Next: currency, Prev: account, Up: Posting field names -2.2.2.2 amount -.............. +8.2.2 amount +------------ 'amountN' sets posting N's amount. If the CSV uses separate fields for inflows and outflows, you can use 'amountN-in' and 'amountN-out' @@ -521,8 +525,8 @@  File: hledger_csv.info, Node: currency, Next: balance, Prev: amount, Up: Posting field names -2.2.2.3 currency -................ +8.2.3 currency +-------------- If the CSV has the currency symbol in a separate field (ie, not part of the amount field), you can use 'currencyN' to prepend it to posting N's @@ -531,8 +535,8 @@  File: hledger_csv.info, Node: balance, Next: comment, Prev: currency, Up: Posting field names -2.2.2.4 balance -............... +8.2.4 balance +------------- 'balanceN' sets a balance assertion amount (or if the posting amount is left empty, a balance assignment) on posting N. @@ -546,8 +550,8 @@  File: hledger_csv.info, Node: comment, Prev: balance, Up: Posting field names -2.2.2.5 comment -............... +8.2.5 comment +------------- Finally, 'commentN' sets a comment on the Nth posting. Comments can also contain tags, as usual. @@ -555,10 +559,10 @@ See TIPS below for more about setting amounts and currency.  -File: hledger_csv.info, Node: field assignment, Next: separator, Prev: fields, Up: CSV RULES +File: hledger_csv.info, Node: field assignment, Next: separator, Prev: fields, Up: Top -2.3 field assignment -==================== +9 field assignment +****************** HLEDGERFIELDNAME FIELDVALUE @@ -580,10 +584,10 @@ referencing other fields.  -File: hledger_csv.info, Node: separator, Next: if block, Prev: field assignment, Up: CSV RULES +File: hledger_csv.info, Node: separator, Next: if block, Prev: field assignment, Up: Top -2.4 'separator' -=============== +10 'separator' +************** You can use the 'separator' rule to read other kinds of character-separated data. The argument is any single separator @@ -605,10 +609,10 @@ inferred automatically, and you won't need this rule.  -File: hledger_csv.info, Node: if block, Next: if table, Prev: separator, Up: CSV RULES +File: hledger_csv.info, Node: if block, Next: if table, Prev: separator, Up: Top -2.5 'if' block -============== +11 'if' block +************* if MATCHER RULE @@ -635,8 +639,8 @@  File: hledger_csv.info, Node: Matching the whole record, Next: Matching individual fields, Up: if block -2.5.1 Matching the whole record -------------------------------- +11.1 Matching the whole record +============================== Each MATCHER can be a record matcher, which looks like this: @@ -658,8 +662,8 @@  File: hledger_csv.info, Node: Matching individual fields, Next: Combining matchers, Prev: Matching the whole record, Up: if block -2.5.2 Matching individual fields --------------------------------- +11.2 Matching individual fields +=============================== Or, MATCHER can be a field matcher, like this: @@ -672,8 +676,8 @@  File: hledger_csv.info, Node: Combining matchers, Next: Rules applied on successful match, Prev: Matching individual fields, Up: if block -2.5.3 Combining matchers ------------------------- +11.3 Combining matchers +======================= A single matcher can be written on the same line as the "if"; or multiple matchers can be written on the following lines, non-indented. @@ -689,8 +693,8 @@  File: hledger_csv.info, Node: Rules applied on successful match, Prev: Combining matchers, Up: if block -2.5.4 Rules applied on successful match ---------------------------------------- +11.4 Rules applied on successful match +====================================== After the patterns there should be one or more rules to apply, all indented by at least one space. Three kinds of rule are allowed in @@ -715,10 +719,10 @@ comment XXX deductible ? check it  -File: hledger_csv.info, Node: if table, Next: end, Prev: if block, Up: CSV RULES +File: hledger_csv.info, Node: if table, Next: end, Prev: if block, Up: Top -2.6 'if' table -============== +12 'if' table +************* if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn MATCHER1,VALUE11,VALUE12,...,VALUE1n @@ -776,10 +780,10 @@ 2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out  -File: hledger_csv.info, Node: end, Next: date-format, Prev: if table, Up: CSV RULES +File: hledger_csv.info, Node: end, Next: date-format, Prev: if table, Up: Top -2.7 'end' -========= +13 'end' +******** 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 @@ -790,10 +794,10 @@ end  -File: hledger_csv.info, Node: date-format, Next: decimal-mark, Prev: end, Up: CSV RULES +File: hledger_csv.info, Node: date-format, Next: decimal-mark, Prev: end, Up: Top -2.8 'date-format' -================= +14 'date-format' +**************** date-format DATEFMT @@ -821,10 +825,10 @@ https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime  -File: hledger_csv.info, Node: decimal-mark, Next: newest-first, Prev: date-format, Up: CSV RULES +File: hledger_csv.info, Node: decimal-mark, Next: newest-first, Prev: date-format, Up: Top -2.9 'decimal-mark' -================== +15 'decimal-mark' +***************** decimal-mark . @@ -839,10 +843,10 @@ misparsed numbers.  -File: hledger_csv.info, Node: newest-first, Next: include, Prev: decimal-mark, Up: CSV RULES +File: hledger_csv.info, Node: newest-first, Next: include, Prev: decimal-mark, Up: Top -2.10 'newest-first' -=================== +16 '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, @@ -861,10 +865,10 @@ newest-first  -File: hledger_csv.info, Node: include, Next: balance-type, Prev: newest-first, Up: CSV RULES +File: hledger_csv.info, Node: include, Next: balance-type, Prev: newest-first, Up: Top -2.11 'include' -============== +17 'include' +************ include RULESFILE @@ -875,19 +879,19 @@ # someaccount.csv.rules -## someaccount-specific rules +# someaccount-specific rules fields date,description,amount account1 assets:someaccount account2 expenses:misc -## common rules +# common rules include categorisation.rules  -File: hledger_csv.info, Node: balance-type, Prev: include, Up: CSV RULES +File: hledger_csv.info, Node: balance-type, Next: TIPS, Prev: include, Up: Top -2.12 'balance-type' -=================== +18 'balance-type' +***************** Balance assertions generated by assigning to balanceN are of the simple '=' type by default, which is a single-commodity, subaccount-excluding @@ -907,29 +911,16 @@ ==* multi commodity, include subaccounts  -File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top - -3 TIPS -****** - -* Menu: +File: hledger_csv.info, Node: TIPS, Next: Rapid feedback, Prev: balance-type, Up: Top -* Rapid feedback:: -* Valid CSV:: -* File Extension:: -* Reading multiple CSV files:: -* Valid transactions:: -* Deduplicating importing:: -* Setting amounts:: -* Setting currency/commodity:: -* Referencing other fields:: -* How CSV rules are evaluated:: +19 TIPS +*******  -File: hledger_csv.info, Node: Rapid feedback, Next: Valid CSV, Up: TIPS +File: hledger_csv.info, Node: Rapid feedback, Next: Valid CSV, Prev: TIPS, Up: Top -3.1 Rapid feedback -================== +20 Rapid feedback +***************** It's a good idea to get rapid feedback while creating/troubleshooting CSV rules. Here's a good way, using entr from @@ -943,10 +934,10 @@ output.  -File: hledger_csv.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: TIPS +File: hledger_csv.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Top -3.2 Valid CSV -============= +21 Valid CSV +************ hledger accepts CSV conforming to RFC 4180. When CSV values are enclosed in quotes, note: @@ -955,10 +946,10 @@ * spaces outside the quotes are not allowed  -File: hledger_csv.info, Node: File Extension, Next: Reading multiple CSV files, Prev: Valid CSV, Up: TIPS +File: hledger_csv.info, Node: File Extension, Next: Reading multiple CSV files, Prev: Valid CSV, Up: Top -3.3 File Extension -================== +22 File Extension +***************** To help hledger identify the format and show the right error messages, CSV/SSV/TSV files should normally be named with a '.csv', '.ssv' or @@ -975,10 +966,10 @@ See also: Input files in the hledger manual.  -File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: File Extension, Up: TIPS +File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: File Extension, Up: Top -3.4 Reading multiple CSV files -============================== +23 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 @@ -986,10 +977,10 @@ used for all the CSV files.  -File: hledger_csv.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: TIPS +File: hledger_csv.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: Top -3.5 Valid transactions -====================== +24 Valid transactions +********************* After reading a CSV file, hledger post-processes and validates the generated journal entries as it would for a journal file - balancing @@ -1005,10 +996,10 @@ $ hledger -f file.csv print | hledger -f- print  -File: hledger_csv.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: TIPS +File: hledger_csv.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Top -3.6 Deduplicating, importing -============================ +25 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 some @@ -1035,10 +1026,10 @@ * https://plaintextaccounting.org -> data import/conversion  -File: hledger_csv.info, Node: Setting amounts, Next: Setting currency/commodity, Prev: Deduplicating importing, Up: TIPS +File: hledger_csv.info, Node: Setting amounts, Next: Setting currency/commodity, Prev: Deduplicating importing, Up: Top -3.7 Setting amounts -=================== +26 Setting amounts +****************** A posting amount can be set in one of these ways: @@ -1064,10 +1055,10 @@ * If an amount value begins with a plus sign, that will be removed  -File: hledger_csv.info, Node: Setting currency/commodity, Next: Referencing other fields, Prev: Setting amounts, Up: TIPS +File: hledger_csv.info, Node: Setting currency/commodity, Next: Referencing other fields, Prev: Setting amounts, Up: Top -3.8 Setting currency/commodity -============================== +27 Setting currency/commodity +***************************** If the currency/commodity symbol is included in the CSV's amount field(s): @@ -1112,10 +1103,10 @@ that would trigger the prepending effect, which we don't want here.  -File: hledger_csv.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Setting currency/commodity, Up: TIPS +File: hledger_csv.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Setting currency/commodity, Up: Top -3.9 Referencing other fields -============================ +28 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 @@ -1149,10 +1140,10 @@ comment C  -File: hledger_csv.info, Node: How CSV rules are evaluated, Prev: Referencing other fields, Up: TIPS +File: hledger_csv.info, Node: How CSV rules are evaluated, Prev: Referencing other fields, Up: Top -3.10 How CSV rules are evaluated -================================ +29 How CSV rules are evaluated +****************************** Here's how to think of CSV rules being evaluated (if you really need to). First, @@ -1192,86 +1183,86 @@  Tag Table: Node: Top72 -Node: EXAMPLES2787 -Ref: #examples2893 -Node: Basic3101 -Ref: #basic3201 -Node: Bank of Ireland3743 -Ref: #bank-of-ireland3878 -Node: Amazon5340 -Ref: #amazon5458 -Node: Paypal7177 -Ref: #paypal7271 -Node: CSV RULES14915 -Ref: #csv-rules15024 -Node: skip15336 -Ref: #skip15429 -Node: fields15804 -Ref: #fields15926 -Node: Transaction field names17091 -Ref: #transaction-field-names17251 -Node: Posting field names17362 -Ref: #posting-field-names17514 -Node: account17584 -Ref: #account17700 -Node: amount18237 -Ref: #amount18368 -Node: currency19475 -Ref: #currency19610 -Node: balance19816 -Ref: #balance19950 -Node: comment20267 -Ref: #comment20384 -Node: field assignment20547 -Ref: #field-assignment20690 -Node: separator21508 -Ref: #separator21643 -Node: if block22183 -Ref: #if-block22308 -Node: Matching the whole record22709 -Ref: #matching-the-whole-record22884 -Node: Matching individual fields23688 -Ref: #matching-individual-fields23892 -Node: Combining matchers24116 -Ref: #combining-matchers24312 -Node: Rules applied on successful match24625 -Ref: #rules-applied-on-successful-match24816 -Node: if table25470 -Ref: #if-table25589 -Node: end27327 -Ref: #end27439 -Node: date-format27663 -Ref: #date-format27795 -Node: decimal-mark28544 -Ref: #decimal-mark28687 -Node: newest-first29026 -Ref: #newest-first29167 -Node: include29850 -Ref: #include29981 -Node: balance-type30425 -Ref: #balance-type30545 -Node: TIPS31245 -Ref: #tips31327 -Node: Rapid feedback31583 -Ref: #rapid-feedback31700 -Node: Valid CSV32160 -Ref: #valid-csv32290 -Node: File Extension32482 -Ref: #file-extension32634 -Node: Reading multiple CSV files33063 -Ref: #reading-multiple-csv-files33248 -Node: Valid transactions33489 -Ref: #valid-transactions33667 -Node: Deduplicating importing34295 -Ref: #deduplicating-importing34474 -Node: Setting amounts35507 -Ref: #setting-amounts35676 -Node: Setting currency/commodity36663 -Ref: #setting-currencycommodity36855 -Node: Referencing other fields38029 -Ref: #referencing-other-fields38229 -Node: How CSV rules are evaluated39126 -Ref: #how-csv-rules-are-evaluated39299 +Node: EXAMPLES3257 +Ref: #examples3359 +Node: Basic3505 +Ref: #basic3613 +Node: Bank of Ireland4155 +Ref: #bank-of-ireland4281 +Node: Amazon5743 +Ref: #amazon5852 +Node: Paypal7571 +Ref: #paypal7674 +Node: CSV RULES15318 +Ref: #csv-rules15425 +Node: skip15559 +Ref: #skip15660 +Node: fields16035 +Ref: #fields16147 +Node: Transaction field names17312 +Ref: #transaction-field-names17468 +Node: Posting field names17579 +Ref: #posting-field-names17727 +Node: account17797 +Ref: #account17909 +Node: amount18446 +Ref: #amount18573 +Node: currency19680 +Ref: #currency19811 +Node: balance20017 +Ref: #balance20147 +Node: comment20464 +Ref: #comment20577 +Node: field assignment20740 +Ref: #field-assignment20873 +Node: separator21691 +Ref: #separator21818 +Node: if block22358 +Ref: #if-block22475 +Node: Matching the whole record22876 +Ref: #matching-the-whole-record23049 +Node: Matching individual fields23853 +Ref: #matching-individual-fields24055 +Node: Combining matchers24279 +Ref: #combining-matchers24473 +Node: Rules applied on successful match24786 +Ref: #rules-applied-on-successful-match24975 +Node: if table25629 +Ref: #if-table25740 +Node: end27478 +Ref: #end27582 +Node: date-format27806 +Ref: #date-format27930 +Node: decimal-mark28679 +Ref: #decimal-mark28814 +Node: newest-first29153 +Ref: #newest-first29284 +Node: include29967 +Ref: #include30088 +Node: balance-type30530 +Ref: #balance-type30653 +Node: TIPS31353 +Ref: #tips31463 +Node: Rapid feedback31463 +Ref: #rapid-feedback31590 +Node: Valid CSV32050 +Ref: #valid-csv32177 +Node: File Extension32369 +Ref: #file-extension32518 +Node: Reading multiple CSV files32947 +Ref: #reading-multiple-csv-files33129 +Node: Valid transactions33370 +Ref: #valid-transactions33545 +Node: Deduplicating importing34173 +Ref: #deduplicating-importing34349 +Node: Setting amounts35382 +Ref: #setting-amounts35548 +Node: Setting currency/commodity36535 +Ref: #setting-currencycommodity36724 +Node: Referencing other fields37898 +Ref: #referencing-other-fields38095 +Node: How CSV rules are evaluated38992 +Ref: #how-csv-rules-are-evaluated39160  End Tag Table diff --git a/hledger_csv.txt b/hledger_csv.txt --- a/hledger_csv.txt +++ b/hledger_csv.txt @@ -946,17 +946,14 @@ COPYRIGHT - Copyright (C) 2007-2019 Simon Michael. + Copyright (C) 2007-2020 Simon Michael. Released under GNU GPL v3 or later. SEE ALSO - 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) - - http://hledger.org + hledger(1), hledger-ui(1), hledger-web(1), hledger_csv(5), + hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) -hledger 1.20 November 2020 hledger_csv(5) +hledger 1.20.1 December 2020 hledger_csv(5) diff --git a/hledger_journal.5 b/hledger_journal.5 --- a/hledger_journal.5 +++ b/hledger_journal.5 @@ -1,6 +1,6 @@ .\"t -.TH "hledger_journal" "5" "November 2020" "hledger 1.20" "hledger User Manuals" +.TH "hledger_journal" "5" "December 2020" "hledger 1.20.1" "hledger User Manuals" @@ -1856,8 +1856,6 @@ They allow hledger to generate temporary future transactions to help with forecasting, so you don\[aq]t have to write out each one in the journal, and it\[aq]s easy to try out different forecasts. -Secondly, they are also used to define the budgets shown in budget -reports. .PP Periodic transactions can be a little tricky, so before you use them, read this whole section - or at least these tips: @@ -1891,6 +1889,9 @@ \f[C]\[ti] every 10th day of month from 2020/01\f[R], which is equivalent to \f[C]\[ti] every 10th day of month from 2020/01/01\f[R], will be adjusted to start on 2019/12/10. +.PP +Periodic transaction rules also have a second meaning: they are used to +define budget goals, shown in budget reports. .SS Periodic rule syntax .PP A periodic transaction rule looks like a normal journal entry, with the @@ -2144,13 +2145,11 @@ .SH COPYRIGHT -Copyright (C) 2007-2019 Simon Michael. +Copyright (C) 2007-2020 Simon Michael. .br Released under GNU GPL v3 or later. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger(1), hledger\-ui(1), hledger\-web(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) - -http://hledger.org diff --git a/hledger_journal.info b/hledger_journal.info --- a/hledger_journal.info +++ b/hledger_journal.info @@ -2,10 +2,10 @@ stdin.  -File: hledger_journal.info, Node: Top, Up: (dir) +File: hledger_journal.info, Node: Top, Next: Transactions, Up: (dir) -hledger_journal(5) hledger 1.20 -******************************* +hledger_journal(5) hledger 1.20.1 +********************************* Journal - hledger's default file format, representing a General Journal @@ -41,9 +41,24 @@ * Menu: * Transactions:: +* Dates:: +* Status:: +* Description:: +* Comments:: +* Tags:: +* Postings:: +* Account names:: +* Amounts:: +* Transaction prices:: +* Lot prices and lot dates:: +* Balance assertions:: +* Balance assignments:: +* Directives:: +* Periodic transactions:: +* Auto postings::  -File: hledger_journal.info, Node: Transactions, Up: Top +File: hledger_journal.info, Node: Transactions, Next: Dates, Prev: Top, Up: Top 1 Transactions ************** @@ -71,29 +86,11 @@ assets:bank:checking $1 income:salary $-1 -* Menu: - -* Dates:: -* Status:: -* Description:: -* Comments:: -* Tags:: -* Postings:: -* Account names:: -* Amounts:: -* Transaction prices:: -* Lot prices and lot dates:: -* Balance assertions:: -* Balance assignments:: -* Directives:: -* Periodic transactions:: -* Auto postings:: -  -File: hledger_journal.info, Node: Dates, Next: Status, Up: Transactions +File: hledger_journal.info, Node: Dates, Next: Status, Prev: Transactions, Up: Top -1.1 Dates -========= +2 Dates +******* * Menu: @@ -104,8 +101,8 @@  File: hledger_journal.info, Node: Simple dates, Next: Secondary dates, Up: Dates -1.1.1 Simple dates ------------------- +2.1 Simple dates +================ Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or 'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional. The year may @@ -120,8 +117,8 @@  File: hledger_journal.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates -1.1.2 Secondary dates ---------------------- +2.2 Secondary dates +=================== Real-life transactions sometimes involve more than one date - eg the date you write a cheque, and the date it clears in your bank. When you @@ -156,8 +153,8 @@  File: hledger_journal.info, Node: Posting dates, Prev: Secondary dates, Up: Dates -1.1.3 Posting dates -------------------- +2.3 Posting dates +================= You can give individual postings a different date from their parent transaction, by adding a posting comment containing a tag (see below) @@ -189,10 +186,10 @@ transaction and DATE2 infers its year from DATE.  -File: hledger_journal.info, Node: Status, Next: Description, Prev: Dates, Up: Transactions +File: hledger_journal.info, Node: Status, Next: Description, Prev: Dates, Up: Top -1.2 Status -========== +3 Status +******** Transactions, or individual postings within a transaction, can have a status mark, which is a single character before the transaction @@ -239,10 +236,10 @@ your finances.  -File: hledger_journal.info, Node: Description, Next: Comments, Prev: Status, Up: Transactions +File: hledger_journal.info, Node: Description, Next: Comments, Prev: Status, Up: Top -1.3 Description -=============== +4 Description +************* A transaction's description is the rest of the line following the date and status mark (or until a comment begins). Sometimes called the @@ -257,8 +254,8 @@  File: hledger_journal.info, Node: Payee and note, Up: Description -1.3.1 Payee and note --------------------- +4.1 Payee and note +================== You can optionally include a '|' (pipe) character in descriptions to subdivide the description into separate fields for payee/payer name on @@ -267,10 +264,10 @@ precise querying and pivoting by payee or by note.  -File: hledger_journal.info, Node: Comments, Next: Tags, Prev: Description, Up: Transactions +File: hledger_journal.info, Node: Comments, Next: Tags, Prev: Description, Up: Top -1.4 Comments -============ +5 Comments +********** Lines in the journal beginning with a semicolon (';') or hash ('#') or star ('*') are comments, and will be ignored. (Star comments cause @@ -307,10 +304,10 @@ 'end comment' directives.  -File: hledger_journal.info, Node: Tags, Next: Postings, Prev: Comments, Up: Transactions +File: hledger_journal.info, Node: Tags, Next: Postings, Prev: Comments, Up: Top -1.5 Tags -======== +6 Tags +****** Tags are a way to add extra labels or labelled data to postings and transactions, which you can then search or pivot on. @@ -350,10 +347,10 @@ are simple strings.  -File: hledger_journal.info, Node: Postings, Next: Account names, Prev: Tags, Up: Transactions +File: hledger_journal.info, Node: Postings, Next: Account names, Prev: Tags, Up: Top -1.6 Postings -============ +7 Postings +********** A posting is an addition of some amount to, or removal of some amount from, an account. Each posting line begins with at least one space or @@ -384,8 +381,8 @@  File: hledger_journal.info, Node: Virtual postings, Up: Postings -1.6.1 Virtual postings ----------------------- +7.1 Virtual postings +==================== A posting with a parenthesised account name is called a _virtual posting_ or _unbalanced posting_, which means it is exempt from the @@ -417,10 +414,10 @@ '-R/--real' flag or 'real:1' query.  -File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Transactions +File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Top -1.7 Account names -================= +8 Account names +*************** Account names typically have several parts separated by a full colon, from which hledger derives a hierarchical chart of accounts. They can @@ -435,10 +432,10 @@ Account names can be aliased.  -File: hledger_journal.info, Node: Amounts, Next: Transaction prices, Prev: Account names, Up: Transactions +File: hledger_journal.info, Node: Amounts, Next: Transaction prices, Prev: Account names, Up: Top -1.8 Amounts -=========== +9 Amounts +********* After the account name, there is usually an amount. (Important: between account name and amount, there must be *two or more spaces*.) @@ -493,8 +490,8 @@  File: hledger_journal.info, Node: Digit group marks, Next: Commodity display style, Up: Amounts -1.8.1 Digit group marks ------------------------ +9.1 Digit group marks +===================== In the integer part of the quantity (left of the decimal mark), groups of digits can optionally be separated by a "digit group mark" - a space, @@ -526,8 +523,8 @@  File: hledger_journal.info, Node: Commodity display style, Next: Rounding, Prev: Digit group marks, Up: Amounts -1.8.2 Commodity display style ------------------------------ +9.2 Commodity display style +=========================== For each commodity, hledger chooses a consistent style to use when displaying amounts. (Except price amounts, which are always displayed @@ -571,8 +568,8 @@  File: hledger_journal.info, Node: Rounding, Prev: Commodity display style, Up: Amounts -1.8.3 Rounding --------------- +9.3 Rounding +============ Amounts are stored internally as decimal numbers with up to 255 decimal places, and displayed with the number of decimal places specified by the @@ -582,10 +579,10 @@ this could vary if hledger was built with Decimal < 0.5.1.)  -File: hledger_journal.info, Node: Transaction prices, Next: Lot prices and lot dates, Prev: Amounts, Up: Transactions +File: hledger_journal.info, Node: Transaction prices, Next: Lot prices and lot dates, Prev: Amounts, Up: Top -1.9 Transaction prices -====================== +10 Transaction prices +********************* Within a transaction, you can note an amount's price in another commodity. This can be used to document the cost (in a purchase) or @@ -649,10 +646,10 @@ €100 assets:euros  -File: hledger_journal.info, Node: Lot prices and lot dates, Next: Balance assertions, Prev: Transaction prices, Up: Transactions +File: hledger_journal.info, Node: Lot prices and lot dates, Next: Balance assertions, Prev: Transaction prices, Up: Top -1.10 Lot prices and lot dates -============================= +11 Lot prices and lot dates +*************************** Ledger allows another kind of price, lot price (four variants: '{UNITPRICE}', '{{TOTALPRICE}}', '{=FIXEDUNITPRICE}', @@ -664,10 +661,10 @@ assertion if any.  -File: hledger_journal.info, Node: Balance assertions, Next: Balance assignments, Prev: Lot prices and lot dates, Up: Transactions +File: hledger_journal.info, Node: Balance assertions, Next: Balance assignments, Prev: Lot prices and lot dates, Up: Top -1.11 Balance assertions -======================= +12 Balance assertions +********************* hledger supports Ledger-style balance assertions in journal files. These look like, for example, '= EXPECTEDBALANCE' following a posting's @@ -704,8 +701,8 @@  File: hledger_journal.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance assertions -1.11.1 Assertions and ordering ------------------------------- +12.1 Assertions and ordering +============================ hledger sorts an account's postings and assertions first by date and then (for postings on the same day) by parse order. Note this is @@ -723,8 +720,8 @@  File: hledger_journal.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance assertions -1.11.2 Assertions and included files ------------------------------------- +12.2 Assertions and included files +================================== With included files, things are a little more complicated. Including preserves the ordering of postings and assertions. If you have multiple @@ -735,8 +732,8 @@  File: hledger_journal.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance assertions -1.11.3 Assertions and multiple -f options ------------------------------------------ +12.3 Assertions and multiple -f options +======================================= Balance assertions don't work well across files specified with multiple -f options. Use include or concatenate the files instead. @@ -744,8 +741,8 @@  File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f options, Up: Balance assertions -1.11.4 Assertions and commodities ---------------------------------- +12.4 Assertions and commodities +=============================== The asserted balance must be a simple single-commodity amount, and in fact the assertion checks only this commodity's balance within the @@ -792,8 +789,8 @@  File: hledger_journal.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions -1.11.5 Assertions and prices ----------------------------- +12.5 Assertions and prices +========================== Balance assertions ignore transaction prices, and should normally be written without one: @@ -810,8 +807,8 @@  File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions -1.11.6 Assertions and subaccounts ---------------------------------- +12.6 Assertions and subaccounts +=============================== The balance assertions above ('=' and '==') do not count the balance from subaccounts; they check the account's exclusive balance only. You @@ -827,8 +824,8 @@  File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance assertions -1.11.7 Assertions and virtual postings --------------------------------------- +12.7 Assertions and virtual postings +==================================== Balance assertions are checked against all postings, both real and virtual. They are not affected by the '--real/-R' flag or 'real:' @@ -837,8 +834,8 @@  File: hledger_journal.info, Node: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions -1.11.8 Assertions and precision -------------------------------- +12.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 @@ -846,10 +843,10 @@ assertion failure messages show exact amounts.  -File: hledger_journal.info, Node: Balance assignments, Next: Directives, Prev: Balance assertions, Up: Transactions +File: hledger_journal.info, Node: Balance assignments, Next: Directives, Prev: Balance assertions, Up: Top -1.12 Balance assignments -======================== +13 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 @@ -885,8 +882,8 @@  File: hledger_journal.info, Node: Balance assignments and prices, Up: Balance assignments -1.12.1 Balance assignments and prices -------------------------------------- +13.1 Balance assignments and prices +=================================== A transaction price in a balance assignment will cause the calculated amount to have that price attached: @@ -899,10 +896,10 @@ (a) $1 @ €2 = $1 @ €2  -File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Prev: Balance assignments, Up: Transactions +File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Prev: Balance assignments, Up: Top -1.13 Directives -=============== +14 Directives +************* A directive is a line in the journal beginning with a special keyword, that influences how the journal is processed. hledger's directives are @@ -1002,8 +999,8 @@  File: hledger_journal.info, Node: Directives and multiple files, Next: Comment blocks, Up: Directives -1.13.1 Directives and multiple files ------------------------------------- +14.1 Directives and multiple files +================================== If you use multiple '-f'/'--file' options, or the 'include' directive, hledger will process multiple input files. But note that directives @@ -1022,8 +1019,8 @@  File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Prev: Directives and multiple files, Up: Directives -1.13.2 Comment blocks ---------------------- +14.2 Comment blocks +=================== 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 @@ -1032,8 +1029,8 @@  File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives -1.13.3 Including other files ----------------------------- +14.3 Including other files +========================== You can pull in the content of additional files by writing an include directive, like this: @@ -1063,8 +1060,8 @@  File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives -1.13.4 Default year -------------------- +14.4 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. @@ -1089,8 +1086,8 @@  File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives -1.13.5 Declaring commodities ----------------------------- +14.5 Declaring commodities +========================== The 'commodity' directive has several functions: @@ -1146,8 +1143,8 @@  File: hledger_journal.info, Node: Commodity error checking, Up: Declaring commodities -1.13.5.1 Commodity error checking -................................. +14.5.1 Commodity error checking +------------------------------- In strict mode, enabled with the '-s'/'--strict' flag, hledger will report an error if a commodity symbol is used that has not been declared @@ -1157,8 +1154,8 @@  File: hledger_journal.info, Node: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: Directives -1.13.6 Default commodity ------------------------- +14.6 Default commodity +====================== The 'D' directive sets a default commodity, to be used for amounts without a commodity symbol (ie, plain numbers). This commodity will be @@ -1184,8 +1181,8 @@  File: hledger_journal.info, Node: Declaring market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives -1.13.7 Declaring market prices ------------------------------- +14.7 Declaring market prices +============================ The 'P' directive declares a market price, which is an exchange rate between two commodities on a certain date. (In Ledger, they are called @@ -1214,8 +1211,8 @@  File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Declaring market prices, Up: Directives -1.13.8 Declaring accounts -------------------------- +14.8 Declaring accounts +======================= 'account' directives can be used to declare accounts (ie, the places that amounts are transferred from and to). Though not required, these @@ -1252,8 +1249,8 @@  File: hledger_journal.info, Node: Account error checking, Next: Account comments, Up: Declaring accounts -1.13.8.1 Account error checking -............................... +14.8.1 Account error checking +----------------------------- By default, accounts come into existence when a transaction references them by name. This is convenient, but it means hledger can't warn you @@ -1280,8 +1277,8 @@  File: hledger_journal.info, Node: Account comments, Next: Account subdirectives, Prev: Account error checking, Up: Declaring accounts -1.13.8.2 Account comments -......................... +14.8.2 Account comments +----------------------- Comments, beginning with a semicolon, can be added: @@ -1300,8 +1297,8 @@  File: hledger_journal.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts -1.13.8.3 Account subdirectives -.............................. +14.8.3 Account subdirectives +---------------------------- We also allow (and ignore) Ledger-style indented subdirectives, just for compatibility.: @@ -1318,8 +1315,8 @@  File: hledger_journal.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts -1.13.8.4 Account types -...................... +14.8.4 Account types +-------------------- hledger recognises five main types of account, corresponding to the account classes in the accounting equation: @@ -1333,10 +1330,24 @@ Additionally, we recognise the 'Cash' type, which is also an 'Asset', and which causes accounts to appear in the cashflow report. ("Cash" here means liquid assets, eg bank balances but typically not investments -or receivables.) Declaring account types Generally, to make these -reports work you should declare your top-level accounts and their types, -using account directives with 'type:' tags. +or receivables.) +* Menu: + +* Declaring account types:: +* Auto-detected account types:: +* Interference from auto-detected account types:: +* Old account type syntax:: + + +File: hledger_journal.info, Node: Declaring account types, Next: Auto-detected account types, Up: Account types + +14.8.4.1 Declaring account types +................................ + +Generally, to make these reports work you should declare your top-level +accounts and their types, using account directives with 'type:' tags. + The tag's value should be one of: 'Asset', 'Liability', 'Equity', 'Revenue', 'Expense', 'Cash', 'A', 'L', 'E', 'R', 'X', 'C' (all case insensitive). The type is inherited by all subaccounts except where @@ -1350,10 +1361,16 @@ account revenues ; type: Revenue account expenses ; type: Expense - Auto-detected account types If you happen to use common english -top-level account names, you may not need to declare account types, as -they will be detected automatically using the following rules: + +File: hledger_journal.info, Node: Auto-detected account types, Next: Interference from auto-detected account types, Prev: Declaring account types, Up: Account types +14.8.4.2 Auto-detected account types +.................................... + +If you happen to use common english top-level account names, you may not +need to declare account types, as they will be detected automatically +using the following rules: + If name matches regular account expression: type is: ------------------------------------------------- @@ -1369,9 +1386,16 @@ '(investment|receivable|:A/R|:fixed)' 'Cash' Even so, explicit declarations may be a good idea, for clarity and -predictability. Interference from auto-detected account types If you -assign any account type, it's a good idea to assign all of them, to -prevent any confusion from mixing declared and auto-detected types. +predictability. + + +File: hledger_journal.info, Node: Interference from auto-detected account types, Next: Old account type syntax, Prev: Auto-detected account types, Up: Account types + +14.8.4.3 Interference from auto-detected account types +...................................................... + +If you assign any account type, it's a good idea to assign all of them, +to prevent any confusion from mixing declared and auto-detected types. Although it's unlikely to happen in real life, here's an example: with the following journal, 'balancesheetequity' shows "liabilities" in both Liabilities and Equity sections. Declaring another account as @@ -1384,10 +1408,16 @@ liabilities 1 equity -2 - Old account type syntax In some hledger journals you might instead -see this old syntax (the letters ALERX, separated from the account name -by two or more spaces); this is deprecated and may be removed soon: + +File: hledger_journal.info, Node: Old account type syntax, Prev: Interference from auto-detected account types, Up: Account types +14.8.4.4 Old account type syntax +................................ + +In some hledger journals you might instead see this old syntax (the +letters ALERX, separated from the account name by two or more spaces); +this is deprecated and may be removed soon: + account assets A account liabilities L account equity E @@ -1397,8 +1427,8 @@  File: hledger_journal.info, Node: Account display order, Prev: Account types, Up: Declaring accounts -1.13.8.5 Account display order -.............................. +14.8.5 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 @@ -1443,8 +1473,8 @@  File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives -1.13.9 Rewriting accounts -------------------------- +14.9 Rewriting accounts +======================= You can define account alias rules which rewrite your account names, or parts of them, before generating reports. This can be useful for: @@ -1473,8 +1503,8 @@  File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts -1.13.9.1 Basic aliases -...................... +14.9.1 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 @@ -1496,8 +1526,8 @@  File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts -1.13.9.2 Regex aliases -...................... +14.9.2 Regex aliases +-------------------- There is also a more powerful variant that uses a regular expression, indicated by the forward slashes: @@ -1521,8 +1551,8 @@  File: hledger_journal.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: Rewriting accounts -1.13.9.3 Combining aliases -.......................... +14.9.3 Combining aliases +------------------------ You can define as many aliases as you like, using journal directives and/or command line options. @@ -1558,8 +1588,8 @@  File: hledger_journal.info, Node: Aliases and multiple files, Next: end aliases, Prev: Combining aliases, Up: Rewriting accounts -1.13.9.4 Aliases and multiple files -................................... +14.9.4 Aliases and multiple files +--------------------------------- As explained at Directives and multiple files, 'alias' directives do not affect parent or sibling files. Eg in this command, @@ -1590,8 +1620,8 @@  File: hledger_journal.info, Node: end aliases, Prev: Aliases and multiple files, Up: Rewriting accounts -1.13.9.5 'end aliases' -...................... +14.9.5 'end aliases' +-------------------- You can clear (forget) all currently defined aliases with the 'end aliases' directive: @@ -1601,8 +1631,8 @@  File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives -1.13.10 Default parent account ------------------------------- +14.10 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 'end apply @@ -1640,16 +1670,15 @@ parent account.  -File: hledger_journal.info, Node: Periodic transactions, Next: Auto postings, Prev: Directives, Up: Transactions +File: hledger_journal.info, Node: Periodic transactions, Next: Auto postings, Prev: Directives, Up: Top -1.14 Periodic transactions -========================== +15 Periodic transactions +************************ Periodic transaction rules describe transactions that recur. They allow 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. +it's easy to try out different forecasts. Periodic transactions can be a little tricky, so before you use them, read this whole section - or at least these tips: @@ -1677,6 +1706,9 @@ day of month from 2020/01/01', will be adjusted to start on 2019/12/10. + Periodic transaction rules also have a second meaning: they are used +to define budget goals, shown in budget reports. + * Menu: * Periodic rule syntax:: @@ -1687,8 +1719,8 @@  File: hledger_journal.info, Node: Periodic rule syntax, Next: Two spaces between period expression and description!, Up: Periodic transactions -1.14.1 Periodic rule syntax ---------------------------- +15.1 Periodic rule syntax +========================= A periodic transaction rule looks like a normal journal entry, with the date replaced by a tilde ('~') followed by a period expression @@ -1710,8 +1742,8 @@  File: hledger_journal.info, Node: Two spaces between period expression and description!, Next: Forecasting with periodic transactions, Prev: Periodic rule syntax, Up: Periodic transactions -1.14.2 Two spaces between period expression and description! ------------------------------------------------------------- +15.2 Two spaces between period expression and description! +========================================================== If the period expression is followed by a transaction description, these must be separated by *two or more spaces*. This helps hledger know @@ -1735,8 +1767,8 @@  File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces between period expression and description!, Up: Periodic transactions -1.14.3 Forecasting with periodic transactions ---------------------------------------------- +15.3 Forecasting with periodic transactions +=========================================== The '--forecast' flag activates any periodic transaction rules in the journal. They will generate temporary recurring transactions, which are @@ -1781,8 +1813,8 @@  File: hledger_journal.info, Node: Budgeting with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions -1.14.4 Budgeting with periodic transactions -------------------------------------------- +15.4 Budgeting with periodic transactions +========================================= With the '--budget' flag, currently supported by the balance command, each periodic transaction rule declares recurring budget goals for the @@ -1794,10 +1826,10 @@ See also: Budgeting and Forecasting.  -File: hledger_journal.info, Node: Auto postings, Prev: Periodic transactions, Up: Transactions +File: hledger_journal.info, Node: Auto postings, Prev: Periodic transactions, Up: Top -1.15 Auto postings -================== +16 Auto postings +**************** "Automated postings" or "auto postings" are extra postings which get added automatically to transactions which match certain queries, defined @@ -1874,8 +1906,8 @@  File: hledger_journal.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings -1.15.1 Auto postings and multiple files ---------------------------------------- +16.1 Auto postings and multiple files +===================================== An auto posting rule can affect any transaction in the current file, or in any parent file or child file. Note, currently it will not affect @@ -1884,8 +1916,8 @@  File: hledger_journal.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings -1.15.2 Auto postings and dates ------------------------------- +16.2 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 be @@ -1894,8 +1926,8 @@  File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings -1.15.3 Auto postings and transaction balancing / inferred amounts / -------------------------------------------------------------------- +16.3 Auto postings and transaction balancing / inferred amounts / +================================================================= balance assertions Currently, auto postings are added: @@ -1910,8 +1942,8 @@  File: hledger_journal.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings -1.15.4 Auto posting tags ------------------------- +16.4 Auto posting tags +====================== Automated postings will have some extra tags: @@ -1932,130 +1964,138 @@  Tag Table: Node: Top76 -Node: Transactions1869 -Ref: #transactions1961 -Node: Dates3245 -Ref: #dates3344 -Node: Simple dates3409 -Ref: #simple-dates3535 -Node: Secondary dates4044 -Ref: #secondary-dates4198 -Node: Posting dates5534 -Ref: #posting-dates5663 -Node: Status7035 -Ref: #status7156 -Node: Description8864 -Ref: #description8998 -Node: Payee and note9318 -Ref: #payee-and-note9432 -Node: Comments9767 -Ref: #comments9893 -Node: Tags11087 -Ref: #tags11202 -Node: Postings12595 -Ref: #postings12723 -Node: Virtual postings13749 -Ref: #virtual-postings13866 -Node: Account names15171 -Ref: #account-names15312 -Node: Amounts15799 -Ref: #amounts15938 -Node: Digit group marks17062 -Ref: #digit-group-marks17213 -Node: Commodity display style18151 -Ref: #commodity-display-style18331 -Node: Rounding19874 -Ref: #rounding19998 -Node: Transaction prices20410 -Ref: #transaction-prices20582 -Node: Lot prices and lot dates23013 -Ref: #lot-prices-and-lot-dates23210 -Node: Balance assertions23698 -Ref: #balance-assertions23884 -Node: Assertions and ordering24917 -Ref: #assertions-and-ordering25105 -Node: Assertions and included files25805 -Ref: #assertions-and-included-files26048 -Node: Assertions and multiple -f options26381 -Ref: #assertions-and-multiple--f-options26637 -Node: Assertions and commodities26769 -Ref: #assertions-and-commodities27001 -Node: Assertions and prices28158 -Ref: #assertions-and-prices28372 -Node: Assertions and subaccounts28812 -Ref: #assertions-and-subaccounts29041 -Node: Assertions and virtual postings29365 -Ref: #assertions-and-virtual-postings29607 -Node: Assertions and precision29749 -Ref: #assertions-and-precision29942 -Node: Balance assignments30209 -Ref: #balance-assignments30383 -Node: Balance assignments and prices31547 -Ref: #balance-assignments-and-prices31719 -Node: Directives31943 -Ref: #directives32102 -Node: Directives and multiple files37600 -Ref: #directives-and-multiple-files37783 -Node: Comment blocks38447 -Ref: #comment-blocks38630 -Node: Including other files38806 -Ref: #including-other-files38986 -Node: Default year39910 -Ref: #default-year40079 -Node: Declaring commodities40486 -Ref: #declaring-commodities40669 -Node: Commodity error checking42513 -Ref: #commodity-error-checking42673 -Node: Default commodity42930 -Ref: #default-commodity43116 -Node: Declaring market prices44005 -Ref: #declaring-market-prices44200 -Node: Declaring accounts45057 -Ref: #declaring-accounts45243 -Node: Account error checking46445 -Ref: #account-error-checking46621 -Node: Account comments47800 -Ref: #account-comments47994 -Node: Account subdirectives48418 -Ref: #account-subdirectives48613 -Node: Account types48926 -Ref: #account-types49110 -Node: Account display order52156 -Ref: #account-display-order52326 -Node: Rewriting accounts53477 -Ref: #rewriting-accounts53662 -Node: Basic aliases54419 -Ref: #basic-aliases54565 -Node: Regex aliases55269 -Ref: #regex-aliases55441 -Node: Combining aliases56160 -Ref: #combining-aliases56353 -Node: Aliases and multiple files57629 -Ref: #aliases-and-multiple-files57838 -Node: end aliases58417 -Ref: #end-aliases58574 -Node: Default parent account58675 -Ref: #default-parent-account58843 -Node: Periodic transactions59727 -Ref: #periodic-transactions59902 -Node: Periodic rule syntax61774 -Ref: #periodic-rule-syntax61980 -Node: Two spaces between period expression and description!62684 -Ref: #two-spaces-between-period-expression-and-description63003 -Node: Forecasting with periodic transactions63687 -Ref: #forecasting-with-periodic-transactions63992 -Node: Budgeting with periodic transactions66047 -Ref: #budgeting-with-periodic-transactions66286 -Node: Auto postings66695 -Ref: #auto-postings66835 -Node: Auto postings and multiple files69014 -Ref: #auto-postings-and-multiple-files69218 -Node: Auto postings and dates69427 -Ref: #auto-postings-and-dates69701 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions69876 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions70227 -Node: Auto posting tags70569 -Ref: #auto-posting-tags70784 +Node: Transactions2154 +Ref: #transactions2272 +Node: Dates3286 +Ref: #dates3393 +Node: Simple dates3458 +Ref: #simple-dates3580 +Node: Secondary dates4089 +Ref: #secondary-dates4239 +Node: Posting dates5575 +Ref: #posting-dates5700 +Node: Status7072 +Ref: #status7180 +Node: Description8888 +Ref: #description9009 +Node: Payee and note9329 +Ref: #payee-and-note9439 +Node: Comments9774 +Ref: #comments9887 +Node: Tags11081 +Ref: #tags11183 +Node: Postings12576 +Ref: #postings12691 +Node: Virtual postings13717 +Ref: #virtual-postings13830 +Node: Account names15135 +Ref: #account-names15263 +Node: Amounts15750 +Ref: #amounts15876 +Node: Digit group marks17000 +Ref: #digit-group-marks17147 +Node: Commodity display style18085 +Ref: #commodity-display-style18261 +Node: Rounding19804 +Ref: #rounding19924 +Node: Transaction prices20336 +Ref: #transaction-prices20497 +Node: Lot prices and lot dates22928 +Ref: #lot-prices-and-lot-dates23112 +Node: Balance assertions23600 +Ref: #balance-assertions23773 +Node: Assertions and ordering24806 +Ref: #assertions-and-ordering24990 +Node: Assertions and included files25690 +Ref: #assertions-and-included-files25929 +Node: Assertions and multiple -f options26262 +Ref: #assertions-and-multiple--f-options26514 +Node: Assertions and commodities26646 +Ref: #assertions-and-commodities26874 +Node: Assertions and prices28031 +Ref: #assertions-and-prices28241 +Node: Assertions and subaccounts28681 +Ref: #assertions-and-subaccounts28906 +Node: Assertions and virtual postings29230 +Ref: #assertions-and-virtual-postings29468 +Node: Assertions and precision29610 +Ref: #assertions-and-precision29799 +Node: Balance assignments30066 +Ref: #balance-assignments30227 +Node: Balance assignments and prices31391 +Ref: #balance-assignments-and-prices31559 +Node: Directives31783 +Ref: #directives31929 +Node: Directives and multiple files37427 +Ref: #directives-and-multiple-files37606 +Node: Comment blocks38270 +Ref: #comment-blocks38449 +Node: Including other files38625 +Ref: #including-other-files38801 +Node: Default year39725 +Ref: #default-year39890 +Node: Declaring commodities40297 +Ref: #declaring-commodities40476 +Node: Commodity error checking42320 +Ref: #commodity-error-checking42476 +Node: Default commodity42733 +Ref: #default-commodity42915 +Node: Declaring market prices43804 +Ref: #declaring-market-prices43995 +Node: Declaring accounts44852 +Ref: #declaring-accounts45034 +Node: Account error checking46236 +Ref: #account-error-checking46408 +Node: Account comments47587 +Ref: #account-comments47777 +Node: Account subdirectives48201 +Ref: #account-subdirectives48392 +Node: Account types48705 +Ref: #account-types48885 +Node: Declaring account types49621 +Ref: #declaring-account-types49806 +Node: Auto-detected account types50456 +Ref: #auto-detected-account-types50703 +Node: Interference from auto-detected account types51600 +Ref: #interference-from-auto-detected-account-types51883 +Node: Old account type syntax52366 +Ref: #old-account-type-syntax52569 +Node: Account display order52869 +Ref: #account-display-order53035 +Node: Rewriting accounts54186 +Ref: #rewriting-accounts54367 +Node: Basic aliases55124 +Ref: #basic-aliases55266 +Node: Regex aliases55970 +Ref: #regex-aliases56138 +Node: Combining aliases56857 +Ref: #combining-aliases57046 +Node: Aliases and multiple files58322 +Ref: #aliases-and-multiple-files58527 +Node: end aliases59106 +Ref: #end-aliases59259 +Node: Default parent account59360 +Ref: #default-parent-account59524 +Node: Periodic transactions60408 +Ref: #periodic-transactions60570 +Node: Periodic rule syntax62487 +Ref: #periodic-rule-syntax62689 +Node: Two spaces between period expression and description!63393 +Ref: #two-spaces-between-period-expression-and-description63708 +Node: Forecasting with periodic transactions64392 +Ref: #forecasting-with-periodic-transactions64693 +Node: Budgeting with periodic transactions66748 +Ref: #budgeting-with-periodic-transactions66983 +Node: Auto postings67392 +Ref: #auto-postings67519 +Node: Auto postings and multiple files69698 +Ref: #auto-postings-and-multiple-files69898 +Node: Auto postings and dates70107 +Ref: #auto-postings-and-dates70377 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions70552 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions70899 +Node: Auto posting tags71241 +Ref: #auto-posting-tags71452  End Tag Table diff --git a/hledger_journal.txt b/hledger_journal.txt --- a/hledger_journal.txt +++ b/hledger_journal.txt @@ -1316,40 +1316,42 @@ 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. + and it's easy to try out different forecasts. - 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 transaction rules also have a second meaning: they are used to + define budget goals, shown in budget reports. + Periodic rule syntax A periodic transaction rule looks like a normal journal entry, with the date replaced by a tilde (~) followed by a period expression (mnemonic: @@ -1563,17 +1565,14 @@ COPYRIGHT - Copyright (C) 2007-2019 Simon Michael. + Copyright (C) 2007-2020 Simon Michael. Released under GNU GPL v3 or later. SEE ALSO - 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) - - http://hledger.org + hledger(1), hledger-ui(1), hledger-web(1), hledger_csv(5), + hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) -hledger 1.20 November 2020 hledger_journal(5) +hledger 1.20.1 December 2020 hledger_journal(5) diff --git a/hledger_timeclock.5 b/hledger_timeclock.5 --- a/hledger_timeclock.5 +++ b/hledger_timeclock.5 @@ -1,5 +1,5 @@ -.TH "hledger_timeclock" "5" "November 2020" "hledger 1.20" "hledger User Manuals" +.TH "hledger_timeclock" "5" "December 2020" "hledger 1.20.1" "hledger User Manuals" @@ -80,13 +80,11 @@ .SH COPYRIGHT -Copyright (C) 2007-2019 Simon Michael. +Copyright (C) 2007-2020 Simon Michael. .br Released under GNU GPL v3 or later. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger(1), hledger\-ui(1), hledger\-web(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) - -http://hledger.org diff --git a/hledger_timeclock.info b/hledger_timeclock.info --- a/hledger_timeclock.info +++ b/hledger_timeclock.info @@ -4,8 +4,8 @@  File: hledger_timeclock.info, Node: Top, Up: (dir) -hledger_timeclock(5) hledger 1.20 -********************************* +hledger_timeclock(5) hledger 1.20.1 +*********************************** Timeclock - the time logging format of timeclock.el, as read by hledger diff --git a/hledger_timeclock.txt b/hledger_timeclock.txt --- a/hledger_timeclock.txt +++ b/hledger_timeclock.txt @@ -65,17 +65,14 @@ COPYRIGHT - Copyright (C) 2007-2019 Simon Michael. + Copyright (C) 2007-2020 Simon Michael. Released under GNU GPL v3 or later. SEE ALSO - 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) - - http://hledger.org + hledger(1), hledger-ui(1), hledger-web(1), hledger_csv(5), + hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) -hledger 1.20 November 2020 hledger_timeclock(5) +hledger 1.20.1 December 2020 hledger_timeclock(5) diff --git a/hledger_timedot.5 b/hledger_timedot.5 --- a/hledger_timedot.5 +++ b/hledger_timedot.5 @@ -1,5 +1,5 @@ -.TH "hledger_timedot" "5" "November 2020" "hledger 1.20" "hledger User Manuals" +.TH "hledger_timedot" "5" "December 2020" "hledger 1.20.1" "hledger User Manuals" @@ -189,13 +189,11 @@ .SH COPYRIGHT -Copyright (C) 2007-2019 Simon Michael. +Copyright (C) 2007-2020 Simon Michael. .br Released under GNU GPL v3 or later. .SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger(1), hledger\-ui(1), hledger\-web(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) - -http://hledger.org diff --git a/hledger_timedot.info b/hledger_timedot.info --- a/hledger_timedot.info +++ b/hledger_timedot.info @@ -4,8 +4,8 @@  File: hledger_timedot.info, Node: Top, Up: (dir) -hledger_timedot(5) hledger 1.20 -******************************* +hledger_timedot(5) hledger 1.20.1 +********************************* Timedot - hledger's human-friendly time logging format diff --git a/hledger_timedot.txt b/hledger_timedot.txt --- a/hledger_timedot.txt +++ b/hledger_timedot.txt @@ -148,17 +148,14 @@ COPYRIGHT - Copyright (C) 2007-2019 Simon Michael. + Copyright (C) 2007-2020 Simon Michael. Released under GNU GPL v3 or later. SEE ALSO - 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) - - http://hledger.org + hledger(1), hledger-ui(1), hledger-web(1), hledger_csv(5), + hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), ledger(1) -hledger 1.20 November 2020 hledger_timedot(5) +hledger 1.20.1 December 2020 hledger_timedot(5)