hledger 1.28 → 1.29

raw patch · 60 files changed

+64836/−61466 lines, 60 filesdep +text-ansidep ~hledger-libPVP ok

version bump matches the API change (PVP)

Dependencies added: text-ansi

Dependency ranges changed: hledger-lib

API changes (from Hackage documentation)

Files

• CHANGES.md +209/−1
• Hledger/Cli/CliOptions.hs +57/−28
• Hledger/Cli/Commands.hs +121/−44
• Hledger/Cli/Commands/Accounts.txt +1/−0
• Hledger/Cli/Commands/Activity.hs +1/−1
• Hledger/Cli/Commands/Activity.txt +1/−0
• Hledger/Cli/Commands/Add.hs +11/−9
• Hledger/Cli/Commands/Add.txt +3/−2
• Hledger/Cli/Commands/Aregister.hs +31/−2
• Hledger/Cli/Commands/Aregister.txt +11/−4
• Hledger/Cli/Commands/Balance.hs +7/−6
• Hledger/Cli/Commands/Balance.txt +376/−310
• Hledger/Cli/Commands/Balancesheet.txt +4/−1
• Hledger/Cli/Commands/Balancesheetequity.txt +4/−1
• Hledger/Cli/Commands/Cashflow.txt +4/−1
• Hledger/Cli/Commands/Check.hs +2/−0
• Hledger/Cli/Commands/Check.txt +5/−3
• Hledger/Cli/Commands/Close.hs +54/−70
• Hledger/Cli/Commands/Close.txt +121/−152
• Hledger/Cli/Commands/Codes.txt +13/−9
• Hledger/Cli/Commands/Commodities.txt +1/−0
• Hledger/Cli/Commands/Descriptions.txt +1/−0
• Hledger/Cli/Commands/Diff.txt +1/−0
• Hledger/Cli/Commands/Files.txt +1/−0
• Hledger/Cli/Commands/Help.txt +1/−0
• Hledger/Cli/Commands/Import.txt +8/−0
• Hledger/Cli/Commands/Incomestatement.txt +4/−1
• Hledger/Cli/Commands/Notes.txt +1/−0
• Hledger/Cli/Commands/Payees.txt +1/−0
• Hledger/Cli/Commands/Prices.txt +4/−4
• Hledger/Cli/Commands/Print.hs +3/−1
• Hledger/Cli/Commands/Print.txt +13/−13
• Hledger/Cli/Commands/Printunique.hs +0/−26
• Hledger/Cli/Commands/Printunique.txt +0/−16
• Hledger/Cli/Commands/Register.hs +74/−3
• Hledger/Cli/Commands/Register.txt +9/−1
• Hledger/Cli/Commands/Registermatch.hs +0/−86
• Hledger/Cli/Commands/Registermatch.txt +0/−8
• Hledger/Cli/Commands/Rewrite.txt +1/−0
• Hledger/Cli/Commands/Roi.hs +10/−7
• Hledger/Cli/Commands/Roi.txt +1/−0
• Hledger/Cli/Commands/Stats.txt +3/−2
• Hledger/Cli/Commands/Tags.txt +1/−0
• Hledger/Cli/Commands/Test.txt +1/−0
• Hledger/Cli/CompoundBalanceCommand.hs +7/−2
• Hledger/Cli/Main.hs +2/−2
• Hledger/Cli/Script.hs +33/−0
• embeddedfiles/hledger-ui.1 +173/−159
• embeddedfiles/hledger-ui.info +227/−219
• embeddedfiles/hledger-ui.txt +77/−64
• embeddedfiles/hledger-web.1 +132/−125
• embeddedfiles/hledger-web.info +165/−163
• embeddedfiles/hledger-web.txt +43/−37
• embeddedfiles/hledger.1 +11771/−11356
• embeddedfiles/hledger.info +10967/−10354
• embeddedfiles/hledger.txt +8656/−8225
• hledger.1 +11771/−11356
• hledger.cabal +14/−13
• hledger.info +10967/−10354
• hledger.txt +8656/−8225

@@ -9,8 +9,216 @@ User-visible changes in the hledger command line tool and library.  -# 1.28 2022-11-30+# 1.29 2023-03-11 +Breaking changes++- Weekly reports are no longer automatically adjusted to start on a+  monday; in some cases you might need to adjust their start date to+  preserve simple week headings (see below).++Features++- In journal format there is now a `tag` directive for declaring tag names,+  and the check command now has a `tags` check to enforce use of declared tag names.++- Periodic transactions and multi-period reports can now start on any date.+  To enable this while still maintaining pretty good backward compatibility,+  hledger now treats inferred dates, and dates where the day is unspecified,+  as "flexible" (which can be automatically adjusted to interval boundaries),+  and dates specified to the day as "exact" (which can not).+  Eg:+  +  - A periodic rule like `~ monthly from 2023-01-15` now works as+    you'd expect instead of raising an error. This also improves+    our ability to read Ledger files.++  - Period options like `-p 'monthly from 2023/1/15'` or `-M -b 2023/1/15`+    now start the report on exactly 1/15 instead of being adjusted to 1/1.+  +  Note: periods using `in` may look partial but are considered to specify exact dates.+  So weekly reports such as `-p 'weekly in 2023-01'`, which previously+  were adjusted to start on a monday, will now start exactly on 2023-01-01.+  This can also cause more verbose column headings.+	To guarantee simple week headings, you must now start such reports+  exactly on a monday, eg `-p 'weekly from 2022-12-26 to 2023-02'`.+  (#1982)++- You can now freely combine @/@@ costs and conversion postings+  in a single transaction. This can help readability, and also allows+  more flexibility when recording cost.  hledger will check that the+  two notations are in agreement, and ignore the redundancy if they are.+  (Conversion postings are postings to accounts with type `V`/`Conversion`+  or name `equity:conversion`/`equity:trade`/`equity:trading`,+  or subaccounts of these. See also COST.)++Improvements++- hledger's commands list has been reorganised for clarity.+  More add-on commands are now recognised and categorised,+  and unrecognised add-on commands are listed in a more compact+  multi-column layout.+  (Simon Michael, Michael Grünewald)++- hledger's commands list and command line help now use ANSI (bold+  headings) when supported.+  +- hledger's commands list and command line help now use a pager+  (respecting $PAGER) for long output except on MS Windows.++- hledger's `--version` output no longer shows `+` for dev builds made+  in dirty repos (it was buggy).++- The add command's Description completions now also include payee names+  (declared with `payee` or recorded in transactions with `|`),+  not just full descriptions.++- aregister now supports HTML output.+  (#1996) (Jonathan Dowland)++- aregister now shows a " (matching query)" hint in report title +  when extra query args (other than date: or depth:) are used,+  to reduce confusion.++- close now has three modes, `--retain`/`--migrate`/`--open`,+  clarifying its uses and providing more useful defaults.++- register-match is now the `--match` mode of the register command.+  (This command was used by ledger-autosync at one point; if you still+  need it, hopefully `register --match` works similarly.)++- print-unique has been dropped, because it doesn't+  support print's options, it disorders same-day transactions, I don't+  know of any users or use cases, and it could easily be recreated as+  an addon script.++- print's JSON output now also includes source positions for `--forecast` transactions.+  (Chris Lemaire)++- Journal format now allows the empty commodity symbol to be written+  as `""`, so it's now possible to declare market prices for it:+  `P 2022-01-01 "" $100`.  This can be useful for timedot data.++- Inferring costs from equity now happens after transaction balancing,+  not before.  As a result, `--infer-costs` now works in transactions+  where an amount is left blank.++- `account` declarations now reject parenthesised account names,+  reducing confusion.+  (Chris Lemaire)++- Our journal reader now accepts more Ledger syntax, improving Ledger+  file compatibility (#1962).  We now test our ability to at least+  read the sample journals from Ledger's baseline functional tests,+  and our success rate has improved from 80% to 90% since 1.28.+  +  - `since` is accepted as synonym of `from` in period expressions+  - `apply year` and `year` are accepted as synonyms of `Y`+  - `(lot notes)` in amounts and `((valuation expressions))` after amounts are now ignored+  - directives +    `A`, `assert`, `bucket`, `capture`, `check`, `define`,+    `expr`, `eval`, `python`, `value`,+    `apply fixed`, `apply tag`,+    `end apply fixed`, `end apply tag`, `end apply year`+	are now ignored+  - subdirectives of `payee`, `tag`, and `commodity` (other than `format`) are now ignored+  - `pop` directive is no longer supported++- When reading CSV, we now check that assigned account names are valid (parseable).+  (#1978)++Fixes++- aregister now handles an extra account query correctly. (#2007)++- balance's `--help` now mentions `--layout=tidy`++- Balance commands with `--layout=bare` now generate proper table+  layout in HTML output.++- register's `-w`/`--width` option no longer gives ugly parse error messages.++- stats's `--help` no longer wrongly claims to support -O/--output-format.++- Balance assignments with a cost now generate a correct balance assertion. (#1965)++- The CSV reader now properly skips header lines before attempting to parse records. (#1967)++Scripts/addons++- Scripts can now use Hledger.Cli.Script, a convenient new prelude which+  helps reduce import boilerplate. It currently re-exports:++	  Control.Monad+	  Data.Either+	  Data.List+	  Data.Maybe+	  Data.Ord+	  Data.Time+	  Text.Printf hiding (formatString)+	  Data.Text (Text, pack, unpack)+	  Safe hiding (at)+	  System.Directory+	  System.Environment+	  System.Exit+	  System.FilePath+	  System.Process+	  Hledger+	  Hledger.Cli+	  Hledger.Cli.Main (argsToCliOpts)++  (Not much of Data.Text/Data.Text.IO because those need to be qualified.)++Docs++- chunk the hledger manual into parts, rename and rearrange sections for better structure/flow+- add a cheatsheet demonstrating all the main journal features that I recommend+- move a number of my not-so-recommended journal features into a less visible "Other syntax" section+- add: payees/descriptions completion+- areg: more advice on account-matching+- bal: --budget: clarify use of print --forecast+- bal: budget: compare with forecasting; add some tips+- balance cleanups/reorder+- check: adjacentconversionpostings was dropped+- cli: balance: fix link to Budgeting page+- cli: fix all links to Journal > Tags / Commands > tags+- codes: improve example suggested by Rob Nielsen+- csv, timeclock, timedot: clarify comment lines (#1953)+- csv: add new coinbase example+- csv: clarify amount-in/amount-out docs (#1970)+- csv: clarify skip/valid csv semantics (#1967)+- csv: clarify valid CSV requirements and issues (fix #1966)+- csv: cleanup, reorder, CSV rules tips -> Working with CSV+- csv: fix wrong if tables doc; rewrite several sections (#1977)+- csv: flatten, clean up CSV sections+- csv: improve Amount field / Setting amounts+- csv: note -in and -out are used together for one posting (#1970)+- csv: rules factoring tips+- csv: try to clarify how CSV fields and hledger fields work+- document --infer-market-prices with signed costs (#1870)+- fix duplicate market prices heading breaking info navigation+- import: note a pitfall with multifile import+- improve Directives summaries+- introduction/input/output improvements+- journal: cheatsheet: clarify date tag+- journal: rewrite Account names, mention brackets/parentheses (#1915)+- mention pivoting on a tag with multiple values (#1950)+- more cost notation docs; describe Ledger and Beancount cost notation+- more mention of posting order effect on inferring cost (#1959)+- period expressions doc updates+- Removed redundant paragraph in documentation. (J. B. Rainsberger)+- rename directive sections, fix many links+- reorganise commands list, like the CLI+- reorganise bin/README & the Scripts page, add entries for recent scripts+- replace "transaction prices" terminology with "costs"+- tags: discuss multi-values/overriding (#1950)+- update market price inference docs per sol+- Updated section on pivoting. Used synonyms for "member" in cases where there could be confusion with the tag named "member." (Robert Nielsen)+- use more standard and consistent boilerplate in hledger, ui, web man pages+- virtual postings: improve wording per Robert Nielsen+++# 1.28 2022-12-01 Features  - The `accounts` command has new flags: `--undeclared` (show accounts used but not declared), `--unused` (show accounts declared but not used),  and `--find` (find the first account matched by the first command argument, a convenience for scripts). Also `-u` and `-d` short flags have been added for `--used` and `--declared`.

@@ -12,6 +12,7 @@ {-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE TemplateHaskell     #-} {-# LANGUAGE TypeFamilies        #-}+{-# LANGUAGE TypeOperators       #-}  module Hledger.Cli.CliOptions ( @@ -58,7 +59,7 @@   outputFileFromOpts,   outputFormatFromOpts,   defaultWidth,-  widthFromOpts,+  -- widthFromOpts,   replaceNumericFlags,   -- | For register:   registerWidthsFromOpts,@@ -78,7 +79,6 @@ import Data.Char import Data.Default import Data.Either (fromRight, isRight)-import Data.Functor.Identity (Identity) import Data.List.Extra (groupSortOn, intercalate, isInfixOf, nubSort) import Data.List.Split (splitOneOf) import Data.Maybe@@ -87,6 +87,7 @@ import qualified Data.Text as T import Data.Void (Void) import Safe+import String.ANSI import System.Console.CmdArgs hiding (Default,def) import System.Console.CmdArgs.Explicit import System.Console.CmdArgs.Text@@ -104,6 +105,7 @@ import Hledger.Cli.DocFiles import Hledger.Cli.Version import Data.Time.Clock.POSIX (POSIXTime)+import Data.List (isPrefixOf, isSuffixOf)   -- common cmdargs flags@@ -370,35 +372,62 @@         ,modeArgs        = argsdescr         } --- | Parse a command's documentation, as follows:+-- | Parse a command's help text file (Somecommand.txt).+-- This is generated from the command's doc source file (Somecommand.md)+-- by Shake cmdhelp, and it should be formatted as follows: ----- - First line: the command name then any aliases, as one or more space or comma-separated words+-- - First line: main command name ----- - Second line to a line containing just _FLAGS, or the end: the short help+-- - Third line: command aliases, comma-and-space separated, in parentheses (optional) ----- - Any lines after _FLAGS: the long help (split into lines for cmdargs)+-- - Fifth or third line to the line containing just _FLAGS (or end of file): short command help ----- The CLI help displays the short help, then the cmdargs-generated--- flags list, then the long help (which some day we might make--- optional again).  The manual displays the short help followed by--- the long help, with no flags list.+-- - Any lines after _FLAGS: long command help --+-- The CLI --help displays the short help, the flags help generated by cmdargs,+-- then the long help (which some day we might make optional again).+-- The manual displays the short help, then the long help (but not the flags list).+-- parseCommandDoc :: CommandDoc -> Maybe ([Name], String, [String]) parseCommandDoc t =   case lines t of     [] -> Nothing-    (l:ls) -> Just (names, shorthelp, longhelplines)+    (l1:_:l3:ls) -> Just (cmdname:cmdaliases, shorthelp, longhelplines)       where-        names = words $ map (\c -> if c `elem` [',','\\'] then ' ' else c) l-        (shorthelpls, longhelpls) = break (== "_FLAGS") ls+        cmdname = strip l1+        (cmdaliases, rest) =+          if "(" `isPrefixOf` l3 && ")" `isSuffixOf` l3+          then (words $ filter (/=',') $ drop 1 $ init l3, ls)+          else ([], l3:ls)+        (shorthelpls, longhelpls) = break (== "_FLAGS") $ dropWhile (=="") rest         shorthelp = unlines $ reverse $ dropWhile null $ reverse shorthelpls         longhelplines = dropWhile null $ drop 1 longhelpls+    _ -> Nothing  -- error' "misformatted command help text file"  -- | Get a mode's usage message as a nicely wrapped string. showModeUsage :: Mode a -> String-showModeUsage = (showText defaultWrap :: [Text] -> String) .-               (helpText [] HelpFormatDefault :: Mode a -> [Text])+showModeUsage =+  highlightHelp .+  (showText defaultWrap :: [Text] -> String) .+  (helpText [] HelpFormatDefault :: Mode a -> [Text]) +-- | Add some ANSI decoration to cmdargs' help output.+highlightHelp+  | not useColorOnStdout = id+  | otherwise = unlines . zipWith (curry f) [1..] . lines+  where+    f (n,s)+      | n==1 = bold s+      | s `elem` [+           "General input flags:"+          ,"General reporting flags:"+          ,"General help flags:"+          ,"Flags:"+          ,"General flags:"+          ,"Examples:"+          ] = bold s+      | otherwise = s+ -- | Get the most appropriate documentation topic for a mode. -- Currently, that is either the hledger, hledger-ui or hledger-web -- manual.@@ -489,8 +518,8 @@   currentDay <- getCurrentDay   let day = case maybestringopt "today" rawopts of               Nothing -> currentDay-              Just d  -> fromRight (error' $ "Unable to parse date \"" ++ d ++ "\"") -- PARTIAL:-                         $ fixSmartDateStrEither' currentDay (T.pack d)+              Just d  -> fromRight (error' $ "Unable to parse date \"" ++ d ++ "\"") $ -- PARTIAL:+                         fromEFDay <$> fixSmartDateStrEither' currentDay (T.pack d)   let iopts = rawOptsToInputOpts day rawopts   rspec <- either error' pure $ rawOptsToReportSpec day rawopts  -- PARTIAL:   mcolumns <- readMay <$> getEnvSafe "COLUMNS"@@ -637,16 +666,16 @@   d <- getCurrentDirectory   maybe (return Nothing) (fmap Just . expandPath d) $ mrules_file_ $ inputopts_ opts --- | Get the width in characters to use for console output.--- This comes from the --width option, or the COLUMNS environment--- variable, or (on posix platforms) the current terminal width, or 80.--- Will raise a parse error for a malformed --width argument.-widthFromOpts :: CliOpts -> Int-widthFromOpts CliOpts{width_=Nothing, available_width_=w} = w-widthFromOpts CliOpts{width_=Just s}  =-    case runParser (read `fmap` some digitChar <* eof :: ParsecT Void String Identity Int) "(unknown)" s of-        Left e   -> usageError $ "could not parse width option: "++show e-        Right w  -> w+-- -- | Get the width in characters to use for console output.+-- -- This comes from the --width option, or the COLUMNS environment+-- -- variable, or (on posix platforms) the current terminal width, or 80.+-- -- Will raise a parse error for a malformed --width argument.+-- widthFromOpts :: CliOpts -> Int+-- widthFromOpts CliOpts{width_=Nothing, available_width_=w} = w+-- widthFromOpts CliOpts{width_=Just s}  =+--     case runParser (read `fmap` some digitChar <* eof :: ParsecT Void String Identity Int) "(unknown)" s of+--         Left e   -> usageError $ "could not parse width option: "++errorBundlePretty e+--         Right w  -> w  -- for register: @@ -663,7 +692,7 @@ registerWidthsFromOpts CliOpts{width_=Nothing, available_width_=w} = (w, Nothing) registerWidthsFromOpts CliOpts{width_=Just s}  =     case runParser registerwidthp "(unknown)" s of-        Left e   -> usageError $ "could not parse width option: "++show e+        Left e   -> usageError $ "could not parse width option: "++errorBundlePretty e         Right ws -> ws     where         registerwidthp :: (Stream s, Char ~ Token s) => ParsecT Void s m (Int, Maybe Int)

@@ -36,9 +36,7 @@   ,module Hledger.Cli.Commands.Payees   ,module Hledger.Cli.Commands.Prices   ,module Hledger.Cli.Commands.Print-  ,module Hledger.Cli.Commands.Printunique   ,module Hledger.Cli.Commands.Register-  ,module Hledger.Cli.Commands.Registermatch   ,module Hledger.Cli.Commands.Rewrite   ,module Hledger.Cli.Commands.Stats   ,module Hledger.Cli.Commands.Tags@@ -50,6 +48,7 @@ import Data.Text (Text) import qualified Data.Text as T import Data.Time.Calendar+import String.ANSI import System.Environment (withArgs) import System.Console.CmdArgs.Explicit as C import Test.Tasty (defaultMain)@@ -79,14 +78,13 @@ import Hledger.Cli.Commands.Payees import Hledger.Cli.Commands.Prices import Hledger.Cli.Commands.Print-import Hledger.Cli.Commands.Printunique import Hledger.Cli.Commands.Register-import Hledger.Cli.Commands.Registermatch import Hledger.Cli.Commands.Rewrite import Hledger.Cli.Commands.Roi import Hledger.Cli.Commands.Stats import Hledger.Cli.Commands.Tags import Hledger.Cli.Utils (tests_Cli_Utils)+import Data.List.Extra (chunksOf)  -- | The cmdargs subcommand mode (for command-line parsing) -- and IO action (for doing the command's work) for each builtin command.@@ -105,7 +103,7 @@   ,(closemode              , close)   ,(codesmode              , codes)   ,(commoditiesmode        , commodities)-  ,(descriptionsmode        , descriptions)+  ,(descriptionsmode       , descriptions)   ,(diffmode               , diff)   ,(filesmode              , files)   ,(helpmode               , help')@@ -115,8 +113,6 @@   ,(payeesmode             , payees)   ,(pricesmode             , prices)   ,(printmode              , print')-  ,(printuniquemode        , printunique)-  ,(registermatchmode      , registermatch)   ,(registermode           , register)   ,(rewritemode            , rewrite)   ,(roimode                , roi)@@ -125,6 +121,48 @@   ,(testmode               , testcmd)   ] +-- figlet -f FONTNAME hledger, then escape backslashes+_banner_slant = drop 1 [""+    -----------------------------------------80-------------------------------------+  ,"    __    __         __               "+  ,"   / /_  / /__  ____/ /___ ____  _____"+  ,"  / __ \\/ / _ \\/ __  / __ `/ _ \\/ ___/"+  ," / / / / /  __/ /_/ / /_/ /  __/ /    "+  ,"/_/ /_/_/\\___/\\__,_/\\__, /\\___/_/     "+  ,"                   /____/             "+  ]++_banner_smslant = drop 1 [""+  ,"   __   __       __            "+  ,"  / /  / /__ ___/ /__ ____ ____"+  ," / _ \\/ / -_) _  / _ `/ -_) __/"+  ,"/_//_/_/\\__/\\_,_/\\_, /\\__/_/   "+  ,"                /___/          "+  ]++_banner_speed = drop 1 [""+  ,"______ ______    _________                    "+  ,"___  /____  /__________  /______ _____________"+  ,"__  __ \\_  /_  _ \\  __  /__  __ `/  _ \\_  ___/"+  ,"_  / / /  / /  __/ /_/ / _  /_/ //  __/  /    "+  ,"/_/ /_//_/  \\___/\\__,_/  _\\__, / \\___//_/     "+  ,"                         /____/               "+  ]++-- | Choose and apply an accent color for hledger output, if possible+-- picking one that will contrast with the current terminal background colour.+accent :: String -> String+accent+  | not useColorOnStdout          = id+  | terminalIsLight == Just False = brightWhite+  | terminalIsLight == Just True  = brightBlack+  | otherwise                     = id++highlightAddon = id++-- More careful version of bold+bold' = if useColorOnStdout then bold else id+ -- | The commands list, showing command names, standard aliases, -- and short descriptions. This is modified at runtime, as follows: --@@ -143,75 +181,115 @@ -- -- TODO: generate more of this automatically. -- -commandsList :: String -> [String] -> [String]-commandsList progversion othercmds = [-  -- keep synced with hledger.m4.md -> Commands, commands.m4 -->+commandsList :: String -> [String] -> Bool -> [String]+commandsList progversion othercmds highlight0 =+  let highlight = highlight0 && useColorOnStdout in+  (if highlight then (map (\s -> if "+" `isPrefixOf` s then highlightAddon (' ' : drop 1 s) else s)) else id) $+  map (bold'.accent) _banner_smslant ++ +  [+  -- Keep the following synced with:+  --  commands.m4+  --  hledger.m4.md -> Commands+  --  commandsFromCommandsList. Only commands should begin with space or plus.    "-------------------------------------------------------------------------------"   ,progversion   ,"Usage: hledger COMMAND [OPTIONS] [-- ADDONCMDOPTIONS]"   ,"Commands (+ addons found in $PATH):"   ,""-  ,"Data entry (these commands modify the journal file):"-  ," add                      add transactions using guided prompts"+  ,"Usage: " ++ bold' "hledger CMD [OPTS] [-- ADDONCMDOPTS]"+  ,""+  ,"Commands:"+  ,bold' "DATA ENTRY: add or edit entries in the journal file"+  ," add                      add transactions using terminal prompts"+  ,"+edit                     edit a subset of transactions"   ,"+iadd                     add transactions using a TUI"-  ," import                   add any new transactions from other files (eg csv)"+  ," import                   add new transactions from other files, eg CSV files"   ,""-  ,"Data management:"+    -----------------------------------------80-------------------------------------+  ,bold' "DATA CREATION: create or convert entries to be added to the journal file"   ,"+autosync                 download/deduplicate/convert OFX data"-  ," check                    check for various kinds of issue in the data"+  ," close                    generate balance-zeroing/restoring transactions"+  ,"+fifo sell                generate a lot-selling transaction, using FIFO"+  ,"+interest                 generate interest transactions"+  ," rewrite                  generate auto postings, like print --auto"+  ,"+stockquotes              download market prices from AlphaVantage"+  ,""+    -----------------------------------------80-------------------------------------+  ,bold' "DATA MANAGEMENT: help validate or manage journal files"+  ," check                    check for various kinds of error in the data"   ,"+check-fancyassertions    check more powerful balance assertions"   ,"+check-tagfiles           check file paths in tag values exist"-  ," close                    generate balance-resetting transactions"   ," diff                     compare account transactions in two journal files"-  ,"+interest                 generate interest transactions"-  ," rewrite                  generate extra postings, similar to print --auto"-  ,"+stockquotes              download market prices from AlphaVantage"+  ,"+git                      record/status/log journal changes easily with git"+  ,"+pijul                    record/status/log journal changes easily with pijul"   ,""-  ,"Financial reports:"+    -----------------------------------------80-------------------------------------+  ,bold' "REPORTS, FINANCIAL: standard financial reports"   ," aregister (areg)         show transactions in a particular account"   ," balancesheet (bs)        show assets, liabilities and net worth"   ," balancesheetequity (bse) show assets, liabilities and equity"   ," cashflow (cf)            show changes in liquid assets"   ," incomestatement (is)     show revenues and expenses"+  ,""+    -----------------------------------------80-------------------------------------+  ,bold' "REPORTS, VERSATILE: more complex/versatile reporting commands"+  ," balance (bal)            show balance changes, end balances, budgets, gains.."+  ,"+fifo lots                show a commodity's remaining lots, using FIFO"+  ,"+plot                     create charts from balance reports, in terminal or GUI"+  ," print                    show transactions or export journal data"+  ," register (reg)           show postings in one or more accounts & running total"   ," roi                      show return on investments"   ,""-  ,"Low-level reports:"+    -----------------------------------------80-------------------------------------+  ,bold' "REPORTS, BASIC: simple reports"   ," accounts                 show account names"-  ," activity                 show postings-per-interval bar charts"-  ," balance (bal)            show balance changes/end balances/budgets in accounts"+  ," activity                 show bar charts of posting counts per period"   ," codes                    show transaction codes"   ," commodities              show commodity/currency symbols"-  ," descriptions             show unique transaction descriptions"+  ," descriptions             show transaction descriptions"   ," files                    show input file paths"-  ," notes                    show unique note segments of transaction descriptions"-  ," payees                   show unique payee segments of transaction descriptions"-  ," prices                   show market price records"-  ," print                    show transactions (journal entries)"-  ," print-unique             show only transactions with unique descriptions"-  ," register (reg)           show postings in one or more accounts & running total"-  ," register-match           show a recent posting that best matches a description"+  ," notes                    show note parts of transaction descriptions"+  ," payees                   show payee parts of transaction descriptions"+  ," prices                   show market prices"   ," stats                    show journal statistics"   ," tags                     show tag names"   ," test                     run self tests"   ,""-  ,"Alternate user interfaces:"+    -----------------------------------------80-------------------------------------+  ,bold' "UIS: other user interfaces"   ,"+ui                       run terminal UI"   ,"+web                      run web UI"   ,""-  ,"Other:"+  ,bold' "OTHER: other hledger-* addon commands found in PATH"   ] ++-  othercmds+  multicol 80 (map (highlightAddon . (' ':) . drop 1) othercmds)   ++   [""-  ,"Help:"-  ," (no arguments)           show this commands list"-  ," -h                       show general flags"-  ," COMMAND -h               show flags & docs for COMMAND"-  ," help [MANUAL]            show hledger manuals in various formats"+    -----------------------------------------80-------------------------------------+  ,bold' "HELP: command-line help and more docs"+  ," hledger                          show this commands list"+  ," hledger -h                       show hledger's general help"+  ," hledger COMMAND -h               show COMMAND's help"+  ," hledger help [-i|-m|-p] [TOPIC]  show the hledger manual with info/man/pager"+  ," https://hledger.org              html manuals, tutorials, support.."   ,""   ] -- edit                     open a text editor on some part of the journal +-- | Convert a single-column list of items to a multicolumn list+-- fitting within the given width. Wide character-aware.+multicol :: Int -> [String] -> [String]+multicol _ [] = []+multicol width strs =+  let+    maxwidth = maximum' $ map length strs+    numcols = min (length strs) (width `div` (maxwidth+2))+    itemspercol = length strs `div` numcols+    colitems = chunksOf itemspercol strs+    cols = map unlines colitems+    sep = " "+  in+    lines $ T.unpack $ textConcatBottomPadded $ map T.pack $ intersperse sep cols  -- | All names and aliases of builtin commands. builtinCommandNames :: [String]@@ -224,19 +302,18 @@ -- | Extract the command names from commandsList: the first word -- of lines beginning with a space or + sign. commandsFromCommandsList :: [String] -> [String]-commandsFromCommandsList s =-  [w | c:l <- s, c `elem` [' ','+'], let w:_ = words l]+commandsFromCommandsList s = [w | c:l <- s, c `elem` [' ','+'], let w:_ = words l]  knownCommands :: [String]-knownCommands = sort . commandsFromCommandsList . drop 1 $ commandsList progname []  -- progname will not be seen+knownCommands = sort . commandsFromCommandsList $ commandsList progname [] False -- progname will not be seen  -- | Print the commands list, modifying the template above based on -- the currently available addons. Missing addons will be removed, and -- extra addons will be added under Misc. printCommandsList :: String -> [String] -> IO () printCommandsList progversion addonsFound =-    putStr . unlines . concatMap adjustline $-    commandsList progversion (map ('+':) unknownCommandsFound)+    pager . unlines . concatMap adjustline $+    commandsList progversion (map ('+':) unknownCommandsFound) True   where     commandsFound = map (' ':) builtinCommandNames ++ map ('+':) addonsFound     unknownCommandsFound = addonsFound \\ knownCommands

@@ -1,4 +1,5 @@ accounts+ Show account names.  _FLAGS

@@ -43,7 +43,7 @@     -- ps = sortBy (comparing postingDate) $ filterempties $ filter matchapats $ filterdepth $ journalPostings j     ps = sortOn postingDate $ filter (q `matchesPosting`) $ journalPostings j -printDayWith f (DateSpan (Just b) _, ps) = printf "%s %s\n" (show b) (f ps)+printDayWith f (DateSpan (Just b) _, ps) = printf "%s %s\n" (show $ fromEFDay b) (f ps) printDayWith _ _ = error "Expected start date for DateSpan"  -- PARTIAL:  countBar ps = replicate (length ps) barchar

@@ -1,4 +1,5 @@ activity+ Show an ascii barchart of posting counts per interval.  _FLAGS

@@ -22,7 +22,7 @@ import Data.Char (toUpper, toLower) import Data.Either (isRight) import Data.Functor.Identity (Identity(..))-import Data.List (isPrefixOf)+import Data.List (isPrefixOf, nub) import Data.Maybe (fromJust, fromMaybe, isJust) import Data.Text (Text) import qualified Data.Text as T@@ -160,14 +160,15 @@ confirmedTransactionWizard prevInput es [] = confirmedTransactionWizard prevInput es [EnterDateAndCode] confirmedTransactionWizard prevInput es@EntryState{..} stack@(currentStage : _) = case currentStage of   EnterDateAndCode -> dateAndCodeWizard prevInput es >>= \case-    Just (date, code) -> do-      let es' = es-            { esArgs = drop 1 esArgs-            , esDefDate = date-            }-          dateAndCodeString = formatTime defaultTimeLocale yyyymmddFormat date+    Just (efd, code) -> do+      let +        date = fromEFDay efd+        es' = es{ esArgs = drop 1 esArgs+                , esDefDate = date+                }+        dateAndCodeString = formatTime defaultTimeLocale yyyymmddFormat date                             ++ T.unpack (if T.null code then "" else " (" <> code <> ")")-          yyyymmddFormat = "%Y-%m-%d"+        yyyymmddFormat = "%Y-%m-%d"       confirmedTransactionWizard prevInput{prevDateAndCode=Just dateAndCodeString} es' (EnterDescAndComment (date, code) : stack)     Nothing ->       confirmedTransactionWizard prevInput es stack@@ -390,8 +391,9 @@ dateCompleter :: String -> CompletionFunc IO dateCompleter = completer ["today","tomorrow","yesterday"] +-- Offer payees declared, payees used, or full descriptions used. descriptionCompleter :: Journal -> String -> CompletionFunc IO-descriptionCompleter j = completer (map T.unpack $ journalDescriptions j)+descriptionCompleter j = completer (map T.unpack $ nub $ journalPayeesDeclaredOrUsed j ++ journalDescriptions j)  accountCompleter :: Journal -> String -> CompletionFunc IO accountCompleter j = completer (map T.unpack $ journalAccountNamesDeclaredOrImplied j)

@@ -1,4 +1,5 @@ add+ Prompt for transactions and add them to the journal. Any arguments will be used as default inputs for the first N prompts. @@ -24,8 +25,8 @@ -   You can also set the initial defaults with command line arguments. -   Readline-style edit keys can be used during data entry. -   The tab key will auto-complete whenever possible - accounts,-    descriptions, dates (yesterday, today, tomorrow). If the input area-    is empty, it will insert the default value.+    payees/descriptions, dates (yesterday, today, tomorrow). If the+    input area is empty, it will insert the default value. -   If the journal defines a default commodity, it will be added to any     bare numbers entered. -   A parenthesised transaction code may be entered following a date.

@@ -25,6 +25,7 @@ import qualified Data.Text as T import qualified Data.Text.Lazy as TL import qualified Data.Text.Lazy.Builder as TB+import Lucid as L hiding (value_) import System.Console.CmdArgs.Explicit (flagNone, flagReq)  import Hledger@@ -57,7 +58,7 @@       ++ " or $COLUMNS). -wN,M sets description width as well."      )   ,flagNone ["align-all"] (setboolopt "align-all") "guarantee alignment across all lines (slower)"-  ,outputFormatFlag ["txt","csv","json"]+  ,outputFormatFlag ["txt","html","csv","json"]   ,outputFileFlag   ])   [generalflagsgroup1]@@ -102,6 +103,7 @@              reverse items     -- select renderer     render | fmt=="txt"  = accountTransactionsReportAsText opts (_rsQuery rspec') thisacctq+           | fmt=="html" = accountTransactionsReportAsHTML opts (_rsQuery rspec') thisacctq            | fmt=="csv"  = printCSV . accountTransactionsReportAsCsv wd (_rsQuery rspec') thisacctq            | fmt=="json" = toJsonText            | otherwise   = error' $ unsupportedOutputFormatError fmt  -- PARTIAL:@@ -126,6 +128,27 @@     amt  = wbToText $ showMixedAmountB csvDisplay change     bal  = wbToText $ showMixedAmountB csvDisplay balance +-- | Render a register report as a HTML snippet.+accountTransactionsReportAsHTML :: CliOpts -> Query -> Query -> AccountTransactionsReport -> TL.Text+accountTransactionsReportAsHTML copts reportq thisacctq items =+    L.renderText $ L.table_ (do L.thead_ (L.tr_ (do L.th_ "date"+                                                    L.th_ "description"+                                                    L.th_ "otheraccounts"+                                                    L.th_ "change"+                                                    L.th_ "balance"))+                                L.tbody_ (mconcat (map (htmlRow copts reportq thisacctq) items)))++-- | Render one account register report line item as a HTML table row snippet.+htmlRow :: CliOpts -> Query -> Query -> AccountTransactionsReportItem -> L.Html ()+htmlRow CliOpts{reportspec_=ReportSpec{_rsReportOpts=ropts}} reportq thisacctq+    (t@Transaction{tdescription}, _, _issplit, otheracctsstr, amt, bal) =+    L.tr_ (do (L.td_ . toHtml . show . transactionRegisterDate (whichDate ropts) reportq thisacctq) t+              (L.td_ . toHtml) tdescription+              (L.td_ . toHtml) otheracctsstr+              -- piggy back on the oneLine display style for now.+              (L.td_ . toHtml . wbUnpack . showMixedAmountB oneLine) amt+              (L.td_ . toHtml . wbUnpack . showMixedAmountB oneLine) bal)+ -- | Render a register report as plain text suitable for console output. accountTransactionsReportAsText :: CliOpts -> Query -> Query -> AccountTransactionsReport -> TL.Text accountTransactionsReportAsText copts reportq thisacctq items = TB.toLazyText $@@ -138,12 +161,18 @@     itembal (_,_,_,_,_,a) = a      -- show a title indicating which account was picked, which can be confusing otherwise-    title = maybe mempty (\s -> foldMap TB.fromText ["Transactions in ", s, " and subaccounts:"]) macct+    title = maybe mempty (\s -> foldMap TB.fromText ["Transactions in ", s, " and subaccounts", qmsg, ":"]) macct       where         -- XXX temporary hack ? recover the account name from the query         macct = case filterQuery queryIsAcct thisacctq of                   Acct r -> Just . T.drop 1 . T.dropEnd 5 $ reString r  -- Acct "^JS:expenses(:|$)"                   _      -> Nothing  -- shouldn't happen+        -- show a hint in the title when results are restricted by an extra query (other than depth or date or date2)+        qmsg = if hasextraquery then " (matching query)" else ""+          where+            hasextraquery =+              length (querystring_ $ _rsReportOpts $ reportspec_ copts) > 1+              && not (queryIsNull $ filterQuery (not.(\q->queryIsDepth q || queryIsDateOrDate2 q)) reportq)  -- | Render one account register report line item as plain text. Layout is like so: -- @

@@ -1,5 +1,7 @@-aregister, areg+aregister +(areg)+ Show the transactions and running historical balance of a single account, with each transaction displayed as one line. @@ -18,9 +20,14 @@  aregister requires one argument: the account to report on. You can write either the full account name, or a case-insensitive regular expression-which will select the alphabetically first matched account. (Eg if you-have assets:aaa:checking and assets:bbb:checking accounts,-hledger areg checking would select assets:aaa:checking.)+which will select the alphabetically first matched account.++When there are multiple matches, the alphabetically-first choice can be+surprising; eg if you have assets:per:checking 1 and+assets:biz:checking 2 accounts, hledger areg checking would select+assets:biz:checking 2. It's just a convenience to save typing, so if in+doubt, write the full account name, or a distinctive substring that+matches uniquely.  Transactions involving subaccounts of this account will also be shown. aregister ignores depth limits, so its final total will always match a

@@ -320,10 +320,11 @@     ,flagNone ["transpose"] (setboolopt "transpose") "transpose rows and columns"     ,flagReq  ["layout"] (\s opts -> Right $ setopt "layout" s opts) "ARG"       (unlines-        ["how to show multi-commodity amounts:"-        ,"'wide[,WIDTH]': all commodities on one line"-        ,"'tall'        : each commodity on a new line"-        ,"'bare'        : bare numbers, symbols in a column"+        ["how to lay out multi-commodity amounts and the overall table:"+        ,"'wide[,WIDTH]': commodities on one line"+        ,"'tall'        : commodities on separate lines"+        ,"'bare'        : commodity symbols in one column"+        ,"'tidy'        : every attribute in its own column"         ])     ,outputFormatFlag ["txt","html","csv","json"]     ,outputFileFlag@@ -738,8 +739,8 @@     cs = if all mixedAmountLooksZero allamts then [""] else S.toList $ foldMap maCommodities allamts     allamts = as ++ [rowtot | totalscolumn && not (null as)] ++ [rowavg | average_ && not (null as)]     addDateColumns spn@(DateSpan s e) = (wbFromText (showDateSpan spn) :)-                                       . (wbFromText (maybe "" showDate s) :)-                                       . (wbFromText (maybe "" (showDate . addDays (-1)) e) :)+                                       . (wbFromText (maybe "" showEFDate s) :)+                                       . (wbFromText (maybe "" (showEFDate . modifyEFDay (addDays (-1))) e) :)      paddedTranspose :: a -> [[a]] -> [[a]]     paddedTranspose _ [] = [[]]

@@ -1,4 +1,7 @@-balance, bal+balance++(bal)+ Show accounts and their balances.  _FLAGS@@ -73,10 +76,13 @@  With no arguments, balance shows a list of all accounts and their change of balance - ie, the sum of posting amounts, both inflows and outflows --during the entire period of the journal. For real-world accounts, this-should also match their end balance at the end of the journal period-(more on this below).+during the entire period of the journal. ("Simple" here means just one+column of numbers, covering a single period. You can also have+multi-period reports, described later.) +For real-world accounts, these numbers will normally be their end+balance at the end of the journal period; more on this below.+ Accounts are sorted by declaration order if any, and then alphabetically by account name. For instance (using examples/sample.journal): @@ -91,8 +97,8 @@ --------------------                    0   -Accounts with a zero balance (and no non-zero subaccounts, in tree mode-- see below) are hidden by default. Use -E/--empty to show them+Accounts with a zero balance (and no non-zero subaccounts, in tree+mode - see below) are hidden by default. Use -E/--empty to show them (revealing assets:bank:checking here):  $ hledger -f examples/sample.journal bal  -E@@ -110,6 +116,65 @@ The total of the amounts displayed is shown as the last line, unless -N/--no-total is used. +Balance report line format++For single-period balance reports displayed in the terminal (only), you+can use --format FMT to customise the format and content of each line.+Eg:++$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"+              assets          $-1+         bank:saving           $1+                cash          $-2+            expenses           $2+                food           $1+            supplies           $1+              income          $-2+               gifts          $-1+              salary          $-1+   liabilities:debts           $1+---------------------------------+                                0++The FMT format string specifies the formatting applied to each+account/balance pair. It may contain any suitable text, with data fields+interpolated like so:++%[MIN][.MAX](FIELDNAME)++-   MIN pads with spaces to at least this width (optional)++-   MAX truncates at this width (optional)++-   FIELDNAME must be enclosed in parentheses, and can be one of:++    -   depth_spacer - a number of spaces equal to the account's depth,+        or if MIN is specified, MIN * depth spaces.+    -   account - the account's name+    -   total - the account's balance/posted total, right justified++Also, FMT can begin with an optional prefix to control how+multi-commodity amounts are rendered:++-   %_ - render on multiple lines, bottom-aligned (the default)+-   %^ - render on multiple lines, top-aligned+-   %, - render on one line, comma-separated++There are some quirks. Eg in one-line mode, %(depth_spacer) has no+effect, instead %(account) has indentation built in. Experimentation may+be needed to get pleasing results.++Some example formats:++-   %(total) - the account's total+-   %-20.20(account) - the account's name, left justified, padded to 20+    characters and clipped at 20 characters+-   %,%-50(account)  %25(total) - account name padded to 50 characters,+    total padded to 20 characters, with multiple commodities rendered on+    one line+-   %20(total)  %2(depth_spacer)%-(account) - the default format for the+    single-column balance report+ Filtered balance report  You can show fewer accounts, a different time period, totals from@@ -190,6 +255,53 @@ --------------------                   $2   +Showing declared accounts++With --declared, accounts which have been declared with an account+directive will be included in the balance report, even if they have no+transactions. (Since they will have a zero balance, you will also need+-E/--empty to see them.)++More precisely, leaf declared accounts (with no subaccounts) will be+included, since those are usually the more useful in reports.++The idea of this is to be able to see a useful "complete" balance+report, even when you don't have transactions in all of your declared+accounts yet.++Sorting by amount++With -S/--sort-amount, accounts with the largest (most positive)+balances are shown first. Eg: hledger bal expenses -MAS shows your+biggest averaged monthly expenses first. When more than one commodity is+present, they will be sorted by the alphabetically earliest commodity+first, and then by subsequent commodities (if an amount is missing a+commodity, it is treated as 0).++Revenues and liability balances are typically negative, however, so -S+shows these in reverse order. To work around this, you can add --invert+to flip the signs. (Or, use one of the higher-level reports, which flip+the sign automatically. Eg: hledger incomestatement -MAS).++Percentages++With -%/--percent, balance reports show each account's value expressed+as a percentage of the (column) total.++Note it is not useful to calculate percentages if the amounts in a+column have mixed signs. In this case, make a separate report for each+sign, eg:++$ hledger bal -% amt:`>0`+$ hledger bal -% amt:`<0`++Similarly, if the amounts in a column have mixed commodities, convert+them to one commodity with -B, -V, -X or --value, or make a separate+report for each commodity:++$ hledger bal -% cur:\\$+$ hledger bal -% cur:€+ Multi-period balance report  With a report interval (set by the -D/--daily, -W/--weekly,@@ -242,193 +354,6 @@ -   Output as HTML and view with a browser:     hledger bal -D -o a.html && open a.html -Showing declared accounts--With --declared, accounts which have been declared with an account-directive will be included in the balance report, even if they have no-transactions. (Since they will have a zero balance, you will also need--E/--empty to see them.)--More precisely, leaf declared accounts (with no subaccounts) will be-included, since those are usually the more useful in reports.--The idea of this is to be able to see a useful "complete" balance-report, even when you don't have transactions in all of your declared-accounts yet.--Data layout--The --layout option affects how multi-commodity amounts are displayed,-and some other things, influencing the overall layout of the report-data:---   --layout=wide[,WIDTH]: commodities are shown on a single line,-    possibly elided to the specified width--   --layout=tall: each commodity is shown on a separate line--   --layout=bare: amounts are shown as bare numbers, with commodity-    symbols in a separate column--   --layout=tidy: data is normalised to tidy form, with one row per-    data value. We currently support this with CSV output only. In tidy-    mode, totals and row averages are disabled (-N/--no-total is implied-    and -T/--row-total and -A/--average will be ignored).--These --layout modes are supported with some but not all of the output-formats:--  -      txt   csv   html   json   sql-  ------ ----- ----- ------ ------ ------  wide   Y     Y     Y             -  tall   Y     Y     Y             -  bare   Y     Y     Y             -  tidy         Y                   --Examples:---   Wide layout. With many commodities, reports can be very wide:--    $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide-    Balance changes in 2012-01-01..2014-12-31:--                      ||                                          2012                                                     2013                                             2014                                                      Total -    ==================++====================================================================================================================================================================================================================-     Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT -    ------------------++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                      || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT ---   Limited wide layout. A width limit reduces the width, but some-    commodities will be hidden:--    $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32-    Balance changes in 2012-01-01..2014-12-31:--                      ||                             2012                             2013                   2014                            Total -    ==================++===========================================================================================================================-     Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. -    ------------------++----------------------------------------------------------------------------------------------------------------------------                      || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. ---   Tall layout. Each commodity gets a new line (may be different in-    each column), and account names are repeated:--    $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall-    Balance changes in 2012-01-01..2014-12-31:--                      ||       2012        2013         2014        Total -    ==================++==================================================-     Assets:US:ETrade || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD -     Assets:US:ETrade || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT -     Assets:US:ETrade ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD -     Assets:US:ETrade || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA -     Assets:US:ETrade ||              18.00 VHT                294.00 VHT -    ------------------++---------------------------------------------------                      || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD -                      || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT -                      ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD -                      || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA -                      ||              18.00 VHT                294.00 VHT ---   Bare layout. Commodity symbols are kept in one column, each-    commodity gets its own report row, account names are repeated:--    $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare-    Balance changes in 2012-01-01..2014-12-31:--                      || Commodity    2012    2013     2014    Total -    ==================++=============================================-     Assets:US:ETrade || GLD             0   70.00        0    70.00 -     Assets:US:ETrade || ITOT        10.00   18.00   -11.00    17.00 -     Assets:US:ETrade || USD        337.18  -98.12  4881.44  5120.50 -     Assets:US:ETrade || VEA         12.00   10.00    14.00    36.00 -     Assets:US:ETrade || VHT        106.00   18.00   170.00   294.00 -    ------------------++----------------------------------------------                      || GLD             0   70.00        0    70.00 -                      || ITOT        10.00   18.00   -11.00    17.00 -                      || USD        337.18  -98.12  4881.44  5120.50 -                      || VEA         12.00   10.00    14.00    36.00 -                      || VHT        106.00   18.00   170.00   294.00 ---   Bare layout also affects CSV output, which is useful for producing-    data that is easier to consume, eg when making charts:--    $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare-    "account","commodity","balance"-    "Assets:US:ETrade","GLD","70.00"-    "Assets:US:ETrade","ITOT","17.00"-    "Assets:US:ETrade","USD","5120.50"-    "Assets:US:ETrade","VEA","36.00"-    "Assets:US:ETrade","VHT","294.00"-    "total","GLD","70.00"-    "total","ITOT","17.00"-    "total","USD","5120.50"-    "total","VEA","36.00"-    "total","VHT","294.00"---   Tidy layout produces normalised "tidy data", where every variable is-    a column and each row represents a single data point (see-    https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html).-    This kind of data is the easiest to process with other software:--    $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy-    "account","period","start_date","end_date","commodity","value"-    "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"-    "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"-    "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"-    "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"-    "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"-    "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"-    "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"-    "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"-    "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"-    "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"-    "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"-    "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"-    "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"-    "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"-    "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"--Sorting by amount--With -S/--sort-amount, accounts with the largest (most positive)-balances are shown first. Eg: hledger bal expenses -MAS shows your-biggest averaged monthly expenses first. When more than one commodity is-present, they will be sorted by the alphabetically earliest commodity-first, and then by subsequent commodities (if an amount is missing a-commodity, it is treated as 0).--Revenues and liability balances are typically negative, however, so -S-shows these in reverse order. To work around this, you can add --invert-to flip the signs. (Or, use one of the higher-level reports, which flip-the sign automatically. Eg: hledger incomestatement -MAS).--Percentages--With -%/--percent, balance reports show each account's value expressed-as a percentage of the (column) total:--$ hledger -f examples/sample.journal bal expenses -Q -%-Balance changes in 2008:--                   || 2008Q1   2008Q2  2008Q3  2008Q4 -===================++=================================- expenses:food     ||      0   50.0 %       0       0 - expenses:supplies ||      0   50.0 %       0       0 --------------------++----------------------------------                   ||      0  100.0 %       0       0 --Note it is not useful to calculate percentages if the amounts in a-column have mixed signs. In this case, make a separate report for each-sign, eg:--$ hledger bal -% amt:`>0`-$ hledger bal -% amt:`<0`--Similarly, if the amounts in a column have mixed commodities, convert-them to one commodity with -B, -V, -X or --value, or make a separate-report for each commodity:--$ hledger bal -% cur:\\$-$ hledger bal -% cur:€- Balance change, end balance  It's important to be clear on the meaning of the numbers shown in@@ -464,59 +389,76 @@  Balance report types -For more flexible reporting, there are three important option groups:+The balance command is quite flexible; here is the full detail on how to+control what it reports. If the following seems complicated, don't+worry - this is for advanced reporting, and it does typically take some+time and experimentation to get clear on all these report modes. +There are three important option groups:+ hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ... -The first two are the most important: calculation type selects the basic-calculation to perform for each table cell, while accumulation type says-which postings should be included in each cell's calculation. Typically-one or both of these are selected by default, so you don't need to write-them explicitly. A valuation type can be added if you want to convert-the basic report to value or cost.+Calculation type -Calculation type: The basic calculation to perform for each table cell. It is one of:  -   --sum : sum the posting amounts (default)--   --budget : like --sum but also show a goal amount+-   --budget : sum the amounts, but also show the budget goal amount+    (for each account/period) -   --valuechange : show the change in period-end historical balance     values (caused by deposits, withdrawals, and/or market price     fluctuations) -   --gain : show the unrealised capital gain/loss, (the current valued     balance minus each amount's original cost) -Accumulation type:-Which postings should be included in each cell's calculation. It is one-of:+Accumulation type --   --change : postings from column start to column end, ie within the-    cell's period. Typically used to see revenues/expenses. (default for-    balance, incomestatement)+How amounts should accumulate across report periods. Another way to say+it: which time period's postings should contribute to each cell's+calculation. It is one of: --   --cumulative : postings from report start to column end, eg to show-    changes accumulated since the report's start date. Rarely used.+-   --change : calculate with postings from column start to column end,+    ie "just this column". Typically used to see revenues/expenses.+    (default for balance, incomestatement) --   --historical/-H : postings from journal start to column end, ie all-    postings from account creation to the end of the cell's period.-    Typically used to see historical end balances of+-   --cumulative : calculate with postings from report start to column+    end, ie "previous columns plus this column". Typically used to show+    changes accumulated since the report's start date. Not often used.++-   --historical/-H : calculate with postings from journal start to+    column end, ie "all postings from before report start date until+    this column's end". Typically used to see historical end balances of     assets/liabilities/equity. (default for balancesheet,     balancesheetequity, cashflow) -Valuation type:-Which kind of valuation, valuation date(s) and optionally a target-valuation commodity to use. It is one of:+Valuation type --   no valuation, show amounts in their original commodities (default)--   --value=cost[,COMM] : no valuation, show amounts converted to cost--   --value=then[,COMM] : show value at transaction dates--   --value=end[,COMM] : show value at period end date(s) (default with-    --valuechange, --gain)--   --value=now[,COMM] : show value at today's date--   --value=YYYY-MM-DD[,COMM] : show value at another date+Which kind of value or cost conversion should be applied, if any, before+displaying the report. It is one of: -or one of their aliases: --cost/-B, --market/-V or --exchange/-X.+-   no valuation type : don't convert to cost or value (default)+-   --value=cost[,COMM] : convert amounts to cost (then optionally to+    some other commodity)+-   --value=then[,COMM] : convert amounts to market value on transaction+    dates+-   --value=end[,COMM] : convert amounts to market value on period end+    date(s)+    (default with --valuechange, --gain)+-   --value=now[,COMM] : convert amounts to market value on today's date+-   --value=YYYY-MM-DD[,COMM] : convert amounts to market value on+    another date +or one of the equivalent simpler flags:++-   -B/--cost : like --value=cost (though, note --cost and --value are+    independent options which can both be used at once)+-   -V/--market : like --value=end+-   -X COMM/--exchange COMM : like --value=end,COMM++See Cost reporting and Valuation for more about these.++Combining balance report types+ Most combinations of these options should produce reasonable reports, but if you find any that seem wrong or misleading, let us know. The following restrictions are applied:@@ -530,8 +472,8 @@ valuation show:    -------------------------------------------------------------------------------------------------  Valuation:         no valuation     --value= then     --value= end    --value= YYYY-MM-DD /now-  >Accumulation: v                                                      +  Valuation:>        no valuation     --value= then     --value= end    --value= YYYY-MM-DD /now+  Accumulation:v                                                           ------------------ ---------------- ----------------- --------------- --------------------------   --change           change in period sum of            period-end      DATE-value of change in                                       posting-date      value of change period@@ -552,47 +494,12 @@                                       end                                  ------------------------------------------------------------------------------------------------ -Useful balance reports--Some frequently used balance options/reports are:---   bal -M revenues expenses-    Show revenues/expenses in each month. Also available as the-    incomestatement command.---   bal -M -H assets liabilities-    Show historical asset/liability balances at each month end. Also-    available as the balancesheet command.---   bal -M -H assets liabilities equity-    Show historical asset/liability/equity balances at each month end.-    Also available as the balancesheetequity command.---   bal -M assets not:receivable-    Show changes to liquid assets in each month. Also available as the-    cashflow command.--Also:---   bal -M expenses -2 -SA-    Show monthly expenses summarised to depth 2 and sorted by average-    amount.---   bal -M --budget expenses-    Show monthly expenses and budget goals.---   bal -M --valuechange investments-    Show monthly change in market value of investment assets.---   bal investments --valuechange -D date:lastweek amt:'>1000' -STA [--invert]-    Show top gainers [or losers] last week- Budget report  The --budget report type activates extra columns showing any budget goals for each account and period. The budget goals are defined by-periodic transactions. This is very useful for comparing planned and-actual income, expenses, time usage, etc.+periodic transactions. This is useful for comparing planned and actual+income, expenses, time usage, etc.  For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget:@@ -699,6 +606,18 @@ ----------------------++----------------------------------------------------                       ||      0 [              0]       0 [              0]  +It's common to limit budgets/budget reports to just expenses++hledger bal -M --budget expenses++or just revenues and expenses (eg, using account types):++hledger bal -M --budget type:rx++It's also common to limit or convert them to a single currency (cur:COMM+or -X COMM [--infer-market-prices]). If showing multiple currencies,+--layout bare or --layout tall can help.+ For more examples and notes, see Budgeting.  Budget report start date@@ -830,8 +749,8 @@  The budget report evaluates periodic transaction rules to generate special "goal transactions", which generate the goal amounts for each-account in each report subperiod. When troubleshooting, you can use the-print command to show these as forecasted transactions:+account in each report subperiod. When troubleshooting, you can use+print --forecast to show these as forecasted transactions:  $ hledger print --forecast=BUDGETREPORTPERIOD tag:generated @@ -848,61 +767,208 @@ rules descriptions (remember that two spaces are needed), and then select from multiple budgets defined in your journal. -Customising single-period balance reports+Budget vs forecast -For single-period balance reports displayed in the terminal (only), you-can use --format FMT to customise the format and content of each line.-Eg:+hledger --forecast ... and hledger balance --budget ... are separate+features, though both of them use the periodic transaction rules defined+in the journal, and both of them generate temporary transactions for+reporting purposes ("forecast transactions" and "budget goal+transactions", respectively). You can use both features at the same time+if you want. Here are some differences between them, as of hledger 1.29: -$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"-              assets          $-1-         bank:saving           $1-                cash          $-2-            expenses           $2-                food           $1-            supplies           $1-              income          $-2-               gifts          $-1-              salary          $-1-   liabilities:debts           $1-----------------------------------                                0+CLI: -The FMT format string (plus a newline) specifies the formatting applied-to each account/balance pair. It may contain any suitable text, with-data fields interpolated like so:+-   --forecast is a general hledger option, usable with any command+-   --budget is a balance command option, usable only with that command. -%[MIN][.MAX](FIELDNAME)+Visibility of generated transactions: --   MIN pads with spaces to at least this width (optional)+-   forecast transactions are visible in any report, like ordinary+    transactions+-   budget goal transactions are invisible except for the goal amounts+    they produce in --budget reports. --   MAX truncates at this width (optional)+Periodic transaction rules: --   FIELDNAME must be enclosed in parentheses, and can be one of:+-   --forecast uses all available periodic transaction rules+-   --budget uses all periodic rules (--budget) or a selected subset+    (--budget=DESCPAT) -    -   depth_spacer - a number of spaces equal to the account's depth,-        or if MIN is specified, MIN * depth spaces.-    -   account - the account's name-    -   total - the account's balance/posted total, right justified+Period of generated transactions: -Also, FMT can begin with an optional prefix to control how-multi-commodity amounts are rendered:+-   --forecast generates forecast transactions+    -   from after the last regular transaction to the end of the report+        period (--forecast)+    -   or, during a specified period (--forecast=PERIODEXPR)+    -   possibly further restricted by a period specified in the+        periodic transaction rule+    -   and always restricted within the bounds of the report period+-   --budget generates budget goal transactions+    -   throughout the report period+    -   possibly restricted by a period specified in the periodic+        transaction rule. --   %_ - render on multiple lines, bottom-aligned (the default)--   %^ - render on multiple lines, top-aligned--   %, - render on one line, comma-separated+Data layout -There are some quirks. Eg in one-line mode, %(depth_spacer) has no-effect, instead %(account) has indentation built in. Experimentation may-be needed to get pleasing results.+The --layout option affects how balance reports show multi-commodity+amounts and commodity symbols, which can improve readability. It can+also normalise the data for easy consumption by other programs. It has+four possible values: -Some example formats:+-   --layout=wide[,WIDTH]: commodities are shown on a single line,+    optionally elided to WIDTH+-   --layout=tall: each commodity is shown on a separate line+-   --layout=bare: commodity symbols are in their own column, amounts+    are bare numbers+-   --layout=tidy: data is normalised to easily-consumed "tidy" form,+    with one row per data value --   %(total) - the account's total--   %-20.20(account) - the account's name, left justified, padded to 20-    characters and clipped at 20 characters--   %,%-50(account)  %25(total) - account name padded to 50 characters,-    total padded to 20 characters, with multiple commodities rendered on-    one line--   %20(total)  %2(depth_spacer)%-(account) - the default format for the-    single-column balance report+Here are the --layout modes supported by each output format; note only+CSV output supports all of them:++  -      txt   csv   html   json   sql+  ------ ----- ----- ------ ------ -----+  wide   Y     Y     Y             +  tall   Y     Y     Y             +  bare   Y     Y     Y             +  tidy         Y                   ++Examples:++-   Wide layout. With many commodities, reports can be very wide:++    $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide+    Balance changes in 2012-01-01..2014-12-31:++                      ||                                          2012                                                     2013                                             2014                                                      Total +    ==================++====================================================================================================================================================================================================================+     Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +    ------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+                      || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT ++-   Limited wide layout. A width limit reduces the width, but some+    commodities will be hidden:++    $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32+    Balance changes in 2012-01-01..2014-12-31:++                      ||                             2012                             2013                   2014                            Total +    ==================++===========================================================================================================================+     Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. +    ------------------++---------------------------------------------------------------------------------------------------------------------------+                      || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. ++-   Tall layout. Each commodity gets a new line (may be different in+    each column), and account names are repeated:++    $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall+    Balance changes in 2012-01-01..2014-12-31:++                      ||       2012        2013         2014        Total +    ==================++==================================================+     Assets:US:ETrade || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD +     Assets:US:ETrade || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT +     Assets:US:ETrade ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD +     Assets:US:ETrade || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA +     Assets:US:ETrade ||              18.00 VHT                294.00 VHT +    ------------------++--------------------------------------------------+                      || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD +                      || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT +                      ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD +                      || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA +                      ||              18.00 VHT                294.00 VHT ++-   Bare layout. Commodity symbols are kept in one column, each+    commodity gets its own report row, account names are repeated:++    $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare+    Balance changes in 2012-01-01..2014-12-31:++                      || Commodity    2012    2013     2014    Total +    ==================++=============================================+     Assets:US:ETrade || GLD             0   70.00        0    70.00 +     Assets:US:ETrade || ITOT        10.00   18.00   -11.00    17.00 +     Assets:US:ETrade || USD        337.18  -98.12  4881.44  5120.50 +     Assets:US:ETrade || VEA         12.00   10.00    14.00    36.00 +     Assets:US:ETrade || VHT        106.00   18.00   170.00   294.00 +    ------------------++---------------------------------------------+                      || GLD             0   70.00        0    70.00 +                      || ITOT        10.00   18.00   -11.00    17.00 +                      || USD        337.18  -98.12  4881.44  5120.50 +                      || VEA         12.00   10.00    14.00    36.00 +                      || VHT        106.00   18.00   170.00   294.00 ++-   Bare layout also affects CSV output, which is useful for producing+    data that is easier to consume, eg for making charts:++    $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare+    "account","commodity","balance"+    "Assets:US:ETrade","GLD","70.00"+    "Assets:US:ETrade","ITOT","17.00"+    "Assets:US:ETrade","USD","5120.50"+    "Assets:US:ETrade","VEA","36.00"+    "Assets:US:ETrade","VHT","294.00"+    "total","GLD","70.00"+    "total","ITOT","17.00"+    "total","USD","5120.50"+    "total","VEA","36.00"+    "total","VHT","294.00"++-   Tidy layout produces normalised "tidy data", where every variable+    has its own column and each row represents a single data point. See+    https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html+    for more. This is the easiest kind of data for other software to+    consume. Here's how it looks:++    $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy+    "account","period","start_date","end_date","commodity","value"+    "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"+    "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"+    "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"+    "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"+    "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"+    "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"+    "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"+    "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"+    "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"+    "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"+    "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"+    "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"+    "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"+    "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"+    "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"++Useful balance reports++Some frequently used balance options/reports are:++-   bal -M revenues expenses+    Show revenues/expenses in each month. Also available as the+    incomestatement command.++-   bal -M -H assets liabilities+    Show historical asset/liability balances at each month end. Also+    available as the balancesheet command.++-   bal -M -H assets liabilities equity+    Show historical asset/liability/equity balances at each month end.+    Also available as the balancesheetequity command.++-   bal -M assets not:receivable+    Show changes to liquid assets in each month. Also available as the+    cashflow command.++Also:++-   bal -M expenses -2 -SA+    Show monthly expenses summarised to depth 2 and sorted by average+    amount.++-   bal -M --budget expenses+    Show monthly expenses and budget goals.++-   bal -M --valuechange investments+    Show monthly change in market value of investment assets.++-   bal investments --valuechange -D date:lastweek amt:'>1000' -STA [--invert]+    Show top gainers [or losers] last week

@@ -1,4 +1,7 @@-balancesheet, bs+balancesheet++(bs)+ This command displays a balance sheet, showing historical ending balances of asset and liability accounts. (To see equity as well, use the balancesheetequity command.) Amounts are shown with normal positive

@@ -1,4 +1,7 @@-balancesheetequity, bse+balancesheetequity++(bse)+ This command displays a balance sheet, showing historical ending balances of asset, liability and equity accounts. Amounts are shown with normal positive sign, as in conventional financial statements.

@@ -1,4 +1,7 @@-cashflow, cf+cashflow++(cf)+ This command displays a cashflow statement, showing the inflows and outflows affecting "cash" (ie, liquid, easily convertible) assets. Amounts are shown with normal positive sign, as in conventional

@@ -66,6 +66,7 @@   | Ordereddates   | Payees   | Recentassertions+  | Tags   | Uniqueleafnames   deriving (Read,Show,Eq,Enum,Bounded) @@ -105,6 +106,7 @@       Ordereddates    -> journalCheckOrdereddates (whichDate ropts) j       Payees          -> journalCheckPayees j       Recentassertions -> journalCheckRecentAssertions d j+      Tags            -> journalCheckTags j       Uniqueleafnames -> journalCheckUniqueleafnames j       -- the other checks have been done earlier during withJournalDo       _               -> Right ()

@@ -1,4 +1,5 @@ check+ Check for various kinds of errors in your data.  _FLAGS@@ -30,8 +31,7 @@  -   balancedwithautoconversion - all transactions are balanced,     inferring missing amounts where necessary, and possibly converting-    commodities using transaction prices or automatically-inferred-    transaction prices+    commodities using costs or automatically-inferred costs  -   assertions - all balance assertions in the journal are passing.     (This check can be disabled with -I/--ignore-assertions.)@@ -47,7 +47,7 @@ -   commodities - all commodity symbols used have been declared  -   balancednoautoconversion - transactions are balanced, possibly using-    explicit transaction prices but not inferred ones+    explicit costs but not inferred ones  Other checks @@ -61,6 +61,8 @@  -   recentassertions - all accounts with balance assertions have a     balance assertion no more than 7 days before their latest posting++-   tags - all tags used by transactions have been declared  -   uniqueleafnames - all account leaf names are unique 

@@ -1,5 +1,6 @@ {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE TemplateHaskell #-}+{-# LANGUAGE MultiWayIf #-}  module Hledger.Cli.Commands.Close (   closemode@@ -20,92 +21,75 @@ import Hledger import Hledger.Cli.CliOptions -defclosingdesc = "closing balances"-defopeningdesc = "opening balances"-defclosingacct = "equity:opening/closing balances"-defopeningacct = defclosingacct+defretaindesc = "retain earnings"+defclosedesc  = "closing balances"+defopendesc   = "opening balances"+defretainacct = "equity:retained earnings"+defcloseacct  = "equity:opening/closing balances"  closemode = hledgerCommandMode   $(embedFileRelative "Hledger/Cli/Commands/Close.txt")-  [flagNone ["close"]        (setboolopt "close") "show just closing transaction"-  ,flagNone ["open"]         (setboolopt "open") "show just opening transaction"-  ,flagReq  ["close-desc"]   (\s opts -> Right $ setopt "close-desc" s opts) "DESC" ("description for closing transaction (default: "++defclosingdesc++")")-  ,flagReq  ["open-desc"]    (\s opts -> Right $ setopt "open-desc"  s opts) "DESC" ("description for opening transaction (default: "++defopeningdesc++")")-  ,flagReq  ["close-acct"]   (\s opts -> Right $ setopt "close-acct" s opts) "ACCT" ("account to transfer closing balances to (default: "++defclosingacct++")")-  ,flagReq  ["open-acct"]    (\s opts -> Right $ setopt "open-acct"  s opts) "ACCT" ("account to transfer opening balances from (default: "++defopeningacct++")")+  [flagNone ["retain"]       (setboolopt "retain")  "show RX retain earnings transaction"+  ,flagNone ["migrate"]      (setboolopt "migrate") "show ALE closing/opening transactions"+  ,flagNone ["open"]         (setboolopt "open")    "show ALE opening transaction"+  ,flagReq  ["close-desc"]   (\s opts -> Right $ setopt "close-desc" s opts) "DESC" ("description for closing transaction (default: "++defclosedesc++")")+  ,flagReq  ["open-desc"]    (\s opts -> Right $ setopt "open-desc"  s opts) "DESC" ("description for opening transaction (default: "++defopendesc++")")+  ,flagReq  ["close-acct"]   (\s opts -> Right $ setopt "close-acct" s opts) "ACCT" ("account to transfer closing balances to (default: "++defcloseacct++")")   ,flagNone ["explicit","x"] (setboolopt "explicit") "show all amounts explicitly"-  ,flagNone ["interleaved"]  (setboolopt "interleaved") "keep equity and non-equity postings adjacent"+  ,flagNone ["interleaved"]  (setboolopt "interleaved") "keep source and destination postings adjacent"   ,flagNone ["show-costs"]   (setboolopt "show-costs") "keep balances with different costs separate"   ]   [generalflagsgroup1]-  (hiddenflags ++-    -- old close flags for compatibility, hidden-    [flagNone ["closing"] (setboolopt "close") "old spelling of --close"-    ,flagNone ["opening"] (setboolopt "open") "old spelling of --open"-    ,flagReq  ["close-to"]  (\s opts -> Right $ setopt "close-acct" s opts) "ACCT" ("old spelling of --close-acct")-    ,flagReq  ["open-from"] (\s opts -> Right $ setopt "open-acct" s opts) "ACCT" ("old spelling of --open-acct")-    ])+  (hiddenflags+    -- any old command flags for compatibility, hidden+    -- ++ []+  )   ([], Just $ argsFlag "[QUERY]") --- debugger, beware: close is incredibly devious. simple rules combine to make a horrid maze.--- tests are in hledger/test/close.test.-close copts@CliOpts{rawopts_=rawopts, reportspec_=rspec'} j = do+-- Debugger, beware: close is incredibly devious; simple rules combine to make a horrid maze.+-- Tests are in hledger/test/close.test.+-- This code is also used by the close command.+close copts@CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do   let-    -- show opening entry, closing entry, or (default) both ?-    (opening, closing) =-      case (boolopt "open" rawopts, boolopt "close" rawopts) of-        (False, False) -> (True, True)-        (o, c)         -> (o, c)+    (close_, open_, defclosedesc_, defopendesc_, defcloseacct_, defacctsq_) = if+      | boolopt "retain"  rawopts -> (True,  False, defretaindesc, undefined,   defretainacct, Type [Revenue, Expense])+      | boolopt "migrate" rawopts -> (True,  True,  defclosedesc,  defopendesc, defcloseacct,  Type [Asset, Liability, Equity])+      | boolopt "open"    rawopts -> (False, True,  undefined,     defopendesc, defcloseacct,  Type [Asset, Liability, Equity])+      | otherwise                 -> (True,  False, defclosedesc,  undefined,   defcloseacct,  Any)      -- descriptions to use for the closing/opening transactions-    closingdesc = maybe (T.pack defclosingdesc) T.pack $ maybestringopt "close-desc" rawopts-    openingdesc = maybe (T.pack defopeningdesc) T.pack $ maybestringopt "open-desc" rawopts--    -- accounts to close to and open from-    -- if only one is specified, it is used for both-    (closingacct, openingacct) =-      let (mc, mo) =-            (T.pack <$> maybestringopt "close-acct" rawopts, T.pack <$> maybestringopt "open-acct" rawopts)-      in case (mc, mo) of-        (Just c, Just o)   -> (c, o)-        (Just c, Nothing)  -> (c, c)-        (Nothing, Just o)  -> (o, o)-        (Nothing, Nothing) -> (T.pack defclosingacct, T.pack defopeningacct)+    closedesc = T.pack $ fromMaybe defclosedesc_ $ maybestringopt "close-desc" rawopts+    opendesc  = T.pack $ fromMaybe defopendesc_  $ maybestringopt "open-desc"  rawopts+    closeacct = T.pack $ fromMaybe defcloseacct_ $ maybestringopt "close-acct" rawopts+    openacct  = closeacct -    ropts = (_rsReportOpts rspec'){balanceaccum_=Historical, accountlistmode_=ALFlat}-    rspec = setDefaultConversionOp NoConversionOp rspec'{_rsReportOpts=ropts}+    ropts = (_rsReportOpts rspec0){balanceaccum_=Historical, accountlistmode_=ALFlat}+    rspec1 = setDefaultConversionOp NoConversionOp rspec0{_rsReportOpts=ropts}      -- dates of the closing and opening transactions-    --     -- Close.md:     -- "The default closing date is yesterday, or the journal's end date, whichever is later.-    ---    -- Unless you are running `close` on exactly the first day of the new period, -    -- you'll want to override the closing date. -    -- This is done by specifying a [report period](#report-start--end-date), +    -- You can change this by specifying a [report end date](#report-start--end-date),     -- where "last day of the report period" will be the closing date.-    -- The opening date is always the following day.-    -- So to close on 2020-12-31 and open on 2021-01-01, any of these work-    ---    -- - `-p 2020`-    -- - `date:2020`-    -- - `-e 2021-01-01`  (remember `-e` specifies an exclusive report end date)-    -- - `-e 2021`"-    ---    q = _rsQuery rspec-    yesterday = addDays (-1) $ _rsDay rspec+    -- (Only the end date matters; a report start date will be ignored.)+    -- The opening date is always the day after the closing date."+    argsq = _rsQuery rspec1+    yesterday = addDays (-1) $ _rsDay rspec1     yesterdayorjournalend = case journalLastDay False j of       Just journalend -> max yesterday journalend       Nothing         -> yesterday-    mreportlastday = addDays (-1) <$> queryEndDate False q-    closingdate = fromMaybe yesterdayorjournalend  mreportlastday-    openingdate = addDays 1 closingdate+    mreportlastday = addDays (-1) <$> queryEndDate False argsq+    closedate = fromMaybe yesterdayorjournalend  mreportlastday+    opendate = addDays 1 closedate      -- should we show the amount(s) on the equity posting(s) ?     explicit = boolopt "explicit" rawopts || copts ^. infer_costs      -- the balances to close-    (acctbals',_) = balanceReport rspec j+    argsacctq = filterQuery (\q -> queryIsAcct q || queryIsType q) argsq+    q2 = if queryIsNull argsacctq then And [argsq, defacctsq_] else argsq+    rspec2 = rspec1{_rsQuery=q2}+    (acctbals',_) = balanceReport rspec2 j     acctbals = map (\(a,_,_,b) -> (a, if show_costs_ ropts then b else mixedAmountStripPrices b)) acctbals'     totalamt = maSum $ map snd acctbals @@ -117,8 +101,8 @@     interleaved = boolopt "interleaved" rawopts      -- the closing transaction-    closingtxn = nulltransaction{tdate=closingdate, tdescription=closingdesc, tpostings=closingps}-    closingps =+    closetxn = nulltransaction{tdate=closedate, tdescription=closedesc, tpostings=closeps}+    closeps =       concat [         posting{paccount          = a                ,pamount           = mixedAmount . precise $ negate b@@ -131,7 +115,7 @@                }          -- maybe an interleaved posting transferring this balance to equity-        : [posting{paccount=closingacct, pamount=mixedAmount $ precise b} | interleaved]+        : [posting{paccount=closeacct, pamount=mixedAmount $ precise b} | interleaved]          | -- get the balances for each commodity and transaction price           (a,mb) <- acctbals@@ -144,11 +128,11 @@        -- or a final multicommodity posting transferring all balances to equity       -- (print will show this as multiple single-commodity postings)-      ++ [posting{paccount=closingacct, pamount=if explicit then mixedAmountSetFullPrecision totalamt else missingmixedamt} | not interleaved]+      ++ [posting{paccount=closeacct, pamount=if explicit then mixedAmountSetFullPrecision totalamt else missingmixedamt} | not interleaved]      -- the opening transaction-    openingtxn = nulltransaction{tdate=openingdate, tdescription=openingdesc, tpostings=openingps}-    openingps =+    opentxn = nulltransaction{tdate=opendate, tdescription=opendesc, tpostings=openps}+    openps =       concat [         posting{paccount          = a                ,pamount           = mixedAmount $ precise b@@ -157,7 +141,7 @@                      Just s  -> Just nullassertion{baamount=precise s{aprice=Nothing}}                      Nothing -> Nothing                }-        : [posting{paccount=openingacct, pamount=mixedAmount . precise $ negate b} | interleaved]+        : [posting{paccount=openacct, pamount=mixedAmount . precise $ negate b} | interleaved]          | (a,mb) <- acctbals         , let bs0 = amounts mb@@ -167,8 +151,8 @@                            , let commoditysum = (sum bs1)]         , (b, mcommoditysum) <- bs2         ]-      ++ [posting{paccount=openingacct, pamount=if explicit then mixedAmountSetFullPrecision (maNegate totalamt) else missingmixedamt} | not interleaved]+      ++ [posting{paccount=openacct, pamount=if explicit then mixedAmountSetFullPrecision (maNegate totalamt) else missingmixedamt} | not interleaved]    -- print them-  when closing . T.putStr $ showTransaction closingtxn-  when opening . T.putStr $ showTransaction openingtxn+  when close_ . T.putStr $ showTransaction closetxn+  when open_  . T.putStr $ showTransaction opentxn

@@ -1,197 +1,166 @@-close, equity-Prints a sample "closing" transaction bringing specified account-balances to zero, and an inverse "opening" transaction restoring the-same account balances.--If like most people you split your journal files by time, eg by year: at-the end of the year you can use this command to "close out" your asset-and liability (and perhaps equity) balances in the old file, and-reinitialise them in the new file. This helps ensure that report-balances remain correct whether you are including old files or not.-(Because all closing/opening transactions except the very first will-cancel out - see example below.)--Some people also use this command to close out revenue and expense-balances at the end of an accounting period. This properly records the-period's profit/loss as "retained earnings" (part of equity), and allows-the accounting equation (A-L=E) to balance, which you could then check-by the bse report's zero total.--_FLAGS--You can print just the closing transaction by using the --close flag, or-just the opening transaction with the --open flag.--Their descriptions are closing balances and opening balances by default;-you can customise these with the --close-desc and --open-desc options.--Just one balancing equity posting is used by default, with the amount-left implicit. The default account name is-equity:opening/closing balances. You can customise the account name(s)-with --close-acct and --open-acct. (If you specify only one of these, it-will be used for both.)+close -With --x/--explicit, the equity posting's amount will be shown-explicitly, and if it involves multiple commodities, there will be a-separate equity posting for each commodity (as in the print command).+close [--retain | --migrate | --open] [QUERY] -With --interleaved, each equity posting is shown next to the posting it-balances (good for troubleshooting).+By default: prints a transaction that zeroes out ("closes") all+accounts, transferring their balances to an equity account. Query+arguments can be added to override the accounts selection. Three other+modes are supported: -close and prices+--retain: prints a transaction closing revenue and expense balances.+This is traditionally done by businesses at the end of each accounting+period; it is less necessary in personal and computer-based accounting,+but it can help balance the accounting equation A=L+E. -Transaction prices are ignored (and discarded) by closing/opening-transactions, by default. With --show-costs, they are preserved; there-will be a separate equity posting for each cost in each commodity. This-means balance -B reports will look the same after the transition. Note-if you have many foreign currency or investment transactions, this will-generate very large journal entries.+--migrate: prints a transaction to close asset, liability and most+equity balances, and another transaction to re-open them. This can be+useful when starting a new file (for performance or data protection).+Adding the closing transaction to the old file allows old and new files+to be combined. -close date+--open: as above, but prints just the opening transaction. This can be+useful for starting a new file, leaving the old file unchanged. Similar+to Ledger's equity command. -The default closing date is yesterday, or the journal's end date,-whichever is later.+_FLAGS -Unless you are running close on exactly the first day of the new period,-you'll want to override the closing date. This is done by specifying a-report end date, where "last day of the report period" will be the-closing date. The opening date is always the following day. So to close-on (end of) 2020-12-31 and open on (start of) 2021-01-01, any of these-will work:+You can change the equity account name with --close-acct ACCT. It+defaults to equity:retained earnings with --retain, or+equity:opening/closing balances otherwise. -  end date argument   explanation-  ------------------- -------------------------------------------------  -e 2021-01-01       end dates are exclusive-  -e 2021             equivalent, per smart dates-  -p 2020             equivalent, the period's begin date is ignored-  date:2020           equivalent query+You can change the transaction description(s) with --close-desc 'DESC'+and --open-desc 'DESC'. It defaults to retain earnings with --retain, or+closing balances and opening balances otherwise. -Example: close asset/liability accounts for file transition+Just one posting to the equity account will be used by default, with an+implicit amount. -Carrying asset/liability balances from 2020.journal into a new file for-2021:+With --x/--explicit the amount will be shown explicitly, and if it+involves multiple commodities, a separate posting will be generated for+each commodity. -$ hledger close -f 2020.journal -p 2020 assets liabilities-# copy/paste the closing transaction to the end of 2020.journal-# copy/paste the opening transaction to the start of 2021.journal+With --interleaved, each equity posting is shown next to the+corresponding source/destination posting. -Or:+The default closing date is yesterday or the journal's end date,+whichever is later. You can change this by specifying a report end date;+the last day of the report period will be the closing date. Eg -e 2022+means "close on 2022-12-31". -$ hledger close -f 2020.journal -p 2020 assets liabilities --open  >> 2021.journal  # add 2021's first transaction-$ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal  # add 2020's last transaction+The default closing date is yesterday, or the journal's end date,+whichever is later. You can change this by specifying a report end date;+(The report start date does not matter.) The last day of the report+period will be the closing date; eg -e 2022 means "close on 2022-12-31".+The opening date is always the day after the closing date. -Now,+close and costs -$ hledger bs -f 2021.journal                   # just new file - balances correct-$ hledger bs -f 2020.journal -f 2021.journal   # old and new files - balances correct-$ hledger bs -f 2020.journal                   # just old files - balances are zero ?-                                               # (exclude final closing txn, see below)+With --show-costs, any amount costs are shown, with separate postings+for each cost. (This currently the best way to view investment assets,+showing lots and cost bases.) If you have many currency conversion or+investment transactions, it can generate very large journal entries. -Hiding opening/closing transactions+close and balance assertions -Although the closing/opening transactions cancel out, they will be-visible in reports like print and register, creating some visual-clutter. You can exclude them all with a query, like:+Balance assertions will be generated, verifying that the accounts have+been reset to zero (and then restored to their previous balances, if+there is an opening transaction). -$ hledger print not:desc:'opening|closing'             # less typing-$ hledger print not:'equity:opening/closing balances'  # more precise+These provide useful error checking, but you can ignore them temporarily+with -I, or remove them if you prefer. -But when reporting on multiple files, this can get a bit tricky; you may-need to keep the earliest opening balances, for a historical register-report; or you may need to suppress a closing transaction, to see-year-end balances. If you find yourself needing more precise queries,-here's one solution: add more easily-matched tags to opening/closing-transactions, like this:+You probably should avoid filtering transactions by status or realness+(-C, -R, status:), or generating postings (--auto), with this command,+since the balance assertions would depend on these. -; 2019.journal-2019-01-01 opening balances  ; earliest opening txn, no tag here-...-2019-12-31 closing balances  ; clopen:2020-...+Note custom posting dates spanning the file boundary will disrupt the+balance assertions: -; 2020.journal-2020-01-01 opening balances  ; clopen:2020-...-2020-12-31 closing balances  ; clopen:2021-...+2023-12-30 a purchase made in december, cleared in january+    expenses:food          5+    assets:bank:checking  -5  ; date: 2023-01-02 -; 2021.journal-2021-01-01 opening balances  ; clopen:2021-...+To solve that you can transfer the money to and from a temporary+account, in effect splitting the multi-day transaction into two+single-day transactions: -Now with+; in 2022.journal:+2022-12-30 a purchase made in december, cleared in january+    expenses:food          5+    equity:pending        -5 -; all.journal-include 2019.journal-include 2020.journal-include 2021.journal+; in 2023.journal:+2023-01-02 last year's transaction cleared+    equity:pending         5 = 0+    assets:bank:checking  -5 -you could do eg:+Example: retain earnings -$ hledger -f all.journal reg -H checking not:tag:clopen-    # all years checking register, hiding non-essential opening/closing txns+Record 2022's revenues/expenses as retained earnings on 2022-12-31,+appending the generated transaction to the journal: -$ hledger -f all.journal bs -p 2020 not:tag:clopen=2020-    # 2020 year end balances, suppressing 2020 closing txn+$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal -close and balance assertions+Now 2022's income statement will show only zeroes. To see it again,+exclude the retain transaction. Eg: -The closing and opening transactions will include balance assertions,-verifying that the accounts have first been reset to zero and then-restored to their previous balance. These provide valuable error-checking, alerting you when things get out of line, but you can ignore-them temporarily with -I or just remove them if you prefer.+$ hledger -f 2022.journal is not:desc:'retain earnings' -You probably shouldn't use status or realness filters (like -C or -R or-status:) with close, or the generated balance assertions will depend on-these flags. Likewise, if you run this command with --auto, the balance-assertions would probably always require --auto.+Example: migrate balances to a new file -Multi-day transactions (where some postings have a different date) break-the balance assertions, because the money is temporarily "invisible"-while in transit:+Close assets/liabilities/equity on 2022-12-31 and re-open them on+2023-01-01: -2020/12/30 a purchase made in december, cleared in the next year-    expenses:food          5-    assets:bank:checking  -5  ; date: 2021/1/2+$ hledger close --migrate -f 2022.journal -p 2022+# copy/paste the closing transaction to the end of 2022.journal+# copy/paste the opening transaction to the start of 2023.journal -To fix the assertions, you can add a temporary account to track such-in-transit money (splitting the multi-day transaction into two-single-day transactions):+Now 2022's balance sheet will show only zeroes, indicating a balanced+accounting equation. (Unless you are using @/@@ notation - in that case,+try adding --infer-equity.) To see it again, exclude the closing+transaction. Eg: -; in 2020.journal:-2020/12/30 a purchase made in december, cleared in the next year-    expenses:food          5-    liabilities:pending+$ hledger -f 2022.journal bs not:desc:'closing balances' -; in 2021.journal:-2021/1/2 clearance of last year's pending transactions-    liabilities:pending    5 = 0-    assets:bank:checking+Example: excluding closing/opening transactions -Example: close revenue/expense accounts to retained earnings+When combining many files for multi-year reports, the closing/opening+transactions cause some noise in reports like print and register. You+can exclude them as shown above, but not:desc:... could be fragile, and+also you will need to avoid excluding the very first opening+transaction, which can be awkward. Here is a way to do it, using tags:+add clopen: tags to all opening/closing balances transactions except the+first, like this: -For this, use --close to suppress the opening transaction, as it's not-needed. Also you'll want to change the equity account name to your-equivalent of "equity:retained earnings".+; 2021.journal+2021-06-01 first opening balances+...+2021-12-31 closing balances  ; clopen:2022+... -Closing 2021's first quarter revenues/expenses:+; 2022.journal+2022-01-01 opening balances  ; clopen:2022+...+2022-12-31 closing balances  ; clopen:2023+... -$ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \-    --close-acct='equity:retained earnings' >> 2021.journal+; 2023.journal+2023-01-01 opening balances  ; clopen:2023+... -The same, using the default journal and current year:+Now, assuming a combined journal like: -$ hledger close --close revenues expenses -p Q1 \-    --close-acct='equity:retained earnings' >> $LEDGER_FILE+; all.journal+include 2021.journal+include 2022.journal+include 2023.journal -Now, the first quarter's balance sheet should show a zero (unless you-are using @/@@ notation without equity postings):+The clopen: tag can exclude all but the first opening transaction. To+show a clean multi-year checking register: -$ hledger bse -p Q1+$ hledger -f all.journal areg checking not:tag:clopen -And we must suppress the closing transaction to see the first quarter's-income statement (using the description; not:'retained earnings' won't-work here):+And the year values allow more precision. To show 2022's year-end+balance sheet: -$ hledger is -p Q1 not:desc:'closing balances'+$ hledger -f all.journal bs -e2023 not:tag:clopen=2023

@@ -1,4 +1,5 @@ codes+ List the codes seen in transactions, in the order parsed.  _FLAGS@@ -16,17 +17,21 @@  Examples: -1/1 (123)- (a)  1+2022/1/1 (123) Supermarket   + Food       $5.00+ Checking     -1/1 ()- (a)  1+2022/1/2 (124) Post Office+ Postage    $8.32+ Checking -1/1- (a)  1+2022/1/3 Supermarket+ Food      $11.23+ Checking  -1/1 (126)- (a)  1+2022/1/4 (126) Post Office+ Postage    $3.21+ Checking  $ hledger codes 123@@ -36,6 +41,5 @@ $ hledger codes -E 123 124-  126

@@ -1,4 +1,5 @@ commodities+ List all commodity/currency symbols used or declared in the journal.  _FLAGS

@@ -1,4 +1,5 @@ descriptions+ List the unique descriptions that appear in transactions.  _FLAGS

@@ -1,4 +1,5 @@ diff+ Compares a particular account's transactions in two input files. It shows any transactions to this account which are in one file but not in the other.

@@ -1,4 +1,5 @@ files+ List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. 

@@ -1,4 +1,5 @@ help+ Show the hledger user manual in the terminal, with info, man, or a pager. With a TOPIC argument, open it at that topic if possible. TOPIC can be any heading in the manual, or a heading prefix, case insensitive.

@@ -1,4 +1,5 @@ import+ Read new transactions added to each FILE since last run, and add them to the journal. Or with --dry-run, just print the transactions that would be added. Or with --catchup, just mark all of the FILEs' transactions as@@ -73,6 +74,13 @@ or (live updating):  $ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'++Note: when importing from multiple files at once, it's currently+possible for some .latest files to be updated successfully, while the+actual import fails because of a problem in one of the files, leaving+them out of sync (and causing some transactions to be missed). To+prevent this, do a --dry-run first and fix any problems before the real+import.  Importing balance assignments 

@@ -1,4 +1,7 @@-incomestatement, is+incomestatement++(is)+ This command displays an income statement, showing revenues and expenses during one or more periods. Amounts are shown with normal positive sign, as in conventional financial statements.

@@ -1,4 +1,5 @@ notes+ List the unique notes that appear in transactions.  _FLAGS

@@ -1,4 +1,5 @@ payees+ List the unique payee/payer names that appear in transactions.  _FLAGS

@@ -1,9 +1,9 @@ prices+ Print market price directives from the journal. With---infer-market-prices, generate additional market prices from-transaction prices. With --infer-reverse-prices, also generate market-prices by inverting transaction prices. Prices (and postings providing-transaction prices) can be filtered by a query. Price amounts are+--infer-market-prices, generate additional market prices from costs.+With --infer-reverse-prices, also generate market prices by inverting+known prices. Prices can be filtered by a query. Price amounts are displayed with their full precision.  _FLAGS

@@ -33,7 +33,7 @@   $(embedFileRelative "Hledger/Cli/Commands/Print.txt")   ([let arg = "DESC" in    flagReq  ["match","m"] (\s opts -> Right $ setopt "match" s opts) arg-    ("fuzzy search for the transaction with description closest to "++arg++", and also most recent")+    ("fuzzy search for one recent transaction with description closest to "++arg)   ,flagNone ["explicit","x"] (setboolopt "explicit")     "show all amounts explicitly"   ,flagNone ["show-costs"] (setboolopt "show-costs")@@ -60,6 +60,8 @@   case maybestringopt "match" $ rawopts_ opts of     Nothing   -> printEntries opts j'     Just desc -> +      -- match mode, prints one recent transaction most similar to given description+      -- XXX should match similarly to register --match       case journalSimilarTransaction opts j' (dbg1 "finding best match for description" $ T.pack desc) of         Just t  -> printEntries opts j'{jtxns=[t]}         Nothing -> putStrLn "no matches found." >> exitFailure

@@ -1,4 +1,5 @@ print+ Show transaction journal entries, sorted by date.  _FLAGS@@ -60,26 +61,25 @@  Normally, the journal entry's explicit or implicit amount style is preserved. For example, when an amount is omitted in the journal, it-will not appear in the output. Similarly, when a transaction price is-implied but not written, it will not appear in the output. You can use-the -x/--explicit flag to make all amounts and transaction prices-explicit, which can be useful for troubleshooting or for making your-journal more readable and robust against data entry errors. -x is also-implied by using any of -B,-V,-X,--value.+will not appear in the output. Similarly, when a cost is implied but not+written, it will not appear in the output. You can use the -x/--explicit+flag to make all amounts and costs explicit, which can be useful for+troubleshooting or for making your journal more readable and robust+against data entry errors. -x is also implied by using any of+-B,-V,-X,--value.  Note, -x/--explicit will cause postings with a multi-commodity amount (these can arise when a multi-commodity transaction has an implicit amount) to be split into multiple single-commodity postings, keeping the output parseable. -With -B/--cost, amounts with transaction prices are converted to cost-using that price. This can be used for troubleshooting.+With -B/--cost, amounts with costs are converted to cost using that+price. This can be used for troubleshooting. -With -m DESC/--match=DESC, print does a fuzzy search for the one-transaction whose description is most similar to DESC, also preferring-recent tranactions. DESC should contain at least two characters. If-there is no similar-enough match, no transaction will be shown and the-program exit code will be non-zero.+With -m DESC/--match=DESC, print does a fuzzy search for one recent+transaction whose description is most similar to DESC. DESC should+contain at least two characters. If there is no similar-enough match, no+transaction will be shown and the program exit code will be non-zero.  With --new, hledger prints only transactions it has not seen on a previous run. This uses the same deduplication system as the import

@@ -1,26 +0,0 @@-{-# LANGUAGE TemplateHaskell #-}--module Hledger.Cli.Commands.Printunique (-  printuniquemode- ,printunique-)-where--import Data.List.Extra (nubSortOn)-import Hledger-import Hledger.Cli.CliOptions-import Hledger.Cli.Commands.Print--printuniquemode = hledgerCommandMode-  $(embedFileRelative "Hledger/Cli/Commands/Printunique.txt")-  []-  [generalflagsgroup1]-  hiddenflags-  ([], Nothing)--printunique opts j@Journal{jtxns=ts} = do-  print' opts j{jtxns=uniquify ts}-  where-    uniquify = nubSortOn thingToCompare-    thingToCompare = tdescription-    -- thingToCompare = tdate

@@ -1,16 +0,0 @@-print-unique-Print transactions which do not reuse an already-seen description.--_FLAGS--Example:--$ cat unique.journal-1/1 test- (acct:one)  1-2/2 test- (acct:two)  2-$ LEDGER_FILE=unique.journal hledger print-unique-(-f option not supported)-2015/01/01 test-    (acct:one)             1

@@ -22,6 +22,7 @@ import Data.Maybe (fromMaybe, isJust) import qualified Data.Text as T import qualified Data.Text.Lazy as TL+import qualified Data.Text.Lazy.IO as TL import qualified Data.Text.Lazy.Builder as TB import System.Console.CmdArgs.Explicit (flagNone, flagReq) @@ -30,6 +31,10 @@ import Hledger.Cli.CliOptions import Hledger.Cli.Utils import Text.Tabular.AsciiWide hiding (render)+import Data.List (sortBy)+import Data.Char (toUpper)+import Data.List.Extra (intersect)+import System.Exit (exitFailure)  registermode = hledgerCommandMode   $(embedFileRelative "Hledger/Cli/Commands/Register.txt")@@ -39,6 +44,9 @@      "show historical running total/balance (includes postings before report start date)\n "   ,flagNone ["average","A"] (setboolopt "average")      "show running average of posting amounts instead of total (implies --empty)"+  ,let arg = "DESC" in+   flagReq  ["match","m"] (\s opts -> Right $ setopt "match" s opts) arg+    ("fuzzy search for one recent posting with description closest to "++arg)   ,flagNone ["related","r"] (setboolopt "related") "show postings' siblings instead"   ,flagNone ["invert"] (setboolopt "invert") "display all amounts with reversed sign"   ,flagReq  ["width","w"] (\s opts -> Right $ setopt "width" s opts) "N"@@ -60,14 +68,28 @@  -- | Print a (posting) register report. register :: CliOpts -> Journal -> IO ()-register opts@CliOpts{reportspec_=rspec} j =-    writeOutputLazyText opts . render $ postingsReport rspec j+register opts@CliOpts{rawopts_=rawopts, reportspec_=rspec} j+  -- match mode, print one recent posting most similar to given description, if any+  -- XXX should match similarly to print --match+  | Just desc <- maybestringopt "match" rawopts = do+      let ps = [p | (_,_,_,p,_) <- rpt]+      case similarPosting ps desc of+        Nothing -> putStrLn "no matches found." >> exitFailure+        Just p  -> TL.putStr $ postingsReportAsText opts [pri]+                  where pri = (Just (postingDate p)+                              ,Nothing+                              ,tdescription <$> ptransaction p+                              ,p+                              ,nullmixedamt)+  -- normal register report, list postings+  | otherwise = writeOutputLazyText opts $ render rpt   where-    fmt = outputFormatFromOpts opts+    rpt = postingsReport rspec j     render | fmt=="txt"  = postingsReportAsText opts            | fmt=="csv"  = printCSV . postingsReportAsCsv            | fmt=="json" = toJsonText            | otherwise   = error' $ unsupportedOutputFormatError fmt  -- PARTIAL:+      where fmt = outputFormatFromOpts opts  postingsReportAsCsv :: PostingsReport -> CSV postingsReportAsCsv is =@@ -178,6 +200,55 @@             BalancedVirtualPosting -> (wrap "[" "]", acctwidth-2)             VirtualPosting         -> (wrap "(" ")", acctwidth-2)             _                      -> (id,acctwidth)++-- for register --match:++-- Identify the closest recent match for this description in the given date-sorted postings.+similarPosting :: [Posting] -> String -> Maybe Posting+similarPosting ps desc =+  let matches =+          sortBy compareRelevanceAndRecency+                     $ filter ((> threshold).fst)+                     [(maybe 0 (\t -> compareDescriptions desc (T.unpack $ tdescription t)) (ptransaction p), p) | p <- ps]+              where+                compareRelevanceAndRecency (n1,p1) (n2,p2) = compare (n2,postingDate p2) (n1,postingDate p1)+                threshold = 0+  in case matches of []  -> Nothing+                     m:_ -> Just $ snd m++-- -- Identify the closest recent match for this description in past transactions.+-- similarTransaction :: Journal -> Query -> String -> Maybe Transaction+-- similarTransaction j q desc =+--   case historymatches = transactionsSimilarTo j q desc of+--     ((,t):_) = Just t+--     []       = Nothing++compareDescriptions :: String -> String -> Double+compareDescriptions s t = compareStrings s' t'+    where s' = simplify s+          t' = simplify t+          simplify = filter (not . (`elem` ("0123456789"::String)))++-- | Return a similarity measure, from 0 to 1, for two strings.+-- This is Simon White's letter pairs algorithm from+-- http://www.catalysoft.com/articles/StrikeAMatch.html+-- with a modification for short strings.+compareStrings :: String -> String -> Double+compareStrings "" "" = 1+compareStrings [_] "" = 0+compareStrings "" [_] = 0+compareStrings [a] [b] = if toUpper a == toUpper b then 1 else 0+compareStrings s1 s2 = 2.0 * fromIntegral i / fromIntegral u+    where+      i = length $ intersect pairs1 pairs2+      u = length pairs1 + length pairs2+      pairs1 = wordLetterPairs $ uppercase s1+      pairs2 = wordLetterPairs $ uppercase s2++wordLetterPairs = concatMap letterPairs . words++letterPairs (a:b:rest) = [a,b] : letterPairs (b:rest)+letterPairs _ = []  -- tests 

@@ -1,4 +1,7 @@-register, reg+register++(reg)+ Show postings and their running total.  _FLAGS@@ -91,6 +94,11 @@ will be adjusted outward if necessary to contain a whole number of intervals. This ensures that the first and last intervals are full length and comparable to the others in the report.++With -m DESC/--match=DESC, register does a fuzzy search for one recent+posting whose description is most similar to DESC. DESC should contain+at least two characters. If there is no similar-enough match, no posting+will be shown and the program exit code will be non-zero.  Custom register output 

@@ -1,86 +0,0 @@-{-# LANGUAGE OverloadedStrings #-}-{-# LANGUAGE TemplateHaskell #-}--module Hledger.Cli.Commands.Registermatch (-  registermatchmode- ,registermatch-)-where--import Data.Char (toUpper)-import Data.List-import qualified Data.Text as T-import qualified Data.Text.Lazy.IO as TL-import Hledger-import Hledger.Cli.CliOptions-import Hledger.Cli.Commands.Register--registermatchmode = hledgerCommandMode-  $(embedFileRelative "Hledger/Cli/Commands/Registermatch.txt")-  []-  [generalflagsgroup1]-  hiddenflags-  ([], Just $ argsFlag "DESC")--registermatch :: CliOpts -> Journal -> IO ()-registermatch opts@CliOpts{rawopts_=rawopts,reportspec_=rspec} j =-  case listofstringopt "args" rawopts of-    [desc] -> do-        let ps = [p | (_,_,_,p,_) <- postingsReport rspec j]-        case similarPosting ps desc of-          Nothing -> putStrLn "no matches found."-          Just p  -> TL.putStr $ postingsReportAsText opts [pri]-                     where pri = (Just (postingDate p)-                                 ,Nothing-                                 ,tdescription <$> ptransaction p-                                 ,p-                                 ,nullmixedamt)-    _ -> putStrLn "please provide one description argument."---- Identify the closest recent match for this description in the given date-sorted postings.-similarPosting :: [Posting] -> String -> Maybe Posting-similarPosting ps desc =-  let matches =-          sortBy compareRelevanceAndRecency-                     $ filter ((> threshold).fst)-                     [(maybe 0 (\t -> compareDescriptions desc (T.unpack $ tdescription t)) (ptransaction p), p) | p <- ps]-              where-                compareRelevanceAndRecency (n1,p1) (n2,p2) = compare (n2,postingDate p2) (n1,postingDate p1)-                threshold = 0-  in case matches of []  -> Nothing-                     m:_ -> Just $ snd m---- -- Identify the closest recent match for this description in past transactions.--- similarTransaction :: Journal -> Query -> String -> Maybe Transaction--- similarTransaction j q desc =---   case historymatches = transactionsSimilarTo j q desc of---     ((,t):_) = Just t---     []       = Nothing--compareDescriptions :: String -> String -> Double-compareDescriptions s t = compareStrings s' t'-    where s' = simplify s-          t' = simplify t-          simplify = filter (not . (`elem` ("0123456789"::String)))---- | Return a similarity measure, from 0 to 1, for two strings.--- This is Simon White's letter pairs algorithm from--- http://www.catalysoft.com/articles/StrikeAMatch.html--- with a modification for short strings.-compareStrings :: String -> String -> Double-compareStrings "" "" = 1-compareStrings [_] "" = 0-compareStrings "" [_] = 0-compareStrings [a] [b] = if toUpper a == toUpper b then 1 else 0-compareStrings s1 s2 = 2.0 * fromIntegral i / fromIntegral u-    where-      i = length $ intersect pairs1 pairs2-      u = length pairs1 + length pairs2-      pairs1 = wordLetterPairs $ uppercase s1-      pairs2 = wordLetterPairs $ uppercase s2--wordLetterPairs = concatMap letterPairs . words--letterPairs (a:b:rest) = [a,b] : letterPairs (b:rest)-letterPairs _ = []-

@@ -1,8 +0,0 @@-register-match-Print the one posting whose transaction description is closest to DESC,-in the style of the register command. If there are multiple equally good-matches, it shows the most recent. Query options (options, not-arguments) can be used to restrict the search space. Helps-ledger-autosync detect already-seen transactions when importing.--_FLAGS

@@ -1,4 +1,5 @@ rewrite+ Print all transactions, rewriting the postings of matched transactions. For now the only rewrite available is adding new postings, like print --auto.

@@ -3,6 +3,7 @@ {-# LANGUAGE TemplateHaskell   #-} {-# LANGUAGE TupleSections     #-} {-# LANGUAGE RecordWildCards   #-}+{-# LANGUAGE ViewPatterns #-} {-|  The @roi@ command prints internal rate of return and time-weighted rate of return for and investment.@@ -95,15 +96,17 @@   tableBody <- forM spans $ \spn@(DateSpan (Just begin) (Just end)) -> do     -- Spans are [begin,end), and end is 1 day after the actual end date we are interested in     let-      cashFlowApplyCostValue = map (\(d,amt) -> (d,mixedAmountValue end d amt))+      b = fromEFDay begin+      e = fromEFDay end+      cashFlowApplyCostValue = map (\(d,amt) -> (d,mixedAmountValue e d amt))        valueBefore =-        mixedAmountValue end begin $ +        mixedAmountValue e b $          total trans (And [ investmentsQuery                          , Date (DateSpan Nothing (Just begin))])        valueAfter  =-        mixedAmountValue end end $ +        mixedAmountValue e e $          total trans (And [investmentsQuery                          , Date (DateSpan Nothing (Just end))]) @@ -123,14 +126,14 @@                                         , Date spn ] )        thisSpan = dbg3 "processing span" $-                 OneSpan begin end valueBefore valueAfter cashFlow pnl+                 OneSpan b e valueBefore valueAfter cashFlow pnl      irr <- internalRateOfReturn showCashFlow prettyTables thisSpan     twr <- timeWeightedReturn showCashFlow prettyTables investmentsQuery trans mixedAmountValue thisSpan     let cashFlowAmt = maNegate . maSum $ map snd cashFlow     let smallIsZero x = if abs x < 0.01 then 0.0 else x-    return [ showDate begin-           , showDate (addDays (-1) end)+    return [ showDate b+           , showDate (addDays (-1) e)            , T.pack $ showMixedAmount valueBefore            , T.pack $ showMixedAmount cashFlowAmt            , T.pack $ showMixedAmount valueAfter@@ -198,7 +201,7 @@         tail $         scanl           (\(_, _, unitPrice, unitBalance) (date, amt) ->-             let valueOnDate = unMix $ mixedAmountValue end date $ total trans (And [investmentsQuery, Date (DateSpan Nothing (Just date))])+             let valueOnDate = unMix $ mixedAmountValue end date $ total trans (And [investmentsQuery, Date (DateSpan Nothing (Just $ Exact date))])              in              case amt of                Right amt' ->

@@ -1,4 +1,5 @@ roi+ Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. 

@@ -1,4 +1,5 @@ stats+ Show journal and performance statistics.  _FLAGS@@ -32,5 +33,5 @@ Run time                 : 0.12 s Throughput               : 8342 txns/s -This command also supports output destination and output format-selection.+This command supports the -o/--output-file option (but not+-O/--output-format selection).

@@ -1,4 +1,5 @@ tags+ List the tags used in the journal, or their values.  _FLAGS

@@ -1,4 +1,5 @@ test+ Run built-in unit tests.  _FLAGS

@@ -279,8 +279,13 @@ compoundBalanceReportAsHtml ropts cbr =   let     CompoundPeriodicReport title colspans subreports netrow = cbr-    colspanattr = colspan_ $ T.pack $ show $-      1 + length colspans + (if row_total_ ropts then 1 else 0) + (if average_ ropts then 1 else 0)+    colspanattr = colspan_ $ T.pack $ show $ sum [+      1,+      length colspans,+      if row_total_ ropts then 1 else 0,+      if average_ ropts then 1 else 0,+      if layout_ ropts == LayoutBare then 1 else 0+      ]     leftattr = style_ "text-align:left"     blankrow = tr_ $ td_ [colspanattr] $ toHtmlRaw (" "::String) 

@@ -140,13 +140,13 @@     isExternalCommand    = not (null cmd) && cmd `elem` addons -- probably     isBadCommand         = not (null rawcmd) && null cmd     hasVersion           = ("--version" `elem`)-    printUsage           = putStr $ showModeUsage $ mainmode addons+    printUsage           = pager $ showModeUsage $ mainmode addons     badCommandError      = error' ("command "++rawcmd++" is not recognized, run with no command to see a list") >> exitFailure  -- PARTIAL:     hasHelpFlag args1     = any (`elem` args1) ["-h","--help"]     hasManFlag args1      = (`elem` args1) "--man"     hasInfoFlag args1     = (`elem` args1) "--info"     f `orShowHelp` mode1-      | hasHelpFlag args = putStr $ showModeUsage mode1+      | hasHelpFlag args = pager $ showModeUsage mode1       | hasInfoFlag args = runInfoForTopic "hledger" (headMay $ modeNames mode1)       | hasManFlag args  = runManForTopic "hledger" (headMay $ modeNames mode1)       | otherwise        = f

@@ -0,0 +1,33 @@+{-|+A convenient module to import in hledger scripts, +aiming to provide the most useful imports and reduce boilerplate.+|-}++{-# LANGUAGE PackageImports #-}++module Hledger.Cli.Script+( module Script+) +where++import Control.Monad as Script+import Data.Either as Script+import Data.List as Script+import Data.Maybe as Script+import Data.Ord as Script+-- import Data.String.QQ (s)  -- https://github.com/audreyt/string-qq/pull/3+import Data.Time as Script+import Text.Printf as Script hiding (formatString)+import "text" Data.Text as Script (Text, pack, unpack)+  -- can't re-export much of Data.Text & Data.Text.IO, they need to be qualified+import Safe as Script hiding (at)+-- import qualified System.Console.CmdArgs.Explicit as Script+import System.Directory as Script+import System.Environment as Script+import System.Exit as Script+import System.FilePath as Script+import System.Process as Script++import Hledger as Script+import Hledger.Cli as Script+import Hledger.Cli.Main as Script (argsToCliOpts)

@@ -1,37 +1,40 @@ -.TH "HLEDGER-UI" "1" "December 2022" "hledger-ui-1.28 " "hledger User Manuals"+.TH "HLEDGER-UI" "1" "March 2023" "hledger-ui-1.29 " "hledger User Manuals"    .SH NAME .PP-hledger-ui is a terminal interface (TUI) for the hledger accounting-tool.-This manual is for hledger-ui 1.28.+hledger-ui - robust, friendly plain text accounting (TUI version) .SH SYNOPSIS .PP-\f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R]+\f[V]hledger-ui [OPTIONS] [QUERYARGS]\f[R] .PD 0 .P .PD-\f[C]hledger ui -- [OPTIONS] [QUERYARGS]\f[R]+\f[V]hledger ui -- [OPTIONS] [QUERYARGS]\f[R] .SH DESCRIPTION .PP-hledger is a reliable, cross-platform set of programs for tracking-money, time, or any other commodity, using double-entry accounting and a-simple, editable file format.-hledger is inspired by and largely compatible with ledger(1).+This manual is for hledger\[aq]s terminal interface, version 1.29.+See also the hledger manual for common concepts and file formats. .PP+hledger is a robust, user-friendly, cross-platform set of programs for+tracking money, time, or any other commodity, using double-entry+accounting and a simple, editable file format.+hledger is inspired by and largely compatible with ledger(1), and+largely interconvertible with beancount(1).+.PP hledger-ui is hledger\[aq]s terminal interface, providing an efficient full-window text UI for viewing accounts and transactions, and some limited data entry capability. It is easier than hledger\[aq]s command-line interface, and sometimes quicker and more convenient than the web interface. .PP-Like hledger, it reads data from one or more files in hledger journal,-timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or-\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,-perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).+Like hledger, it reads data from one or more files in journal,+timeclock, timedot, or CSV format.+The default file is \f[V].hledger.journal\f[R] in your home directory;+this can be overridden with one or more \f[V]-f FILE\f[R] options, or+the \f[V]LEDGER_FILE\f[R] environment variable. For more about this see hledger(1), hledger_journal(5) etc. .PP Unlike hledger, hledger-ui hides all future-dated transactions by@@ -41,155 +44,155 @@ enable \[dq]forecast mode\[dq]. .SH OPTIONS .PP-Note: if invoking hledger-ui as a hledger subcommand, write \f[C]--\f[R]+Note: if invoking hledger-ui as a hledger subcommand, write \f[V]--\f[R] before options as shown above. .PP Any QUERYARGS are interpreted as a hledger search query which filters the data. .TP-\f[B]\f[CB]-w --watch\f[B]\f[R]+\f[V]-w --watch\f[R] watch for data and date changes and reload automatically .TP-\f[B]\f[CB]--theme=default|terminal|greenterm\f[B]\f[R]+\f[V]--theme=default|terminal|greenterm\f[R] use this custom display theme .TP-\f[B]\f[CB]--menu\f[B]\f[R]+\f[V]--menu\f[R] start in the menu screen .TP-\f[B]\f[CB]--all\f[B]\f[R]+\f[V]--all\f[R] start in the all accounts screen .TP-\f[B]\f[CB]--bs\f[B]\f[R]+\f[V]--bs\f[R] start in the balance sheet accounts screen .TP-\f[B]\f[CB]--is\f[B]\f[R]+\f[V]--is\f[R] start in the income statement accounts screen .TP-\f[B]\f[CB]--register=ACCTREGEX\f[B]\f[R]+\f[V]--register=ACCTREGEX\f[R] start in the (first) matched account\[aq]s register screen .TP-\f[B]\f[CB]--change\f[B]\f[R]+\f[V]--change\f[R] show period balances (changes) at startup instead of historical balances .TP-\f[B]\f[CB]-l --flat\f[B]\f[R]+\f[V]-l --flat\f[R] show accounts as a flat list (default) .TP-\f[B]\f[CB]-t --tree\f[B]\f[R]+\f[V]-t --tree\f[R] show accounts as a tree .PP hledger input options: .TP-\f[B]\f[CB]-f FILE --file=FILE\f[B]\f[R]+\f[V]-f FILE --file=FILE\f[R] use a different input file.-For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or-\f[C]$HOME/.hledger.journal\f[R])+For stdin, use - (default: \f[V]$LEDGER_FILE\f[R] or+\f[V]$HOME/.hledger.journal\f[R]) .TP-\f[B]\f[CB]--rules-file=RULESFILE\f[B]\f[R]+\f[V]--rules-file=RULESFILE\f[R] Conversion rules file to use when reading CSV (default: FILE.rules) .TP-\f[B]\f[CB]--separator=CHAR\f[B]\f[R]+\f[V]--separator=CHAR\f[R] Field separator to expect when reading CSV (default: \[aq],\[aq]) .TP-\f[B]\f[CB]--alias=OLD=NEW\f[B]\f[R]+\f[V]--alias=OLD=NEW\f[R] rename accounts named OLD to NEW .TP-\f[B]\f[CB]--anon\f[B]\f[R]+\f[V]--anon\f[R] anonymize accounts and payees .TP-\f[B]\f[CB]--pivot FIELDNAME\f[B]\f[R]+\f[V]--pivot FIELDNAME\f[R] use some other field or tag for the account name .TP-\f[B]\f[CB]-I --ignore-assertions\f[B]\f[R]+\f[V]-I --ignore-assertions\f[R] disable balance assertion checks (note: does not disable balance assignments) .TP-\f[B]\f[CB]-s --strict\f[B]\f[R]+\f[V]-s --strict\f[R] do extra error checking (check that all posted accounts are declared) .PP hledger reporting options: .TP-\f[B]\f[CB]-b --begin=DATE\f[B]\f[R]+\f[V]-b --begin=DATE\f[R] include postings/txns on or after this date (will be adjusted to preceding subperiod start when using a report interval) .TP-\f[B]\f[CB]-e --end=DATE\f[B]\f[R]+\f[V]-e --end=DATE\f[R] include postings/txns before this date (will be adjusted to following subperiod end when using a report interval) .TP-\f[B]\f[CB]-D --daily\f[B]\f[R]+\f[V]-D --daily\f[R] multiperiod/multicolumn report by day .TP-\f[B]\f[CB]-W --weekly\f[B]\f[R]+\f[V]-W --weekly\f[R] multiperiod/multicolumn report by week .TP-\f[B]\f[CB]-M --monthly\f[B]\f[R]+\f[V]-M --monthly\f[R] multiperiod/multicolumn report by month .TP-\f[B]\f[CB]-Q --quarterly\f[B]\f[R]+\f[V]-Q --quarterly\f[R] multiperiod/multicolumn report by quarter .TP-\f[B]\f[CB]-Y --yearly\f[B]\f[R]+\f[V]-Y --yearly\f[R] multiperiod/multicolumn report by year .TP-\f[B]\f[CB]-p --period=PERIODEXP\f[B]\f[R]+\f[V]-p --period=PERIODEXP\f[R] set start date, end date, and/or reporting interval all at once using period expressions syntax .TP-\f[B]\f[CB]--date2\f[B]\f[R]+\f[V]--date2\f[R] match the secondary date instead (see command help for other effects) .TP-\f[B]\f[CB]--today=DATE\f[B]\f[R]+\f[V]--today=DATE\f[R] override today\[aq]s date (affects relative smart dates, for tests/examples) .TP-\f[B]\f[CB]-U --unmarked\f[B]\f[R]+\f[V]-U --unmarked\f[R] include only unmarked postings/txns (can combine with -P or -C) .TP-\f[B]\f[CB]-P --pending\f[B]\f[R]+\f[V]-P --pending\f[R] include only pending postings/txns .TP-\f[B]\f[CB]-C --cleared\f[B]\f[R]+\f[V]-C --cleared\f[R] include only cleared postings/txns .TP-\f[B]\f[CB]-R --real\f[B]\f[R]+\f[V]-R --real\f[R] include only non-virtual postings .TP-\f[B]\f[CB]-NUM --depth=NUM\f[B]\f[R]+\f[V]-NUM --depth=NUM\f[R] hide/aggregate accounts or postings more than NUM levels deep .TP-\f[B]\f[CB]-E --empty\f[B]\f[R]+\f[V]-E --empty\f[R] show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) .TP-\f[B]\f[CB]-B --cost\f[B]\f[R]+\f[V]-B --cost\f[R] convert amounts to their cost/selling amount at transaction time .TP-\f[B]\f[CB]-V --market\f[B]\f[R]+\f[V]-V --market\f[R] convert amounts to their market value in default valuation commodities .TP-\f[B]\f[CB]-X --exchange=COMM\f[B]\f[R]+\f[V]-X --exchange=COMM\f[R] convert amounts to their market value in commodity COMM .TP-\f[B]\f[CB]--value\f[B]\f[R]+\f[V]--value\f[R] convert amounts to cost or market value, more flexibly than -B/-V/-X .TP-\f[B]\f[CB]--infer-market-prices\f[B]\f[R]+\f[V]--infer-market-prices\f[R] use transaction prices (recorded with \[at] or \[at]\[at]) as additional market prices, as if they were P directives .TP-\f[B]\f[CB]--auto\f[B]\f[R]+\f[V]--auto\f[R] apply automated posting rules to modify transactions. .TP-\f[B]\f[CB]--forecast\f[B]\f[R]+\f[V]--forecast\f[R] generate future transactions from periodic transaction rules, for the next 6 months or till report end date. In hledger-ui, also make ordinary future transactions visible. .TP-\f[B]\f[CB]--commodity-style\f[B]\f[R]+\f[V]--commodity-style\f[R] Override the commodity style in the output for the specified commodity. For example \[aq]EUR1.000,00\[aq]. .TP-\f[B]\f[CB]--color=WHEN (or --colour=WHEN)\f[B]\f[R]+\f[V]--color=WHEN (or --colour=WHEN)\f[R] Should color-supporting commands use ANSI color codes in text output. \[aq]auto\[aq] (default): whenever stdout seems to be a color-supporting terminal.@@ -198,7 +201,7 @@ \[aq]never\[aq] or \[aq]no\[aq]: never. A NO_COLOR environment variable overrides this. .TP-\f[B]\f[CB]--pretty[=WHEN]\f[B]\f[R]+\f[V]--pretty[=WHEN]\f[R] Show prettier output, e.g. using unicode box-drawing characters. Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq],@@ -213,24 +216,24 @@ .PP hledger help options: .TP-\f[B]\f[CB]-h --help\f[B]\f[R]+\f[V]-h --help\f[R] show general or COMMAND help .TP-\f[B]\f[CB]--man\f[B]\f[R]+\f[V]--man\f[R] show general or COMMAND user manual with man .TP-\f[B]\f[CB]--info\f[B]\f[R]+\f[V]--info\f[R] show general or COMMAND user manual with info .TP-\f[B]\f[CB]--version\f[B]\f[R]+\f[V]--version\f[R] show general or ADDONCMD version .TP-\f[B]\f[CB]--debug[=N]\f[B]\f[R]+\f[V]--debug[=N]\f[R] show debug output (levels 1-9, default: 1) .PP A \[at]FILE argument will be expanded to the contents of FILE, which should contain one command line option/argument per line.-(To prevent this, insert a \f[C]--\f[R] argument before.)+(To prevent this, insert a \f[V]--\f[R] argument before.) .SH MOUSE .PP In most modern terminals, you can navigate through the screens with a@@ -245,19 +248,20 @@ .PP Keyboard gives more control. .PP-\f[C]?\f[R] shows a help dialog listing all keys.+\f[V]?\f[R] shows a help dialog listing all keys. (Some of these also appear in the quick help at the bottom of each-screen.) Press \f[C]?\f[R] again (or \f[C]ESCAPE\f[R], or-\f[C]LEFT\f[R], or \f[C]q\f[R]) to close it.+screen.)+Press \f[V]?\f[R] again (or \f[V]ESCAPE\f[R], or \f[V]LEFT\f[R], or+\f[V]q\f[R]) to close it. The following keys work on most screens: .PP-The cursor keys navigate: \f[C]RIGHT\f[R] or \f[C]ENTER\f[R] goes-deeper, \f[C]LEFT\f[R] returns to the previous screen,-\f[C]UP\f[R]/\f[C]DOWN\f[R]/\f[C]PGUP\f[R]/\f[C]PGDN\f[R]/\f[C]HOME\f[R]/\f[C]END\f[R]+The cursor keys navigate: \f[V]RIGHT\f[R] or \f[V]ENTER\f[R] goes+deeper, \f[V]LEFT\f[R] returns to the previous screen,+\f[V]UP\f[R]/\f[V]DOWN\f[R]/\f[V]PGUP\f[R]/\f[V]PGDN\f[R]/\f[V]HOME\f[R]/\f[V]END\f[R] move up and down through lists. Emacs-style-(\f[C]CTRL-p\f[R]/\f[C]CTRL-n\f[R]/\f[C]CTRL-f\f[R]/\f[C]CTRL-b\f[R])-and VI-style (\f[C]k\f[R],\f[C]j\f[R],\f[C]l\f[R],\f[C]h\f[R]) movement+(\f[V]CTRL-p\f[R]/\f[V]CTRL-n\f[R]/\f[V]CTRL-f\f[R]/\f[V]CTRL-b\f[R])+and VI-style (\f[V]k\f[R],\f[V]j\f[R],\f[V]l\f[R],\f[V]h\f[R]) movement keys are also supported. A tip: movement speed is limited by your keyboard repeat rate, to move faster you may want to adjust it.@@ -265,84 +269,94 @@ .PP With shift pressed, the cursor keys adjust the report period, limiting the transactions to be shown (by default, all are shown).-\f[C]SHIFT-DOWN/UP\f[R] steps downward and upward through these standard+\f[V]SHIFT-DOWN/UP\f[R] steps downward and upward through these standard report period durations: year, quarter, month, week, day.-Then, \f[C]SHIFT-LEFT/RIGHT\f[R] moves to the previous/next period.-\f[C]T\f[R] sets the report period to today.-With the \f[C]-w/--watch\f[R] option, when viewing a \[dq]current\[dq]+Then, \f[V]SHIFT-LEFT/RIGHT\f[R] moves to the previous/next period.+\f[V]T\f[R] sets the report period to today.+With the \f[V]-w/--watch\f[R] option, when viewing a \[dq]current\[dq] period (the current day, week, month, quarter, or year), the period will move automatically to track the current date.-To set a non-standard period, you can use \f[C]/\f[R] and a-\f[C]date:\f[R] query.+To set a non-standard period, you can use \f[V]/\f[R] and a+\f[V]date:\f[R] query. .PP-\f[C]/\f[R] lets you set a general filter query limiting the data shown,+(Mac users: SHIFT-DOWN/UP keys do not work by default in Terminal, as of+MacOS Monterey.+You can configure them as follows: open Terminal, press CMD-comma to+open preferences, click Profiles, select your current terminal profile+on the left, click Keyboard on the right, click + and add this for+Shift-Down: \f[V]\[rs]033[1;2B\f[R], click + and add this for Shift-Up:+\f[V]\[rs]033[1;2A\f[R].+Press the Escape key to enter the \f[V]\[rs]033\f[R] part, you can\[aq]t+type it directly.)+.PP+\f[V]/\f[R] lets you set a general filter query limiting the data shown, using the same query terms as in hledger and hledger-web. While editing the query, you can use CTRL-a/e/d/k, BS, cursor keys;-press \f[C]ENTER\f[R] to set it, or \f[C]ESCAPE\f[R]to cancel.+press \f[V]ENTER\f[R] to set it, or \f[V]ESCAPE\f[R]to cancel. There are also keys for quickly adjusting some common filters like account depth and transaction status (see below).-\f[C]BACKSPACE\f[R] or \f[C]DELETE\f[R] removes all filters, showing all+\f[V]BACKSPACE\f[R] or \f[V]DELETE\f[R] removes all filters, showing all transactions. .PP As mentioned above, by default hledger-ui hides future transactions - both ordinary transactions recorded in the journal, and periodic transactions generated by rule.-\f[C]F\f[R] toggles forecast mode, in which future/forecasted+\f[V]F\f[R] toggles forecast mode, in which future/forecasted transactions are shown. .PP-\f[C]ESCAPE\f[R] resets the UI state and jumps back to the top screen,+\f[V]ESCAPE\f[R] resets the UI state and jumps back to the top screen, restoring the app\[aq]s initial state at startup. Or, it cancels minibuffer data entry or the help dialog. .PP-\f[C]CTRL-l\f[R] redraws the screen and centers the selection if+\f[V]CTRL-l\f[R] redraws the screen and centers the selection if possible (selections near the top won\[aq]t be centered, since we don\[aq]t scroll above the top). .PP-\f[C]g\f[R] reloads from the data file(s) and updates the current screen+\f[V]g\f[R] reloads from the data file(s) and updates the current screen and any previous screens. (With large files, this could cause a noticeable pause.) .PP-\f[C]I\f[R] toggles balance assertion checking.+\f[V]I\f[R] toggles balance assertion checking. Disabling balance assertions temporarily can be useful for troubleshooting. .PP-\f[C]a\f[R] runs command-line hledger\[aq]s add command, and reloads the+\f[V]a\f[R] runs command-line hledger\[aq]s add command, and reloads the updated file. This allows some basic data entry. .PP-\f[C]A\f[R] is like \f[C]a\f[R], but runs the hledger-iadd tool, which+\f[V]A\f[R] is like \f[V]a\f[R], but runs the hledger-iadd tool, which provides a terminal interface.-This key will be available if \f[C]hledger-iadd\f[R] is installed in+This key will be available if \f[V]hledger-iadd\f[R] is installed in $path. .PP-\f[C]E\f[R] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default-(\f[C]emacsclient -a \[dq]\[dq] -nw\f[R]) on the journal file.+\f[V]E\f[R] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default+(\f[V]emacsclient -a \[dq]\[dq] -nw\f[R]) on the journal file. With some editors (emacs, vi), the cursor will be positioned at the current transaction when invoked from the register and transaction screens, and at the error location (if possible) when invoked from the error screen. .PP-\f[C]B\f[R] toggles cost mode, showing amounts in their transaction-price\[aq]s commodity (like toggling the \f[C]-B/--cost\f[R] flag).+\f[V]B\f[R] toggles cost mode, showing amounts in their cost\[aq]s+commodity (like toggling the \f[V]-B/--cost\f[R] flag). .PP-\f[C]V\f[R] toggles value mode, showing amounts\[aq] current market+\f[V]V\f[R] toggles value mode, showing amounts\[aq] current market value in their default valuation commodity (like toggling the-\f[C]-V/--market\f[R] flag).+\f[V]-V/--market\f[R] flag). Note, \[dq]current market value\[dq] means the value on the report end date if specified, otherwise today. To see the value on another date, you can temporarily set that as the report end date. Eg: to see a transaction as it was valued on july 30, go to the accounts-or register screen, press \f[C]/\f[R], and add \f[C]date:-7/30\f[R] to+or register screen, press \f[V]/\f[R], and add \f[V]date:-7/30\f[R] to the query. .PP At most one of cost or value mode can be active at once. .PP There\[aq]s not yet any visual reminder when cost or value mode is-active; for now pressing \f[C]b\f[R] \f[C]b\f[R] \f[C]v\f[R] should+active; for now pressing \f[V]b\f[R] \f[V]b\f[R] \f[V]v\f[R] should reliably reset to normal mode. .PP-\f[C]q\f[R] quits the application.+\f[V]q\f[R] quits the application. .PP Additional screen-specific keys are described below. .SH SCREENS@@ -358,7 +372,7 @@ If a starting screen is specified with --menu/--all/--bs/--is/--register on the command line, it starts in that screen. .PP-From any screen you can press \f[C]LEFT\f[R] or \f[C]ESC\f[R] to+From any screen you can press \f[V]LEFT\f[R] or \f[V]ESC\f[R] to navigate back to the top level \[dq]Menu\[dq] screen. .SS Menu .PP@@ -369,19 +383,19 @@ This screen shows all accounts (possibly filtered by a query), and their end balances on the date shown in the title bar (or their balance changes in the period shown in the title bar, toggleable with-\f[C]H\f[R]).-It is like the \f[C]hledger balance\f[R] command.+\f[V]H\f[R]).+It is like the \f[V]hledger balance\f[R] command. .SS Balance sheet accounts .PP This screen shows asset, liability and equity accounts, if these can be detected (see account types). It always shows end balances.-It is like the \f[C]hledger balancesheetequity\f[R] command.+It is like the \f[V]hledger balancesheetequity\f[R] command. .SS Income statement accounts .PP This screen shows revenue and expense accounts. It always shows balance changes.-It is like the \f[C]hledger incomestatement\f[R] command.+It is like the \f[V]hledger incomestatement\f[R] command. .PP All of these accounts screens work in much the same way: .PP@@ -389,30 +403,30 @@ accounts which have been declared with an account directive (except for empty parent accounts). .PP-If you specify a query on the command line or with \f[C]/\f[R] in the+If you specify a query on the command line or with \f[V]/\f[R] in the app, they show just the matched accounts, and the balances from matched transactions. .PP hledger-ui shows accounts with zero balances by default (unlike command-line hledger).-To hide these, press \f[C]z\f[R] to toggle nonzero mode.+To hide these, press \f[V]z\f[R] to toggle nonzero mode. .PP-Account names are shown as a flat list by default; press \f[C]t\f[R] to+Account names are shown as a flat list by default; press \f[V]t\f[R] to toggle tree mode. In list mode, account balances are exclusive of subaccounts, except where subaccounts are hidden by a depth limit (see below). In tree mode, all account balances are inclusive of subaccounts. .PP-To see less detail, press a number key, \f[C]1\f[R] to \f[C]9\f[R], to+To see less detail, press a number key, \f[V]1\f[R] to \f[V]9\f[R], to set a depth limit.-Or use \f[C]-\f[R] to decrease and \f[C]+\f[R]/\f[C]=\f[R] to increase+Or use \f[V]-\f[R] to decrease and \f[V]+\f[R]/\f[V]=\f[R] to increase the depth limit.-\f[C]0\f[R] shows even less detail, collapsing all accounts to a single+\f[V]0\f[R] shows even less detail, collapsing all accounts to a single total. To remove the depth limit, set it higher than the maximum account depth,-or press \f[C]ESCAPE\f[R].+or press \f[V]ESCAPE\f[R]. .PP-\f[C]H\f[R] toggles between showing historical balances or period+\f[V]H\f[R] toggles between showing historical balances or period balances (on the \[dq]All accounts\[dq] screen). Historical balances (the default) are ending balances at the end of the report period, taking into account all transactions before that date@@ -424,18 +438,18 @@ they show the change in balance during the report period. They are more useful eg when viewing a time log. .PP-\f[C]U\f[R] toggles filtering by unmarked status, including or excluding+\f[V]U\f[R] toggles filtering by unmarked status, including or excluding unmarked postings in the balances.-Similarly, \f[C]P\f[R] toggles pending postings, and \f[C]C\f[R] toggles+Similarly, \f[V]P\f[R] toggles pending postings, and \f[V]C\f[R] toggles cleared postings. (By default, balances include all postings; if you activate one or two status filters, only those postings are included; and if you activate all three, the filter is removed.) .PP-\f[C]R\f[R] toggles real mode, in which virtual postings are ignored.+\f[V]R\f[R] toggles real mode, in which virtual postings are ignored. .PP-Press \f[C]RIGHT\f[R] to view an account\[aq]s register screen, Or,-\f[C]LEFT\f[R] to see the menu screen.+Press \f[V]RIGHT\f[R] to view an account\[aq]s register screen, Or,+\f[V]LEFT\f[R] to see the menu screen. .SS Register .PP This screen shows the transactions affecting a particular account, like@@ -451,7 +465,7 @@ .IP \[bu] 2 the running historical total or period total for the current account, after the transaction.-This can be toggled with \f[C]H\f[R].+This can be toggled with \f[V]H\f[R]. Similar to the accounts screen, the historical total is affected by transactions (filtered by the filter query) before the report start date, while the period total is not.@@ -465,23 +479,23 @@ a depth limit. In other words, the register always shows the transactions contributing to the balance shown on the accounts screen.-Tree mode/list mode can be toggled with \f[C]t\f[R] here also.+Tree mode/list mode can be toggled with \f[V]t\f[R] here also. .PP-\f[C]U\f[R] toggles filtering by unmarked status, showing or hiding+\f[V]U\f[R] toggles filtering by unmarked status, showing or hiding unmarked transactions.-Similarly, \f[C]P\f[R] toggles pending transactions, and \f[C]C\f[R]+Similarly, \f[V]P\f[R] toggles pending transactions, and \f[V]C\f[R] toggles cleared transactions. (By default, transactions with all statuses are shown; if you activate one or two status filters, only those transactions are shown; and if you activate all three, the filter is removed.) .PP-\f[C]R\f[R] toggles real mode, in which virtual postings are ignored.+\f[V]R\f[R] toggles real mode, in which virtual postings are ignored. .PP-\f[C]z\f[R] toggles nonzero mode, in which only transactions posting a+\f[V]z\f[R] toggles nonzero mode, in which only transactions posting a nonzero change are shown (hledger-ui shows zero items by default, unlike command-line hledger). .PP-Press \f[C]RIGHT\f[R] to view the selected transaction in detail.+Press \f[V]RIGHT\f[R] to view the selected transaction in detail. .SS Transaction .PP This screen shows a single transaction, as a general journal entry,@@ -493,7 +507,7 @@ Simple transactions have two postings, but there can be more (or in certain cases, fewer). .PP-\f[C]UP\f[R] and \f[C]DOWN\f[R] will step through all transactions+\f[V]UP\f[R] and \f[V]DOWN\f[R] will step through all transactions listed in the previous account register screen. In the title bar, the numbers in parentheses show your position within that account register.@@ -513,7 +527,7 @@ .SS Watch mode .PP One of hledger-ui\[aq]s best features is the auto-reloading-\f[C]-w/--watch\f[R] mode.+\f[V]-w/--watch\f[R] mode. With this flag, it will update the display automatically whenever changes are saved to the data files. .PP@@ -537,25 +551,25 @@ Here are some current limitations to be aware of: .PP Changes might not be detected with certain editors, possibly including-Jetbrains IDEs, \f[C]gedit\f[R], other Gnome applications; or on certain+Jetbrains IDEs, \f[V]gedit\f[R], other Gnome applications; or on certain unusual filesystems. (#1617, #911).-To work around, reload manually by pressing \f[C]g\f[R] in the+To work around, reload manually by pressing \f[V]g\f[R] in the hledger-ui window. (Or see #1617 for another workaround, and let us know if it works for you.) .PP CPU and memory usage can sometimes gradually increase, if-\f[C]hledger-ui --watch\f[R] is left running for days.+\f[V]hledger-ui --watch\f[R] is left running for days. (Possibly correlated with certain platforms, many transactions, and/or large numbers of other files present).-To work around, \f[C]q\f[R]uit and restart it, or (where supported)-suspend (\f[C]CTRL-z\f[R]) and restart it (\f[C]fg\f[R]).+To work around, \f[V]q\f[R]uit and restart it, or (where supported)+suspend (\f[V]CTRL-z\f[R]) and restart it (\f[V]fg\f[R]). .SS Debug output .PP-You can add \f[C]--debug[=N]\f[R] to the command line to log debug+You can add \f[V]--debug[=N]\f[R] to the command line to log debug output.-This will be logged to the file \f[C]hledger-ui.log\f[R] in the current+This will be logged to the file \f[V]hledger-ui.log\f[R] in the current directory. N ranges from 1 (least output, the default) to 9 (maximum output). .SH ENVIRONMENT@@ -564,19 +578,19 @@ Default: the full terminal width. .PP \f[B]LEDGER_FILE\f[R] The journal file path when not specified with-\f[C]-f\f[R].+\f[V]-f\f[R]. .PP On unix computers, the default value is:-\f[C]\[ti]/.hledger.journal\f[R].+\f[V]\[ti]/.hledger.journal\f[R]. .PP A more typical value is something like-\f[C]\[ti]/finance/YYYY.journal\f[R], where \f[C]\[ti]/finance\f[R] is a+\f[V]\[ti]/finance/YYYY.journal\f[R], where \f[V]\[ti]/finance\f[R] is a version-controlled finance directory and YYYY is the current year.-Or, \f[C]\[ti]/finance/current.journal\f[R], where current.journal is a+Or, \f[V]\[ti]/finance/current.journal\f[R], where current.journal is a symbolic link to YYYY.journal. .PP The usual way to set this permanently is to add a command to one of your-shell\[aq]s startup files (eg \f[C]\[ti]/.profile\f[R]):+shell\[aq]s startup files (eg \f[V]\[ti]/.profile\f[R]): .IP .nf \f[C]@@ -587,7 +601,7 @@ On some Mac computers, there is a more thorough way to set environment variables, that will also affect applications started from the GUI (eg, Emacs started from a dock icon): In-\f[C]\[ti]/.MacOSX/environment.plist\f[R], add an entry like:+\f[V]\[ti]/.MacOSX/environment.plist\f[R], add an entry like: .IP .nf \f[C]@@ -597,11 +611,11 @@ \f[R] .fi .PP-For this to take effect you might need to \f[C]killall Dock\f[R], or+For this to take effect you might need to \f[V]killall Dock\f[R], or reboot. .PP On Windows computers, the default value is probably-\f[C]C:\[rs]Users\[rs]YOURNAME\[rs].hledger.journal\f[R].+\f[V]C:\[rs]Users\[rs]YOURNAME\[rs].hledger.journal\f[R]. You can change this by running a command like this in a powershell window (let us know if you need to be an Administrator, and if this persists across a reboot):@@ -616,24 +630,22 @@ https://www.java.com/en/download/help/path.html. .SH FILES .PP-Reads data from one or more files in hledger journal, timeclock,-timedot, or CSV format specified with \f[C]-f\f[R], or-\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,-perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).+Reads data from one or more files in journal, timeclock, timedot, or CSV+format.+The default file is \f[V].hledger.journal\f[R] in your home directory;+this can be overridden with one or more \f[V]-f FILE\f[R] options, or+the \f[V]LEDGER_FILE\f[R] environment variable. .SH BUGS .PP-The need to precede options with \f[C]--\f[R] when invoked from hledger-is awkward.-.PP-\f[C]-f-\f[R] doesn\[aq]t work (hledger-ui can\[aq]t read from stdin).+\f[V]-f-\f[R] doesn\[aq]t work (hledger-ui can\[aq]t read from stdin). .PP-\f[C]-V\f[R] affects only the accounts screen.+\f[V]-V\f[R] affects only the accounts screen. .PP-When you press \f[C]g\f[R], the current and all previous screens are+When you press \f[V]g\f[R], the current and all previous screens are regenerated, which may cause a noticeable pause with large files. Also there is no visual indication that this is in progress. .PP-\f[C]--watch\f[R] is not yet fully robust.+\f[V]--watch\f[R] is not yet fully robust. It works well for normal usage, but many file changes in a short time (eg saving the file thousands of times with an editor macro) can cause problems at least on OSX.@@ -643,21 +655,23 @@ until the program is restarted. .PP Also, if you are viewing files mounted from another machine,-\f[C]-w/--watch\f[R] requires that both machine clocks are roughly in+\f[V]-w/--watch\f[R] requires that both machine clocks are roughly in step.   .SH "REPORTING BUGS" Report bugs at http://bugs.hledger.org-(or on the #hledger IRC channel or hledger mail list)+(or on the #hledger chat or hledger mail list)  .SH AUTHORS-Simon Michael <simon@joyful.com> and contributors+Simon Michael <simon@joyful.com> and contributors.+.br+See http://hledger.org/CREDITS.html  .SH COPYRIGHT+Copyright 2007-2023 Simon Michael and contributors. -Copyright (C) 2007-2020 Simon Michael.-.br+.SH LICENSE Released under GNU GPL v3 or later.  .SH SEE ALSO

@@ -1,4 +1,4 @@-This is hledger-ui.info, produced by makeinfo version 6.8 from stdin.+This is hledger-ui.info, produced by makeinfo version 7.0.1 from stdin.  INFO-DIR-SECTION User Applications START-INFO-DIR-ENTRY@@ -11,32 +11,35 @@ hledger-ui(1) ************* -hledger-ui is a terminal interface (TUI) for the hledger accounting-tool.  This manual is for hledger-ui 1.28.+hledger-ui - robust, friendly plain text accounting (TUI version) -   'hledger-ui [OPTIONS] [QUERYARGS]'-'hledger ui -- [OPTIONS] [QUERYARGS]'+   ‘hledger-ui [OPTIONS] [QUERYARGS]’+‘hledger ui -- [OPTIONS] [QUERYARGS]’ -   hledger is a reliable, cross-platform set of programs for tracking-money, time, or any other commodity, using double-entry accounting and a-simple, editable file format.  hledger is inspired by and largely-compatible with ledger(1).+   This manual is for hledger’s terminal interface, version 1.29.  See+also the hledger manual for common concepts and file formats. -   hledger-ui is hledger's terminal interface, providing an efficient+   hledger is a robust, user-friendly, cross-platform set of programs+for tracking money, time, or any other commodity, using double-entry+accounting and a simple, editable file format.  hledger is inspired by+and largely compatible with ledger(1), and largely interconvertible with+beancount(1).++   hledger-ui is hledger’s terminal interface, providing an efficient full-window text UI for viewing accounts and transactions, and some-limited data entry capability.  It is easier than hledger's command-line+limited data entry capability.  It is easier than hledger’s command-line interface, and sometimes quicker and more convenient than the web interface. -   Like hledger, it reads data from one or more files in hledger-journal, timeclock, timedot, or CSV format specified with '-f', or-'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps-'C:/Users/USER/.hledger.journal').  For more about this see hledger(1),-hledger_journal(5) etc.+   Like hledger, it reads data from one or more files in journal,+timeclock, timedot, or CSV format.  The default file is+‘.hledger.journal’ in your home directory; this can be overridden with+one or more ‘-f FILE’ options, or the ‘LEDGER_FILE’ environment+variable.  For more about this see hledger(1), hledger_journal(5) etc.     Unlike hledger, hledger-ui hides all future-dated transactions by default.  They can be revealed, along with any rule-generated periodic-transactions, by pressing the F key (or starting with -forecast) to+transactions, by pressing the F key (or starting with –forecast) to enable "forecast mode".  * Menu:@@ -56,173 +59,173 @@ 1 OPTIONS ********* -Note: if invoking hledger-ui as a hledger subcommand, write '--' before+Note: if invoking hledger-ui as a hledger subcommand, write ‘--’ before options as shown above.     Any QUERYARGS are interpreted as a hledger search query which filters the data. -'-w --watch'+‘-w --watch’       watch for data and date changes and reload automatically-'--theme=default|terminal|greenterm'+‘--theme=default|terminal|greenterm’       use this custom display theme-'--menu'+‘--menu’       start in the menu screen-'--all'+‘--all’       start in the all accounts screen-'--bs'+‘--bs’       start in the balance sheet accounts screen-'--is'+‘--is’       start in the income statement accounts screen-'--register=ACCTREGEX'+‘--register=ACCTREGEX’ -     start in the (first) matched account's register screen-'--change'+     start in the (first) matched account’s register screen+‘--change’       show period balances (changes) at startup instead of historical      balances-'-l --flat'+‘-l --flat’       show accounts as a flat list (default)-'-t --tree'+‘-t --tree’       show accounts as a tree     hledger input options: -'-f FILE --file=FILE'+‘-f FILE --file=FILE’       use a different input file.  For stdin, use - (default:-     '$LEDGER_FILE' or '$HOME/.hledger.journal')-'--rules-file=RULESFILE'+     ‘$LEDGER_FILE’ or ‘$HOME/.hledger.journal’)+‘--rules-file=RULESFILE’       Conversion rules file to use when reading CSV (default: FILE.rules)-'--separator=CHAR'+‘--separator=CHAR’ -     Field separator to expect when reading CSV (default: ',')-'--alias=OLD=NEW'+     Field separator to expect when reading CSV (default: ’,’)+‘--alias=OLD=NEW’       rename accounts named OLD to NEW-'--anon'+‘--anon’       anonymize accounts and payees-'--pivot FIELDNAME'+‘--pivot FIELDNAME’       use some other field or tag for the account name-'-I --ignore-assertions'+‘-I --ignore-assertions’       disable balance assertion checks (note: does not disable balance      assignments)-'-s --strict'+‘-s --strict’       do extra error checking (check that all posted accounts are      declared)     hledger reporting options: -'-b --begin=DATE'+‘-b --begin=DATE’       include postings/txns on or after this date (will be adjusted to      preceding subperiod start when using a report interval)-'-e --end=DATE'+‘-e --end=DATE’       include postings/txns before this date (will be adjusted to      following subperiod end when using a report interval)-'-D --daily'+‘-D --daily’       multiperiod/multicolumn report by day-'-W --weekly'+‘-W --weekly’       multiperiod/multicolumn report by week-'-M --monthly'+‘-M --monthly’       multiperiod/multicolumn report by month-'-Q --quarterly'+‘-Q --quarterly’       multiperiod/multicolumn report by quarter-'-Y --yearly'+‘-Y --yearly’       multiperiod/multicolumn report by year-'-p --period=PERIODEXP'+‘-p --period=PERIODEXP’       set start date, end date, and/or reporting interval all at once      using period expressions syntax-'--date2'+‘--date2’       match the secondary date instead (see command help for other      effects)-'--today=DATE'+‘--today=DATE’ -     override today's date (affects relative smart dates, for+     override today’s date (affects relative smart dates, for      tests/examples)-'-U --unmarked'+‘-U --unmarked’       include only unmarked postings/txns (can combine with -P or -C)-'-P --pending'+‘-P --pending’       include only pending postings/txns-'-C --cleared'+‘-C --cleared’       include only cleared postings/txns-'-R --real'+‘-R --real’       include only non-virtual postings-'-NUM --depth=NUM'+‘-NUM --depth=NUM’       hide/aggregate accounts or postings more than NUM levels deep-'-E --empty'+‘-E --empty’       show items with zero amount, normally hidden (and vice-versa in      hledger-ui/hledger-web)-'-B --cost'+‘-B --cost’       convert amounts to their cost/selling amount at transaction time-'-V --market'+‘-V --market’       convert amounts to their market value in default valuation      commodities-'-X --exchange=COMM'+‘-X --exchange=COMM’       convert amounts to their market value in commodity COMM-'--value'+‘--value’       convert amounts to cost or market value, more flexibly than      -B/-V/-X-'--infer-market-prices'+‘--infer-market-prices’       use transaction prices (recorded with @ or @@) as additional market      prices, as if they were P directives-'--auto'+‘--auto’       apply automated posting rules to modify transactions.-'--forecast'+‘--forecast’       generate future transactions from periodic transaction rules, for      the next 6 months or till report end date.  In hledger-ui, also      make ordinary future transactions visible.-'--commodity-style'+‘--commodity-style’       Override the commodity style in the output for the specified-     commodity.  For example 'EUR1.000,00'.-'--color=WHEN (or --colour=WHEN)'+     commodity.  For example ’EUR1.000,00’.+‘--color=WHEN (or --colour=WHEN)’       Should color-supporting commands use ANSI color codes in text-     output.  'auto' (default): whenever stdout seems to be a-     color-supporting terminal.  'always' or 'yes': always, useful eg-     when piping output into 'less -R'. 'never' or 'no': never.  A+     output.  ’auto’ (default): whenever stdout seems to be a+     color-supporting terminal.  ’always’ or ’yes’: always, useful eg+     when piping output into ’less -R’.  ’never’ or ’no’: never.  A      NO_COLOR environment variable overrides this.-'--pretty[=WHEN]'+‘--pretty[=WHEN]’       Show prettier output, e.g.  using unicode box-drawing characters.-     Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never'-     also work).  If you provide an argument you must use '=', e.g.-     '-pretty=yes'.+     Accepts ’yes’ (the default) or ’no’ (’y’, ’n’, ’always’, ’never’+     also work).  If you provide an argument you must use ’=’, e.g.+     ’–pretty=yes’.     When a reporting option appears more than once in the command line, the last one takes precedence.@@ -231,25 +234,25 @@     hledger help options: -'-h --help'+‘-h --help’       show general or COMMAND help-'--man'+‘--man’       show general or COMMAND user manual with man-'--info'+‘--info’       show general or COMMAND user manual with info-'--version'+‘--version’       show general or ADDONCMD version-'--debug[=N]'+‘--debug[=N]’       show debug output (levels 1-9, default: 1)     A @FILE argument will be expanded to the contents of FILE, which should contain one command line option/argument per line.  (To prevent-this, insert a '--' argument before.)+this, insert a ‘--’ argument before.)   File: hledger-ui.info,  Node: MOUSE,  Next: KEYS,  Prev: OPTIONS,  Up: Top@@ -260,9 +263,9 @@ In most modern terminals, you can navigate through the screens with a mouse or touchpad: -   * Use mouse wheel or trackpad to scroll up and down-   * Click on list items to go deeper-   * Click on the left margin (column 0) to go back.+   • Use mouse wheel or trackpad to scroll up and down+   • Click on list items to go deeper+   • Click on the left margin (column 0) to go back.   File: hledger-ui.info,  Node: KEYS,  Next: SCREENS,  Prev: MOUSE,  Up: Top@@ -272,88 +275,96 @@  Keyboard gives more control. -   '?' shows a help dialog listing all keys.  (Some of these also appear-in the quick help at the bottom of each screen.)  Press '?' again (or-'ESCAPE', or 'LEFT', or 'q') to close it.  The following keys work on+   ‘?’ shows a help dialog listing all keys.  (Some of these also appear+in the quick help at the bottom of each screen.)  Press ‘?’ again (or+‘ESCAPE’, or ‘LEFT’, or ‘q’) to close it.  The following keys work on most screens: -   The cursor keys navigate: 'RIGHT' or 'ENTER' goes deeper, 'LEFT'-returns to the previous screen, 'UP'/'DOWN'/'PGUP'/'PGDN'/'HOME'/'END'+   The cursor keys navigate: ‘RIGHT’ or ‘ENTER’ goes deeper, ‘LEFT’+returns to the previous screen, ‘UP’/‘DOWN’/‘PGUP’/‘PGDN’/‘HOME’/‘END’ move up and down through lists.  Emacs-style-('CTRL-p'/'CTRL-n'/'CTRL-f'/'CTRL-b') and VI-style ('k','j','l','h')+(‘CTRL-p’/‘CTRL-n’/‘CTRL-f’/‘CTRL-b’) and VI-style (‘k’,‘j’,‘l’,‘h’) movement keys are also supported.  A tip: movement speed is limited by your keyboard repeat rate, to move faster you may want to adjust it.-(If you're on a mac, the karabiner app is one way to do that.)+(If you’re on a mac, the karabiner app is one way to do that.)     With shift pressed, the cursor keys adjust the report period, limiting the transactions to be shown (by default, all are shown).-'SHIFT-DOWN/UP' steps downward and upward through these standard report+‘SHIFT-DOWN/UP’ steps downward and upward through these standard report period durations: year, quarter, month, week, day.  Then,-'SHIFT-LEFT/RIGHT' moves to the previous/next period.  'T' sets the-report period to today.  With the '-w/--watch' option, when viewing a+‘SHIFT-LEFT/RIGHT’ moves to the previous/next period.  ‘T’ sets the+report period to today.  With the ‘-w/--watch’ option, when viewing a "current" period (the current day, week, month, quarter, or year), the period will move automatically to track the current date.  To set a-non-standard period, you can use '/' and a 'date:' query.+non-standard period, you can use ‘/’ and a ‘date:’ query. -   '/' lets you set a general filter query limiting the data shown,+   (Mac users: SHIFT-DOWN/UP keys do not work by default in Terminal, as+of MacOS Monterey.  You can configure them as follows: open Terminal,+press CMD-comma to open preferences, click Profiles, select your current+terminal profile on the left, click Keyboard on the right, click + and+add this for Shift-Down: ‘\033[1;2B’, click + and add this for Shift-Up:+‘\033[1;2A’.  Press the Escape key to enter the ‘\033’ part, you can’t+type it directly.)++   ‘/’ lets you set a general filter query limiting the data shown, using the same query terms as in hledger and hledger-web.  While editing-the query, you can use CTRL-a/e/d/k, BS, cursor keys; press 'ENTER' to-set it, or 'ESCAPE'to cancel.  There are also keys for quickly adjusting+the query, you can use CTRL-a/e/d/k, BS, cursor keys; press ‘ENTER’ to+set it, or ‘ESCAPE’to cancel.  There are also keys for quickly adjusting some common filters like account depth and transaction status (see-below).  'BACKSPACE' or 'DELETE' removes all filters, showing all+below).  ‘BACKSPACE’ or ‘DELETE’ removes all filters, showing all transactions.     As mentioned above, by default hledger-ui hides future transactions - both ordinary transactions recorded in the journal, and periodic-transactions generated by rule.  'F' toggles forecast mode, in which+transactions generated by rule.  ‘F’ toggles forecast mode, in which future/forecasted transactions are shown. -   'ESCAPE' resets the UI state and jumps back to the top screen,-restoring the app's initial state at startup.  Or, it cancels minibuffer+   ‘ESCAPE’ resets the UI state and jumps back to the top screen,+restoring the app’s initial state at startup.  Or, it cancels minibuffer data entry or the help dialog. -   'CTRL-l' redraws the screen and centers the selection if possible-(selections near the top won't be centered, since we don't scroll above+   ‘CTRL-l’ redraws the screen and centers the selection if possible+(selections near the top won’t be centered, since we don’t scroll above the top). -   'g' reloads from the data file(s) and updates the current screen and+   ‘g’ reloads from the data file(s) and updates the current screen and any previous screens.  (With large files, this could cause a noticeable pause.) -   'I' toggles balance assertion checking.  Disabling balance assertions+   ‘I’ toggles balance assertion checking.  Disabling balance assertions temporarily can be useful for troubleshooting. -   'a' runs command-line hledger's add command, and reloads the updated+   ‘a’ runs command-line hledger’s add command, and reloads the updated file.  This allows some basic data entry. -   'A' is like 'a', but runs the hledger-iadd tool, which provides a-terminal interface.  This key will be available if 'hledger-iadd' is+   ‘A’ is like ‘a’, but runs the hledger-iadd tool, which provides a+terminal interface.  This key will be available if ‘hledger-iadd’ is installed in $path. -   'E' runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default ('emacsclient--a "" -nw') on the journal file.  With some editors (emacs, vi), the+   ‘E’ runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (‘emacsclient+-a "" -nw’) on the journal file.  With some editors (emacs, vi), the cursor will be positioned at the current transaction when invoked from the register and transaction screens, and at the error location (if possible) when invoked from the error screen. -   'B' toggles cost mode, showing amounts in their transaction price's-commodity (like toggling the '-B/--cost' flag).+   ‘B’ toggles cost mode, showing amounts in their cost’s commodity+(like toggling the ‘-B/--cost’ flag). -   'V' toggles value mode, showing amounts' current market value in-their default valuation commodity (like toggling the '-V/--market'+   ‘V’ toggles value mode, showing amounts’ current market value in+their default valuation commodity (like toggling the ‘-V/--market’ flag).  Note, "current market value" means the value on the report end date if specified, otherwise today.  To see the value on another date, you can temporarily set that as the report end date.  Eg: to see a transaction as it was valued on july 30, go to the accounts or register-screen, press '/', and add 'date:-7/30' to the query.+screen, press ‘/’, and add ‘date:-7/30’ to the query.     At most one of cost or value mode can be active at once. -   There's not yet any visual reminder when cost or value mode is-active; for now pressing 'b' 'b' 'v' should reliably reset to normal+   There’s not yet any visual reminder when cost or value mode is+active; for now pressing ‘b’ ‘b’ ‘v’ should reliably reset to normal mode. -   'q' quits the application.+   ‘q’ quits the application.     Additional screen-specific keys are described below. @@ -367,14 +378,14 @@ the "Balance sheet accounts" screen to start with, except in the following situations: -   * If no asset/liability/equity accounts can be detected, or if an+   • If no asset/liability/equity accounts can be detected, or if an      account query has been given on the command line, it starts in the      "All accounts" screen. -   * If a starting screen is specified with -menu/-all/-bs/-is/-register+   • If a starting screen is specified with –menu/–all/–bs/–is/–register      on the command line, it starts in that screen. -   From any screen you can press 'LEFT' or 'ESC' to navigate back to the+   From any screen you can press ‘LEFT’ or ‘ESC’ to navigate back to the top level "Menu" screen.  * Menu:@@ -404,8 +415,8 @@  This screen shows all accounts (possibly filtered by a query), and their end balances on the date shown in the title bar (or their balance-changes in the period shown in the title bar, toggleable with 'H').  It-is like the 'hledger balance' command.+changes in the period shown in the title bar, toggleable with ‘H’).  It+is like the ‘hledger balance’ command.   File: hledger-ui.info,  Node: Balance sheet accounts,  Next: Income statement accounts,  Prev: All accounts,  Up: SCREENS@@ -415,7 +426,7 @@  This screen shows asset, liability and equity accounts, if these can be detected (see account types).  It always shows end balances.  It is like-the 'hledger balancesheetequity' command.+the ‘hledger balancesheetequity’ command.   File: hledger-ui.info,  Node: Income statement accounts,  Next: Register,  Prev: Balance sheet accounts,  Up: SCREENS@@ -424,7 +435,7 @@ =============================  This screen shows revenue and expense accounts.  It always shows balance-changes.  It is like the 'hledger incomestatement' command.+changes.  It is like the ‘hledger incomestatement’ command.     All of these accounts screens work in much the same way: @@ -432,26 +443,26 @@ as accounts which have been declared with an account directive (except for empty parent accounts). -   If you specify a query on the command line or with '/' in the app,+   If you specify a query on the command line or with ‘/’ in the app, they show just the matched accounts, and the balances from matched transactions.     hledger-ui shows accounts with zero balances by default (unlike-command-line hledger).  To hide these, press 'z' to toggle nonzero mode.+command-line hledger).  To hide these, press ‘z’ to toggle nonzero mode. -   Account names are shown as a flat list by default; press 't' to+   Account names are shown as a flat list by default; press ‘t’ to toggle tree mode.  In list mode, account balances are exclusive of subaccounts, except where subaccounts are hidden by a depth limit (see below).  In tree mode, all account balances are inclusive of subaccounts. -   To see less detail, press a number key, '1' to '9', to set a depth-limit.  Or use '-' to decrease and '+'/'=' to increase the depth limit.-'0' shows even less detail, collapsing all accounts to a single total.+   To see less detail, press a number key, ‘1’ to ‘9’, to set a depth+limit.  Or use ‘-’ to decrease and ‘+’/‘=’ to increase the depth limit.+‘0’ shows even less detail, collapsing all accounts to a single total. To remove the depth limit, set it higher than the maximum account depth,-or press 'ESCAPE'.+or press ‘ESCAPE’. -   'H' toggles between showing historical balances or period balances+   ‘H’ toggles between showing historical balances or period balances (on the "All accounts" screen).  Historical balances (the default) are ending balances at the end of the report period, taking into account all transactions before that date (filtered by the filter query if any),@@ -462,16 +473,16 @@ change in balance during the report period.  They are more useful eg when viewing a time log. -   'U' toggles filtering by unmarked status, including or excluding-unmarked postings in the balances.  Similarly, 'P' toggles pending-postings, and 'C' toggles cleared postings.  (By default, balances+   ‘U’ toggles filtering by unmarked status, including or excluding+unmarked postings in the balances.  Similarly, ‘P’ toggles pending+postings, and ‘C’ toggles cleared postings.  (By default, balances include all postings; if you activate one or two status filters, only those postings are included; and if you activate all three, the filter is removed.) -   'R' toggles real mode, in which virtual postings are ignored.+   ‘R’ toggles real mode, in which virtual postings are ignored. -   Press 'RIGHT' to view an account's register screen, Or, 'LEFT' to see+   Press ‘RIGHT’ to view an account’s register screen, Or, ‘LEFT’ to see the menu screen.  @@ -483,42 +494,42 @@ This screen shows the transactions affecting a particular account, like a check register.  Each line represents one transaction and shows: -   * the other account(s) involved, in abbreviated form.  (If there are+   • the other account(s) involved, in abbreviated form.  (If there are      both real and virtual postings, it shows only the accounts affected      by real postings.) -   * the overall change to the current account's balance; positive for+   • the overall change to the current account’s balance; positive for      an inflow to this account, negative for an outflow. -   * the running historical total or period total for the current-     account, after the transaction.  This can be toggled with 'H'.+   • the running historical total or period total for the current+     account, after the transaction.  This can be toggled with ‘H’.      Similar to the accounts screen, the historical total is affected by      transactions (filtered by the filter query) before the report start      date, while the period total is not.  If the historical total is      not disturbed by a filter query, it will be the running historical      balance you would see on a bank register for the current account. -   Transactions affecting this account's subaccounts will be included in-the register if the accounts screen is in tree mode, or if it's in list+   Transactions affecting this account’s subaccounts will be included in+the register if the accounts screen is in tree mode, or if it’s in list mode but this account has subaccounts which are not shown due to a depth limit.  In other words, the register always shows the transactions contributing to the balance shown on the accounts screen.  Tree-mode/list mode can be toggled with 't' here also.+mode/list mode can be toggled with ‘t’ here also. -   'U' toggles filtering by unmarked status, showing or hiding unmarked-transactions.  Similarly, 'P' toggles pending transactions, and 'C'+   ‘U’ toggles filtering by unmarked status, showing or hiding unmarked+transactions.  Similarly, ‘P’ toggles pending transactions, and ‘C’ toggles cleared transactions.  (By default, transactions with all statuses are shown; if you activate one or two status filters, only those transactions are shown; and if you activate all three, the filter is removed.) -   'R' toggles real mode, in which virtual postings are ignored.+   ‘R’ toggles real mode, in which virtual postings are ignored. -   'z' toggles nonzero mode, in which only transactions posting a+   ‘z’ toggles nonzero mode, in which only transactions posting a nonzero change are shown (hledger-ui shows zero items by default, unlike command-line hledger). -   Press 'RIGHT' to view the selected transaction in detail.+   Press ‘RIGHT’ to view the selected transaction in detail.   File: hledger-ui.info,  Node: Transaction,  Next: Error,  Prev: Register,  Up: SCREENS@@ -527,20 +538,20 @@ ===============  This screen shows a single transaction, as a general journal entry,-similar to hledger's print command and journal format+similar to hledger’s print command and journal format (hledger_journal(5)). -   The transaction's date(s) and any cleared flag, transaction code,+   The transaction’s date(s) and any cleared flag, transaction code, description, comments, along with all of its account postings are shown. Simple transactions have two postings, but there can be more (or in certain cases, fewer). -   'UP' and 'DOWN' will step through all transactions listed in the+   ‘UP’ and ‘DOWN’ will step through all transactions listed in the previous account register screen.  In the title bar, the numbers in parentheses show your position within that account register.  They will vary depending on which account register you came from (remember most transactions appear in multiple account registers).  The #N number-preceding them is the transaction's position within the complete+preceding them is the transaction’s position within the complete unfiltered journal, which is a more stable id (at least until the next reload). @@ -572,12 +583,12 @@ 5.1 Watch mode ============== -One of hledger-ui's best features is the auto-reloading '-w/--watch'+One of hledger-ui’s best features is the auto-reloading ‘-w/--watch’ mode.  With this flag, it will update the display automatically whenever changes are saved to the data files.     This is very useful when reconciling.  A good workflow is to have-your bank's online register open in a browser window, for reference; the+your bank’s online register open in a browser window, for reference; the journal file open in an editor window; and hledger-ui in watch mode in a terminal window, eg: @@ -592,16 +603,16 @@    Here are some current limitations to be aware of:     Changes might not be detected with certain editors, possibly-including Jetbrains IDEs, 'gedit', other Gnome applications; or on+including Jetbrains IDEs, ‘gedit’, other Gnome applications; or on certain unusual filesystems.  (#1617, #911).  To work around, reload-manually by pressing 'g' in the hledger-ui window.  (Or see #1617 for+manually by pressing ‘g’ in the hledger-ui window.  (Or see #1617 for another workaround, and let us know if it works for you.) -   CPU and memory usage can sometimes gradually increase, if 'hledger-ui---watch' is left running for days.  (Possibly correlated with certain+   CPU and memory usage can sometimes gradually increase, if ‘hledger-ui+--watch’ is left running for days.  (Possibly correlated with certain platforms, many transactions, and/or large numbers of other files-present).  To work around, 'q'uit and restart it, or (where supported)-suspend ('CTRL-z') and restart it ('fg').+present).  To work around, ‘q’uit and restart it, or (where supported)+suspend (‘CTRL-z’) and restart it (‘fg’).   File: hledger-ui.info,  Node: Debug output,  Prev: Watch mode,  Up: TIPS@@ -609,8 +620,8 @@ 5.2 Debug output ================ -You can add '--debug[=N]' to the command line to log debug output.  This-will be logged to the file 'hledger-ui.log' in the current directory.  N+You can add ‘--debug[=N]’ to the command line to log debug output.  This+will be logged to the file ‘hledger-ui.log’ in the current directory.  N ranges from 1 (least output, the default) to 9 (maximum output).  @@ -621,33 +632,33 @@  *COLUMNS* The screen width to use.  Default: the full terminal width. -   *LEDGER_FILE* The journal file path when not specified with '-f'.+   *LEDGER_FILE* The journal file path when not specified with ‘-f’. -   On unix computers, the default value is: '~/.hledger.journal'.+   On unix computers, the default value is: ‘~/.hledger.journal’. -   A more typical value is something like '~/finance/YYYY.journal',-where '~/finance' is a version-controlled finance directory and YYYY is-the current year.  Or, '~/finance/current.journal', where+   A more typical value is something like ‘~/finance/YYYY.journal’,+where ‘~/finance’ is a version-controlled finance directory and YYYY is+the current year.  Or, ‘~/finance/current.journal’, where current.journal is a symbolic link to YYYY.journal.     The usual way to set this permanently is to add a command to one of-your shell's startup files (eg '~/.profile'):+your shell’s startup files (eg ‘~/.profile’):  export LEDGER_FILE=~/finance/current.journal`     On some Mac computers, there is a more thorough way to set environment variables, that will also affect applications started from the GUI (eg, Emacs started from a dock icon): In-'~/.MacOSX/environment.plist', add an entry like:+‘~/.MacOSX/environment.plist’, add an entry like:  {   "LEDGER_FILE" : "~/finance/current.journal" } -   For this to take effect you might need to 'killall Dock', or reboot.+   For this to take effect you might need to ‘killall Dock’, or reboot.     On Windows computers, the default value is probably-'C:\Users\YOURNAME\.hledger.journal'.  You can change this by running a+‘C:\Users\YOURNAME\.hledger.journal’.  You can change this by running a command like this in a powershell window (let us know if you need to be an Administrator, and if this persists across a reboot): @@ -662,10 +673,10 @@ 7 FILES ******* -Reads data from one or more files in hledger journal, timeclock,-timedot, or CSV format specified with '-f', or '$LEDGER_FILE', or-'$HOME/.hledger.journal' (on windows, perhaps-'C:/Users/USER/.hledger.journal').+Reads data from one or more files in journal, timeclock, timedot, or CSV+format.  The default file is ‘.hledger.journal’ in your home directory;+this can be overridden with one or more ‘-f FILE’ options, or the+‘LEDGER_FILE’ environment variable.   File: hledger-ui.info,  Node: BUGS,  Prev: FILES,  Up: Top@@ -673,18 +684,15 @@ 8 BUGS ****** -The need to precede options with '--' when invoked from hledger is-awkward.--   '-f-' doesn't work (hledger-ui can't read from stdin).+‘-f-’ doesn’t work (hledger-ui can’t read from stdin). -   '-V' affects only the accounts screen.+   ‘-V’ affects only the accounts screen. -   When you press 'g', the current and all previous screens are+   When you press ‘g’, the current and all previous screens are regenerated, which may cause a noticeable pause with large files.  Also there is no visual indication that this is in progress. -   '--watch' is not yet fully robust.  It works well for normal usage,+   ‘--watch’ is not yet fully robust.  It works well for normal usage, but many file changes in a short time (eg saving the file thousands of times with an editor macro) can cause problems at least on OSX. Symptoms include: unresponsive UI, periodic resetting of the cursor position,@@ -693,45 +701,45 @@ program is restarted.     Also, if you are viewing files mounted from another machine,-'-w/--watch' requires that both machine clocks are roughly in step.+‘-w/--watch’ requires that both machine clocks are roughly in step.   Tag Table:-Node: Top221-Node: OPTIONS1654-Ref: #options1752-Node: MOUSE6836-Ref: #mouse6931-Node: KEYS7168-Ref: #keys7261-Node: SCREENS11336-Ref: #screens11434-Node: Menu12120-Ref: #menu12212-Node: All accounts12289-Ref: #all-accounts12428-Node: Balance sheet accounts12679-Ref: #balance-sheet-accounts12859-Node: Income statement accounts13047-Ref: #income-statement-accounts13229-Node: Register15649-Ref: #register15786-Node: Transaction17770-Ref: #transaction17893-Node: Error18763-Ref: #error18857-Node: TIPS19101-Ref: #tips19200-Node: Watch mode19242-Ref: #watch-mode19349-Node: Debug output20805-Ref: #debug-output20916-Node: ENVIRONMENT21128-Ref: #environment21239-Node: FILES22624-Ref: #files22723-Node: BUGS22936-Ref: #bugs23013+Node: Top223+Node: OPTIONS1869+Ref: #options1967+Node: MOUSE7334+Ref: #mouse7429+Node: KEYS7672+Ref: #keys7765+Node: SCREENS12524+Ref: #screens12622+Node: Menu13330+Ref: #menu13422+Node: All accounts13499+Ref: #all-accounts13638+Node: Balance sheet accounts13897+Ref: #balance-sheet-accounts14077+Node: Income statement accounts14269+Ref: #income-statement-accounts14451+Node: Register16945+Ref: #register17082+Node: Transaction19110+Ref: #transaction19233+Node: Error20117+Ref: #error20211+Node: TIPS20455+Ref: #tips20554+Node: Watch mode20596+Ref: #watch-mode20703+Node: Debug output22191+Ref: #debug-output22302+Node: ENVIRONMENT22522+Ref: #environment22633+Node: FILES24056+Ref: #files24155+Node: BUGS24415+Ref: #bugs24492  End Tag Table 

@@ -4,41 +4,44 @@   NAME-       hledger-ui  is  a  terminal  interface (TUI) for the hledger accounting-       tool.  This manual is for hledger-ui 1.28.+       hledger-ui - robust, friendly plain text accounting (TUI version)  SYNOPSIS        hledger-ui [OPTIONS] [QUERYARGS]        hledger ui -- [OPTIONS] [QUERYARGS]  DESCRIPTION-       hledger is a reliable, cross-platform  set  of  programs  for  tracking-       money,  time, or any other commodity, using double-entry accounting and-       a simple, editable file format.  hledger is  inspired  by  and  largely-       compatible with ledger(1).+       This  manual  is  for  hledger's terminal interface, version 1.29.  See+       also the hledger manual for common concepts and file formats. -       hledger-ui  is  hledger's  terminal  interface,  providing an efficient-       full-window text UI for viewing accounts  and  transactions,  and  some-       limited  data  entry  capability.  It is easier than hledger's command--       line interface, and sometimes quicker and more convenient than the  web+       hledger is a robust, user-friendly, cross-platform set of programs  for+       tracking  money,  time,  or  any  other  commodity,  using double-entry+       accounting and a simple, editable file format.  hledger is inspired  by+       and  largely  compatible  with  ledger(1), and largely interconvertible+       with beancount(1).++       hledger-ui is hledger's  terminal  interface,  providing  an  efficient+       full-window  text  UI  for  viewing accounts and transactions, and some+       limited data entry capability.  It is easier  than  hledger's  command-+       line  interface, and sometimes quicker and more convenient than the web        interface. -       Like  hledger, it reads data from one or more files in hledger journal,-       timeclock, timedot, or CSV format specified with -f,  or  $LEDGER_FILE,-       or        $HOME/.hledger.journal       (on       windows,       perhaps-       C:/Users/USER/.hledger.journal).  For more about this  see  hledger(1),-       hledger_journal(5) etc.+       Like hledger, it reads data from one or more files  in  journal,  time-+       clock, timedot, or CSV format.  The default file is .hledger.journal in+       your home directory; this can be overridden with one or  more  -f  FILE+       options,  or the LEDGER_FILE environment variable.  For more about this+       see hledger(1), hledger_journal(5) etc. -       Unlike  hledger,  hledger-ui  hides  all  future-dated  transactions by-       default.  They can be revealed, along with any rule-generated  periodic-       transactions,  by  pressing  the F key (or starting with --forecast) to+       Unlike hledger,  hledger-ui  hides  all  future-dated  transactions  by+       default.   They can be revealed, along with any rule-generated periodic+       transactions, by pressing the F key (or starting  with  --forecast)  to        enable "forecast mode".  OPTIONS-       Note: if invoking hledger-ui as a hledger subcommand, write  --  before+       Note:  if  invoking hledger-ui as a hledger subcommand, write -- before        options as shown above. -       Any  QUERYARGS  are interpreted as a hledger search query which filters+       Any QUERYARGS are interpreted as a hledger search query  which  filters        the data.         -w --watch@@ -59,7 +62,7 @@               start in the (first) matched account's register screen         --change-              show period balances (changes) at startup instead of  historical+              show  period balances (changes) at startup instead of historical               balances         -l --flat@@ -75,7 +78,7 @@               $LEDGER_FILE or $HOME/.hledger.journal)         --rules-file=RULESFILE-              Conversion  rules  file  to  use  when  reading  CSV   (default:+              Conversion   rules  file  to  use  when  reading  CSV  (default:               FILE.rules)         --separator=CHAR@@ -94,7 +97,7 @@               assignments)         -s --strict-              do extra error checking (check  that  all  posted  accounts  are+              do  extra  error  checking  (check  that all posted accounts are               declared)         hledger reporting options:@@ -123,15 +126,15 @@               multiperiod/multicolumn report by year         -p --period=PERIODEXP-              set  start date, end date, and/or reporting interval all at once+              set start date, end date, and/or reporting interval all at  once               using period expressions syntax         --date2-              match the secondary date instead (see  command  help  for  other+              match  the  secondary  date  instead (see command help for other               effects)         --today=DATE-              override   today's  date  (affects  relative  smart  dates,  for+              override  today's  date  (affects  relative  smart  dates,   for               tests/examples)         -U --unmarked@@ -150,49 +153,49 @@               hide/aggregate accounts or postings more than NUM levels deep         -E --empty-              show items with zero amount, normally hidden (and vice-versa  in+              show  items with zero amount, normally hidden (and vice-versa in               hledger-ui/hledger-web)         -B --cost               convert amounts to their cost/selling amount at transaction time         -V --market-              convert amounts to their market value in default valuation  com-+              convert  amounts to their market value in default valuation com-               modities         -X --exchange=COMM               convert amounts to their market value in commodity COMM         --value-              convert  amounts  to  cost  or  market value, more flexibly than+              convert amounts to cost or  market  value,  more  flexibly  than               -B/-V/-X         --infer-market-prices-              use transaction prices (recorded with @  or  @@)  as  additional+              use  transaction  prices  (recorded  with @ or @@) as additional               market prices, as if they were P directives         --auto apply automated posting rules to modify transactions.         --forecast-              generate  future  transactions  from periodic transaction rules,-              for the next 6 months or till report end date.   In  hledger-ui,+              generate future transactions from  periodic  transaction  rules,+              for  the  next 6 months or till report end date.  In hledger-ui,               also make ordinary future transactions visible.         --commodity-style-              Override  the  commodity  style  in the output for the specified+              Override the commodity style in the  output  for  the  specified               commodity.  For example 'EUR1.000,00'.         --color=WHEN (or --colour=WHEN)-              Should color-supporting commands use ANSI color  codes  in  text-              output.   'auto' (default): whenever stdout seems to be a color--              supporting terminal.  'always' or 'yes': always, useful eg  when-              piping  output  into  'less  -R'.   'never'  or  'no': never.  A+              Should  color-supporting  commands  use ANSI color codes in text+              output.  'auto' (default): whenever stdout seems to be a  color-+              supporting  terminal.  'always' or 'yes': always, useful eg when+              piping output into  'less  -R'.   'never'  or  'no':  never.   A               NO_COLOR environment variable overrides this.         --pretty[=WHEN]-              Show prettier output, e.g.  using  unicode  box-drawing  charac--              ters.   Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',-              'never' also work).  If you provide an  argument  you  must  use+              Show  prettier  output,  e.g.  using unicode box-drawing charac-+              ters.  Accepts 'yes' (the default) or 'no' ('y', 'n',  'always',+              'never'  also  work).   If  you provide an argument you must use               '=', e.g.  '--pretty=yes'.         When a reporting option appears more than once in the command line, the@@ -216,11 +219,11 @@               show debug output (levels 1-9, default: 1)         A @FILE argument will be expanded to the contents of FILE, which should-       contain  one  command line option/argument per line.  (To prevent this,+       contain one command line option/argument per line.  (To  prevent  this,        insert a -- argument before.)  MOUSE-       In most modern terminals, you can navigate through the screens  with  a+       In  most  modern terminals, you can navigate through the screens with a        mouse or touchpad:         o Use mouse wheel or trackpad to scroll up and down@@ -232,9 +235,10 @@ KEYS        Keyboard gives more control. -       ?  shows a help dialog listing all keys.  (Some of these also appear in-       the quick help at the bottom of each screen.) Press ? again (or ESCAPE,-       or LEFT, or q) to close it.  The following keys work on most screens:+       ? shows a help dialog listing all keys.  (Some of these also appear  in+       the  quick  help  at  the  bottom  of  each screen.)  Press ? again (or+       ESCAPE, or LEFT, or q) to close it.  The following keys  work  on  most+       screens:         The  cursor  keys navigate: RIGHT or ENTER goes deeper, LEFT returns to        the  previous  screen,  UP/DOWN/PGUP/PGDN/HOME/END  move  up  and  down@@ -254,6 +258,14 @@        ically to track the current date.  To set a  non-standard  period,  you        can use / and a date: query. +       (Mac  users:  SHIFT-DOWN/UP keys do not work by default in Terminal, as+       of MacOS Monterey.  You can configure them as follows:  open  Terminal,+       press  CMD-comma  to open preferences, click Profiles, select your cur-+       rent terminal profile on the left, click Keyboard on the right, click ++       and add this for Shift-Down: \033[1;2B, click + and add this for Shift-+       Up: \033[1;2A.  Press the Escape key to enter the \033 part, you  can't+       type it directly.)+        /  lets  you  set a general filter query limiting the data shown, using        the same query terms as in hledger and hledger-web.  While editing  the        query,  you  can  use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set@@ -294,8 +306,8 @@        register and transaction screens, and at the error location (if  possi-        ble) when invoked from the error screen. -       B  toggles cost mode, showing amounts in their transaction price's com--       modity (like toggling the -B/--cost flag).+       B  toggles  cost  mode, showing amounts in their cost's commodity (like+       toggling the -B/--cost flag).         V toggles value mode, showing amounts' current market  value  in  their        default  valuation  commodity  (like  toggling  the  -V/--market flag).@@ -536,27 +548,24 @@        load/help/path.html.  FILES-       Reads  data from one or more files in hledger journal, timeclock, time--       dot,  or  CSV  format  specified   with   -f,   or   $LEDGER_FILE,   or-       $HOME/.hledger.journal           (on          windows,          perhaps-       C:/Users/USER/.hledger.journal).+       Reads  data  from  one or more files in journal, timeclock, timedot, or+       CSV format.  The default file is .hledger.journal in your  home  direc-+       tory;  this  can be overridden with one or more -f FILE options, or the+       LEDGER_FILE environment variable.  BUGS-       The need to precede options with -- when invoked from hledger  is  awk--       ward.-        -f- doesn't work (hledger-ui can't read from stdin).         -V affects only the accounts screen.         When you press g, the current and all previous screens are regenerated,-       which may cause a noticeable pause with large files.  Also there is  no+       which  may cause a noticeable pause with large files.  Also there is no        visual indication that this is in progress. -       --watch  is  not yet fully robust.  It works well for normal usage, but-       many file changes in a short time (eg  saving  the  file  thousands  of-       times  with an editor macro) can cause problems at least on OSX.  Symp--       toms include: unresponsive UI, periodic resetting of the  cursor  posi-+       --watch is not yet fully robust.  It works well for normal  usage,  but+       many  file  changes  in  a  short time (eg saving the file thousands of+       times with an editor macro) can cause problems at least on OSX.   Symp-+       toms  include:  unresponsive UI, periodic resetting of the cursor posi-        tion, momentary display of parse errors, high CPU usage eventually sub-        siding, and possibly a small but persistent build-up of CPU usage until        the program is restarted.@@ -567,16 +576,20 @@   REPORTING BUGS-       Report bugs at http://bugs.hledger.org (or on the #hledger IRC  channel-       or hledger mail list)+       Report  bugs  at  http://bugs.hledger.org  (or  on the #hledger chat or+       hledger mail list)   AUTHORS-       Simon Michael <simon@joyful.com> and contributors+       Simon Michael <simon@joyful.com> and contributors.+       See http://hledger.org/CREDITS.html   COPYRIGHT-       Copyright (C) 2007-2020 Simon Michael.+       Copyright 2007-2023 Simon Michael and contributors.+++LICENSE        Released under GNU GPL v3 or later.  @@ -585,4 +598,4 @@   -hledger-ui-1.28                  December 2022                   HLEDGER-UI(1)+hledger-ui-1.29                   March 2023                     HLEDGER-UI(1)

@@ -1,33 +1,37 @@ -.TH "HLEDGER-WEB" "1" "December 2022" "hledger-web-1.28 " "hledger User Manuals"+.TH "HLEDGER-WEB" "1" "March 2023" "hledger-web-1.29 " "hledger User Manuals"    .SH NAME .PP-hledger-web is a web interface (WUI) for the hledger accounting tool.-This manual is for hledger-web 1.28.+hledger-web - robust, friendly plain text accounting (Web version) .SH SYNOPSIS .PP-\f[C]hledger-web [OPTIONS]              # run temporarily & browse\f[R]+\f[V]hledger-web [OPTIONS]                  # run temporarily & browse\f[R] .PD 0 .P .PD-\f[C]hledger-web --serve [OPTIONS]      # run without stopping\f[R]+\f[V]hledger-web --serve [OPTIONS]          # run without stopping\f[R] .PD 0 .P .PD-\f[C]hledger-web --serve-api [OPTIONS]  # run JSON server only\f[R]+\f[V]hledger-web --serve-api [OPTIONS]      # run JSON server only\f[R] .PD 0 .P .PD+\f[V]hledger web -- [OPTIONS] [QUERYARGS]\f[R] # start from hledger .SH DESCRIPTION .PP-hledger is a reliable, cross-platform set of programs for tracking-money, time, or any other commodity, using double-entry accounting and a-simple, editable file format.-hledger is inspired by and largely compatible with ledger(1).+This manual is for hledger\[aq]s web interface, version 1.29.+See also the hledger manual for common concepts and file formats. .PP+hledger is a robust, user-friendly, cross-platform set of programs for+tracking money, time, or any other commodity, using double-entry+accounting and a simple, editable file format.+hledger is inspired by and largely compatible with ledger(1), and+largely interconvertible with beancount(1).+.PP hledger-web is a simple web application for browsing and adding transactions. It provides a more user-friendly UI than the hledger CLI or hledger-ui@@ -43,10 +47,11 @@ instance, it writes a numbered backup of the main journal file (only) on every edit. .PP-Like hledger, it reads data from one or more files in hledger journal,-timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or-\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,-perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).+Like hledger, it reads data from one or more files in journal,+timeclock, timedot, or CSV format.+The default file is \f[V].hledger.journal\f[R] in your home directory;+this can be overridden with one or more \f[V]-f FILE\f[R] options, or+the \f[V]LEDGER_FILE\f[R] environment variable. For more about this see hledger(1). .PP hledger-web can be run in three modes:@@ -56,10 +61,10 @@ minutes of inactivity (no requests received and no open browser windows viewing it). .IP \[bu] 2-With \f[C]--serve\f[R]: the app runs without stopping, and without+With \f[V]--serve\f[R]: the app runs without stopping, and without opening a browser. .IP \[bu] 2-With \f[C]--serve-api\f[R]: only the JSON API is served.+With \f[V]--serve-api\f[R]: only the JSON API is served. .PP In all cases hledger-web runs as a foreground process, logging requests to stdout.@@ -71,163 +76,164 @@ in addition to any search query entered there. .PP Note: if invoking hledger-web as a hledger subcommand, write-\f[C]--\f[R] before options, as shown in the synopsis above.+\f[V]--\f[R] before options, as shown in the synopsis above. .TP-\f[B]\f[CB]--serve\f[B]\f[R]+\f[V]--serve\f[R] serve and log requests, don\[aq]t browse or auto-exit after timeout .TP-\f[B]\f[CB]--serve-api\f[B]\f[R]+\f[V]--serve-api\f[R] like --serve, but serve only the JSON web API, without the server-side web UI .TP-\f[B]\f[CB]--host=IPADDR\f[B]\f[R]+\f[V]--host=IPADDR\f[R] listen on this IP address (default: 127.0.0.1) .TP-\f[B]\f[CB]--port=PORT\f[B]\f[R]+\f[V]--port=PORT\f[R] listen on this TCP port (default: 5000) .TP-\f[B]\f[CB]--socket=SOCKETFILE\f[B]\f[R]+\f[V]--socket=SOCKETFILE\f[R] use a unix domain socket file to listen for requests instead of a TCP socket.-Implies \f[C]--serve\f[R].+Implies \f[V]--serve\f[R]. It can only be used if the operating system can provide this type of socket. .TP-\f[B]\f[CB]--base-url=URL\f[B]\f[R]+\f[V]--base-url=URL\f[R] set the base url (default: http://IPADDR:PORT).-You would change this when sharing over the network, or integrating-within a larger website.+Note: affects url generation but not route parsing.+Can be useful if running behind a reverse web proxy that does path+rewriting. .TP-\f[B]\f[CB]--file-url=URL\f[B]\f[R]+\f[V]--file-url=URL\f[R] set the static files url (default: BASEURL/static). hledger-web normally serves static files itself, but if you wanted to serve them from another server for efficiency, you would set the url with this. .TP-\f[B]\f[CB]--capabilities=CAP[,CAP..]\f[B]\f[R]+\f[V]--capabilities=CAP[,CAP..]\f[R] enable the view, add, and/or manage capabilities (default: view,add) .TP-\f[B]\f[CB]--capabilities-header=HTTPHEADER\f[B]\f[R]+\f[V]--capabilities-header=HTTPHEADER\f[R] read capabilities to enable from a HTTP header, like X-Sandstorm-Permissions (default: disabled) .TP-\f[B]\f[CB]--test\f[B]\f[R]+\f[V]--test\f[R] run hledger-web\[aq]s tests and exit. hspec test runner args may follow a --, eg: hledger-web --test -- --help .PP hledger input options: .TP-\f[B]\f[CB]-f FILE --file=FILE\f[B]\f[R]+\f[V]-f FILE --file=FILE\f[R] use a different input file.-For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or-\f[C]$HOME/.hledger.journal\f[R])+For stdin, use - (default: \f[V]$LEDGER_FILE\f[R] or+\f[V]$HOME/.hledger.journal\f[R]) .TP-\f[B]\f[CB]--rules-file=RULESFILE\f[B]\f[R]+\f[V]--rules-file=RULESFILE\f[R] Conversion rules file to use when reading CSV (default: FILE.rules) .TP-\f[B]\f[CB]--separator=CHAR\f[B]\f[R]+\f[V]--separator=CHAR\f[R] Field separator to expect when reading CSV (default: \[aq],\[aq]) .TP-\f[B]\f[CB]--alias=OLD=NEW\f[B]\f[R]+\f[V]--alias=OLD=NEW\f[R] rename accounts named OLD to NEW .TP-\f[B]\f[CB]--anon\f[B]\f[R]+\f[V]--anon\f[R] anonymize accounts and payees .TP-\f[B]\f[CB]--pivot FIELDNAME\f[B]\f[R]+\f[V]--pivot FIELDNAME\f[R] use some other field or tag for the account name .TP-\f[B]\f[CB]-I --ignore-assertions\f[B]\f[R]+\f[V]-I --ignore-assertions\f[R] disable balance assertion checks (note: does not disable balance assignments) .TP-\f[B]\f[CB]-s --strict\f[B]\f[R]+\f[V]-s --strict\f[R] do extra error checking (check that all posted accounts are declared) .PP hledger reporting options: .TP-\f[B]\f[CB]-b --begin=DATE\f[B]\f[R]+\f[V]-b --begin=DATE\f[R] include postings/txns on or after this date (will be adjusted to preceding subperiod start when using a report interval) .TP-\f[B]\f[CB]-e --end=DATE\f[B]\f[R]+\f[V]-e --end=DATE\f[R] include postings/txns before this date (will be adjusted to following subperiod end when using a report interval) .TP-\f[B]\f[CB]-D --daily\f[B]\f[R]+\f[V]-D --daily\f[R] multiperiod/multicolumn report by day .TP-\f[B]\f[CB]-W --weekly\f[B]\f[R]+\f[V]-W --weekly\f[R] multiperiod/multicolumn report by week .TP-\f[B]\f[CB]-M --monthly\f[B]\f[R]+\f[V]-M --monthly\f[R] multiperiod/multicolumn report by month .TP-\f[B]\f[CB]-Q --quarterly\f[B]\f[R]+\f[V]-Q --quarterly\f[R] multiperiod/multicolumn report by quarter .TP-\f[B]\f[CB]-Y --yearly\f[B]\f[R]+\f[V]-Y --yearly\f[R] multiperiod/multicolumn report by year .TP-\f[B]\f[CB]-p --period=PERIODEXP\f[B]\f[R]+\f[V]-p --period=PERIODEXP\f[R] set start date, end date, and/or reporting interval all at once using period expressions syntax .TP-\f[B]\f[CB]--date2\f[B]\f[R]+\f[V]--date2\f[R] match the secondary date instead (see command help for other effects) .TP-\f[B]\f[CB]--today=DATE\f[B]\f[R]+\f[V]--today=DATE\f[R] override today\[aq]s date (affects relative smart dates, for tests/examples) .TP-\f[B]\f[CB]-U --unmarked\f[B]\f[R]+\f[V]-U --unmarked\f[R] include only unmarked postings/txns (can combine with -P or -C) .TP-\f[B]\f[CB]-P --pending\f[B]\f[R]+\f[V]-P --pending\f[R] include only pending postings/txns .TP-\f[B]\f[CB]-C --cleared\f[B]\f[R]+\f[V]-C --cleared\f[R] include only cleared postings/txns .TP-\f[B]\f[CB]-R --real\f[B]\f[R]+\f[V]-R --real\f[R] include only non-virtual postings .TP-\f[B]\f[CB]-NUM --depth=NUM\f[B]\f[R]+\f[V]-NUM --depth=NUM\f[R] hide/aggregate accounts or postings more than NUM levels deep .TP-\f[B]\f[CB]-E --empty\f[B]\f[R]+\f[V]-E --empty\f[R] show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) .TP-\f[B]\f[CB]-B --cost\f[B]\f[R]+\f[V]-B --cost\f[R] convert amounts to their cost/selling amount at transaction time .TP-\f[B]\f[CB]-V --market\f[B]\f[R]+\f[V]-V --market\f[R] convert amounts to their market value in default valuation commodities .TP-\f[B]\f[CB]-X --exchange=COMM\f[B]\f[R]+\f[V]-X --exchange=COMM\f[R] convert amounts to their market value in commodity COMM .TP-\f[B]\f[CB]--value\f[B]\f[R]+\f[V]--value\f[R] convert amounts to cost or market value, more flexibly than -B/-V/-X .TP-\f[B]\f[CB]--infer-market-prices\f[B]\f[R]+\f[V]--infer-market-prices\f[R] use transaction prices (recorded with \[at] or \[at]\[at]) as additional market prices, as if they were P directives .TP-\f[B]\f[CB]--auto\f[B]\f[R]+\f[V]--auto\f[R] apply automated posting rules to modify transactions. .TP-\f[B]\f[CB]--forecast\f[B]\f[R]+\f[V]--forecast\f[R] generate future transactions from periodic transaction rules, for the next 6 months or till report end date. In hledger-ui, also make ordinary future transactions visible. .TP-\f[B]\f[CB]--commodity-style\f[B]\f[R]+\f[V]--commodity-style\f[R] Override the commodity style in the output for the specified commodity. For example \[aq]EUR1.000,00\[aq]. .TP-\f[B]\f[CB]--color=WHEN (or --colour=WHEN)\f[B]\f[R]+\f[V]--color=WHEN (or --colour=WHEN)\f[R] Should color-supporting commands use ANSI color codes in text output. \[aq]auto\[aq] (default): whenever stdout seems to be a color-supporting terminal.@@ -236,7 +242,7 @@ \[aq]never\[aq] or \[aq]no\[aq]: never. A NO_COLOR environment variable overrides this. .TP-\f[B]\f[CB]--pretty[=WHEN]\f[B]\f[R]+\f[V]--pretty[=WHEN]\f[R] Show prettier output, e.g. using unicode box-drawing characters. Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq],@@ -251,46 +257,46 @@ .PP hledger help options: .TP-\f[B]\f[CB]-h --help\f[B]\f[R]+\f[V]-h --help\f[R] show general or COMMAND help .TP-\f[B]\f[CB]--man\f[B]\f[R]+\f[V]--man\f[R] show general or COMMAND user manual with man .TP-\f[B]\f[CB]--info\f[B]\f[R]+\f[V]--info\f[R] show general or COMMAND user manual with info .TP-\f[B]\f[CB]--version\f[B]\f[R]+\f[V]--version\f[R] show general or ADDONCMD version .TP-\f[B]\f[CB]--debug[=N]\f[B]\f[R]+\f[V]--debug[=N]\f[R] show debug output (levels 1-9, default: 1) .PP A \[at]FILE argument will be expanded to the contents of FILE, which should contain one command line option/argument per line.-(To prevent this, insert a \f[C]--\f[R] argument before.)+(To prevent this, insert a \f[V]--\f[R] argument before.) .PP By default the server listens on IP address 127.0.0.1, accessible only to local requests.-You can use \f[C]--host\f[R] to change this, eg \f[C]--host 0.0.0.0\f[R]+You can use \f[V]--host\f[R] to change this, eg \f[V]--host 0.0.0.0\f[R] to listen on all configured addresses. .PP-Similarly, use \f[C]--port\f[R] to set a TCP port other than 5000, eg if+Similarly, use \f[V]--port\f[R] to set a TCP port other than 5000, eg if you are running multiple hledger-web instances. .PP-Both of these options are ignored when \f[C]--socket\f[R] is used.-In this case, it creates an \f[C]AF_UNIX\f[R] socket file at the+Both of these options are ignored when \f[V]--socket\f[R] is used.+In this case, it creates an \f[V]AF_UNIX\f[R] socket file at the supplied path and uses that for communication. This is an alternative way of running multiple hledger-web instances behind a reverse proxy that handles authentication for different users. The path can be derived in a predictable way, eg by using the username within the path.-As an example, \f[C]nginx\f[R] as reverse proxy can use the variable-\f[C]$remote_user\f[R] to derive a path from the username used in a HTTP+As an example, \f[V]nginx\f[R] as reverse proxy can use the variable+\f[V]$remote_user\f[R] to derive a path from the username used in a HTTP basic authentication.-The following \f[C]proxy_pass\f[R] directive allows access to all-\f[C]hledger-web\f[R] instances that created a socket in-\f[C]/tmp/hledger/\f[R]:+The following \f[V]proxy_pass\f[R] directive allows access to all+\f[V]hledger-web\f[R] instances that created a socket in+\f[V]/tmp/hledger/\f[R]: .IP .nf \f[C]@@ -298,14 +304,14 @@ \f[R] .fi .PP-You can use \f[C]--base-url\f[R] to change the protocol, hostname, port+You can use \f[V]--base-url\f[R] to change the protocol, hostname, port and path that appear in hyperlinks, useful eg for integrating hledger-web within a larger website.-The default is \f[C]http://HOST:PORT/\f[R] using the server\[aq]s-configured host address and TCP port (or \f[C]http://HOST\f[R] if PORT+The default is \f[V]http://HOST:PORT/\f[R] using the server\[aq]s+configured host address and TCP port (or \f[V]http://HOST\f[R] if PORT is 80). .PP-With \f[C]--file-url\f[R] you can set a different base url for static+With \f[V]--file-url\f[R] you can set a different base url for static files, eg for better caching or cookie-less serving on high performance websites. .SH PERMISSIONS@@ -315,7 +321,7 @@ .PP You can restrict who can reach it by .IP \[bu] 2-setting the IP address it listens on (see \f[C]--host\f[R] above).+setting the IP address it listens on (see \f[V]--host\f[R] above). By default it listens on 127.0.0.1, accessible to all users on the local machine. .IP \[bu] 2@@ -325,27 +331,27 @@ .PP You can restrict what the users who reach it can do, by .IP \[bu] 2-using the \f[C]--capabilities=CAP[,CAP..]\f[R] flag when you start it,+using the \f[V]--capabilities=CAP[,CAP..]\f[R] flag when you start it, enabling one or more of the following capabilities.-The default value is \f[C]view,add\f[R]:+The default value is \f[V]view,add\f[R]: .RS 2 .IP \[bu] 2-\f[C]view\f[R] - allows viewing the journal file and all included files+\f[V]view\f[R] - allows viewing the journal file and all included files .IP \[bu] 2-\f[C]add\f[R] - allows adding new transactions to the main journal file+\f[V]add\f[R] - allows adding new transactions to the main journal file .IP \[bu] 2-\f[C]manage\f[R] - allows editing, uploading or downloading the main or+\f[V]manage\f[R] - allows editing, uploading or downloading the main or included files .RE .IP \[bu] 2-using the \f[C]--capabilities-header=HTTPHEADER\f[R] flag to specify a+using the \f[V]--capabilities-header=HTTPHEADER\f[R] flag to specify a HTTP header from which it will read capabilities to enable. hledger-web on Sandstorm uses the X-Sandstorm-Permissions header to integrate with Sandstorm\[aq]s permissions. This is disabled by default. .SH EDITING, UPLOADING, DOWNLOADING .PP-If you enable the \f[C]manage\f[R] capability mentioned above,+If you enable the \f[V]manage\f[R] capability mentioned above, you\[aq]ll see a new \[dq]spanner\[dq] button to the right of the search form. Clicking this will let you edit, upload, or download the journal file or@@ -356,9 +362,10 @@ .PP Normally whenever a file is changed in this way, hledger-web saves a numbered backup (assuming file permissions allow it, the disk is not-full, etc.) hledger-web is not aware of version control systems,-currently; if you use one, you\[aq]ll have to arrange to commit the-changes yourself (eg with a cron job or a file watcher like entr).+full, etc.)+hledger-web is not aware of version control systems, currently; if you+use one, you\[aq]ll have to arrange to commit the changes yourself (eg+with a cron job or a file watcher like entr). .PP Changes which would leave the journal file(s) unparseable or non-valid (eg with failing balance assertions) are prevented.@@ -378,7 +385,7 @@ .PP In addition to the web UI, hledger-web also serves a JSON API that can be used to get data or add new transactions.-If you want the JSON API only, you can use the \f[C]--serve-api\f[R]+If you want the JSON API only, you can use the \f[V]--serve-api\f[R] flag. Eg: .IP@@ -456,25 +463,25 @@ Most of the JSON corresponds to hledger\[aq]s data types; for details of what the fields mean, see the Hledger.Data.Json haddock docs and click on the various data types, eg Transaction.-And for a higher level understanding, see the journal manual.+And for a higher level understanding, see the journal docs. .PP In some cases there is outer JSON corresponding to a \[dq]Report\[dq] type. To understand that, go to the Hledger.Web.Handler.MiscR haddock and look at the source for the appropriate handler to see what it returns.-Eg for \f[C]/accounttransactions\f[R] it\[aq]s getAccounttransactionsR,-returning a \[dq]\f[C]accountTransactionsReport ...\f[R]\[dq].+Eg for \f[V]/accounttransactions\f[R] it\[aq]s getAccounttransactionsR,+returning a \[dq]\f[V]accountTransactionsReport ...\f[R]\[dq]. Looking up the haddock for that we can see that /accounttransactions returns an AccountTransactionsReport, which consists of a report title and a list of AccountTransactionsReportItem (etc). .PP You can add a new transaction to the journal with a PUT request to-\f[C]/add\f[R], if hledger-web was started with the \f[C]add\f[R]+\f[V]/add\f[R], if hledger-web was started with the \f[V]add\f[R] capability (enabled by default). The payload must be the full, exact JSON representation of a hledger transaction (partial data won\[aq]t do).-You can get sample JSON from hledger-web\[aq]s \f[C]/transactions\f[R]-or \f[C]/accounttransactions\f[R], or you can export it with+You can get sample JSON from hledger-web\[aq]s \f[V]/transactions\f[R]+or \f[V]/accounttransactions\f[R], or you can export it with hledger-lib, eg like so: .IP .nf@@ -589,7 +596,7 @@ .SH DEBUG OUTPUT .SS Debug output .PP-You can add \f[C]--debug[=N]\f[R] to the command line to log debug+You can add \f[V]--debug[=N]\f[R] to the command line to log debug output. N ranges from 1 (least output, the default) to 9 (maximum output). Typically you would start with 1 and increase until you are seeing@@ -601,23 +608,23 @@ .PD 0 .P .PD-\f[C]hledger-web --debug=3 2>hledger-web.log\f[R].+\f[V]hledger-web --debug=3 2>hledger-web.log\f[R]. .SH ENVIRONMENT .PP \f[B]LEDGER_FILE\f[R] The journal file path when not specified with-\f[C]-f\f[R].+\f[V]-f\f[R]. .PP On unix computers, the default value is:-\f[C]\[ti]/.hledger.journal\f[R].+\f[V]\[ti]/.hledger.journal\f[R]. .PP A more typical value is something like-\f[C]\[ti]/finance/YYYY.journal\f[R], where \f[C]\[ti]/finance\f[R] is a+\f[V]\[ti]/finance/YYYY.journal\f[R], where \f[V]\[ti]/finance\f[R] is a version-controlled finance directory and YYYY is the current year.-Or, \f[C]\[ti]/finance/current.journal\f[R], where current.journal is a+Or, \f[V]\[ti]/finance/current.journal\f[R], where current.journal is a symbolic link to YYYY.journal. .PP The usual way to set this permanently is to add a command to one of your-shell\[aq]s startup files (eg \f[C]\[ti]/.profile\f[R]):+shell\[aq]s startup files (eg \f[V]\[ti]/.profile\f[R]): .IP .nf \f[C]@@ -628,7 +635,7 @@ On some Mac computers, there is a more thorough way to set environment variables, that will also affect applications started from the GUI (eg, Emacs started from a dock icon): In-\f[C]\[ti]/.MacOSX/environment.plist\f[R], add an entry like:+\f[V]\[ti]/.MacOSX/environment.plist\f[R], add an entry like: .IP .nf \f[C]@@ -638,11 +645,11 @@ \f[R] .fi .PP-For this to take effect you might need to \f[C]killall Dock\f[R], or+For this to take effect you might need to \f[V]killall Dock\f[R], or reboot. .PP On Windows computers, the default value is probably-\f[C]C:\[rs]Users\[rs]YOURNAME\[rs].hledger.journal\f[R].+\f[V]C:\[rs]Users\[rs]YOURNAME\[rs].hledger.journal\f[R]. You can change this by running a command like this in a powershell window (let us know if you need to be an Administrator, and if this persists across a reboot):@@ -657,16 +664,14 @@ https://www.java.com/en/download/help/path.html. .SH FILES .PP-Reads data from one or more files in hledger journal, timeclock,-timedot, or CSV format specified with \f[C]-f\f[R], or-\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,-perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).+Reads data from one or more files in journal, timeclock, timedot, or CSV+format.+The default file is \f[V].hledger.journal\f[R] in your home directory;+this can be overridden with one or more \f[V]-f FILE\f[R] options, or+the \f[V]LEDGER_FILE\f[R] environment variable. .SH BUGS .PP-The need to precede options with \f[C]--\f[R] when invoked from hledger-is awkward.-.PP-\f[C]-f-\f[R] doesn\[aq]t work (hledger-web can\[aq]t read from stdin).+\f[V]-f-\f[R] doesn\[aq]t work (hledger-web can\[aq]t read from stdin). .PP Query arguments and some hledger options are ignored. .PP@@ -677,15 +682,17 @@  .SH "REPORTING BUGS" Report bugs at http://bugs.hledger.org-(or on the #hledger IRC channel or hledger mail list)+(or on the #hledger chat or hledger mail list)  .SH AUTHORS-Simon Michael <simon@joyful.com> and contributors+Simon Michael <simon@joyful.com> and contributors.+.br+See http://hledger.org/CREDITS.html  .SH COPYRIGHT+Copyright 2007-2023 Simon Michael and contributors. -Copyright (C) 2007-2020 Simon Michael.-.br+.SH LICENSE Released under GNU GPL v3 or later.  .SH SEE ALSO