hledger 1.15.2 → 1.16
raw patch · 60 files changed
+4852/−2846 lines, 60 filesdep +tastydep −easytestdep −test-frameworkdep −test-framework-hunitdep ~basedep ~base-compat-batteriesdep ~hledger-libPVP ok
version bump matches the API change (PVP)
Dependencies added: tasty
Dependencies removed: easytest, test-framework, test-framework-hunit
Dependency ranges changed: base, base-compat-batteries, hledger-lib
API changes (from Hackage documentation)
- Hledger.Cli: tests_Cli :: Test ()
- Hledger.Cli.CliOptions: decodeRawOpts :: RawOpts -> RawOpts
- Hledger.Cli.Commands: tests_Commands :: Test ()
+ Hledger.Cli.Anon: anon :: Anon a => a -> a
+ Hledger.Cli.Anon: anonAccount :: AccountName -> AccountName
+ Hledger.Cli.Anon: class Anon a
+ Hledger.Cli.Anon: instance Hledger.Cli.Anon.Anon Data.Text.Internal.Text
+ Hledger.Cli.Anon: instance Hledger.Cli.Anon.Anon Hledger.Data.Types.Journal
+ Hledger.Cli.Anon: instance Hledger.Cli.Anon.Anon Hledger.Data.Types.Posting
+ Hledger.Cli.Anon: instance Hledger.Cli.Anon.Anon Hledger.Data.Types.Transaction
+ Hledger.Cli.Commands: tests_Hledger_Cli :: TestTree
- Hledger.Cli.Commands.Balance: tests_Balance :: Test ()
+ Hledger.Cli.Commands.Balance: tests_Balance :: TestTree
- Hledger.Cli.Commands.Register: tests_Register :: Test ()
+ Hledger.Cli.Commands.Register: tests_Register :: TestTree
- Hledger.Cli.Utils: tests_Cli_Utils :: Test ()
+ Hledger.Cli.Utils: tests_Cli_Utils :: TestTree
Files
- CHANGES.md +124/−2
- Hledger/Cli.hs +1/−6
- Hledger/Cli/Anon.hs +53/−0
- Hledger/Cli/CliOptions.hs +6/−12
- Hledger/Cli/Commands.hs +66/−60
- Hledger/Cli/Commands/Add.hs +4/−6
- Hledger/Cli/Commands/Balance.hs +7/−5
- Hledger/Cli/Commands/Balance.txt +28/−0
- Hledger/Cli/Commands/Balancesheet.txt +1/−1
- Hledger/Cli/Commands/Cashflow.txt +2/−1
- Hledger/Cli/Commands/Checkdates.hs +5/−4
- Hledger/Cli/Commands/Close.hs +16/−16
- Hledger/Cli/Commands/Help.txt +1/−1
- Hledger/Cli/Commands/Import.hs +16/−5
- Hledger/Cli/Commands/Import.txt +2/−1
- Hledger/Cli/Commands/Incomestatement.txt +2/−1
- Hledger/Cli/Commands/Prices.hs +16/−7
- Hledger/Cli/Commands/Prices.txt +2/−1
- Hledger/Cli/Commands/Print.hs +2/−2
- Hledger/Cli/Commands/Register.hs +4/−2
- Hledger/Cli/Commands/Rewrite.hs +2/−2
- Hledger/Cli/Commands/Roi.hs +12/−8
- Hledger/Cli/Commands/Stats.hs +1/−1
- Hledger/Cli/Commands/Tags.hs +1/−1
- Hledger/Cli/Commands/Test.txt +14/−13
- Hledger/Cli/CompoundBalanceCommand.hs +13/−13
- Hledger/Cli/DocFiles.hs +0/−5
- Hledger/Cli/Main.hs +5/−7
- Hledger/Cli/Utils.hs +9/−28
- README.md +1/−2
- embeddedfiles/hledger-api.1 +0/−129
- embeddedfiles/hledger-api.info +0/−87
- embeddedfiles/hledger-api.txt +0/−120
- embeddedfiles/hledger-ui.1 +35/−7
- embeddedfiles/hledger-ui.info +41/−17
- embeddedfiles/hledger-ui.txt +89/−66
- embeddedfiles/hledger-web.1 +4/−5
- embeddedfiles/hledger-web.info +3/−4
- embeddedfiles/hledger-web.txt +20/−21
- embeddedfiles/hledger.1 +72/−25
- embeddedfiles/hledger.info +256/−227
- embeddedfiles/hledger.txt +179/−150
- embeddedfiles/hledger_csv.5 +976/−361
- embeddedfiles/hledger_csv.info +939/−379
- embeddedfiles/hledger_csv.txt +641/−157
- embeddedfiles/hledger_journal.5 +185/−122
- embeddedfiles/hledger_journal.info +292/−207
- embeddedfiles/hledger_journal.txt +142/−90
- embeddedfiles/hledger_timeclock.5 +2/−2
- embeddedfiles/hledger_timeclock.info +2/−2
- embeddedfiles/hledger_timeclock.txt +2/−2
- embeddedfiles/hledger_timedot.5 +2/−2
- embeddedfiles/hledger_timedot.info +4/−4
- embeddedfiles/hledger_timedot.txt +2/−2
- hledger.1 +72/−25
- hledger.cabal +28/−35
- hledger.info +256/−227
- hledger.txt +179/−150
- test/test.hs +0/−8
- test/unittest.hs +13/−0
CHANGES.md view
@@ -1,6 +1,128 @@ User-visible changes in the hledger command line tool and library. +# 1.16 2019-12-01++## General++- add support for GHC 8.8, base-compat 0.11 (#1090)++- drop support for GHC 7.10++- The benchmark suite has been disabled.++- The --anon flag now also anonymises transaction codes and account+ names declared with account directives. (Mykola Orliuk) (#901)++## commands++- balance/bs/cf/is: balance commands now support the -%/--percent flag+ to show amounts as percentages of the column's total. (Michael Kainer)++ If there are multiple commodities involved in a report hledger bails+ with an error message. This can be avoided by using -B/--cost. Also note+ that if one uses -% with the balance command the chances are high that+ all numbers are 0. This is due to the fact that by default balance sums+ up to zero. If one wants to use -% in a meaningful way with balance one+ has to add a query.++ In order to keep the implementation as simple as possible --tree has no+ influence over how the percentages are calculated, i.e., the percentages+ always represent the fraction of the columns total. If one wants to know+ the percentages relative to a parent account, one has to use a query to+ narrow down the accounts.++- balance: --budget no longer errors when there is neither budget nor+ transactions in the report period (Dmitry Astapov)++- balance: --budget has improved debug output (shows budget txns)+ (Dmitry Astapov)++- check-dates: now sets the exit status code (Amitai Burstein)++- close: no longer strips zeroes after the decimal mark, and preserves+ parseable output (#1137)++- close: the --close-to, --open-from options allow closing/opening+ account names to be chosen++- import: create the journal if missing, like the add command+ Streamlines import/migration instructions.++- import: --catchup marks all transactions imported, without importing++- import: more informative output: mention the input files, also show+ a message when nothing was imported++- prices: show price amounts with proper display style; always show+ full precision++- roi: don't give an error with empty input data (Dmitry Astapov)++- tests: unit tests are now run by tasty (#1090).+ Test running options have changed, see the command help. + Some unit tests have been collapsed, so the reported test count has+ dropped a little.++## journal format++- journal: fix generation of periodic transactions with+ days/months/... repeat (Dmitry Astapov)++## csv format++- CSV reading improvements (#1095)++ - can now generate a variable number of postings, from zero to nine (#627, #1095)+ - can now generate postings with balance assignments (#1000)+ - skip can be used in conditional blocks; so can the new "end" rule (skips all remaining) (#1076)+ - both the amount-in/amount-out fields having a value is now ok, if one of them is zero (#570)+ - line feeds/carriage returns in quoted CSV values are now converted to spaces (#416, #841)+ - field assignments can now unset a field (eg a posting can be+ suppressed by assigning no value to its account)+ - fixed: empty field assignment consumes next line (#1001)+ - fixed: interpolation of field names containing punctuation (underscore, hyphens etc)+ - fixed: show two spaces between description and comment, not three+ - clarified that hledger field assignments can reference csv fields only, not other hledger fields (#500)+ - new docs, tests++ Migration notes:++ - When `print`ing from CSV, there is now one less space between+ transaction descriptions and comments. If you are comparing old+ and new reports, diff -w (--ignore-all-space) will ignore this+ change.++ - CSV rules now give you more freedom to generate any journal+ entries you want, including malformed or unbalanced ones. + The csv reader now checks the journal after conversion,+ so it will report any problems with the generated entries.++ - Balance assertions generated from CSV are not checked, currently.+ This is appropriate when you are downloading partial CSV data to+ be merged into your main journal. If you do need to check balance+ assertions right away, you can pipe through hledger again:++ $ hledger -f a.csv print | hledger -f- print++- csv: finalise and check journals generated from CSV (#1000)+ Invalid transactions generated from CSV will now be rejected.+ I updated some csv tests to avoid this, except for 21, which+ probably needs more cleanup.++- csv: allow csv records with varying lengths, padding with empties+ Sometimes trailing empty fields are omitted entirely (including the+ commas) in CSV records. (I see this in exported Google spreadsheets.)+ Now we don't raise an error in this case, instead we automatically pad+ any "short" records with empty fields. Not yet well tested.++- csv: fix parsing of whitespace on line after an if block (fix #1120)++- csv: csv reader gets balance-type directive (Dmitry Astapov)++- csv: support generation of (un)balanced virtual postings in csv reader (Dmitry Astapov)++ # 1.15.2 2019-09-05 - -V and -X now respect a report end date (set with -e or -p or date:)@@ -399,7 +521,7 @@ It seems the simple and really only way to do this reliably is to require an explicit decimal point character. Most folks probably do this already.- Unfortunately, it makes another potential incompatiblity with ledger and+ Unfortunately, it makes another potential incompatibility with ledger and beancount journals. But the error message will be clear and easy to work around. @@ -1243,7 +1365,7 @@ On non-windows systems, we now build with terminfo support by default, useful for detecting terminal width and other things. - This requires the C curses dev libaries, which makes POSIX+ This requires the C curses dev libraries, which makes POSIX installation slightly harder; if it causes problems you can disable terminfo support with the new `curses` cabal flag, eg: cabal install -f-curses ... (or cabal might try this
Hledger/Cli.hs view
@@ -16,7 +16,6 @@ module Hledger.Cli.Utils, module Hledger.Cli.Version, module Hledger,- tests_Cli, module System.Console.CmdArgs.Explicit ) where@@ -29,8 +28,4 @@ import Hledger.Cli.Utils import Hledger.Cli.Version --- unit tests for code under Hledger.Cli (hledger-lib tests not included)-tests_Cli = tests "Hledger.Cli" [- tests_Cli_Utils- ,tests_Commands- ]+-- unit tests (tests_Hledger_Cli) are defined in Hledger.Cli.Commands
+ Hledger/Cli/Anon.hs view
@@ -0,0 +1,53 @@+{-|++Instances for anonymizing sensitive data in various types.++Note that there is no clear way to anonymize numbers.++-}++module Hledger.Cli.Anon+ ( Anon(..)+ , anonAccount+ )+where++import Control.Arrow (first)+import Data.Hashable (hash)+import Data.Word (Word32)+import Numeric (showHex)+import qualified Data.Text as T++import Hledger.Data++class Anon a where+ -- | Consistent converter to structure with sensitive data anonymized+ anon :: a -> a++instance Anon Journal where+ -- Apply the anonymisation transformation on a journal after finalisation+ anon j = j { jtxns = map anon . jtxns $ j+ , jparseparentaccounts = map anonAccount $ jparseparentaccounts j+ , jparsealiases = [] -- already applied+ , jdeclaredaccounts = map (first anon) $ jdeclaredaccounts j+ }++instance Anon Posting where+ anon p = p { paccount = anonAccount . paccount $ p+ , pcomment = T.empty+ , ptransaction = fmap anon . ptransaction $ p -- Note that this will be overriden+ , poriginal = anon <$> poriginal p+ }++instance Anon Transaction where+ anon txn = txnTieKnot $ txn { tpostings = map anon . tpostings $ txn+ , tdescription = anon . tdescription $ txn+ , tcode = anon . tcode $ txn+ , tcomment = T.empty+ }++-- | Anonymize account name preserving hierarchy+anonAccount :: AccountName -> AccountName+anonAccount = T.intercalate (T.pack ":") . map anon . T.splitOn (T.pack ":")++instance Anon T.Text where anon = T.pack . flip showHex "" . (fromIntegral :: Int -> Word32) . hash
Hledger/Cli/CliOptions.hs view
@@ -35,7 +35,6 @@ CliOpts(..), defcliopts, getHledgerCliOpts,- decodeRawOpts, rawOptsToCliOpts, checkCliOpts, outputFormats,@@ -224,7 +223,7 @@ ,groupHidden = [] -- flags not displayed in the usage } ,modeArgs = ([], Nothing) -- description of arguments accepted by the command- ,modeValue = [] -- value returned when this mode is used to parse a command line+ ,modeValue = def -- value returned when this mode is used to parse a command line ,modeCheck = Right -- whether the mode's value is correct ,modeReform = const Nothing -- function to convert the value back to a command line arguments ,modeExpandAt = True -- expand @ arguments for program ?@@ -246,7 +245,7 @@ ,groupHidden = [] -- flags not displayed in the usage } ,modeArgs = ([], Just $ argsFlag "[QUERY]")- ,modeValue=[("command", headDef "" names)]+ ,modeValue=setopt "command" (headDef "" names) def } -- | A cmdargs mode representing the hledger add-on command with the@@ -329,13 +328,12 @@ (helpText [] HelpFormatDefault :: Mode a -> [Text]) -- | Get the most appropriate documentation topic for a mode.--- Currently, that is either the hledger, hledger-ui, hledger-web or--- hledger-api manual.+-- Currently, that is either the hledger, hledger-ui or hledger-web+-- manual. topicForMode :: Mode a -> Topic topicForMode m | n == "hledger-ui" = "ui" | n == "hledger-web" = "web"- -- | n == "hledger-api" = lookupDocTxt "api" -- hledger-api uses docopt | otherwise = "cli" where n = headDef "" $ modeNames m @@ -395,10 +393,6 @@ def defaultWidth --- | Convert possibly encoded option values to regular unicode strings.-decodeRawOpts :: RawOpts -> RawOpts-decodeRawOpts = map (\(name',val) -> (name', fromSystemString val))- -- | Default width for hledger console output, when not otherwise specified. defaultWidth :: Int defaultWidth = 80@@ -431,7 +425,7 @@ return defcliopts { rawopts_ = rawopts ,command_ = stringopt "command" rawopts- ,file_ = map (T.unpack . stripquotes . T.pack) $ listofstringopt "file" rawopts+ ,file_ = listofstringopt "file" rawopts ,inputopts_ = iopts ,reportopts_ = ropts ,output_file_ = maybestringopt "output-file" rawopts@@ -478,7 +472,7 @@ getHledgerCliOpts :: Mode RawOpts -> IO CliOpts getHledgerCliOpts mode' = do args' <- getArgs >>= expandArgsAt- let rawopts = either usageError decodeRawOpts $ process mode' args'+ let rawopts = either usageError id $ process mode' args' opts <- rawOptsToCliOpts rawopts debugArgs args' opts when ("help" `inRawOpts` rawopts_ opts) $ putStr shorthelp >> exitSuccess
Hledger/Cli/Commands.hs view
@@ -16,7 +16,7 @@ ,builtinCommands ,builtinCommandNames ,printCommandsList- ,tests_Commands+ ,tests_Hledger_Cli ,module Hledger.Cli.Commands.Accounts ,module Hledger.Cli.Commands.Activity ,module Hledger.Cli.Commands.Add@@ -55,9 +55,9 @@ import Data.Text (Text) import qualified Data.Text as T import Data.Time.Calendar-import qualified EasyTest+import System.Environment (withArgs) import System.Console.CmdArgs.Explicit as C-import System.Exit+import Test.Tasty (defaultMain) import Hledger import Hledger.Cli.CliOptions@@ -259,92 +259,98 @@ [] [generalflagsgroup3] []- ([], Just $ argsFlag "[TESTPATTERN] [SEED]")+ ([], Just $ argsFlag "[-- TASTYOPTS]") --- | The test command.+-- | The test command, which runs the hledger and hledger-lib+-- packages' unit tests. This command also accepts tasty test runner+-- options, written after a -- (double hyphen).+-- -- Unlike most hledger commands, this one does not read the user's journal. -- A 'Journal' argument remains in the type signature, but it should -- not be used (and would raise an error).+-- testcmd :: CliOpts -> Journal -> IO () testcmd opts _undefined = do - let args = words' $ query_ $ reportopts_ opts- -- workaround for https://github.com/joelburget/easytest/issues/11 --- import System.IO (hSetEncoding, stdout, stderr, utf8)--- hSetEncoding stdout utf8--- hSetEncoding stderr utf8- e <- runEasytests args $ EasyTest.tests [- tests_Hledger- ,tests "Hledger.Cli" [- tests_Cli_Utils- ,tests_Commands+ withArgs (words' $ query_ $ reportopts_ opts) $+ Test.Tasty.defaultMain $ tests "hledger" [+ tests_Hledger+ ,tests_Hledger_Cli ]- ]- if e then exitFailure else exitSuccess +-- All unit tests for Hledger.Cli, defined here rather than+-- Hledger.Cli so testcmd can use them.+tests_Hledger_Cli = tests "Hledger.Cli" [+ tests_Cli_Utils+ ,tests_Commands+ ] tests_Commands = tests "Commands" [ tests_Balance ,tests_Register -- some more tests easiest to define here:- - ,test "apply account directive" $ do - let ignoresourcepos j = j{jtxns=map (\t -> t{tsourcepos=nullsourcepos}) (jtxns j)}- let sameParse str1 str2 = do j1 <- io $ readJournal def Nothing str1 >>= either error' (return . ignoresourcepos)- j2 <- io $ readJournal def Nothing str2 >>= either error' (return . ignoresourcepos)- j1 `is` j2{jlastreadtime=jlastreadtime j1, jfiles=jfiles j1} --, jparsestate=jparsestate j1}- sameParse- ("2008/12/07 One\n alpha $-1\n beta $1\n" <>- "apply account outer\n2008/12/07 Two\n aigh $-2\n bee $2\n" <>- "apply account inner\n2008/12/07 Three\n gamma $-3\n delta $3\n" <>- "end apply account\n2008/12/07 Four\n why $-4\n zed $4\n" <>- "end apply account\n2008/12/07 Five\n foo $-5\n bar $5\n"- )- ("2008/12/07 One\n alpha $-1\n beta $1\n" <>- "2008/12/07 Two\n outer:aigh $-2\n outer:bee $2\n" <>- "2008/12/07 Three\n outer:inner:gamma $-3\n outer:inner:delta $3\n" <>- "2008/12/07 Four\n outer:why $-4\n outer:zed $4\n" <>- "2008/12/07 Five\n foo $-5\n bar $5\n"- ) - ,test "apply account directive should preserve \"virtual\" posting type" $ do- j <- io $ readJournal def Nothing "apply account test\n2008/12/07 One\n (from) $-1\n (to) $1\n" >>= either error' return- let p = head $ tpostings $ head $ jtxns j- paccount p `is` "test:from"- ptype p `is` VirtualPosting- - ,test "account aliases" $ do- j <- io $ readJournal def Nothing "!alias expenses = equity:draw:personal\n1/1\n (expenses:food) 1\n" >>= either error' return+ ,tests "apply account directive" [+ test "works" $ do+ let+ ignoresourcepos j = j{jtxns=map (\t -> t{tsourcepos=nullsourcepos}) (jtxns j)}+ sameParse str1 str2 = do+ j1 <- readJournal def Nothing str1 >>= either error' (return . ignoresourcepos)+ j2 <- readJournal def Nothing str2 >>= either error' (return . ignoresourcepos)+ j1 @?= j2{jlastreadtime=jlastreadtime j1, jfiles=jfiles j1} --, jparsestate=jparsestate j1}+ sameParse+ ("2008/12/07 One\n alpha $-1\n beta $1\n" <>+ "apply account outer\n2008/12/07 Two\n aigh $-2\n bee $2\n" <>+ "apply account inner\n2008/12/07 Three\n gamma $-3\n delta $3\n" <>+ "end apply account\n2008/12/07 Four\n why $-4\n zed $4\n" <>+ "end apply account\n2008/12/07 Five\n foo $-5\n bar $5\n"+ )+ ("2008/12/07 One\n alpha $-1\n beta $1\n" <>+ "2008/12/07 Two\n outer:aigh $-2\n outer:bee $2\n" <>+ "2008/12/07 Three\n outer:inner:gamma $-3\n outer:inner:delta $3\n" <>+ "2008/12/07 Four\n outer:why $-4\n outer:zed $4\n" <>+ "2008/12/07 Five\n foo $-5\n bar $5\n"+ )++ ,test "preserves \"virtual\" posting type" $ do+ j <- readJournal def Nothing "apply account test\n2008/12/07 One\n (from) $-1\n (to) $1\n" >>= either error' return+ let p = head $ tpostings $ head $ jtxns j+ paccount p @?= "test:from"+ ptype p @?= VirtualPosting+ ]++ ,test "alias directive" $ do+ j <- readJournal def Nothing "!alias expenses = equity:draw:personal\n1/1\n (expenses:food) 1\n" >>= either error' return let p = head $ tpostings $ head $ jtxns j- paccount p `is` "equity:draw:personal:food"+ paccount p @?= "equity:draw:personal:food" + ,test "Y default year directive" $ do+ j <- readJournal def Nothing defaultyear_journal_txt >>= either error' return+ tdate (head $ jtxns j) @?= fromGregorian 2009 1 1+ ,test "ledgerAccountNames" $- ledgerAccountNames ledger7 `is`- ["assets","assets:cash","assets:checking","assets:saving","equity","equity:opening balances",- "expenses","expenses:food","expenses:food:dining","expenses:phone","expenses:vacation",- "liabilities","liabilities:credit cards","liabilities:credit cards:discover"]+ (ledgerAccountNames ledger7)+ @?=+ ["assets","assets:cash","assets:checking","assets:saving","equity","equity:opening balances",+ "expenses","expenses:food","expenses:food:dining","expenses:phone","expenses:vacation",+ "liabilities","liabilities:credit cards","liabilities:credit cards:discover"] -- ,test "journalCanonicaliseAmounts" ~: -- "use the greatest precision" ~:- -- (map asprecision $ journalAmountAndPriceCommodities $ journalCanonicaliseAmounts $ journalWithAmounts ["1","2.00"]) `is` [2,2]+ -- (map asprecision $ journalAmountAndPriceCommodities $ journalCanonicaliseAmounts $ journalWithAmounts ["1","2.00"]) @?= [2,2] -- don't know what this should do -- ,test "elideAccountName" ~: do -- (elideAccountName 50 "aaaaaaaaaaaaaaaaaaaa:aaaaaaaaaaaaaaaaaaaa:aaaaaaaaaaaaaaaaaaaa"- -- `is` "aa:aaaaaaaaaaaaaaaaaaaa:aaaaaaaaaaaaaaaaaaaa")+ -- @?= "aa:aaaaaaaaaaaaaaaaaaaa:aaaaaaaaaaaaaaaaaaaa") -- (elideAccountName 20 "aaaaaaaaaaaaaaaaaaaa:aaaaaaaaaaaaaaaaaaaa:aaaaaaaaaaaaaaaaaaaa"- -- `is` "aa:aa:aaaaaaaaaaaaaa")-- ,test "default year" $ do- j <- io $ readJournal def Nothing defaultyear_journal_txt >>= either error' return- tdate (head $ jtxns j) `is` fromGregorian 2009 1 1-- ,test "show dollars" $ showAmount (usd 1) `is` "$1.00"+ -- @?= "aa:aa:aaaaaaaaaaaaaa") - ,test "show hours" $ showAmount (hrs 1) `is` "1.00h"+ ,test "show dollars" $ showAmount (usd 1) @?= "$1.00" - ]+ ,test "show hours" $ showAmount (hrs 1) @?= "1.00h" + ] -- test data
Hledger/Cli/Commands/Add.hs view
@@ -15,10 +15,8 @@ ) where -import Prelude ()-import "base-compat-batteries" Prelude.Compat import Control.Exception as E-import Control.Monad+import Control.Monad (when) import Control.Monad.Trans.Class import Control.Monad.State.Strict (evalState, evalStateT) import Control.Monad.Trans (liftIO)@@ -92,7 +90,7 @@ showHelp today <- getCurrentDay let es = defEntryState{esOpts=opts- ,esArgs=map (T.unpack . stripquotes . T.pack) $ listofstringopt "args" $ rawopts_ opts+ ,esArgs=listofstringopt "args" $ rawopts_ opts ,esToday=today ,esDefDate=today ,esJournal=j@@ -118,7 +116,7 @@ getAndAddTransactions es@EntryState{..} = (do mt <- runInputT (setComplete noCompletion defaultSettings) (System.Console.Wizard.run $ haskeline $ confirmedTransactionWizard es) case mt of- Nothing -> fail "urk ?"+ Nothing -> error "Could not interpret the input, restarting" -- caught below causing a restart, I believe Just t -> do j <- if debug_ esOpts > 0 then do hPrintf stderr "Skipping journal add due to debug mode.\n"@@ -371,7 +369,7 @@ journalAddTransaction :: Journal -> CliOpts -> Transaction -> IO Journal journalAddTransaction j@Journal{jtxns=ts} opts t = do let f = journalFilePath j- appendToJournalFileOrStdout f $ showTransactionUnelided t+ appendToJournalFileOrStdout f $ showTransaction t -- unelided shows all amounts explicitly, in case there's a price, cf #283 when (debug_ opts > 0) $ do putStrLn $ printf "\nAdded transaction to %s:" f
Hledger/Cli/Commands/Balance.hs view
@@ -226,7 +226,7 @@ /What to show in empty cells/ An empty periodic balance report cell is one which has no corresponding postings.-An empty cumulative/historical balance report cell is one which has no correponding+An empty cumulative/historical balance report cell is one which has no corresponding or prior postings, ie the account doesn't exist yet. Currently, empty cells show 0. @@ -292,6 +292,7 @@ ,flagNone ["budget"] (setboolopt "budget") "show performance compared to budget goals defined by periodic transactions" ,flagNone ["invert"] (setboolopt "invert") "display all amounts with reversed sign" ,flagNone ["transpose"] (setboolopt "transpose") "transpose rows and columns"+ ,flagNone ["percent", "%"] (setboolopt "percent") "express values in percentage of each column's total" ] ++ outputflags )@@ -640,15 +641,16 @@ tests "balanceReportAsText" [ test "unicode in balance layout" $ do- j <- io $ readJournal' "2009/01/01 * медвежья шкура\n расходы:покупки 100\n актив:наличные\n"+ j <- readJournal' "2009/01/01 * медвежья шкура\n расходы:покупки 100\n актив:наличные\n" let opts = defreportopts- balanceReportAsText opts (balanceReport opts (queryFromOpts (parsedate "2008/11/26") opts) j) `is`+ balanceReportAsText opts (balanceReport opts (queryFromOpts (parsedate "2008/11/26") opts) j)+ @?= unlines [" -100 актив:наличные" ," 100 расходы:покупки" ,"--------------------" ," 0" ]- ]+ ] - ]+ ]
Hledger/Cli/Commands/Balance.txt view
@@ -160,6 +160,34 @@ Flat-mode balance reports, which normally show exclusive balances, show inclusive balances at the depth limit. +Percentages++With -% or --percent, balance reports show each account's value+expressed as a percentage of the column's total. This is useful to get+an overview of the relative sizes of account balances. For example to+obtain an overview of expenses:++$ hledger balance expenses -%+ 100.0 % expenses+ 50.0 % food+ 50.0 % supplies+--------------------+ 100.0 %++Note that --tree does not have an effect on -%. The percentages are+always relative to the total sum of each column, they are never relative+to the parent account.++Since the percentages are relative to the columns sum, it is usually not+useful to calculate percentages if the signs of the amounts are mixed.+Although the results are technically correct, they are most likely+useless. Especially in a balance report that sums up to zero (eg+hledger balance -B) all percentage values will be zero.++This flag does not work if the report contains any mixed commodity+accounts. If there are mixed commodity accounts in the report be sure to+use -V or -B to coerce the report into using a single commodity.+ Multicolumn balance report Multicolumn or tabular balance reports are a very useful hledger
Hledger/Cli/Commands/Balancesheet.txt view
@@ -37,7 +37,7 @@ balancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates (and -T/--row-total, since summing end balances generally does not make-sense).+sense). Instead of absolute values percentages can be displayed with -%. This command also supports output destination and output format selection.
Hledger/Cli/Commands/Cashflow.txt view
@@ -27,7 +27,8 @@ With a reporting interval, multiple columns will be shown, one for each report period. Normally cashflow shows changes in assets per period, though as with multicolumn balance reports you can alter the report mode-with --change/--cumulative/--historical.+with --change/--cumulative/--historical. Instead of absolute values+percentages can be displayed with -%. This command also supports output destination and output format selection.
Hledger/Cli/Commands/Checkdates.hs view
@@ -9,6 +9,7 @@ import Hledger import Hledger.Cli.CliOptions import System.Console.CmdArgs.Explicit+import System.Exit import Text.Printf checkdatesmode :: Mode RawOpts@@ -33,10 +34,10 @@ then date a < date b else date a <= date b case checkTransactions compare ts of- FoldAcc{fa_previous=Nothing} -> putStrLn "ok (empty journal)"- FoldAcc{fa_error=Nothing} -> putStrLn "ok"+ FoldAcc{fa_previous=Nothing} -> putStrLn "ok (empty journal)" >> exitSuccess+ FoldAcc{fa_error=Nothing} -> putStrLn "ok" >> exitSuccess FoldAcc{fa_error=Just error, fa_previous=Just previous} ->- putStrLn $ printf ("ERROR: transaction out of%s date order"+ (putStrLn $ printf ("ERROR: transaction out of%s date order" ++ "\nPrevious date: %s" ++ "\nDate: %s" ++ "\nLocation: %s"@@ -45,7 +46,7 @@ (show $ date previous) (show $ date error) (show $ tsourcepos error)- (showTransactionUnelided error)+ (showTransaction error)) >> exitFailure data FoldAcc a b = FoldAcc { fa_error :: Maybe a
Hledger/Cli/Commands/Close.hs view
@@ -11,17 +11,22 @@ import Data.Function (on) import Data.List (groupBy) import Data.Maybe+import qualified Data.Text as T (pack) import Data.Time.Calendar import System.Console.CmdArgs.Explicit as C import Hledger import Hledger.Cli.CliOptions +defclosingacct = "equity:closing balances"+defopeningacct = "equity:opening balances"+ closemode = hledgerCommandMode $(embedFileRelative "Hledger/Cli/Commands/Close.txt")- [flagNone ["opening"] (setboolopt "opening") "show just opening transaction"- ,flagNone ["closing"] (setboolopt "closing") "show just closing transaction"- -- ,flagNone ["explicit","x"] (setboolopt "explicit") "show all amounts explicitly"+ [flagNone ["closing"] (setboolopt "closing") "show just closing transaction"+ ,flagNone ["opening"] (setboolopt "opening") "show just opening transaction"+ ,flagReq ["close-to"] (\s opts -> Right $ setopt "close-to" s opts) "ACCT" ("account to transfer closing balances to (default: "++defclosingacct++")")+ ,flagReq ["open-from"] (\s opts -> Right $ setopt "open-from" s opts) "ACCT" ("account to transfer opening balances from (default: "++defopeningacct++")") ] [generalflagsgroup1] hiddenflags@@ -34,6 +39,8 @@ case (boolopt "opening" rawopts, boolopt "closing" rawopts) of (False, False) -> (True, True) -- by default show both opening and closing (o, c) -> (o, c)+ closingacct = T.pack $ fromMaybe defclosingacct $ maybestringopt "close-to" rawopts+ openingacct = T.pack $ fromMaybe defopeningacct $ maybestringopt "open-from" rawopts ropts_ = ropts{balancetype_=HistoricalBalance, accountlistmode_=ALFlat} q = queryFromOpts today ropts_ openingdate = fromMaybe today $ queryEndDate False q@@ -42,9 +49,8 @@ balancingamt = negate $ sum $ map (\(_,_,_,b) -> normaliseMixedAmount b) acctbals -- since balance assertion amounts are required to be exact, the- -- amounts in opening/closing transactions should be too (#941)- -- setprec = setFullPrecision- setprec = setNaturalPrecision+ -- amounts in opening/closing transactions should be too (#941, #1137)+ setprec = setFullPrecision -- balance assertion amounts will be unpriced (#824) -- only the last posting in each commodity will have a balance assertion (#1035) closingps = [posting{paccount = a@@ -62,7 +68,7 @@ -- The balancing posting to equity. Allow this one to have a multicommodity amount, -- and don't try to assert its balance. ++- [posting{paccount = "equity:closing balances"+ [posting{paccount = closingacct ,pamount = negate balancingamt } ]@@ -83,17 +89,11 @@ , (b, mcommoditysum) <- bs' ] ++- [posting{paccount = "equity:opening balances"+ [posting{paccount = openingacct ,pamount = balancingamt } ] - -- With -x, show all amounts explicitly (ie, also in the balancing equity posting(s)).- -- print also does it for -B; I think that isn't needed here.- -- showtxn | boolopt "explicit" rawopts = showTransactionUnelided- -- | otherwise = showTransaction- showtxn = showTransactionUnelided-- when closing $ putStr $ showtxn (nulltransaction{tdate=closingdate, tdescription="closing balances", tpostings=closingps})- when opening $ putStr $ showtxn (nulltransaction{tdate=openingdate, tdescription="opening balances", tpostings=openingps})+ when closing $ putStr $ showTransaction (nulltransaction{tdate=closingdate, tdescription="closing balances", tpostings=closingps})+ when opening $ putStr $ showTransaction (nulltransaction{tdate=openingdate, tdescription="opening balances", tpostings=openingps})
Hledger/Cli/Commands/Help.txt view
@@ -16,7 +16,7 @@ $ hledger help Please choose a manual by typing "hledger help MANUAL" (a substring is ok).-Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot+Manuals: hledger hledger-ui hledger-web journal csv timeclock timedot $ hledger help h --man
Hledger/Cli/Commands/Import.hs view
@@ -18,14 +18,19 @@ importmode = hledgerCommandMode $(embedFileRelative "Hledger/Cli/Commands/Import.txt")- [flagNone ["dry-run"] (setboolopt "dry-run") "just show the transactions to be imported"]+ [flagNone ["catchup"] (setboolopt "catchup") "just mark all transactions as already imported"+ ,flagNone ["dry-run"] (setboolopt "dry-run") "just show the transactions to be imported"+ ] [generalflagsgroup1] hiddenflags ([], Just $ argsFlag "FILE [...]") importcmd opts@CliOpts{rawopts_=rawopts,inputopts_=iopts} j = do+ -- XXX could be helpful to show the last-seen date, and number of old transactions, too let inputfiles = listofstringopt "args" rawopts+ inputstr = intercalate ", " $ map quoteIfNeeded inputfiles+ catchup = boolopt "catchup" rawopts dryrun = boolopt "dry-run" rawopts iopts' = iopts{new_=True, new_save_=not dryrun} case inputfiles of@@ -36,12 +41,18 @@ Left e -> error' e Right newj -> case sortOn tdate $ jtxns newj of- [] -> return ()+ -- with --dry-run the output should be valid journal format, so messages have ; prepended+ [] -> do+ -- in this case, we vary the output depending on --dry-run, which is a bit awkward+ let semicolon = if dryrun then "; " else "" :: String+ printf "%sno new transactions found in %s\n\n" semicolon inputstr newts | dryrun -> do- printf "; would import %d new transactions:\n\n" (length newts)+ printf "; would import %d new transactions from %s:\n\n" (length newts) inputstr -- TODO how to force output here ? -- length (jtxns newj) `seq` print' opts{rawopts_=("explicit",""):rawopts} newj- mapM_ (putStr . showTransactionUnelided) newts+ mapM_ (putStr . showTransaction) newts+ newts | catchup -> do+ printf "marked %s as caught up, skipping %d unimported transactions\n\n" inputstr (length newts) newts -> do foldM_ (`journalAddTransaction` opts) j newts -- gets forced somehow.. (how ?)- printf "imported %d new transactions\n" (length newts)+ printf "imported %d new transactions from %s\n" (length newts) inputstr
Hledger/Cli/Commands/Import.txt view
@@ -1,7 +1,8 @@ import Read new transactions added to each FILE since last run, and add them to the main journal file. Or with --dry-run, just print the transactions-that would be added.+that would be added. Or with --catchup, just mark all of the FILEs'+transactions as imported, without actually importing any. _FLAGS_
Hledger/Cli/Commands/Incomestatement.txt view
@@ -36,7 +36,8 @@ With a reporting interval, multiple columns will be shown, one for each report period. Normally incomestatement shows revenues/expenses per period, though as with multicolumn balance reports you can alter the-report mode with --change/--cumulative/--historical.+report mode with --change/--cumulative/--historical. Instead of absolute+values percentages can be displayed with -%. This command also supports output destination and output format selection.
Hledger/Cli/Commands/Prices.hs view
@@ -6,6 +6,7 @@ ) where +import qualified Data.Map as M import Data.Maybe import Data.List import qualified Data.Text as T@@ -26,11 +27,12 @@ prices opts j = do d <- getCurrentDay let+ styles = journalCommodityStyles j q = queryFromOpts d (reportopts_ opts) ps = filter (matchesPosting q) $ allPostings j mprices = jpricedirectives j- cprices = concatMap postingCosts ps- icprices = concatMap postingCosts . mapAmount invertPrice $ ps+ cprices = map (stylePriceDirectiveExceptPrecision styles) $ concatMap postingsPriceDirectivesFromCosts ps+ icprices = map (stylePriceDirectiveExceptPrecision styles) $ concatMap postingsPriceDirectivesFromCosts $ mapAmount invertPrice ps allprices = mprices ++ ifBoolOpt "costs" cprices ++ ifBoolOpt "inverted-costs" icprices mapM_ (putStrLn . showPriceDirective) $ sortOn pddate $@@ -65,8 +67,12 @@ a { aquantity = aquantity pa * signum (aquantity a), acommodity = acommodity pa, aprice = Just $ TotalPrice pa' } where pa' = pa { aquantity = abs $ aquantity a, acommodity = acommodity a, aprice = Nothing, astyle = astyle a } -amountCost :: Day -> Amount -> Maybe PriceDirective-amountCost d a =+postingsPriceDirectivesFromCosts :: Posting -> [PriceDirective]+postingsPriceDirectivesFromCosts p = mapMaybe (amountPriceDirectiveFromCost date) . amounts $ pamount p where+ date = fromMaybe (tdate . fromJust $ ptransaction p) $ pdate p++amountPriceDirectiveFromCost :: Day -> Amount -> Maybe PriceDirective+amountPriceDirectiveFromCost d a = case aprice a of Nothing -> Nothing Just (UnitPrice pa) -> Just@@ -74,9 +80,12 @@ Just (TotalPrice pa) -> Just PriceDirective { pddate = d, pdcommodity = acommodity a, pdamount = abs (aquantity a) `divideAmount'` pa } -postingCosts :: Posting -> [PriceDirective]-postingCosts p = mapMaybe (amountCost date) . amounts $ pamount p where- date = fromMaybe (tdate . fromJust $ ptransaction p) $ pdate p+-- | Given a map of standard amount display styles, apply the+-- appropriate one, if any, to this price directive's amount.+-- But keep the number of decimal places unchanged.+stylePriceDirectiveExceptPrecision :: M.Map CommoditySymbol AmountStyle -> PriceDirective -> PriceDirective+stylePriceDirectiveExceptPrecision styles pd@PriceDirective{pdamount=a} =+ pd{pdamount = styleAmountExceptPrecision styles a} allPostings :: Journal -> [Posting] allPostings = concatMap tpostings . jtxns
Hledger/Cli/Commands/Prices.txt view
@@ -2,6 +2,7 @@ Print market price directives from the journal. With --costs, also print synthetic market prices based on transaction prices. With --inverted-costs, also print inverse prices based on transaction prices.-Prices (and postings providing prices) can be filtered by a query.+Prices (and postings providing prices) can be filtered by a query. Price+amounts are always displayed with their full precision. _FLAGS_
Hledger/Cli/Commands/Print.hs view
@@ -59,7 +59,7 @@ writeOutput opts $ render $ entriesReport ropts' q j entriesReportAsText :: CliOpts -> EntriesReport -> String-entriesReportAsText opts = concatMap (showTransactionUnelided . gettxn)+entriesReportAsText opts = concatMap (showTransaction . gettxn) where gettxn | useexplicittxn = id -- use fully inferred amounts & txn prices | otherwise = originalTransaction -- use original as-written amounts/txn prices@@ -162,7 +162,7 @@ let q = queryFromOpts d ropts case similarTransaction' j q desc of Nothing -> putStrLn "no matches found."- Just t -> putStr $ showTransactionUnelided t+ Just t -> putStr $ showTransaction t where -- Identify the closest recent match for this description in past transactions.
Hledger/Cli/Commands/Register.hs view
@@ -195,9 +195,11 @@ tests "postingsReportAsText" [ test "unicode in register layout" $ do- j <- io $ readJournal' "2009/01/01 * медвежья шкура\n расходы:покупки 100\n актив:наличные\n"+ j <- readJournal' "2009/01/01 * медвежья шкура\n расходы:покупки 100\n актив:наличные\n" let opts = defreportopts- (postingsReportAsText defcliopts $ postingsReport opts (queryFromOpts (parsedate "2008/11/26") opts) j) `is` unlines+ (postingsReportAsText defcliopts $ postingsReport opts (queryFromOpts (parsedate "2008/11/26") opts) j)+ @?=+ unlines ["2009/01/01 медвежья шкура расходы:покупки 100 100" ," актив:наличные -100 0"] ]
Hledger/Cli/Commands/Rewrite.hs view
@@ -50,7 +50,7 @@ TransactionModifier{tmquerytxt=q, tmpostingrules=ps} where q = T.pack $ query_ ropts- ps = map (parseposting . stripquotes . T.pack) $ listofstringopt "add-posting" rawopts+ ps = map (parseposting . T.pack) $ listofstringopt "add-posting" rawopts parseposting t = either (error' . errorBundlePretty) id ep where ep = runIdentity (runJournalParser (postingp Nothing <* eof) t')@@ -132,7 +132,7 @@ diffs = map mapDiff $ D.getDiff source changed' source | Just contents <- lookup fp $ jfiles j = map T.unpack . drop (line-1) . take line' $ T.lines contents | otherwise = []- changed = lines $ showTransactionUnelided t'+ changed = lines $ showTransaction t' changed' | null changed = changed | null $ last changed = init changed | otherwise = changed
Hledger/Cli/Commands/Roi.hs view
@@ -148,7 +148,8 @@ cashflow let finalUnitBalance = if null units then initialUnits else let (_,_,_,u) = last units in u- finalUnitPrice = valueAfter / finalUnitBalance+ finalUnitPrice = if finalUnitBalance == 0 then initialUnitPrice+ else valueAfter / finalUnitBalance totalTWR = roundTo 2 $ (finalUnitPrice - initialUnitPrice) years = fromIntegral (diffDays spanEnd spanBegin) / 365 :: Double annualizedTWR = 100*((1+(realToFrac totalTWR/100))**(1/years)-1) :: Double@@ -202,16 +203,19 @@ (map ((:[]) . show) amounts)) -- 0% is always a solution, so require at least something here- case ridders+ case totalCF of+ [] -> return 0+ _ -> + case ridders #if MIN_VERSION_math_functions(0,3,0)- (RiddersParam 100 (AbsTol 0.00001))+ (RiddersParam 100 (AbsTol 0.00001)) #else- 0.00001+ 0.00001 #endif- (0.000000000001,10000) (interestSum spanEnd totalCF) of- Root rate -> return ((rate-1)*100)- NotBracketed -> error "Error: No solution -- not bracketed."- SearchFailed -> error "Error: Failed to find solution."+ (0.000000000001,10000) (interestSum spanEnd totalCF) of+ Root rate -> return ((rate-1)*100)+ NotBracketed -> error "Error: No solution -- not bracketed."+ SearchFailed -> error "Error: Failed to find solution." type CashFlow = [(Day, Quantity)]
Hledger/Cli/Commands/Stats.hs view
@@ -81,7 +81,7 @@ path = journalFilePath j ts = sortOn tdate $ filter (spanContainsDate span . tdate) $ jtxns j as = nub $ map paccount $ concatMap tpostings ts- cs = Map.keys $ commodityStylesFromAmounts $ concatMap (amounts . pamount) $ concatMap tpostings ts+ cs = either error' Map.keys $ commodityStylesFromAmounts $ concatMap (amounts . pamount) $ concatMap tpostings ts lastdate | null ts = Nothing | otherwise = Just $ tdate $ last ts lastelapsed = fmap (diffDays today) lastdate
Hledger/Cli/Commands/Tags.hs view
@@ -30,7 +30,7 @@ mtagpat = headMay args queryargs = drop 1 args values = boolopt "values" rawopts- q = queryFromOpts d $ ropts{query_ = unwords queryargs}+ q = queryFromOpts d $ ropts{query_ = unwords $ map quoteIfNeeded queryargs} txns = filter (q `matchesTransaction`) $ jtxns $ journalSelectingAmountFromOpts ropts j tagsorvalues = nubSort $
Hledger/Cli/Commands/Test.txt view
@@ -3,19 +3,20 @@ _FLAGS_ -This command runs the unit tests built in to hledger-lib and hledger,-printing test names and results on stdout. If any test fails, the exit-code will be non-zero.+This command runs the unit tests built in to hledger and hledger-lib,+printing the results on stdout. If any test fails, the exit code will be+non-zero. -Test names include a group prefix. If a (exact, case sensitive) group-prefix, or a full test name is provided as the first argument, only that-group or test is run.+This is mainly used by hledger developers, but you can also use it to+sanity-check the installed hledger executable on your platform. All+tests are expected to pass - if you ever see a failure, please report as+a bug! -If a numeric second argument is provided, it will set the randomness-seed, for repeatable results from tests using randomness (currently none-of them).+This command also accepts tasty test runner options, written after a --+(double hyphen). Eg to run only the tests in Hledger.Data.Amount, with+ANSI colour codes disabled: -This is mainly used by developers, but it's nice to be able to-sanity-check your installed hledger executable at any time. All tests-are expected to pass - if you ever see otherwise, something has gone-wrong, please report a bug!+$ hledger test -- -pData.Amount --color=never++For help on these, see https://github.com/feuerbach/tasty#options+(-- --help currently doesn't show them).
Hledger/Cli/CompoundBalanceCommand.hs view
@@ -1,4 +1,4 @@-{-# LANGUAGE OverloadedStrings, RecordWildCards #-}+{-# LANGUAGE OverloadedStrings, RecordWildCards, LambdaCase #-} {-| Common helpers for making multi-section balance report commands@@ -106,6 +106,7 @@ ,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)" ,flagNone ["pretty-tables"] (setboolopt "pretty-tables") "use unicode when displaying tables" ,flagNone ["sort-amount","S"] (setboolopt "sort-amount") "sort by amount instead of account code/name"+ ,flagNone ["percent", "%"] (setboolopt "percent") "express values in percentage of each column's total" ,outputFormatFlag ,outputFileFlag ]@@ -124,24 +125,23 @@ let -- use the default balance type for this report, unless the user overrides mBalanceTypeOverride =- case reverse $ filter (`elem` ["change","cumulative","historical"]) $ map fst rawopts of- "historical":_ -> Just HistoricalBalance- "cumulative":_ -> Just CumulativeChange- "change":_ -> Just PeriodChange- _ -> Nothing+ choiceopt parse rawopts where+ parse = \case+ "historical" -> Just HistoricalBalance+ "cumulative" -> Just CumulativeChange+ "change" -> Just PeriodChange+ _ -> Nothing balancetype = fromMaybe cbctype mBalanceTypeOverride -- Set balance type in the report options. -- Also, use tree mode (by default, at least?) if --cumulative/--historical -- are used in single column mode, since in that situation we will be using -- balanceReportFromMultiBalanceReport which does not support eliding boring parents, -- and tree mode hides this.. or something.. XXX- ropts'- | not (flat_ ropts) &&- interval_==NoInterval &&- balancetype `elem` [CumulativeChange, HistoricalBalance]- = ropts{balancetype_=balancetype, accountlistmode_=ALTree}- | otherwise- = ropts{balancetype_=balancetype}+ ropts' = ropts{+ balancetype_=balancetype,+ accountlistmode_=if not (flat_ ropts) && interval_==NoInterval && balancetype `elem` [CumulativeChange, HistoricalBalance] then ALTree else accountlistmode_,+ no_total_=if percent_ && length cbcqueries > 1 then True else no_total_+ } userq = queryFromOpts d ropts' format = outputFormatFromOpts opts
Hledger/Cli/DocFiles.hs view
@@ -53,11 +53,6 @@ ,$(embedFileRelative "embeddedfiles/hledger-web.txt") ,$(embedFileRelative "embeddedfiles/hledger-web.info") ))- ,("hledger-api",- ($(embedFileRelative "embeddedfiles/hledger-api.1")- ,$(embedFileRelative "embeddedfiles/hledger-api.txt")- ,$(embedFileRelative "embeddedfiles/hledger-api.info")- )) ,("journal", ($(embedFileRelative "embeddedfiles/hledger_journal.5") ,$(embedFileRelative "embeddedfiles/hledger_journal.txt")
Hledger/Cli/Main.hs view
@@ -171,12 +171,11 @@ -- builtin commands | Just (cmdmode, cmdaction) <- findCommand cmd =- (case cmd of+ (case True of -- these commands should not require or read the journal- "test" -> cmdaction opts journallesserror- "help" -> cmdaction opts journallesserror- -- this command should create the journal if missing- "add" -> do+ _ | cmd `elem` ["test","help"] -> cmdaction opts journallesserror+ -- these commands should create the journal if missing+ _ | cmd `elem` ["add","import"] -> do (ensureJournalFileExists =<< (head <$> journalFilePathFromOpts opts)) withJournalDo opts (cmdaction opts) -- other commands read the journal and should fail if it's missing@@ -208,8 +207,7 @@ let args' = moveFlagsAfterCommand $ replaceNumericFlags args cmdargsopts = either usageError id $ C.process (mainmode addons) args'- cmdargsopts' = decodeRawOpts cmdargsopts- rawOptsToCliOpts cmdargsopts'+ rawOptsToCliOpts cmdargsopts -- | A hacky workaround for cmdargs not accepting flags before the -- subcommand name: try to detect and move such flags after the
Hledger/Cli/Utils.hs view
@@ -31,14 +31,11 @@ import Control.Exception as C import Control.Monad -import Data.Hashable (hash) import Data.List import Data.Maybe import qualified Data.Text as T import qualified Data.Text.IO as T import Data.Time (Day, addDays)-import Data.Word-import Numeric import Safe (readMay) import System.Console.CmdArgs import System.Directory (getModificationTime, getDirectoryContents, copyFile)@@ -54,6 +51,7 @@ import Data.Time.Clock.POSIX (utcTimeToPOSIXSeconds) import Hledger.Cli.CliOptions+import Hledger.Cli.Anon import Hledger.Data import Hledger.Read import Hledger.Reports@@ -98,40 +96,23 @@ -- | Apply the anonymisation transformation on a journal, if option is present anonymiseByOpts :: CliOpts -> Journal -> Journal anonymiseByOpts opts =- case maybestringopt "anon" . rawopts_ $ opts of- Just _ -> anonymise- Nothing -> id---- | Apply the anonymisation transformation on a journal-anonymise :: Journal -> Journal-anonymise j- = let- pAnons p = p { paccount = T.intercalate (T.pack ":") . map anon . T.splitOn (T.pack ":") . paccount $ p- , pcomment = T.empty- , ptransaction = fmap tAnons . ptransaction $ p- , poriginal = pAnons <$> poriginal p- }- tAnons txn = txn { tpostings = map pAnons . tpostings $ txn- , tdescription = anon . tdescription $ txn- , tcomment = T.empty- }- in- j { jtxns = map tAnons . jtxns $ j }- where- anon = T.pack . flip showHex "" . (fromIntegral :: Int -> Word32) . hash+ if anon_ . inputopts_ $ opts+ then anon+ else id -- | Generate periodic transactions from all periodic transaction rules in the journal. -- These transactions are added to the in-memory Journal (but not the on-disk file). ----- They start on or after the day following the latest normal transaction in the journal,--- or today if there are none.--- They end on or before the specified report end date, or 180 days from today if unspecified.+-- They can start no earlier than: the day following the latest normal+-- transaction in the journal (or today if there are none).+-- They end on or before the specified report end date, or 180 days+-- from today if unspecified. -- journalAddForecast :: CliOpts -> Journal -> IO Journal journalAddForecast opts@CliOpts{inputopts_=iopts, reportopts_=ropts} j = do today <- getCurrentDay - -- "They start on or after the day following the latest normal transaction in the journal, or today if there are none."+ -- "They can start no earlier than: the day following the latest normal transaction in the journal (or today if there are none)." let mjournalend = dbg2 "journalEndDate" $ journalEndDate False j -- ignore secondary dates forecaststart = dbg2 "forecaststart" $ fromMaybe today mjournalend
README.md view
@@ -5,7 +5,7 @@ hledger is a computer program for easily tracking money, time, or other commodities, on unix, mac and windows (and web-capable mobile devices, to some extent). -It is first a command-line tool, but there are also curses-style and+It is first a command-line tool, but there are also terminal and web interfaces, and a Haskell library (http://hackage.haskell.org/package/hledger-lib) for building your own programs and scripts (hledger is written in Haskell). hledger was@@ -121,5 +121,4 @@ [](http://packdeps.haskellers.com/feed?needle=hledger) [](http://packdeps.haskellers.com/feed?needle=hledger-ui) [](http://packdeps.haskellers.com/feed?needle=hledger-web)-[](http://packdeps.haskellers.com/feed?needle=hledger-api)
− embeddedfiles/hledger-api.1
@@ -1,129 +0,0 @@--.TH "hledger-api" "1" "March 2019" "hledger-api 1.14.99" "hledger User Manuals"----.SH NAME-.PP-hledger-api - web API server for the hledger accounting tool-.SH SYNOPSIS-.PP-\f[C]hledger-api [OPTIONS]\f[R]-.PD 0-.P-.PD-\f[C]hledger api -- [OPTIONS]\f[R]-.SH DESCRIPTION-.PP-hledger is a cross-platform program 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).-.PP-hledger-api is a simple web API server, intended to support client-side-web apps operating on hledger data.-It comes with a series of simple client-side app examples, which drive-its evolution.-.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]).-For more about this see hledger(1), hledger_journal(5) etc.-.PP-The server listens on IP address 127.0.0.1, accessible only to local-requests, by default.-You can change this with \f[C]--host\f[R], eg \f[C]--host 0.0.0.0\f[R]-to listen on all addresses.-Note there is no other access control, and hledger-api allows file-browsing, so on shared machines you will certainly need to put it behind-an authenticating proxy to restrict access.-.PP-You can change the TCP port it listens on (default: 8001) with-\f[C]-p PORT\f[R].-.PP-API methods look like:-.IP-.nf-\f[C]-/api/v1/accountnames-/api/v1/transactions-/api/v1/prices-/api/v1/commodities-/api/v1/accounts-/api/v1/accounts/ACCTNAME-\f[R]-.fi-.PP-See \f[C]/api/swagger.json\f[R] for a full list in Swagger 2.0 format.-(Or you can run \f[C]hledger-api --swagger\f[R] to print this in the-console.)-.PP-hledger-api also serves files, from the current directory by default,-and the \f[C]/\f[R] path will also show a directory listing.-This is convenient for serving client-side web code, in addition to the-server-side api.-.SH OPTIONS-.PP-Note: if invoking hledger-api as a hledger subcommand, write-\f[C]--\f[R] before options as shown above.-.TP-.B \f[C]-f --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])-.TP-.B \f[C]-d --static-dir=DIR\f[R]-serve files from a different directory (default: \f[C].\f[R])-.TP-.B \f[C]--host=IPADDR\f[R]-listen on this IP address (default: 127.0.0.1)-.TP-.B \f[C]-p --port=PORT\f[R]-listen on this TCP port (default: 8001)-.TP-.B \f[C]--swagger\f[R]-print API docs in Swagger 2.0 format, and exit-.TP-.B \f[C]--version\f[R]-show version-.TP-.B \f[C]-h --help\f[R]-show usage-.SH ENVIRONMENT-.PP-\f[B]LEDGER_FILE\f[R] The journal file path when not specified with-\f[C]-f\f[R].-Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps-\f[C]C:/Users/USER/.hledger.journal\f[R]).-.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]).-.SH BUGS-.PP-The need to precede options with \f[C]--\f[R] when invoked from hledger-is awkward.---.SH "REPORTING BUGS"-Report bugs at http://bugs.hledger.org-(or on the #hledger IRC channel or hledger mail list)--.SH AUTHORS-Simon Michael <simon@joyful.com> and contributors--.SH COPYRIGHT--Copyright (C) 2007-2016 Simon Michael.-.br-Released under GNU GPL v3 or later.--.SH SEE ALSO-hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),-hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5),-ledger(1)--http://hledger.org
− embeddedfiles/hledger-api.info
@@ -1,87 +0,0 @@-This is hledger-api.info, produced by makeinfo version 6.5 from stdin.---File: hledger-api.info, Node: Top, Next: OPTIONS, Up: (dir)--hledger-api(1) hledger-api 1.14.99-**********************************--hledger-api is a simple web API server, intended to support client-side-web apps operating on hledger data. It comes with a series of simple-client-side app examples, which drive its evolution.-- 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.-- The server listens on IP address 127.0.0.1, accessible only to local-requests, by default. You can change this with '--host', eg '--host-0.0.0.0' to listen on all addresses. Note there is no other access-control, and hledger-api allows file browsing, so on shared machines you-will certainly need to put it behind an authenticating proxy to restrict-access.-- You can change the TCP port it listens on (default: 8001) with '-p-PORT'.-- API methods look like:--/api/v1/accountnames-/api/v1/transactions-/api/v1/prices-/api/v1/commodities-/api/v1/accounts-/api/v1/accounts/ACCTNAME-- See '/api/swagger.json' for a full list in Swagger 2.0 format. (Or-you can run 'hledger-api --swagger' to print this in the console.)-- hledger-api also serves files, from the current directory by default,-and the '/' path will also show a directory listing. This is convenient-for serving client-side web code, in addition to the server-side api.--* Menu:--* OPTIONS::---File: hledger-api.info, Node: OPTIONS, Prev: Top, Up: Top--1 OPTIONS-*********--Note: if invoking hledger-api as a hledger subcommand, write '--' before-options as shown above.--'-f --file=FILE'-- use a different input file. For stdin, use - (default:- '$LEDGER_FILE' or '$HOME/.hledger.journal')-'-d --static-dir=DIR'-- serve files from a different directory (default: '.')-'--host=IPADDR'-- listen on this IP address (default: 127.0.0.1)-'-p --port=PORT'-- listen on this TCP port (default: 8001)-'--swagger'-- print API docs in Swagger 2.0 format, and exit-'--version'-- show version-'-h --help'-- show usage---Tag Table:-Node: Top72-Node: OPTIONS1667-Ref: #options1752--End Tag Table
− embeddedfiles/hledger-api.txt
@@ -1,120 +0,0 @@--hledger-api(1) hledger User Manuals hledger-api(1)----NAME- hledger-api - web API server for the hledger accounting tool--SYNOPSIS- hledger-api [OPTIONS]- hledger api -- [OPTIONS]--DESCRIPTION- hledger is a cross-platform program 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).-- hledger-api is a simple web API server, intended to support client-side- web apps operating on hledger data. It comes with a series of simple- client-side app examples, which drive its evolution.-- 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.-- The server listens on IP address 127.0.0.1, accessible only to local- requests, by default. You can change this with --host, eg --host- 0.0.0.0 to listen on all addresses. Note there is no other access con-- trol, and hledger-api allows file browsing, so on shared machines you- will certainly need to put it behind an authenticating proxy to- restrict access.-- You can change the TCP port it listens on (default: 8001) with -p PORT.-- API methods look like:-- /api/v1/accountnames- /api/v1/transactions- /api/v1/prices- /api/v1/commodities- /api/v1/accounts- /api/v1/accounts/ACCTNAME-- See /api/swagger.json for a full list in Swagger 2.0 format. (Or you- can run hledger-api --swagger to print this in the console.)-- hledger-api also serves files, from the current directory by default,- and the / path will also show a directory listing. This is convenient- for serving client-side web code, in addition to the server-side api.--OPTIONS- Note: if invoking hledger-api as a hledger subcommand, write -- before- options as shown above.-- -f --file=FILE- use a different input file. For stdin, use - (default:- $LEDGER_FILE or $HOME/.hledger.journal)-- -d --static-dir=DIR- serve files from a different directory (default: .)-- --host=IPADDR- listen on this IP address (default: 127.0.0.1)-- -p --port=PORT- listen on this TCP port (default: 8001)-- --swagger- print API docs in Swagger 2.0 format, and exit-- --version- show version-- -h --help- show usage--ENVIRONMENT- LEDGER_FILE The journal file path when not specified with -f. Default:- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-- nal).--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).--BUGS- The need to precede options with -- when invoked from hledger is awk-- ward.----REPORTING BUGS- Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel- or hledger mail list)---AUTHORS- Simon Michael <simon@joyful.com> and contributors---COPYRIGHT- Copyright (C) 2007-2016 Simon Michael.- Released under GNU GPL v3 or later.---SEE ALSO- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-- dot(5), ledger(1)-- http://hledger.org----hledger-api 1.14.99 March 2019 hledger-api(1)
embeddedfiles/hledger-ui.1 view
@@ -1,11 +1,11 @@ -.TH "hledger-ui" "1" "August 2019" "hledger-ui 1.15" "hledger User Manuals"+.TH "hledger-ui" "1" "December 2019" "hledger-ui 1.16" "hledger User Manuals" .SH NAME .PP-hledger-ui - curses-style interface for the hledger accounting tool+hledger-ui - terminal interface for the hledger accounting tool .SH SYNOPSIS .PP \f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R]@@ -20,9 +20,9 @@ file format. hledger is inspired by and largely compatible with ledger(1). .PP-hledger-ui is hledger\[aq]s curses-style interface, providing an-efficient full-window text UI for viewing accounts and transactions, and-some limited data entry capability.+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@@ -245,7 +245,7 @@ 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-provides a curses-style interface.+provides a terminal interface. This key will be available if \f[C]hledger-iadd\f[R] is installed in $PATH. .PP@@ -258,6 +258,34 @@ .PP \f[C]q\f[R] quits the application. .PP+Experimental:+.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).+.PP+\f[C]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).+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+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+reliably reset to normal mode.+.PP+With --watch active, if you save an edit to the journal file while+viewing the transaction screen in cost or value mode, the+\f[C]B\f[R]/\f[C]V\f[R] keys will stop working.+To work around, press g to force a manual reload, or exit the+transaction screen.+.PP Additional screen-specific keys are described below. .SH SCREENS .SS Accounts screen@@ -440,7 +468,7 @@ .SH COPYRIGHT -Copyright (C) 2007-2016 Simon Michael.+Copyright (C) 2007-2019 Simon Michael. .br Released under GNU GPL v3 or later.
embeddedfiles/hledger-ui.info view
@@ -3,10 +3,10 @@ File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-ui(1) hledger-ui 1.15+hledger-ui(1) hledger-ui 1.16 ***************************** -hledger-ui is hledger's curses-style interface, providing an efficient+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@@ -239,7 +239,7 @@ file. This allows some basic data entry. 'A' is like 'a', but runs the hledger-iadd tool, which provides a-curses-style interface. This key will be available if 'hledger-iadd' is+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@@ -250,6 +250,30 @@ 'q' quits the application. + Experimental:++ 'B' toggles cost mode, showing amounts in their transaction price'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). 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.++ 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+mode.++ With -watch active, if you save an edit to the journal file while+viewing the transaction screen in cost or value mode, the 'B'/'V' keys+will stop working. To work around, press g to force a manual reload, or+exit the transaction screen.+ Additional screen-specific keys are described below. @@ -399,19 +423,19 @@ Tag Table: Node: Top71-Node: OPTIONS1101-Ref: #options1198-Node: KEYS4589-Ref: #keys4684-Node: SCREENS7940-Ref: #screens8025-Node: Accounts screen8115-Ref: #accounts-screen8243-Node: Register screen10459-Ref: #register-screen10614-Node: Transaction screen12610-Ref: #transaction-screen12768-Node: Error screen13638-Ref: #error-screen13760+Node: OPTIONS1097+Ref: #options1194+Node: KEYS4585+Ref: #keys4680+Node: SCREENS8987+Ref: #screens9072+Node: Accounts screen9162+Ref: #accounts-screen9290+Node: Register screen11506+Ref: #register-screen11661+Node: Transaction screen13657+Ref: #transaction-screen13815+Node: Error screen14685+Ref: #error-screen14807 End Tag Table
embeddedfiles/hledger-ui.txt view
@@ -4,7 +4,7 @@ NAME- hledger-ui - curses-style interface for the hledger accounting tool+ hledger-ui - terminal interface for the hledger accounting tool SYNOPSIS hledger-ui [OPTIONS] [QUERYARGS]@@ -16,7 +16,7 @@ file format. hledger is inspired by and largely compatible with ledger(1). - hledger-ui is hledger's curses-style interface, providing an efficient+ 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@@ -226,9 +226,9 @@ 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 curses-- style interface. This key will be available if hledger-iadd is in-- stalled in $PATH.+ 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 cursor@@ -238,47 +238,70 @@ q quits the application. + Experimental:++ B toggles cost mode, showing amounts in their transaction price's com-+ modity (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).+ 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.++ 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 mode.++ With --watch active, if you save an edit to the journal file while+ viewing the transaction screen in cost or value mode, the B/V keys will+ stop working. To work around, press g to force a manual reload, or+ exit the transaction screen.+ Additional screen-specific keys are described below. SCREENS Accounts screen- This is normally the first screen displayed. It lists accounts and- their balances, like hledger's balance command. By default, it shows- all accounts and their latest ending balances (including the balances- of subaccounts). if you specify a query on the command line, it shows+ This is normally the first screen displayed. It lists accounts and+ their balances, like hledger's balance command. By default, it shows+ all accounts and their latest ending balances (including the balances+ of subaccounts). if you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions. - Account names are shown as a flat list by default. Press T to toggle- tree mode. In flat mode, account balances are exclusive of subac-- counts, except where subaccounts are hidden by a depth limit (see be-+ Account names are shown as a flat list by default. Press T to toggle+ tree mode. In flat mode, account balances are exclusive of subac-+ counts, except where subaccounts are hidden by a depth limit (see be- low). 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.+ 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+ less detail, collapsing all accounts to a single total. To remove the depth limit, set it higher than the maximum account depth, or press ES- CAPE. H toggles between showing historical balances or period balances. His-- torical 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), including transactions before- the start of the report period. In other words, historical balances- are what you would see on a bank statement for that account (unless- disturbed by a filter query). Period balances ignore transactions be-- fore the report start date, so they show the change in balance during+ torical 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), including transactions before+ the start of the report period. In other words, historical balances+ are what you would see on a bank statement for that account (unless+ disturbed by a filter query). Period balances ignore transactions be-+ fore the report start date, so they show the 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 include all postings;- if you activate one or two status filters, only those postings are in-+ toggles cleared postings. (By default, balances include all postings;+ if you activate one or two status filters, only those postings are in- cluded; and if you activate all three, the filter is removed.) R toggles real mode, in which virtual postings are ignored. - Z toggles nonzero mode, in which only accounts with nonzero balances- are shown (hledger-ui shows zero items by default, unlike command-line+ Z toggles nonzero mode, in which only accounts with nonzero balances+ are shown (hledger-ui shows zero items by default, unlike command-line hledger). Press right or enter to view an account's transactions register.@@ -287,63 +310,63 @@ This screen shows the transactions affecting a particular account, like a check register. Each line represents one transaction and shows: - o the other account(s) involved, in abbreviated form. (If there are- both real and virtual postings, it shows only the accounts affected+ o 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.) - o the overall change to the current account's balance; positive for an+ o the overall change to the current account's balance; positive for an inflow to this account, negative for an outflow. o 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+ 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+ 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+ 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 flat- mode but this account has subaccounts which are not shown due to a- depth limit. In other words, the register always shows the transac-+ mode but this account has subaccounts which are not shown due to a+ depth limit. In other words, the register always shows the transac- tions contributing to the balance shown on the accounts screen. Tree mode/flat mode can be toggled with T here also. - U toggles filtering by unmarked status, showing or hiding unmarked+ 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 transac-+ cleared transactions. (By default, transactions with all statuses are+ shown; if you activate one or two status filters, only those transac- tions are shown; and if you activate all three, the filter is removed.) R toggles real mode, in which virtual postings are ignored. - Z toggles nonzero mode, in which only transactions posting a nonzero- change are shown (hledger-ui shows zero items by default, unlike com-+ Z toggles nonzero mode, in which only transactions posting a nonzero+ change are shown (hledger-ui shows zero items by default, unlike com- mand-line hledger). Press right (or enter) to view the selected transaction in detail. Transaction screen- This screen shows a single transaction, as a general journal entry,- similar to hledger's print command and journal format (hledger_jour-+ This screen shows a single transaction, as a general journal entry,+ similar to hledger's print command and journal format (hledger_jour- nal(5)). - The transaction's date(s) and any cleared flag, transaction code, de-- scription, comments, along with all of its account postings are shown.- Simple transactions have two postings, but there can be more (or in+ The transaction's date(s) and any cleared flag, transaction code, de-+ scription, 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 previous- account register screen. In the title bar, the numbers in parentheses- show your position within that account register. They will vary de-+ 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 de- pending on which account register you came from (remember most transac-- tions appear in multiple account registers). The #N number preceding+ tions appear in multiple account registers). The #N number preceding them is the transaction's position within the complete unfiltered jour- nal, which is a more stable id (at least until the next reload). Error screen- This screen will appear if there is a problem, such as a parse error,- when you press g to reload. Once you have fixed the problem, press g+ This screen will appear if there is a problem, such as a parse error,+ when you press g to reload. Once you have fixed the problem, press g again to reload and resume normal operation. (Or, you can press escape to cancel the reload attempt.) @@ -351,17 +374,17 @@ COLUMNS The screen width to use. Default: the full terminal width. LEDGER_FILE The journal file path when not specified with -f. Default:- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-+ ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). 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+ 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). BUGS- The need to precede options with -- when invoked from hledger is awk-+ The need to precede options with -- when invoked from hledger is awk- ward. -f- doesn't work (hledger-ui can't read from stdin).@@ -369,24 +392,24 @@ -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. - Also, if you are viewing files mounted from another machine, --watch+ Also, if you are viewing files mounted from another machine, --watch requires that both machine clocks are roughly in step. REPORTING BUGS- Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel+ Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -395,12 +418,12 @@ COPYRIGHT- Copyright (C) 2007-2016 Simon Michael.+ Copyright (C) 2007-2019 Simon Michael. Released under GNU GPL v3 or later. SEE ALSO- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) @@ -408,4 +431,4 @@ -hledger-ui 1.15 August 2019 hledger-ui(1)+hledger-ui 1.16 December 2019 hledger-ui(1)
embeddedfiles/hledger-web.1 view
@@ -1,5 +1,5 @@ -.TH "hledger-web" "1" "August 2019" "hledger-web 1.15" "hledger User Manuals"+.TH "hledger-web" "1" "December 2019" "hledger-web 1.16" "hledger User Manuals" @@ -289,9 +289,8 @@ .PP In addition to the web UI, hledger-web provides some API routes that serve JSON in response to GET requests.-Currently these are same ones provided by the hledger-api tool, but-hledger-web will likely receive more attention than hledger-api in-future:+(And when started with \f[C]--serve-api\f[R], it provides only these+routes.): .IP .nf \f[C]@@ -377,7 +376,7 @@ .SH COPYRIGHT -Copyright (C) 2007-2016 Simon Michael.+Copyright (C) 2007-2019 Simon Michael. .br Released under GNU GPL v3 or later.
embeddedfiles/hledger-web.info view
@@ -3,7 +3,7 @@ File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-web(1) hledger-web 1.15+hledger-web(1) hledger-web 1.16 ******************************* hledger-web is hledger's web interface. It starts a simple web@@ -298,9 +298,8 @@ ********** In addition to the web UI, hledger-web provides some API routes that-serve JSON in response to GET requests. Currently these are same ones-provided by the hledger-api tool, but hledger-web will likely receive-more attention than hledger-api in future:+serve JSON in response to GET requests. (And when started with+'--serve-api', it provides only these routes.): /accountnames /transactions
embeddedfiles/hledger-web.txt view
@@ -270,9 +270,8 @@ JSON API In addition to the web UI, hledger-web provides some API routes that- serve JSON in response to GET requests. Currently these are same ones- provided by the hledger-api tool, but hledger-web will likely receive- more attention than hledger-api in future:+ serve JSON in response to GET requests. (And when started with+ --serve-api, it provides only these routes.): /accountnames /transactions@@ -281,17 +280,17 @@ /accounts /accounttransactions/#AccountName - Also, you can append a new transaction to the journal by sending a PUT- request to /add (hledger-web only). As with the web UI's add form,- hledger-web must be started with the add capability for this (enabled+ Also, you can append a new transaction to the journal by sending a PUT+ request to /add (hledger-web only). As with the web UI's add form,+ hledger-web must be started with the add capability for this (enabled by default). - The payload should be a valid hledger transaction as JSON, similar to+ The payload should be a valid hledger transaction as JSON, similar to what you get from /transactions or /accounttransactions. - Another way to generate test data is with the readJsonFile/writeJson-- File helpers in Hledger.Web.Json, which read or write any of hledger's- JSON-capable types from or to a file. Eg here we write the first+ Another way to generate test data is with the readJsonFile/writeJson-+ File helpers in Hledger.Web.Json, which read or write any of hledger's+ JSON-capable types from or to a file. Eg here we write the first transaction of a sample journal: $ make ghci-web@@ -306,23 +305,23 @@ $ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo - By default, both the server-side HTML UI and the JSON API are served.- Running with --serve-api disables the former, useful if you only want+ By default, both the server-side HTML UI and the JSON API are served.+ Running with --serve-api disables the former, useful if you only want to serve the API. ENVIRONMENT LEDGER_FILE The journal file path when not specified with -f. Default:- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-+ ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). 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+ 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). BUGS- The need to precede options with -- when invoked from hledger is awk-+ The need to precede options with -- when invoked from hledger is awk- ward. -f- doesn't work (hledger-web can't read from stdin).@@ -336,7 +335,7 @@ REPORTING BUGS- Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel+ Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -345,12 +344,12 @@ COPYRIGHT- Copyright (C) 2007-2016 Simon Michael.+ Copyright (C) 2007-2019 Simon Michael. Released under GNU GPL v3 or later. SEE ALSO- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) @@ -358,4 +357,4 @@ -hledger-web 1.15 August 2019 hledger-web(1)+hledger-web 1.16 December 2019 hledger-web(1)
embeddedfiles/hledger.1 view
@@ -1,6 +1,6 @@ .\"t -.TH "hledger" "1" "September 2019" "hledger 1.15.2" "hledger User Manuals"+.TH "hledger" "1" "December 2019" "hledger 1.16" "hledger User Manuals" @@ -30,8 +30,8 @@ Tested on unix, mac, windows, hledger aims to be a reliable, practical tool for daily use. .PP-This is hledger\[cq]s command-line interface (there are also curses and-web interfaces).+This is hledger\[cq]s command-line interface (there are also terminal+and web interfaces). Its basic function is to read a plain text file describing financial transactions (in accounting terms, a general journal) and print useful reports on standard output, or export them as CSV.@@ -829,7 +829,7 @@ l. T{ \f[C]-p \[dq]weekly from 2009/1/1 to 2009/4/1\[dq]\f[R] -- starts on-2008/12/29, closest preceeding Monday+2008/12/29, closest preceding Monday T} T{ \f[C]-p \[dq]monthly in 2008/11/25\[dq]\f[R] -- starts on 2018/11/01@@ -863,7 +863,7 @@ boundaries on 2008/01/01, 2008/03/01, ... T} T{-\f[C]-p \[dq]every 2 weeks\[dq]\f[R] -- starts on closest preceeding+\f[C]-p \[dq]every 2 weeks\[dq]\f[R] -- starts on closest preceding Monday T} T{@@ -2083,6 +2083,41 @@ .PP Flat-mode balance reports, which normally show exclusive balances, show inclusive balances at the depth limit.+.SS Percentages+.PP+With \f[C]-%\f[R] or \f[C]--percent\f[R], balance reports show each+account\[aq]s value expressed as a percentage of the column\[aq]s total.+This is useful to get an overview of the relative sizes of account+balances.+For example to obtain an overview of expenses:+.IP+.nf+\f[C]+$ hledger balance expenses -%+ 100.0 % expenses+ 50.0 % food+ 50.0 % supplies+--------------------+ 100.0 %+\f[R]+.fi+.PP+Note that \f[C]--tree\f[R] does not have an effect on \f[C]-%\f[R].+The percentages are always relative to the total sum of each column,+they are never relative to the parent account.+.PP+Since the percentages are relative to the columns sum, it is usually not+useful to calculate percentages if the signs of the amounts are mixed.+Although the results are technically correct, they are most likely+useless.+Especially in a balance report that sums up to zero (eg+\f[C]hledger balance -B\f[R]) all percentage values will be zero.+.PP+This flag does not work if the report contains any mixed commodity+accounts.+If there are mixed commodity accounts in the report be sure to use+\f[C]-V\f[R] or \f[C]-B\f[R] to coerce the report into using a single+commodity. .SS Multicolumn balance report .PP Multicolumn or tabular balance reports are a very useful hledger@@ -2510,6 +2545,8 @@ you need for a balance sheet; note this means it ignores report begin dates (and \f[C]-T/--row-total\f[R], since summing end balances generally does not make sense).+Instead of absolute values percentages can be displayed with+\f[C]-%\f[R]. .PP This command also supports output destination and output format selection.@@ -2591,6 +2628,8 @@ Normally cashflow shows changes in assets per period, though as with multicolumn balance reports you can alter the report mode with \f[C]--change\f[R]/\f[C]--cumulative\f[R]/\f[C]--historical\f[R].+Instead of absolute values percentages can be displayed with+\f[C]-%\f[R]. .PP This command also supports output destination and output format selection.@@ -2820,7 +2859,7 @@ \f[C] $ hledger help Please choose a manual by typing \[dq]hledger help MANUAL\[dq] (a substring is ok).-Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot+Manuals: hledger hledger-ui hledger-web journal csv timeclock timedot \f[R] .fi .IP@@ -2852,6 +2891,8 @@ Read new transactions added to each FILE since last run, and add them to the main journal file. Or with --dry-run, just print the transactions that would be added.+Or with --catchup, just mark all of the FILEs\[aq] transactions as+imported, without actually importing any. .PP The input files are specified as arguments - no need to write -f before each one.@@ -2940,6 +2981,8 @@ Normally incomestatement shows revenues/expenses per period, though as with multicolumn balance reports you can alter the report mode with \f[C]--change\f[R]/\f[C]--cumulative\f[R]/\f[C]--historical\f[R].+Instead of absolute values percentages can be displayed with+\f[C]-%\f[R]. .PP This command also supports output destination and output format selection.@@ -2986,6 +3029,7 @@ With --inverted-costs, also print inverse prices based on transaction prices. Prices (and postings providing prices) can be filtered by a query.+Price amounts are always displayed with their full precision. .SS print .PP print, txns, p@@ -3551,22 +3595,28 @@ .PD Run built-in unit tests. .PP-This command runs the unit tests built in to hledger-lib and hledger,-printing test names and results on stdout.+This command runs the unit tests built in to hledger and hledger-lib,+printing the results on stdout. If any test fails, the exit code will be non-zero. .PP-Test names include a group prefix.-If a (exact, case sensitive) group prefix, or a full test name is-provided as the first argument, only that group or test is run.+This is mainly used by hledger developers, but you can also use it to+sanity-check the installed hledger executable on your platform.+All tests are expected to pass - if you ever see a failure, please+report as a bug! .PP-If a numeric second argument is provided, it will set the randomness-seed, for repeatable results from tests using randomness (currently none-of them).+This command also accepts tasty test runner options, written after a --+(double hyphen).+Eg to run only the tests in Hledger.Data.Amount, with ANSI colour codes+disabled:+.IP+.nf+\f[C]+$ hledger test -- -pData.Amount --color=never+\f[R]+.fi .PP-This is mainly used by developers, but it\[aq]s nice to be able to-sanity-check your installed hledger executable at any time.-All tests are expected to pass - if you ever see otherwise, something-has gone wrong, please report a bug!+For help on these, see https://github.com/feuerbach/tasty#options+(\f[C]-- --help\f[R] currently doesn\[aq]t show them). .SH ADD-ON COMMANDS .PP hledger also searches for external add-on commands, and will include@@ -3602,12 +3652,9 @@ .SS Official add-ons .PP These are maintained and released along with hledger.-.SS api-.PP-hledger-api serves hledger data as a JSON web API. .SS ui .PP-hledger-ui provides an efficient curses-style interface.+hledger-ui provides an efficient terminal interface. .SS web .PP hledger-web provides a simple web interface.@@ -3621,7 +3668,7 @@ one journal file and another. .SS iadd .PP-hledger-iadd is a curses-style, more interactive replacement for the add+hledger-iadd is a more interactive, terminal UI replacement for the add command. .SS interest .PP@@ -3634,7 +3681,7 @@ .SS Experimental add-ons .PP These are available in source form in the hledger repo\[aq]s bin/-directory; installing them is pretty easy.+directory. They may be less mature and documented than built-in commands. Reading and tweaking these is a good way to start making your own! .SS autosync@@ -3784,7 +3831,7 @@ .SH COPYRIGHT -Copyright (C) 2007-2016 Simon Michael.+Copyright (C) 2007-2019 Simon Michael. .br Released under GNU GPL v3 or later.
embeddedfiles/hledger.info view
@@ -3,16 +3,16 @@ File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir) -hledger(1) hledger 1.15.2-*************************+hledger(1) hledger 1.16+*********************** -This is hledger's command-line interface (there are also curses and web-interfaces). Its basic function is to read a plain text file describing-financial transactions (in accounting terms, a general journal) and-print useful reports on standard output, or export them as CSV. hledger-can also read some other file formats such as CSV files, translating-them to journal format. Additionally, hledger lists other hledger-*-executables found in the user's $PATH and can invoke them as+This is hledger's command-line interface (there are also terminal and+web interfaces). Its basic function is to read a plain text file+describing financial transactions (in accounting terms, a general+journal) and print useful reports on standard output, or export them as+CSV. hledger can also read some other file formats such as CSV files,+translating them to journal format. Additionally, hledger lists other+hledger-* executables found in the user's $PATH and can invoke them as subcommands. hledger reads data from one or more files in hledger journal,@@ -628,7 +628,7 @@ For example: -'-p "weekly from 2009/1/1 to 2009/4/1"' - starts on 2008/12/29, closest preceeding Monday+'-p "weekly from 2009/1/1 to 2009/4/1"' - starts on 2008/12/29, closest preceding Monday '-p "monthly in 2008/11/25"' - starts on 2018/11/01 '-p "quarterly from 2009-05-05 to 2009-06-01"' - starts on 2009/04/01, ends on 2009/06/30, which are first and last days of Q2 2009 '-p "yearly from 2009-12-29"' - starts on 2009/01/01, first day of 2009@@ -643,7 +643,7 @@ Examples: '-p "bimonthly from 2008"' - periods will have boundaries on 2008/01/01, 2008/03/01, ...-'-p "every 2 weeks"' - starts on closest preceeding Monday+'-p "every 2 weeks"' - starts on closest preceding Monday '-p "every 5 month from 2009/03"' - periods will have boundaries on 2009/03/01, 2009/08/01, ... If you want intervals that start on arbitrary day of your choosing@@ -1498,6 +1498,7 @@ * Colour support:: * Flat mode:: * Depth limited balance reports::+* Percentages:: * Multicolumn balance report:: * Budget report:: * Output format::@@ -1639,7 +1640,7 @@ $1 supplies -File: hledger.info, Node: Depth limited balance reports, Next: Multicolumn balance report, Prev: Flat mode, Up: balance+File: hledger.info, Node: Depth limited balance reports, Next: Percentages, Prev: Flat mode, Up: balance 4.4.5 Depth limited balance reports -----------------------------------@@ -1658,9 +1659,41 @@ show inclusive balances at the depth limit. -File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Depth limited balance reports, Up: balance+File: hledger.info, Node: Percentages, Next: Multicolumn balance report, Prev: Depth limited balance reports, Up: balance -4.4.6 Multicolumn balance report+4.4.6 Percentages+-----------------++With '-%' or '--percent', balance reports show each account's value+expressed as a percentage of the column's total. This is useful to get+an overview of the relative sizes of account balances. For example to+obtain an overview of expenses:++$ hledger balance expenses -%+ 100.0 % expenses+ 50.0 % food+ 50.0 % supplies+--------------------+ 100.0 %++ Note that '--tree' does not have an effect on '-%'. The percentages+are always relative to the total sum of each column, they are never+relative to the parent account.++ Since the percentages are relative to the columns sum, it is usually+not useful to calculate percentages if the signs of the amounts are+mixed. Although the results are technically correct, they are most+likely useless. Especially in a balance report that sums up to zero (eg+'hledger balance -B') all percentage values will be zero.++ This flag does not work if the report contains any mixed commodity+accounts. If there are mixed commodity accounts in the report be sure+to use '-V' or '-B' to coerce the report into using a single commodity.+++File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Percentages, Up: balance++4.4.7 Multicolumn balance report -------------------------------- Multicolumn or tabular balance reports are a very useful hledger@@ -1777,7 +1810,7 @@ File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance -4.4.7 Budget report+4.4.8 Budget report ------------------- With '--budget', extra columns are displayed showing budget goals for@@ -1900,7 +1933,7 @@ File: hledger.info, Node: Nested budgets, Up: Budget report -4.4.7.1 Nested budgets+4.4.8.1 Nested budgets ...................... You can add budgets to any account in your account hierarchy. If you@@ -1985,7 +2018,7 @@ ----------------------------------------++------------------------------- || 0 [ 0] -4.4.8 Output format+4.4.9 Output format ------------------- The balance command supports output destination and output format@@ -2034,7 +2067,8 @@ balancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates (and '-T/--row-total', since summing end balances generally does not make-sense).+sense). Instead of absolute values percentages can be displayed with+'-%'. This command also supports output destination and output format selection.@@ -2108,7 +2142,8 @@ With a reporting interval, multiple columns will be shown, one for each report period. Normally cashflow shows changes in assets per period, though as with multicolumn balance reports you can alter the-report mode with '--change'/'--cumulative'/'--historical'.+report mode with '--change'/'--cumulative'/'--historical'. Instead of+absolute values percentages can be displayed with '-%'. This command also supports output destination and output format selection.@@ -2320,7 +2355,7 @@ $ hledger help Please choose a manual by typing "hledger help MANUAL" (a substring is ok).-Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot+Manuals: hledger hledger-ui hledger-web journal csv timeclock timedot $ hledger help h --man @@ -2347,7 +2382,8 @@ import Read new transactions added to each FILE since last run, and add them to the main journal file. Or with -dry-run, just print the transactions-that would be added.+that would be added. Or with -catchup, just mark all of the FILEs'+transactions as imported, without actually importing any. The input files are specified as arguments - no need to write -f before each one. So eg to add new transactions from all CSV files to@@ -2427,7 +2463,8 @@ With a reporting interval, multiple columns will be shown, one for each report period. Normally incomestatement shows revenues/expenses per period, though as with multicolumn balance reports you can alter the-report mode with '--change'/'--cumulative'/'--historical'.+report mode with '--change'/'--cumulative'/'--historical'. Instead of+absolute values percentages can be displayed with '-%'. This command also supports output destination and output format selection.@@ -2476,6 +2513,7 @@ synthetic market prices based on transaction prices. With -inverted-costs, also print inverse prices based on transaction prices. Prices (and postings providing prices) can be filtered by a query.+Price amounts are always displayed with their full precision. File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS@@ -2970,23 +3008,24 @@ test Run built-in unit tests. - This command runs the unit tests built in to hledger-lib and hledger,-printing test names and results on stdout. If any test fails, the exit-code will be non-zero.+ This command runs the unit tests built in to hledger and hledger-lib,+printing the results on stdout. If any test fails, the exit code will+be non-zero. - Test names include a group prefix. If a (exact, case sensitive)-group prefix, or a full test name is provided as the first argument,-only that group or test is run.+ This is mainly used by hledger developers, but you can also use it to+sanity-check the installed hledger executable on your platform. All+tests are expected to pass - if you ever see a failure, please report as+a bug! - If a numeric second argument is provided, it will set the randomness-seed, for repeatable results from tests using randomness (currently none-of them).+ This command also accepts tasty test runner options, written after a+- (double hyphen). Eg to run only the tests in Hledger.Data.Amount,+with ANSI colour codes disabled: - This is mainly used by developers, but it's nice to be able to-sanity-check your installed hledger executable at any time. All tests-are expected to pass - if you ever see otherwise, something has gone-wrong, please report a bug!+$ hledger test -- -pData.Amount --color=never + For help on these, see https://github.com/feuerbach/tasty#options+('-- --help' currently doesn't show them).+ File: hledger.info, Node: ADD-ON COMMANDS, Prev: COMMANDS, Up: Top @@ -3036,30 +3075,21 @@ * Menu: -* api:: * ui:: * web:: -File: hledger.info, Node: api, Next: ui, Up: Official add-ons--5.1.1 api------------hledger-api serves hledger data as a JSON web API.---File: hledger.info, Node: ui, Next: web, Prev: api, Up: Official add-ons+File: hledger.info, Node: ui, Next: web, Up: Official add-ons -5.1.2 ui+5.1.1 ui -------- -hledger-ui provides an efficient curses-style interface.+hledger-ui provides an efficient terminal interface. File: hledger.info, Node: web, Prev: ui, Up: Official add-ons -5.1.3 web+5.1.2 web --------- hledger-web provides a simple web interface.@@ -3092,7 +3122,7 @@ 5.2.2 iadd ---------- -hledger-iadd is a curses-style, more interactive replacement for the add+hledger-iadd is a more interactive, terminal UI replacement for the add command. @@ -3119,10 +3149,9 @@ 5.3 Experimental add-ons ======================== -These are available in source form in the hledger repo's bin/ directory;-installing them is pretty easy. They may be less mature and documented-than built-in commands. Reading and tweaking these is a good way to-start making your own!+These are available in source form in the hledger repo's bin/ directory.+They may be less mature and documented than built-in commands. Reading+and tweaking these is a good way to start making your own! * Menu: @@ -3160,179 +3189,179 @@ Tag Table: Node: Top68-Node: EXAMPLES1889-Ref: #examples1989-Node: OPTIONS3635-Ref: #options3737-Node: General options4136-Ref: #general-options4261-Node: Command options6915-Ref: #command-options7066-Node: Command arguments7464-Ref: #command-arguments7618-Node: Argument files7739-Ref: #argument-files7915-Node: Special characters in arguments and queries8181-Ref: #special-characters-in-arguments-and-queries8415-Node: More escaping8866-Ref: #more-escaping9028-Node: Even more escaping9324-Ref: #even-more-escaping9518-Node: Less escaping10189-Ref: #less-escaping10351-Node: Command line tips10596-Ref: #command-line-tips10782-Node: Unicode characters11159-Ref: #unicode-characters11315-Node: Input files12727-Ref: #input-files12863-Node: Smart dates14792-Ref: #smart-dates14933-Node: Report start & end date16339-Ref: #report-start-end-date16511-Node: Report intervals17935-Ref: #report-intervals18100-Node: Period expressions18490-Ref: #period-expressions18650-Node: Depth limiting22607-Ref: #depth-limiting22751-Node: Pivoting23093-Ref: #pivoting23216-Node: Valuation24892-Ref: #valuation25021-Node: -B Cost25201-Ref: #b-cost25312-Node: -V Market value25510-Ref: #v-market-value25684-Node: -X Market value in specified commodity27116-Ref: #x-market-value-in-specified-commodity27355-Node: --value Flexible valuation27531-Ref: #value-flexible-valuation27757-Node: Effect of --value on reports31947-Ref: #effect-of---value-on-reports32163-Node: Combining -B -V -X --value37094-Ref: #combining--b--v--x---value37277-Node: Output destination37313-Ref: #output-destination37465-Node: Output format37748-Ref: #output-format37900-Node: Regular expressions38285-Ref: #regular-expressions38422-Node: QUERIES39783-Ref: #queries39885-Node: COMMANDS43847-Ref: #commands43959-Node: accounts45023-Ref: #accounts45121-Node: activity45820-Ref: #activity45930-Node: add46313-Ref: #add46412-Node: balance49157-Ref: #balance49268-Node: Classic balance report50710-Ref: #classic-balance-report50883-Node: Customising the classic balance report52252-Ref: #customising-the-classic-balance-report52480-Node: Colour support54556-Ref: #colour-support54723-Node: Flat mode54896-Ref: #flat-mode55044-Node: Depth limited balance reports55457-Ref: #depth-limited-balance-reports55657-Node: Multicolumn balance report56113-Ref: #multicolumn-balance-report56311-Node: Budget report61625-Ref: #budget-report61768-Node: Nested budgets66970-Ref: #nested-budgets67082-Ref: #output-format-170562-Node: balancesheet70640-Ref: #balancesheet70776-Node: balancesheetequity72091-Ref: #balancesheetequity72240-Node: cashflow72801-Ref: #cashflow72929-Node: check-dates73957-Ref: #check-dates74084-Node: check-dupes74363-Ref: #check-dupes74487-Node: close74780-Ref: #close74894-Node: commodities78481-Ref: #commodities78608-Node: descriptions78690-Ref: #descriptions78818-Node: diff78999-Ref: #diff79105-Node: files80152-Ref: #files80252-Node: help80399-Ref: #help80499-Node: import81592-Ref: #import81706-Node: Importing balance assignments82494-Ref: #importing-balance-assignments82642-Node: incomestatement83291-Ref: #incomestatement83424-Node: notes84760-Ref: #notes84873-Node: payees84999-Ref: #payees85105-Node: prices85263-Ref: #prices85369-Node: print85648-Ref: #print85758-Node: print-unique90251-Ref: #print-unique90377-Node: register90662-Ref: #register90789-Node: Custom register output94961-Ref: #custom-register-output95090-Node: register-match96352-Ref: #register-match96486-Node: rewrite96837-Ref: #rewrite96952-Node: Re-write rules in a file98807-Ref: #re-write-rules-in-a-file98941-Node: Diff output format100151-Ref: #diff-output-format100320-Node: rewrite vs print --auto101412-Ref: #rewrite-vs.-print---auto101591-Node: roi102147-Ref: #roi102245-Node: stats103257-Ref: #stats103356-Node: tags104144-Ref: #tags104242-Node: test104536-Ref: #test104620-Node: ADD-ON COMMANDS105381-Ref: #add-on-commands105491-Node: Official add-ons106779-Ref: #official-add-ons106919-Node: api107007-Ref: #api107096-Node: ui107148-Ref: #ui107247-Node: web107305-Ref: #web107394-Node: Third party add-ons107440-Ref: #third-party-add-ons107615-Ref: #diff-1107774-Node: iadd107873-Ref: #iadd107983-Node: interest108066-Ref: #interest108187-Node: irr108282-Ref: #irr108380-Node: Experimental add-ons108511-Ref: #experimental-add-ons108663-Node: autosync108944-Ref: #autosync109055-Node: chart109294-Ref: #chart109413-Node: check109484-Ref: #check109586+Node: EXAMPLES1887+Ref: #examples1987+Node: OPTIONS3633+Ref: #options3735+Node: General options4134+Ref: #general-options4259+Node: Command options6913+Ref: #command-options7064+Node: Command arguments7462+Ref: #command-arguments7616+Node: Argument files7737+Ref: #argument-files7913+Node: Special characters in arguments and queries8179+Ref: #special-characters-in-arguments-and-queries8413+Node: More escaping8864+Ref: #more-escaping9026+Node: Even more escaping9322+Ref: #even-more-escaping9516+Node: Less escaping10187+Ref: #less-escaping10349+Node: Command line tips10594+Ref: #command-line-tips10780+Node: Unicode characters11157+Ref: #unicode-characters11313+Node: Input files12725+Ref: #input-files12861+Node: Smart dates14790+Ref: #smart-dates14931+Node: Report start & end date16337+Ref: #report-start-end-date16509+Node: Report intervals17933+Ref: #report-intervals18098+Node: Period expressions18488+Ref: #period-expressions18648+Node: Depth limiting22603+Ref: #depth-limiting22747+Node: Pivoting23089+Ref: #pivoting23212+Node: Valuation24888+Ref: #valuation25017+Node: -B Cost25197+Ref: #b-cost25308+Node: -V Market value25506+Ref: #v-market-value25680+Node: -X Market value in specified commodity27112+Ref: #x-market-value-in-specified-commodity27351+Node: --value Flexible valuation27527+Ref: #value-flexible-valuation27753+Node: Effect of --value on reports31943+Ref: #effect-of---value-on-reports32159+Node: Combining -B -V -X --value37090+Ref: #combining--b--v--x---value37273+Node: Output destination37309+Ref: #output-destination37461+Node: Output format37744+Ref: #output-format37896+Node: Regular expressions38281+Ref: #regular-expressions38418+Node: QUERIES39779+Ref: #queries39881+Node: COMMANDS43843+Ref: #commands43955+Node: accounts45019+Ref: #accounts45117+Node: activity45816+Ref: #activity45926+Node: add46309+Ref: #add46408+Node: balance49153+Ref: #balance49264+Node: Classic balance report50722+Ref: #classic-balance-report50895+Node: Customising the classic balance report52264+Ref: #customising-the-classic-balance-report52492+Node: Colour support54568+Ref: #colour-support54735+Node: Flat mode54908+Ref: #flat-mode55056+Node: Depth limited balance reports55469+Ref: #depth-limited-balance-reports55654+Node: Percentages56110+Ref: #percentages56276+Node: Multicolumn balance report57413+Ref: #multicolumn-balance-report57593+Node: Budget report62907+Ref: #budget-report63050+Node: Nested budgets68252+Ref: #nested-budgets68364+Ref: #output-format-171844+Node: balancesheet71922+Ref: #balancesheet72058+Node: balancesheetequity73441+Ref: #balancesheetequity73590+Node: cashflow74151+Ref: #cashflow74279+Node: check-dates75375+Ref: #check-dates75502+Node: check-dupes75781+Ref: #check-dupes75905+Node: close76198+Ref: #close76312+Node: commodities79899+Ref: #commodities80026+Node: descriptions80108+Ref: #descriptions80236+Node: diff80417+Ref: #diff80523+Node: files81570+Ref: #files81670+Node: help81817+Ref: #help81917+Node: import82998+Ref: #import83112+Node: Importing balance assignments84005+Ref: #importing-balance-assignments84153+Node: incomestatement84802+Ref: #incomestatement84935+Node: notes86339+Ref: #notes86452+Node: payees86578+Ref: #payees86684+Node: prices86842+Ref: #prices86948+Node: print87289+Ref: #print87399+Node: print-unique91892+Ref: #print-unique92018+Node: register92303+Ref: #register92430+Node: Custom register output96602+Ref: #custom-register-output96731+Node: register-match97993+Ref: #register-match98127+Node: rewrite98478+Ref: #rewrite98593+Node: Re-write rules in a file100448+Ref: #re-write-rules-in-a-file100582+Node: Diff output format101792+Ref: #diff-output-format101961+Node: rewrite vs print --auto103053+Ref: #rewrite-vs.-print---auto103232+Node: roi103788+Ref: #roi103886+Node: stats104898+Ref: #stats104997+Node: tags105785+Ref: #tags105883+Node: test106177+Ref: #test106261+Node: ADD-ON COMMANDS107008+Ref: #add-on-commands107118+Node: Official add-ons108406+Ref: #official-add-ons108546+Node: ui108626+Ref: #ui108713+Node: web108767+Ref: #web108856+Node: Third party add-ons108902+Ref: #third-party-add-ons109077+Ref: #diff-1109236+Node: iadd109335+Ref: #iadd109445+Node: interest109527+Ref: #interest109648+Node: irr109743+Ref: #irr109841+Node: Experimental add-ons109972+Ref: #experimental-add-ons110124+Node: autosync110372+Ref: #autosync110483+Node: chart110722+Ref: #chart110841+Node: check110912+Ref: #check111014 End Tag Table
embeddedfiles/hledger.txt view
@@ -19,12 +19,12 @@ Tested on unix, mac, windows, hledger aims to be a reliable, practical tool for daily use. - This is hledger's command-line interface (there are also curses and web- interfaces). Its basic function is to read a plain text file describ-- ing financial transactions (in accounting terms, a general journal) and- print useful reports on standard output, or export them as CSV.- hledger can also read some other file formats such as CSV files, trans-- lating them to journal format. Additionally, hledger lists other+ This is hledger's command-line interface (there are also terminal and+ web interfaces). Its basic function is to read a plain text file de-+ scribing financial transactions (in accounting terms, a general jour-+ nal) and print useful reports on standard output, or export them as+ CSV. hledger can also read some other file formats such as CSV files,+ translating them to journal format. Additionally, hledger lists other hledger-* executables found in the user's $PATH and can invoke them as subcommands. @@ -558,7 +558,7 @@ -p "weekly from 2009/1/1 to 2009/4/1" -- starts on 2008/12/29, closest pre-- ceeding Monday+ ceding Monday -p "monthly in 2008/11/25" -- starts on 2018/11/01 -p "quarterly from 2009-05-05 to@@ -581,7 +581,7 @@ will have boundaries on 2008/01/01, 2008/03/01, ... -p "every 2 weeks" -- starts on closest- preceeding Monday+ preceding Monday -p "every 5 month from 2009/03" -- pe- riods will have boundaries on 2009/03/01, 2009/08/01, ...@@ -1454,18 +1454,45 @@ Flat-mode balance reports, which normally show exclusive balances, show inclusive balances at the depth limit. + Percentages+ With -% or --percent, balance reports show each account's value ex-+ pressed as a percentage of the column's total. This is useful to get+ an overview of the relative sizes of account balances. For example to+ obtain an overview of expenses:++ $ hledger balance expenses -%+ 100.0 % expenses+ 50.0 % food+ 50.0 % supplies+ --------------------+ 100.0 %++ Note that --tree does not have an effect on -%. The percentages are+ always relative to the total sum of each column, they are never rela-+ tive to the parent account.++ Since the percentages are relative to the columns sum, it is usually+ not useful to calculate percentages if the signs of the amounts are+ mixed. Although the results are technically correct, they are most+ likely useless. Especially in a balance report that sums up to zero+ (eg hledger balance -B) all percentage values will be zero.++ This flag does not work if the report contains any mixed commodity ac-+ counts. If there are mixed commodity accounts in the report be sure to+ use -V or -B to coerce the report into using a single commodity.+ Multicolumn balance report- Multicolumn or tabular balance reports are a very useful hledger fea-- ture, and usually the preferred style. They share many of the above- features, but they show the report as a table, with columns represent-- ing time periods. This mode is activated by providing a reporting in-+ Multicolumn or tabular balance reports are a very useful hledger fea-+ ture, and usually the preferred style. They share many of the above+ features, but they show the report as a table, with columns represent-+ ing time periods. This mode is activated by providing a reporting in- terval. - There are three types of multicolumn balance report, showing different+ There are three types of multicolumn balance report, showing different information: 1. By default: each column shows the sum of postings in that period, ie- the account's change of balance in that period. This is useful eg+ the account's change of balance in that period. This is useful eg for a monthly income statement: $ hledger balance --quarterly income expenses -E@@ -1481,7 +1508,7 @@ || $-1 $1 0 0 2. With --cumulative: each column shows the ending balance for that pe-- riod, accumulating the changes across periods, starting from 0 at+ riod, accumulating the changes across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative@@ -1497,8 +1524,8 @@ || $-1 0 0 0 3. With --historical/-H: each column shows the actual historical ending- balance for that period, accumulating the changes across periods,- starting from the actual balance at the report start date. This is+ balance for that period, accumulating the changes across periods,+ starting from the actual balance at the report start date. This is useful eg for a multi-period balance sheet, and when you are showing only the data after a certain start date: @@ -1517,26 +1544,26 @@ Note that --cumulative or --historical/-H disable --row-total/-T, since summing end balances generally does not make sense. - Multicolumn balance reports display accounts in flat mode by default;+ Multicolumn balance reports display accounts in flat mode by default; to see the hierarchy, use --tree. - With a reporting interval (like --quarterly above), the report- start/end dates will be adjusted if necessary so that they encompass+ With a reporting interval (like --quarterly above), the report+ start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last peri- ods will be "full" and comparable to the others. - The -E/--empty flag does two things in multicolumn balance reports:+ The -E/--empty flag does two things in multicolumn balance reports: first, the report will show all columns within the specified report pe-- riod (without -E, leading and trailing columns with all zeroes are not- shown). Second, all accounts which existed at the report start date- will be considered, not just the ones with activity during the report- period (use -E to include low-activity accounts which would otherwise+ riod (without -E, leading and trailing columns with all zeroes are not+ shown). Second, all accounts which existed at the report start date+ will be considered, not just the ones with activity during the report+ period (use -E to include low-activity accounts which would otherwise would be omitted). The -T/--row-total flag adds an additional column showing the total for each row. - The -A/--average flag adds a column showing the average value in each+ The -A/--average flag adds a column showing the average value in each row. Here's an example of all three:@@ -1560,20 +1587,20 @@ Limitations: In multicolumn reports the -V/--value flag uses the market price on the- report end date, for all columns (not the price on each column's end+ report end date, for all columns (not the price on each column's end date). - Eliding of boring parent accounts in tree mode, as in the classic bal-+ Eliding of boring parent accounts in tree mode, as in the classic bal- ance report, is not yet supported in multicolumn reports. Budget report- With --budget, extra columns are displayed showing budget goals for- each account and period, if any. Budget goals are defined by periodic+ With --budget, extra columns are displayed showing budget goals for+ each account and period, if any. Budget goals are defined by periodic transactions. This is very useful for comparing planned and actual in-- come, expenses, time usage, etc. --budget is most often combined with+ come, expenses, time usage, etc. --budget is most often combined with a report interval. - For example, you can take average monthly expenses in the common ex-+ For example, you can take average monthly expenses in the common ex- pense categories to construct a minimal monthly budget: ;; Budget@@ -1620,25 +1647,25 @@ Note this is different from a normal balance report in several ways: - o Only accounts with budget goals during the report period are shown,+ o Only accounts with budget goals during the report period are shown, by default. - o In each column, in square brackets after the actual amount, budgeted+ o In each column, in square brackets after the actual amount, budgeted amounts are shown, along with the percentage of budget used. - o All parent accounts are always shown, even in flat mode. Eg assets,+ o All parent accounts are always shown, even in flat mode. Eg assets, assets:bank, and expenses above. - o Amounts always include all subaccounts, budgeted or unbudgeted, even+ o Amounts always include all subaccounts, budgeted or unbudgeted, even in flat mode. This means that the numbers displayed will not always add up! Eg above,- the expenses actual amount includes the gifts and supplies transac-- tions, but the expenses:gifts and expenses:supplies accounts are not+ the expenses actual amount includes the gifts and supplies transac-+ tions, but the expenses:gifts and expenses:supplies accounts are not shown, as they have no budget amounts declared. - This can be confusing. When you need to make things clearer, use the- -E/--empty flag, which will reveal all accounts including unbudgeted+ This can be confusing. When you need to make things clearer, use the+ -E/--empty flag, which will reveal all accounts including unbudgeted ones, giving the full picture. Eg: $ hledger balance -M --budget --empty@@ -1680,12 +1707,12 @@ For more examples, see Budgeting and Forecasting. Nested budgets- You can add budgets to any account in your account hierarchy. If you+ You can add budgets to any account in your account hierarchy. If you have budgets on both parent account and some of its children, then bud-- get(s) of the child account(s) would be added to the budget of their+ get(s) of the child account(s) would be added to the budget of their parent, much like account balances behave. - In the most simple case this means that once you add a budget to any+ In the most simple case this means that once you add a budget to any account, all its parents would have budget as well. To illustrate this, consider the following budget:@@ -1695,13 +1722,13 @@ expenses:personal:electronics $100.00 liabilities - With this, monthly budget for electronics is defined to be $100 and- budget for personal expenses is an additional $1000, which implicity+ With this, monthly budget for electronics is defined to be $100 and+ budget for personal expenses is an additional $1000, which implicity means that budget for both expenses:personal and expenses is $1100. - Transactions in expenses:personal:electronics will be counted both to-+ Transactions in expenses:personal:electronics will be counted both to- wards its $100 budget and $1100 of expenses:personal , and transactions- in any other subaccount of expenses:personal would be counted towards+ in any other subaccount of expenses:personal would be counted towards only towards the budget of expenses:personal. For example, let's consider these transactions:@@ -1727,9 +1754,9 @@ expenses:personal $30.00 liabilities - As you can see, we have transactions in expenses:personal:electron-- ics:upgrades and expenses:personal:train tickets, and since both of- these accounts are without explicitly defined budget, these transac-+ As you can see, we have transactions in expenses:personal:electron-+ ics:upgrades and expenses:personal:train tickets, and since both of+ these accounts are without explicitly defined budget, these transac- tions would be counted towards budgets of expenses:personal:electronics and expenses:personal accordingly: @@ -1745,7 +1772,7 @@ -------------------------------++------------------------------- || 0 [ 0] - And with --empty, we can get a better picture of budget allocation and+ And with --empty, we can get a better picture of budget allocation and consumption: $ hledger balance --budget -M --empty@@ -1763,17 +1790,17 @@ || 0 [ 0] Output format- The balance command supports output destination and output format se-+ The balance command supports output destination and output format se- lection. balancesheet balancesheet, bs This command displays a simple balance sheet, showing historical ending- balances of asset and liability accounts (ignoring any report begin- date). It assumes that these accounts are under a top-level asset or+ balances of asset and liability accounts (ignoring any report begin+ date). It assumes that these accounts are under a top-level asset or liability account (case insensitive, plural forms also allowed). - Note this report shows all account balances with normal positive sign+ Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). @@ -1799,12 +1826,13 @@ 0 With a reporting interval, multiple columns will be shown, one for each- report period. As with multicolumn balance reports, you can alter the- report mode with --change/--cumulative/--historical. Normally bal-- ancesheet shows historical ending balances, which is what you need for- a balance sheet; note this means it ignores report begin dates (and- -T/--row-total, since summing end balances generally does not make- sense).+ report period. As with multicolumn balance reports, you can alter the+ report mode with --change/--cumulative/--historical. Normally bal-+ ancesheet shows historical ending balances, which is what you need for+ a balance sheet; note this means it ignores report begin dates (and+ -T/--row-total, since summing end balances generally does not make+ sense). Instead of absolute values percentages can be displayed with+ -%. This command also supports output destination and output format selec- tion.@@ -1868,79 +1896,80 @@ With a reporting interval, multiple columns will be shown, one for each report period. Normally cashflow shows changes in assets per period, though as with multicolumn balance reports you can alter the report- mode with --change/--cumulative/--historical.+ mode with --change/--cumulative/--historical. Instead of absolute val-+ ues percentages can be displayed with -%. - This command also supports output destination and output format selec-+ This command also supports output destination and output format selec- tion. check-dates check-dates- Check that transactions are sorted by increasing date. With --date2,- checks secondary dates instead. With --strict, dates must also be- unique. With a query, only matched transactions' dates are checked.+ Check that transactions are sorted by increasing date. With --date2,+ checks secondary dates instead. With --strict, dates must also be+ unique. With a query, only matched transactions' dates are checked. Reads the default journal file, or another specified with -f. check-dupes check-dupes- Reports account names having the same leaf but different prefixes. In- other words, two or more leaves that are categorized differently.+ Reports account names having the same leaf but different prefixes. In+ other words, two or more leaves that are categorized differently. Reads the default journal file, or another specified as an argument. An example: http://stefanorodighiero.net/software/hledger-dupes.html close close, equity- Prints a "closing balances" transaction and an "opening balances"+ Prints a "closing balances" transaction and an "opening balances" transaction that bring account balances to and from zero, respectively. Useful for bringing asset/liability balances forward into a new journal- file, or for closing out revenues/expenses to retained earnings at the+ file, or for closing out revenues/expenses to retained earnings at the end of a period. - The closing transaction transfers balances to "equity:closing bal-- ances". The opening transaction transfers balances from "equity:open-+ The closing transaction transfers balances to "equity:closing bal-+ ances". The opening transaction transfers balances from "equity:open- ing balances". You can choose to print just one of the transactions by using the --opening or --closing flag. If you split your journal files by time (eg yearly), you will typically- run this command at the end of the year, and save the closing transac-- tion as last entry of the old file, and the opening transaction as the- first entry of the new file. This makes the files self contained, so- that correct balances are reported no matter which of them are loaded.- Ie, if you load just one file, the balances are initialised correctly;- or if you load several files, the redundant closing/opening transac-- tions cancel each other out. (They will show up in print or register- reports; you can exclude them with a query like not:desc:'(open-+ run this command at the end of the year, and save the closing transac-+ tion as last entry of the old file, and the opening transaction as the+ first entry of the new file. This makes the files self contained, so+ that correct balances are reported no matter which of them are loaded.+ Ie, if you load just one file, the balances are initialised correctly;+ or if you load several files, the redundant closing/opening transac-+ tions cancel each other out. (They will show up in print or register+ reports; you can exclude them with a query like not:desc:'(open- ing|closing) balances'.) If you're running a business, you might also use this command to "close- the books" at the end of an accounting period, transferring income- statement account balances to retained earnings. (You may want to+ the books" at the end of an accounting period, transferring income+ statement account balances to retained earnings. (You may want to change the equity account name to something like "equity:retained earn- ings".) - By default, the closing transaction is dated yesterday, the balances- are calculated as of end of yesterday, and the opening transaction is- dated today. To close on some other date, use: hledger close -e OPEN-- INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019.+ By default, the closing transaction is dated yesterday, the balances+ are calculated as of end of yesterday, and the opening transaction is+ dated today. To close on some other date, use: hledger close -e OPEN-+ INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. You can also use -p or date:PERIOD (any starting date is ignored). - Both transactions will include balance assertions for the closed/re-+ Both transactions will include balance assertions for the closed/re- opened accounts. You probably shouldn't use status or realness filters- (like -C or -R or status:) with this command, or the generated balance- assertions will depend on these flags. Likewise, if you run this com-- mand with --auto, the balance assertions will probably always require+ (like -C or -R or status:) with this command, or the generated balance+ assertions will depend on these flags. Likewise, if you run this com-+ mand with --auto, the balance assertions will probably always require --auto. - When account balances have cost information (transaction prices), the- closing/opening transactions will preserve it, so that eg balance -B+ When account balances have cost information (transaction prices), the+ closing/opening transactions will preserve it, so that eg balance -B reports will not be affected. Examples: - Carrying asset/liability balances into a new file for 2019, all from+ Carrying asset/liability balances into a new file for 2019, all from command line: - Warning: we use >> here to append; be careful not to type a single >+ Warning: we use >> here to append; be careful not to type a single > which would wipe your journal! $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal@@ -1989,18 +2018,18 @@ diff diff- Compares a particular account's transactions in two input files. It+ 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. More precisely, for each posting affecting this account in either file,- it looks for a corresponding posting in the other file which posts the- same amount to the same account (ignoring date, description, etc.)+ it looks for a corresponding posting in the other file which posts the+ same amount to the same account (ignoring date, description, etc.) Since postings not transactions are compared, this also works when mul- tiple bank transactions have been combined into a single journal entry. This is useful eg if you have downloaded an account's transactions from- your bank (eg as CSV data). When hledger and your bank disagree about+ your bank (eg as CSV data). When hledger and your bank disagree about the account balance, you can compare the bank data with your journal to find out the cause. @@ -2018,27 +2047,27 @@ files files- List all files included in the journal. With a REGEX argument, only+ List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. help help Show any of the hledger manuals. - The help command displays any of the main hledger manuals, in one of- several ways. Run it with no argument to list the manuals, or provide+ The help command displays any of the main hledger manuals, in one of+ several ways. Run it with no argument to list the manuals, or provide a full or partial manual name to select one. - hledger manuals are available in several formats. hledger help will- use the first of these display methods that it finds: info, man,- $PAGER, less, stdout (or when non-interactive, just stdout). You can+ hledger manuals are available in several formats. hledger help will+ use the first of these display methods that it finds: info, man,+ $PAGER, less, stdout (or when non-interactive, just stdout). You can force a particular viewer with the --info, --man, --pager, --cat flags. Examples: $ hledger help Please choose a manual by typing "hledger help MANUAL" (a substring is ok).- Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot+ Manuals: hledger hledger-ui hledger-web journal csv timeclock timedot $ hledger help h --man @@ -2058,9 +2087,10 @@ import import- Read new transactions added to each FILE since last run, and add them- to the main journal file. Or with --dry-run, just print the transac-- tions that would be added.+ Read new transactions added to each FILE since last run, and add them+ to the main journal file. Or with --dry-run, just print the transac-+ tions that would be added. Or with --catchup, just mark all of the+ FILEs' transactions as imported, without actually importing any. The input files are specified as arguments - no need to write -f before each one. So eg to add new transactions from all CSV files to the main@@ -2126,9 +2156,10 @@ With a reporting interval, multiple columns will be shown, one for each report period. Normally incomestatement shows revenues/expenses per period, though as with multicolumn balance reports you can alter the- report mode with --change/--cumulative/--historical.+ report mode with --change/--cumulative/--historical. Instead of abso-+ lute values percentages can be displayed with -%. - This command also supports output destination and output format selec-+ This command also supports output destination and output format selec- tion. notes@@ -2156,10 +2187,11 @@ prices prices- Print market price directives from the journal. With --costs, also- print synthetic market prices based on transaction prices. With --in-- verted-costs, also print inverse prices based on transaction prices.- Prices (and postings providing prices) can be filtered by a query.+ Print market price directives from the journal. With --costs, also+ print synthetic market prices based on transaction prices. With --in-+ verted-costs, also print inverse prices based on transaction prices.+ Prices (and postings providing prices) can be filtered by a query.+ Price amounts are always displayed with their full precision. print print, txns, p@@ -2577,46 +2609,47 @@ test Run built-in unit tests. - This command runs the unit tests built in to hledger-lib and hledger,- printing test names and results on stdout. If any test fails, the exit- code will be non-zero.+ This command runs the unit tests built in to hledger and hledger-lib,+ printing the results on stdout. If any test fails, the exit code will+ be non-zero. - Test names include a group prefix. If a (exact, case sensitive) group- prefix, or a full test name is provided as the first argument, only- that group or test is run.+ This is mainly used by hledger developers, but you can also use it to+ sanity-check the installed hledger executable on your platform. All+ tests are expected to pass - if you ever see a failure, please report+ as a bug! - If a numeric second argument is provided, it will set the randomness- seed, for repeatable results from tests using randomness (currently- none of them).+ This command also accepts tasty test runner options, written after a --+ (double hyphen). Eg to run only the tests in Hledger.Data.Amount, with+ ANSI colour codes disabled: - This is mainly used by developers, but it's nice to be able to sanity-- check your installed hledger executable at any time. All tests are ex-- pected to pass - if you ever see otherwise, something has gone wrong,- please report a bug!+ $ hledger test -- -pData.Amount --color=never + For help on these, see https://github.com/feuerbach/tasty#options (--+ --help currently doesn't show them).+ ADD-ON COMMANDS- hledger also searches for external add-on commands, and will include+ hledger also searches for external add-on commands, and will include these in the commands list. These are programs or scripts in your PATH- whose name starts with hledger- and ends with a recognised file exten-+ whose name starts with hledger- and ends with a recognised file exten- sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). - Add-ons can be invoked like any hledger command, but there are a few+ Add-ons can be invoked like any hledger command, but there are a few things to be aware of. Eg if the hledger-web add-on is installed, - o hledger -h web shows hledger's help, while hledger web -h shows+ o hledger -h web shows hledger's help, while hledger web -h shows hledger-web's help. - o Flags specific to the add-on must have a preceding -- to hide them- from hledger. So hledger web --serve --port 9000 will be rejected;+ o Flags specific to the add-on must have a preceding -- to hide them+ from hledger. So hledger web --serve --port 9000 will be rejected; you must use hledger web -- --serve --port 9000. o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - Add-ons are a relatively easy way to add local features or experiment- with new ideas. They can be written in any language, but haskell- scripts have a big advantage: they can use the same hledger (and- haskell) library functions that built-in commands do, for command-line+ Add-ons are a relatively easy way to add local features or experiment+ with new ideas. They can be written in any language, but haskell+ scripts have a big advantage: they can use the same hledger (and+ haskell) library functions that built-in commands do, for command-line options, journal parsing, reporting, etc. Here are some hledger add-ons available:@@ -2624,17 +2657,14 @@ Official add-ons These are maintained and released along with hledger. - api- hledger-api serves hledger data as a JSON web API.- ui- hledger-ui provides an efficient curses-style interface.+ hledger-ui provides an efficient terminal interface. web hledger-web provides a simple web interface. Third party add-ons- These are maintained separately, and usually updated shortly after a+ These are maintained separately, and usually updated shortly after a hledger release. diff@@ -2642,8 +2672,8 @@ journal file and another. iadd- hledger-iadd is a curses-style, more interactive replacement for the- add command.+ hledger-iadd is a more interactive, terminal UI replacement for the add+ command. interest hledger-interest generates interest transactions for an account accord-@@ -2654,10 +2684,9 @@ count, but it's superseded now by the built-in roi command. Experimental add-ons- These are available in source form in the hledger repo's bin/ direc-- tory; installing them is pretty easy. They may be less mature and doc-- umented than built-in commands. Reading and tweaking these is a good- way to start making your own!+ These are available in source form in the hledger repo's bin/ direc-+ tory. They may be less mature and documented than built-in commands.+ Reading and tweaking these is a good way to start making your own! autosync hledger-autosync is a symbolic link for easily running ledger-autosync,@@ -2777,7 +2806,7 @@ COPYRIGHT- Copyright (C) 2007-2016 Simon Michael.+ Copyright (C) 2007-2019 Simon Michael. Released under GNU GPL v3 or later. @@ -2790,4 +2819,4 @@ -hledger 1.15.2 September 2019 hledger(1)+hledger 1.16 December 2019 hledger(1)
embeddedfiles/hledger_csv.5 view
@@ -1,364 +1,979 @@--.TH "hledger_csv" "5" "September 2019" "hledger 1.15.2" "hledger User Manuals"----.SH NAME-.PP-CSV - how hledger reads CSV data, and the CSV rules file format-.SH DESCRIPTION-.PP-hledger can read CSV (comma-separated value) files as if they were-journal files, automatically converting each CSV record into a-transaction.-(To learn about \f[I]writing\f[R] CSV, see CSV output.)-.PP-Converting CSV to transactions requires some special conversion rules.-These do several things:-.IP \[bu] 2-they describe the layout and format of the CSV data-.IP \[bu] 2-they can customize the generated journal entries using a simple-templating language-.IP \[bu] 2-they can add refinements based on patterns in the CSV data, eg-categorizing transactions with more detailed account names.-.PP-When reading a CSV file named \f[C]FILE.csv\f[R], hledger looks for a-conversion rules file named \f[C]FILE.csv.rules\f[R] in the same-directory.-You can override this with the \f[C]--rules-file\f[R] option.-If the rules file does not exist, hledger will auto-create one with some-example rules, which you\[aq]ll need to adjust.-.PP-At minimum, the rules file must identify the date and amount fields.-It\[aq]s often necessary to specify the date format, and the number of-header lines to skip, also.-Eg:-.IP-.nf-\f[C]-fields date, _, _, amount-date-format %d/%m/%Y-skip 1-\f[R]-.fi-.PP-A more complete example:-.IP-.nf-\f[C]-# hledger CSV rules for amazon.com order history--# sample:-# \[dq]Date\[dq],\[dq]Type\[dq],\[dq]To/From\[dq],\[dq]Name\[dq],\[dq]Status\[dq],\[dq]Amount\[dq],\[dq]Fees\[dq],\[dq]Transaction ID\[dq]-# \[dq]Jul 29, 2012\[dq],\[dq]Payment\[dq],\[dq]To\[dq],\[dq]Adapteva, Inc.\[dq],\[dq]Completed\[dq],\[dq]$25.00\[dq],\[dq]$0.00\[dq],\[dq]17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL\[dq]--# skip one header line-skip 1--# name the csv fields (and assign the transaction\[aq]s date, amount and code)-fields date, _, toorfrom, name, amzstatus, amount, fees, code--# how to parse the date-date-format %b %-d, %Y--# combine two fields to make the description-description %toorfrom %name--# save these fields as tags-comment status:%amzstatus, fees:%fees--# set the base account for all transactions-account1 assets:amazon--# flip the sign on the amount-amount -%amount-\f[R]-.fi-.PP-For more examples, see Convert CSV files.-.SH CSV RULES-.PP-The following seven kinds of rule can appear in the rules file, in any-order.-Blank lines and lines beginning with \f[C]#\f[R] or \f[C];\f[R] are-ignored.-.SS skip-.PP-\f[C]skip\f[R]\f[I]\f[CI]N\f[I]\f[R]-.PP-Skip this number of CSV records at the beginning.-You\[aq]ll need this whenever your CSV data contains header lines.-Eg:-.IP-.nf-\f[C]-# ignore the first CSV line-skip 1-\f[R]-.fi-.SS date-format-.PP-\f[C]date-format\f[R]\f[I]\f[CI]DATEFMT\f[I]\f[R]-.PP-When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[R]-(or \f[C]YYYY-MM-DD\f[R] or \f[C]YYYY.MM.DD\f[R]), you\[aq]ll need to-specify the format.-DATEFMT is a strptime-like date parsing pattern, which must parse the-date field values completely.-Examples:-.IP-.nf-\f[C]-# for dates like \[dq]11/06/2013\[dq]:-date-format %m/%d/%Y-\f[R]-.fi-.IP-.nf-\f[C]-# for dates like \[dq]6/11/2013\[dq] (note the - to make leading zeros optional):-date-format %-d/%-m/%Y-\f[R]-.fi-.IP-.nf-\f[C]-# for dates like \[dq]2013-Nov-06\[dq]:-date-format %Y-%h-%d-\f[R]-.fi-.IP-.nf-\f[C]-# for dates like \[dq]11/6/2013 11:32 PM\[dq]:-date-format %-m/%-d/%Y %l:%M %p-\f[R]-.fi-.SS field list-.PP-\f[C]fields\f[R]\f[I]\f[CI]FIELDNAME1\f[I]\f[R],-\f[I]\f[CI]FIELDNAME2\f[I]\f[R]...-.PP-This (a) names the CSV fields, in order (names may not contain-whitespace; uninteresting names may be left blank), and (b) assigns them-to journal entry fields if you use any of these standard field names:-\f[C]date\f[R], \f[C]date2\f[R], \f[C]status\f[R], \f[C]code\f[R],-\f[C]description\f[R], \f[C]comment\f[R], \f[C]account1\f[R],-\f[C]account2\f[R], \f[C]amount\f[R], \f[C]amount-in\f[R],-\f[C]amount-out\f[R], \f[C]currency\f[R], \f[C]balance\f[R],-\f[C]balance1\f[R], \f[C]balance2\f[R].-Eg:-.IP-.nf-\f[C]-# use the 1st, 2nd and 4th CSV fields as the entry\[aq]s date, description and amount,-# and give the 7th and 8th fields meaningful names for later reference:-#-# CSV field:-# 1 2 3 4 5 6 7 8-# entry field:-fields date, description, , amount, , , somefield, anotherfield-\f[R]-.fi-.SS field assignment-.PP-\f[I]\f[CI]ENTRYFIELDNAME\f[I]\f[R] \f[I]\f[CI]FIELDVALUE\f[I]\f[R]-.PP-This sets a journal entry field (one of the standard names above) to the-given text value, which can include CSV field values interpolated by-name (\f[C]%CSVFIELDNAME\f[R]) or 1-based position (\f[C]%N\f[R]).-Eg:-.IP-.nf-\f[C]-# set the amount to the 4th CSV field with \[dq]USD \[dq] prepended-amount USD %4-\f[R]-.fi-.IP-.nf-\f[C]-# combine three fields to make a comment (containing two tags)-comment note: %somefield - %anotherfield, date: %1-\f[R]-.fi-.PP-Field assignments can be used instead of or in addition to a field list.-.PP-Note, interpolation strips any outer whitespace, so a CSV value like-\f[C]\[dq] 1 \[dq]\f[R] becomes \f[C]1\f[R] when interpolated (#1051).-.SS conditional block-.PP-\f[C]if\f[R] \f[I]\f[CI]PATTERN\f[I]\f[R]-.PD 0-.P-.PD-\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[R]...-.PP-\f[C]if\f[R]-.PD 0-.P-.PD-\f[I]\f[CI]PATTERN\f[I]\f[R]-.PD 0-.P-.PD-\f[I]\f[CI]PATTERN\f[I]\f[R]...-.PD 0-.P-.PD-\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[R]...-.PP-This applies one or more field assignments, only to those CSV records-matched by one of the PATTERNs.-The patterns are case-insensitive regular expressions which match-anywhere within the whole CSV record (it\[aq]s not yet possible to match-within a specific field).-When there are multiple patterns they can be written on separate lines,-unindented.-The field assignments are on separate lines indented by at least one-space.-Examples:-.IP-.nf-\f[C]-# if the CSV record contains \[dq]groceries\[dq], set account2 to \[dq]expenses:groceries\[dq]-if groceries- account2 expenses:groceries-\f[R]-.fi-.IP-.nf-\f[C]-# if the CSV record contains any of these patterns, set account2 and comment as shown-if-monthly service fee-atm transaction fee-banking thru software- account2 expenses:business:banking- comment XXX deductible ? check it-\f[R]-.fi-.SS include-.PP-\f[C]include\f[R]\f[I]\f[CI]RULESFILE\f[I]\f[R]-.PP-Include another rules file at this point.-\f[C]RULESFILE\f[R] is either an absolute file path or a path relative-to the current file\[aq]s directory.-Eg:-.IP-.nf-\f[C]-# rules reused with several CSV files-include common.rules-\f[R]-.fi-.SS newest-first-.PP-\f[C]newest-first\f[R]-.PP-Consider adding this rule if all of the following are true: you might be-processing just one day of data, your CSV records are in reverse-chronological order (newest first), and you care about preserving the-order of same-day transactions.-It usually isn\[aq]t needed, because hledger autodetects the CSV order,-but when all CSV records have the same date it will assume they are-oldest first.-.SH CSV TIPS-.SS CSV ordering-.PP-The generated journal entries will be sorted by date.-The order of same-day entries will be preserved (except in the special-case where you might need \f[C]newest-first\f[R], see above).-.SS CSV accounts-.PP-Each journal entry will have two postings, to \f[C]account1\f[R] and-\f[C]account2\f[R] respectively.-It\[aq]s not yet possible to generate entries with more than two-postings.-It\[aq]s conventional and recommended to use \f[C]account1\f[R] for the-account whose CSV we are reading.-.SS CSV amounts-.PP-A transaction amount must be set, in one of these ways:-.IP \[bu] 2-with an \f[C]amount\f[R] field assignment, which sets the first-posting\[aq]s amount-.IP \[bu] 2-(When the CSV has debit and credit amounts in separate fields:)-.PD 0-.P-.PD-with field assignments for the \f[C]amount-in\f[R] and-\f[C]amount-out\f[R] pseudo fields (both of them).-Whichever one has a value will be used, with appropriate sign.-If both contain a value, it might not work so well.-.IP \[bu] 2-or implicitly by means of a balance assignment (see below).-.PP-There is some special handling for sign in amounts:-.IP \[bu] 2-If an amount value is parenthesised, it will be de-parenthesised and-sign-flipped.-.IP \[bu] 2-If an amount value begins with a double minus sign, those will cancel-out and be removed.-.PP-If the currency/commodity symbol is provided as a separate CSV field,-assign it to the \f[C]currency\f[R] pseudo field; the symbol will be-prepended to the amount (TODO: when there is an amount).-Or, you can use an \f[C]amount\f[R] field assignment for more control,-eg:-.IP-.nf-\f[C]-fields date,description,currency,amount-amount %amount %currency-\f[R]-.fi-.SS CSV balance assertions/assignments-.PP-If the CSV includes a running balance, you can assign that to one of the-pseudo fields \f[C]balance\f[R] (or \f[C]balance1\f[R]) or-\f[C]balance2\f[R].-This will generate a balance assertion (or if the amount is left empty,-a balance assignment), on the first or second posting, whenever the-running balance field is non-empty.-(TODO: #1000)-.SS Reading multiple CSV files-.PP-You can read multiple CSV files at once using multiple \f[C]-f\f[R]-arguments on the command line, and hledger will look for a-correspondingly-named rules file for each.-Note if you use the \f[C]--rules-file\f[R] option, this one rules file-will be used for all the CSV files being read.-.SS Valid CSV-.PP-hledger follows RFC 4180, with the addition of a customisable separator-character.-.PP-Some things to note:-.PP-When quoting fields,-.IP \[bu] 2-you must use double quotes, not single quotes-.IP \[bu] 2-spaces outside the quotes are not allowed.---.SH "REPORTING BUGS"-Report bugs at http://bugs.hledger.org-(or on the #hledger IRC channel or hledger mail list)--.SH AUTHORS-Simon Michael <simon@joyful.com> and contributors--.SH COPYRIGHT--Copyright (C) 2007-2016 Simon Michael.+.\"t++.TH "hledger_csv" "5" "December 2019" "hledger 1.16" "hledger User Manuals"++++.SH NAME+.PP+CSV - how hledger reads CSV data, and the CSV rules file format+.SH DESCRIPTION+.PP+hledger can read CSV (comma-separated value, or character-separated+value) files as if they were journal files, automatically converting+each CSV record into a transaction.+(To learn about \f[I]writing\f[R] CSV, see CSV output.)+.PP+We describe each CSV file\[aq]s format with a corresponding \f[I]rules+file\f[R].+By default this is named like the CSV file with a \f[C].rules\f[R]+extension added.+Eg when reading \f[C]FILE.csv\f[R], hledger also looks for+\f[C]FILE.csv.rules\f[R] in the same directory.+You can specify a different rules file with the \f[C]--rules-file\f[R]+option.+If a rules file is not found, hledger will create a sample rules file,+which you\[aq]ll need to adjust.+.PP+This file contains rules describing the CSV data (header line, fields+layout, date format etc.), and how to construct hledger journal entries+(transactions) from it.+Often there will also be a list of conditional rules for categorising+transactions based on their descriptions.+Here\[aq]s an overview of the CSV rules; these are described more fully+below, after the examples:+.PP+.TS+tab(@);+l l.+T{+\f[B]\f[CB]skip\f[B]\f[R]+T}@T{+skip one or more header lines or matched CSV records+T}+T{+\f[B]\f[CB]fields\f[B]\f[R]+T}@T{+name CSV fields, assign them to hledger fields+T}+T{+\f[B]field assignment\f[R]+T}@T{+assign a value to one hledger field, with interpolation+T}+T{+\f[B]\f[CB]if\f[B]\f[R]+T}@T{+apply some rules to matched CSV records+T}+T{+\f[B]\f[CB]end\f[B]\f[R]+T}@T{+skip the remaining CSV records+T}+T{+\f[B]\f[CB]date-format\f[B]\f[R]+T}@T{+describe the format of CSV dates+T}+T{+\f[B]\f[CB]newest-first\f[B]\f[R]+T}@T{+disambiguate record order when there\[aq]s only one date+T}+T{+\f[B]\f[CB]include\f[B]\f[R]+T}@T{+inline another CSV rules file+T}+.TE+.PP+There\[aq]s also a Convert CSV files tutorial on hledger.org.+.SH EXAMPLES+.PP+Here are some sample hledger CSV rules files.+See also the full collection at:+.PD 0+.P+.PD+https://github.com/simonmichael/hledger/tree/master/examples/csv+.SS Basic+.PP+At minimum, the rules file must identify the date and amount fields, and+often it also specifies the date format and how many header lines there+are.+Here\[aq]s a simple CSV file and a rules file for it:+.IP+.nf+\f[C]+Date, Description, Id, Amount+12/11/2019, Foo, 123, 10.23+\f[R]+.fi+.IP+.nf+\f[C]+# basic.csv.rules+skip 1+fields date, description, _, amount+date-format %d/%m/%Y+\f[R]+.fi+.IP+.nf+\f[C]+$ hledger print -f basic.csv+2019/11/12 Foo+ expenses:unknown 10.23+ income:unknown -10.23+\f[R]+.fi+.PP+Default account names are chosen, since we didn\[aq]t set them.+.SS Bank of Ireland+.PP+Here\[aq]s a CSV with two amount fields (Debit and Credit), and a+balance field, which we can use to add balance assertions, which is not+necessary but provides extra error checking:+.IP+.nf+\f[C]+Date,Details,Debit,Credit,Balance+07/12/2012,LODGMENT 529898,,10.0,131.21+07/12/2012,PAYMENT,5,,126+\f[R]+.fi+.IP+.nf+\f[C]+# bankofireland-checking.csv.rules++# skip the header line+skip++# name the csv fields, and assign some of them as journal entry fields+fields date, description, amount-out, amount-in, balance++# We generate balance assertions by assigning to \[dq]balance\[dq]+# above, but you may sometimes need to remove these because:+#+# - the CSV balance differs from the true balance, +# by up to 0.0000000000005 in my experience+#+# - it is sometimes calculated based on non-chronological ordering,+# eg when multiple transactions clear on the same day++# date is in UK/Ireland format+date-format %d/%m/%Y++# set the currency+currency EUR++# set the base account for all txns+account1 assets:bank:boi:checking+\f[R]+.fi+.IP+.nf+\f[C]+$ hledger -f bankofireland-checking.csv print+2012/12/07 LODGMENT 529898+ assets:bank:boi:checking EUR10.0 = EUR131.2+ income:unknown EUR-10.0++2012/12/07 PAYMENT+ assets:bank:boi:checking EUR-5.0 = EUR126.0+ expenses:unknown EUR5.0+\f[R]+.fi+.PP+The balance assertions don\[aq]t raise an error above, because we\[aq]re+reading directly from CSV, but they will be checked if these entries are+imported into a journal file.+.SS Amazon+.PP+Here we convert amazon.com order history, and use an if block to+generate a third posting if there\[aq]s a fee.+(In practice you\[aq]d probably get this data from your bank instead,+but it\[aq]s an example.)+.IP+.nf+\f[C]+\[dq]Date\[dq],\[dq]Type\[dq],\[dq]To/From\[dq],\[dq]Name\[dq],\[dq]Status\[dq],\[dq]Amount\[dq],\[dq]Fees\[dq],\[dq]Transaction ID\[dq]+\[dq]Jul 29, 2012\[dq],\[dq]Payment\[dq],\[dq]To\[dq],\[dq]Foo.\[dq],\[dq]Completed\[dq],\[dq]$20.00\[dq],\[dq]$0.00\[dq],\[dq]16000000000000DGLNJPI1P9B8DKPVHL\[dq]+\[dq]Jul 30, 2012\[dq],\[dq]Payment\[dq],\[dq]To\[dq],\[dq]Adapteva, Inc.\[dq],\[dq]Completed\[dq],\[dq]$25.00\[dq],\[dq]$1.00\[dq],\[dq]17LA58JSKRD4HDGLNJPI1P9B8DKPVHL\[dq]+\f[R]+.fi+.IP+.nf+\f[C]+# amazon-orders.csv.rules++# skip one header line+skip 1++# name the csv fields, and assign the transaction\[aq]s date, amount and code.+# Avoided the \[dq]status\[dq] and \[dq]amount\[dq] hledger field names to prevent confusion.+fields date, _, toorfrom, name, amzstatus, amzamount, fees, code++# how to parse the date+date-format %b %-d, %Y++# combine two fields to make the description+description %toorfrom %name++# save the status as a tag+comment status:%amzstatus++# set the base account for all transactions+account1 assets:amazon+# leave amount1 blank so it can balance the other(s).+# I\[aq]m assuming amzamount excludes the fees, don\[aq]t remember++# set a generic account2+account2 expenses:misc+amount2 %amzamount+# and maybe refine it further:+#include categorisation.rules++# add a third posting for fees, but only if they are non-zero.+# Commas in the data makes counting fields hard, so count from the right instead.+# (Regex translation: \[dq]a field containing a non-zero dollar amount, +# immediately before the 1 right-most fields\[dq])+if ,\[rs]$[1-9][.0-9]+(,[\[ha],]*){1}$+ account3 expenses:fees+ amount3 %fees+\f[R]+.fi+.IP+.nf+\f[C]+$ hledger -f amazon-orders.csv print+2012/07/29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed+ assets:amazon+ expenses:misc $20.00++2012/07/30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed+ assets:amazon+ expenses:misc $25.00+ expenses:fees $1.00+\f[R]+.fi+.SS Paypal+.PP+Here\[aq]s a real-world rules file for (customised) Paypal CSV, with+some Paypal-specific rules, and a second rules file included:+.IP+.nf+\f[C]+\[dq]Date\[dq],\[dq]Time\[dq],\[dq]TimeZone\[dq],\[dq]Name\[dq],\[dq]Type\[dq],\[dq]Status\[dq],\[dq]Currency\[dq],\[dq]Gross\[dq],\[dq]Fee\[dq],\[dq]Net\[dq],\[dq]From Email Address\[dq],\[dq]To Email Address\[dq],\[dq]Transaction ID\[dq],\[dq]Item Title\[dq],\[dq]Item ID\[dq],\[dq]Reference Txn ID\[dq],\[dq]Receipt ID\[dq],\[dq]Balance\[dq],\[dq]Note\[dq]+\[dq]10/01/2019\[dq],\[dq]03:46:20\[dq],\[dq]PDT\[dq],\[dq]Calm Radio\[dq],\[dq]Subscription Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]-6.99\[dq],\[dq]0.00\[dq],\[dq]-6.99\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]memberships\[at]calmradio.com\[dq],\[dq]60P57143A8206782E\[dq],\[dq]MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month\[dq],\[dq]\[dq],\[dq]I-R8YLY094FJYR\[dq],\[dq]\[dq],\[dq]-6.99\[dq],\[dq]\[dq]+\[dq]10/01/2019\[dq],\[dq]03:46:20\[dq],\[dq]PDT\[dq],\[dq]\[dq],\[dq]Bank Deposit to PP Account \[dq],\[dq]Pending\[dq],\[dq]USD\[dq],\[dq]6.99\[dq],\[dq]0.00\[dq],\[dq]6.99\[dq],\[dq]\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]0TU1544T080463733\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]60P57143A8206782E\[dq],\[dq]\[dq],\[dq]0.00\[dq],\[dq]\[dq]+\[dq]10/01/2019\[dq],\[dq]08:57:01\[dq],\[dq]PDT\[dq],\[dq]Patreon\[dq],\[dq]PreApproved Payment Bill User Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]-7.00\[dq],\[dq]0.00\[dq],\[dq]-7.00\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]support\[at]patreon.com\[dq],\[dq]2722394R5F586712G\[dq],\[dq]Patreon* Membership\[dq],\[dq]\[dq],\[dq]B-0PG93074E7M86381M\[dq],\[dq]\[dq],\[dq]-7.00\[dq],\[dq]\[dq]+\[dq]10/01/2019\[dq],\[dq]08:57:01\[dq],\[dq]PDT\[dq],\[dq]\[dq],\[dq]Bank Deposit to PP Account \[dq],\[dq]Pending\[dq],\[dq]USD\[dq],\[dq]7.00\[dq],\[dq]0.00\[dq],\[dq]7.00\[dq],\[dq]\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]71854087RG994194F\[dq],\[dq]Patreon* Membership\[dq],\[dq]\[dq],\[dq]2722394R5F586712G\[dq],\[dq]\[dq],\[dq]0.00\[dq],\[dq]\[dq]+\[dq]10/19/2019\[dq],\[dq]03:02:12\[dq],\[dq]PDT\[dq],\[dq]Wikimedia Foundation, Inc.\[dq],\[dq]Subscription Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]-2.00\[dq],\[dq]0.00\[dq],\[dq]-2.00\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]tle\[at]wikimedia.org\[dq],\[dq]K9U43044RY432050M\[dq],\[dq]Monthly donation to the Wikimedia Foundation\[dq],\[dq]\[dq],\[dq]I-R5C3YUS3285L\[dq],\[dq]\[dq],\[dq]-2.00\[dq],\[dq]\[dq]+\[dq]10/19/2019\[dq],\[dq]03:02:12\[dq],\[dq]PDT\[dq],\[dq]\[dq],\[dq]Bank Deposit to PP Account \[dq],\[dq]Pending\[dq],\[dq]USD\[dq],\[dq]2.00\[dq],\[dq]0.00\[dq],\[dq]2.00\[dq],\[dq]\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]3XJ107139A851061F\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]K9U43044RY432050M\[dq],\[dq]\[dq],\[dq]0.00\[dq],\[dq]\[dq]+\[dq]10/22/2019\[dq],\[dq]05:07:06\[dq],\[dq]PDT\[dq],\[dq]Noble Benefactor\[dq],\[dq]Subscription Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]10.00\[dq],\[dq]-0.59\[dq],\[dq]9.41\[dq],\[dq]noble\[at]bene.fac.tor\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]6L8L1662YP1334033\[dq],\[dq]Joyful Systems\[dq],\[dq]\[dq],\[dq]I-KC9VBGY2GWDB\[dq],\[dq]\[dq],\[dq]9.41\[dq],\[dq]\[dq]+\f[R]+.fi+.IP+.nf+\f[C]+# paypal-custom.csv.rules++# Tips:+# Export from Activity -> Statements -> Custom -> Activity download+# Suggested transaction type: \[dq]Balance affecting\[dq]+# Paypal\[aq]s default fields in 2018 were:+# \[dq]Date\[dq],\[dq]Time\[dq],\[dq]TimeZone\[dq],\[dq]Name\[dq],\[dq]Type\[dq],\[dq]Status\[dq],\[dq]Currency\[dq],\[dq]Gross\[dq],\[dq]Fee\[dq],\[dq]Net\[dq],\[dq]From Email Address\[dq],\[dq]To Email Address\[dq],\[dq]Transaction ID\[dq],\[dq]Shipping Address\[dq],\[dq]Address Status\[dq],\[dq]Item Title\[dq],\[dq]Item ID\[dq],\[dq]Shipping and Handling Amount\[dq],\[dq]Insurance Amount\[dq],\[dq]Sales Tax\[dq],\[dq]Option 1 Name\[dq],\[dq]Option 1 Value\[dq],\[dq]Option 2 Name\[dq],\[dq]Option 2 Value\[dq],\[dq]Reference Txn ID\[dq],\[dq]Invoice Number\[dq],\[dq]Custom Number\[dq],\[dq]Quantity\[dq],\[dq]Receipt ID\[dq],\[dq]Balance\[dq],\[dq]Address Line 1\[dq],\[dq]Address Line 2/District/Neighborhood\[dq],\[dq]Town/City\[dq],\[dq]State/Province/Region/County/Territory/Prefecture/Republic\[dq],\[dq]Zip/Postal Code\[dq],\[dq]Country\[dq],\[dq]Contact Phone Number\[dq],\[dq]Subject\[dq],\[dq]Note\[dq],\[dq]Country Code\[dq],\[dq]Balance Impact\[dq]+# This rules file assumes the following more detailed fields, configured in \[dq]Customize report fields\[dq]:+# \[dq]Date\[dq],\[dq]Time\[dq],\[dq]TimeZone\[dq],\[dq]Name\[dq],\[dq]Type\[dq],\[dq]Status\[dq],\[dq]Currency\[dq],\[dq]Gross\[dq],\[dq]Fee\[dq],\[dq]Net\[dq],\[dq]From Email Address\[dq],\[dq]To Email Address\[dq],\[dq]Transaction ID\[dq],\[dq]Item Title\[dq],\[dq]Item ID\[dq],\[dq]Reference Txn ID\[dq],\[dq]Receipt ID\[dq],\[dq]Balance\[dq],\[dq]Note\[dq]++fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note++skip 1++date-format %-m/%-d/%Y++# ignore some paypal events+if+In Progress+Temporary Hold+Update to + skip++# add more fields to the description+description %description_ %itemtitle ++# save some other fields as tags+comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_++# convert to short currency symbols+# Note: in conditional block regexps, the line of csv being matched is+# a synthetic one: the unquoted field values, with commas between them.+if ,USD,+ currency $+if ,EUR,+ currency E+if ,GBP,+ currency P++# generate postings++# the first posting will be the money leaving/entering my paypal account+# (negative means leaving my account, in all amount fields)+account1 assets:online:paypal+amount1 %netamount++# the second posting will be money sent to/received from other party+# (account2 is set below)+amount2 -%grossamount++# if there\[aq]s a fee (9th field), add a third posting for the money taken by paypal.+# TODO: This regexp fails when fields contain a comma (generates a third posting with zero amount)+if \[ha]([\[ha],]+,){8}[\[ha]0]+ account3 expenses:banking:paypal+ amount3 -%feeamount+ comment3 business:++# choose an account for the second posting++# override the default account names:+# if amount (8th field) is positive, it\[aq]s income (a debit)+if \[ha]([\[ha],]+,){7}[0-9]+ account2 income:unknown+# if negative, it\[aq]s an expense (a credit)+if \[ha]([\[ha],]+,){7}-+ account2 expenses:unknown++# apply common rules for setting account2 & other tweaks+include common.rules++# apply some overrides specific to this csv++# Transfers from/to bank. These are usually marked Pending, +# which can be disregarded in this case.+if +Bank Account+Bank Deposit to PP Account+ description %type for %referencetxnid %itemtitle+ account2 assets:bank:wf:pchecking+ account1 assets:online:paypal++# Currency conversions+if Currency Conversion+ account2 equity:currency conversion+\f[R]+.fi+.IP+.nf+\f[C]+# common.rules++if+darcs+noble benefactor+ account2 revenues:foss donations:darcshub+ comment2 business:++if+Calm Radio+ account2 expenses:online:apps++if+electronic frontier foundation+Patreon+wikimedia+Advent of Code+ account2 expenses:dues++if Google+ account2 expenses:online:apps+ description google | music+\f[R]+.fi+.IP+.nf+\f[C]+$ hledger -f paypal-custom.csv print+2019/10/01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon\[at]joyful.com, toemail:memberships\[at]calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed+ assets:online:paypal $-6.99 = $-6.99+ expenses:online:apps $6.99++2019/10/01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon\[at]joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $6.99 = $0.00+ assets:bank:wf:pchecking $-6.99++2019/10/01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon\[at]joyful.com, toemail:support\[at]patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed+ assets:online:paypal $-7.00 = $-7.00+ expenses:dues $7.00++2019/10/01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon\[at]joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $7.00 = $0.00+ assets:bank:wf:pchecking $-7.00++2019/10/19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon\[at]joyful.com, toemail:tle\[at]wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed+ assets:online:paypal $-2.00 = $-2.00+ expenses:dues $2.00+ expenses:banking:paypal ; business:++2019/10/19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon\[at]joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $2.00 = $0.00+ assets:bank:wf:pchecking $-2.00++2019/10/22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble\[at]bene.fac.tor, toemail:simon\[at]joyful.com, time:05:07:06, type:Subscription Payment, status:Completed+ assets:online:paypal $9.41 = $9.41+ revenues:foss donations:darcshub $-10.00 ; business:+ expenses:banking:paypal $0.59 ; business:+\f[R]+.fi+.SH CSV RULES+.PP+The following kinds of rule can appear in the rules file, in any order.+Blank lines and lines beginning with \f[C]#\f[R] or \f[C];\f[R] are+ignored.+.SS \f[C]skip\f[R]+.IP+.nf+\f[C]+skip N+\f[R]+.fi+.PP+The word \[dq]skip\[dq] followed by a number (or no number, meaning 1)+tells hledger to ignore this many non-empty lines preceding the CSV+data.+(Empty/blank lines are skipped automatically.) You\[aq]ll need this+whenever your CSV data contains header lines.+.PP+It also has a second purpose: it can be used inside if blocks to ignore+certain CSV records (described below).+.SS \f[C]fields\f[R]+.IP+.nf+\f[C]+fields FIELDNAME1, FIELDNAME2, ...+\f[R]+.fi+.PP+A fields list (the word \[dq]fields\[dq] followed by comma-separated+field names) is the quick way to assign CSV field values to hledger+fields.+It does two things:+.IP "1." 3+it names the CSV fields.+This is optional, but can be convenient later for interpolating them.+.IP "2." 3+when you use a standard hledger field name, it assigns the CSV value to+that part of the hledger transaction.+.PP+Here\[aq]s an example that says \[dq]use the 1st, 2nd and 4th fields as+the transaction\[aq]s date, description and amount; name the last two+fields for later reference; and ignore the others\[dq]:+.IP+.nf+\f[C]+fields date, description, , amount, , , somefield, anotherfield+\f[R]+.fi+.PP+Field names may not contain whitespace.+Fields you don\[aq]t care about can be left unnamed.+Currently there must be least two items (there must be at least one+comma).+.PP+Here are the standard hledger field/pseudo-field names.+For more about the transaction parts they refer to, see the manual for+hledger\[aq]s journal format.+.SS Transaction field names+.PP+\f[C]date\f[R], \f[C]date2\f[R], \f[C]status\f[R], \f[C]code\f[R],+\f[C]description\f[R], \f[C]comment\f[R] can be used to form the+transaction\[aq]s first line.+.SS Posting field names+.PP+\f[C]accountN\f[R], where N is 1 to 9, generates a posting, with that+account name.+Most often there are two postings, so you\[aq]ll want to set+\f[C]account1\f[R] and \f[C]account2\f[R].+If a posting\[aq]s account name is left unset but its amount is set, a+default account name will be chosen (like expenses:unknown or+income:unknown).+.PP+\f[C]amountN\f[R] sets posting N\[aq]s amount.+Or, \f[C]amount\f[R] with no N sets posting 1\[aq]s.+If the CSV has debits and credits in separate fields, use+\f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] instead.+Or \f[C]amount-in\f[R] and \f[C]amount-out\f[R] with no N for posting 1.+.PP+For convenience and backwards compatibility, if you set the amount of+posting 1 only, a second posting with the negative amount will be+generated automatically.+(Unless the account name is parenthesised indicating an unbalanced+posting.)+.PP+If the CSV has the currency symbol in a separate field, you can use+\f[C]currencyN\f[R] to prepend it to posting N\[aq]s amount.+\f[C]currency\f[R] with no N affects ALL postings.+.PP+\f[C]balanceN\f[R] sets a balance assertion amount (or if the posting+amount is left empty, a balance assignment).+.PP+Finally, \f[C]commentN\f[R] sets a comment on the Nth posting.+Comments can also contain tags, as usual.+.PP+See TIPS below for more about setting amounts and currency.+.SS field assignment+.IP+.nf+\f[C]+HLEDGERFIELDNAME FIELDVALUE+\f[R]+.fi+.PP+Instead of or in addition to a fields list, you can use a \[dq]field+assignment\[dq] rule to set the value of a single hledger field, by+writing its name (any of the standard hledger field names above)+followed by a text value.+The value may contain interpolated CSV fields, referenced by their+1-based position in the CSV record (\f[C]%N\f[R]), or by the name they+were given in the fields list (\f[C]%CSVFIELDNAME\f[R]).+Some examples:+.IP+.nf+\f[C]+# set the amount to the 4th CSV field, with \[dq] USD\[dq] appended+amount %4 USD++# combine three fields to make a comment, containing note: and date: tags+comment note: %somefield - %anotherfield, date: %1+\f[R]+.fi+.PP+Interpolation strips outer whitespace (so a CSV value like+\f[C]\[dq] 1 \[dq]\f[R] becomes \f[C]1\f[R] when interpolated) (#1051).+See TIPS below for more about referencing other fields.+.SS \f[C]if\f[R]+.IP+.nf+\f[C]+if PATTERN+ RULE++if+PATTERN+PATTERN+PATTERN+ RULE+ RULE+\f[R]+.fi+.PP+Conditional blocks (\[dq]if blocks\[dq]) are a block of rules that are+applied only to CSV records which match certain patterns.+They are often used for customising account names based on transaction+descriptions.+.PP+A single pattern can be written on the same line as the \[dq]if\[dq]; or+multiple patterns can be written on the following lines, non-indented.+Multiple patterns are OR\[aq]d (any one of them can match).+Patterns are case-insensitive regular expressions which try to match+anywhere within the whole CSV record (POSIX extended regular expressions+with some additions, see+https://hledger.org/hledger.html#regular-expressions).+Note the CSV record they see is close to, but not identical to, the one+in the CSV file; enclosing double quotes will be removed, and the+separator character is always comma.+.PP+It\[aq]s not yet easy to match within a specific field.+If the data does not contain commas, you can hack it with a regular+expression like:+.IP+.nf+\f[C]+# match \[dq]foo\[dq] in the fourth field+if \[ha]([\[ha],]*,){3}foo+\f[R]+.fi+.PP+After the patterns there should be one or more rules to apply, all+indented by at least one space.+Three kinds of rule are allowed in conditional blocks:+.IP \[bu] 2+field assignments (to set a hledger field)+.IP \[bu] 2+skip (to skip the matched CSV record)+.IP \[bu] 2+end (to skip all remaining CSV records).+.PP+Examples:+.IP+.nf+\f[C]+# if the CSV record contains \[dq]groceries\[dq], set account2 to \[dq]expenses:groceries\[dq]+if groceries+ account2 expenses:groceries+\f[R]+.fi+.IP+.nf+\f[C]+# if the CSV record contains any of these patterns, set account2 and comment as shown+if+monthly service fee+atm transaction fee+banking thru software+ account2 expenses:business:banking+ comment XXX deductible ? check it+\f[R]+.fi+.SS \f[C]end\f[R]+.PP+This rule can be used inside if blocks (only), to make hledger stop+reading this CSV file and move on to the next input file, or to command+execution.+Eg:+.IP+.nf+\f[C]+# ignore everything following the first empty record+if ,,,,+ end+\f[R]+.fi+.SS \f[C]date-format\f[R]+.IP+.nf+\f[C]+date-format DATEFMT+\f[R]+.fi+.PP+This is a helper for the \f[C]date\f[R] (and \f[C]date2\f[R]) fields.+If your CSV dates are not formatted like \f[C]YYYY-MM-DD\f[R],+\f[C]YYYY/MM/DD\f[R] or \f[C]YYYY.MM.DD\f[R], you\[aq]ll need to add a+date-format rule describing them with a strptime date parsing pattern,+which must parse the CSV date value completely.+Some examples:+.IP+.nf+\f[C]+# MM/DD/YY+date-format %m/%d/%y+\f[R]+.fi+.IP+.nf+\f[C]+# D/M/YYYY+# The - makes leading zeros optional.+date-format %-d/%-m/%Y+\f[R]+.fi+.IP+.nf+\f[C]+# YYYY-Mmm-DD+date-format %Y-%h-%d+\f[R]+.fi+.IP+.nf+\f[C]+# M/D/YYYY HH:MM AM some other junk+# Note the time and junk must be fully parsed, though only the date is used.+date-format %-m/%-d/%Y %l:%M %p some other junk+\f[R]+.fi+.PP+For the supported strptime syntax, see:+.PD 0+.P+.PD+https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime+.SS \f[C]newest-first\f[R]+.PP+hledger always sorts the generated transactions by date.+Transactions on the same date should appear in the same order as their+CSV records, as hledger can usually auto-detect whether the CSV\[aq]s+normal order is oldest first or newest first.+But if all of the following are true:+.IP \[bu] 2+the CSV might sometimes contain just one day of data (all records having+the same date)+.IP \[bu] 2+the CSV records are normally in reverse chronological order (newest at+the top)+.IP \[bu] 2+and you care about preserving the order of same-day transactions+.PP+then, you should add the \f[C]newest-first\f[R] rule as a hint.+Eg:+.IP+.nf+\f[C]+# tell hledger explicitly that the CSV is normally newest first+newest-first+\f[R]+.fi+.SS \f[C]include\f[R]+.IP+.nf+\f[C]+include RULESFILE+\f[R]+.fi+.PP+This includes the contents of another CSV rules file at this point.+\f[C]RULESFILE\f[R] is an absolute file path or a path relative to the+current file\[aq]s directory.+This can be useful for sharing common rules between several rules files,+eg:+.IP+.nf+\f[C]+# someaccount.csv.rules++## someaccount-specific rules+fields date,description,amount+account1 assets:someaccount+account2 expenses:misc++## common rules+include categorisation.rules+\f[R]+.fi+.SH TIPS+.SS Valid CSV+.PP+hledger accepts CSV conforming to RFC 4180.+When CSV values are enclosed in quotes, note:+.IP \[bu] 2+they must be double quotes (not single quotes)+.IP \[bu] 2+spaces outside the quotes are not allowed+.SS Other separator characters+.PP+With the \f[C]--separator \[aq]CHAR\[aq]\f[R] option (experimental),+hledger will expect the separator to be CHAR instead of a comma.+Ie it will read other \[dq]Character Separated Values\[dq] formats, such+as TSV (Tab Separated Values).+Note: on the command line, use a real tab character in quotes, not Eg:+.IP+.nf+\f[C]+$ hledger -f foo.tsv --separator \[aq] \[aq] print+\f[R]+.fi+.SS Reading multiple CSV files+.PP+If you use multiple \f[C]-f\f[R] options to read multiple CSV files at+once, hledger will look for a correspondingly-named rules file for each+CSV file.+But if you use the \f[C]--rules-file\f[R] option, that rules file will+be used for all the CSV files.+.SS Valid transactions+.PP+After reading a CSV file, hledger post-processes and validates the+generated journal entries as it would for a journal file - balancing+them, applying balance assignments, and canonicalising amount styles.+Any errors at this stage will be reported in the usual way, displaying+the problem entry.+.PP+There is one exception: balance assertions, if you have generated them,+will not be checked, since normally these will work only when the CSV+data is part of the main journal.+If you do need to check balance assertions generated from CSV right+away, pipe into another hledger:+.IP+.nf+\f[C]+$ hledger -f file.csv print | hledger -f- print+\f[R]+.fi+.SS Deduplicating, importing+.PP+When you download a CSV file periodically, eg to get your latest bank+transactions, the new file may overlap with the old one, containing some+of the same records.+.PP+The import command will (a) detect the new transactions, and (b) append+just those transactions to your main journal.+It is idempotent, so you don\[aq]t have to remember how many times you+ran it or with which version of the CSV.+(It keeps state in a hidden \f[C].latest.FILE.csv\f[R] file.) This is+the easiest way to import CSV data.+Eg:+.IP+.nf+\f[C]+# download the latest CSV files, then run this command.+# Note, no -f flags needed here.+$ hledger import *.csv [--dry]+\f[R]+.fi+.PP+This method works for most CSV files.+(Where records have a stable chronological order, and new records appear+only at the new end.)+.PP+A number of other tools and workflows, hledger-specific and otherwise,+exist for converting, deduplicating, classifying and managing CSV data.+See:+.IP \[bu] 2+https://hledger.org -> sidebar -> real world setups+.IP \[bu] 2+https://plaintextaccounting.org -> data import/conversion+.SS Setting amounts+.PP+A posting amount can be set in one of these ways:+.IP \[bu] 2+by assigning (with a fields list or field assigment) to+\f[C]amountN\f[R] (posting N\[aq]s amount) or \f[C]amount\f[R] (posting+1\[aq]s amount)+.IP \[bu] 2+by assigning to \f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] (or+\f[C]amount-in\f[R] and \f[C]amount-out\f[R]).+For each CSV record, whichever of these has a non-zero value will be+used, with appropriate sign.+If both contain a non-zero value, this may not work.+.IP \[bu] 2+by assigning to \f[C]balanceN\f[R] (or \f[C]balance\f[R]) instead of the+above, setting the amount indirectly via a balance assignment.+If you do this the default account name may be wrong, so you should set+that explicitly.+.PP+There is some special handling for an amount\[aq]s sign:+.IP \[bu] 2+If an amount value is parenthesised, it will be de-parenthesised and+sign-flipped.+.IP \[bu] 2+If an amount value begins with a double minus sign, those cancel out and+are removed.+.IP \[bu] 2+If an amount value begins with a plus sign, that will be removed+.SS Setting currency/commodity+.PP+If the currency/commodity symbol is included in the CSV\[aq]s amount+field(s), you don\[aq]t have to do anything special.+.PP+If the currency is provided as a separate CSV field, you can either:+.IP \[bu] 2+assign that to \f[C]currency\f[R], which adds it to all posting amounts.+The symbol will prepended to the amount quantity (on the left side).+If you write a trailing space after the symbol, there will be a space+between symbol and amount (an exception to the usual whitespace+stripping).+.IP \[bu] 2+or assign it to \f[C]currencyN\f[R] which adds it to posting N\[aq]s+amount only.+.IP \[bu] 2+or for more control, construct the amount from symbol and quantity using+field assignment, eg:+.RS 2+.IP+.nf+\f[C]+fields date,description,currency,quantity+# add currency symbol on the right:+amount %quantity %currency+\f[R]+.fi+.RE+.SS Referencing other fields+.PP+In field assignments, you can interpolate only CSV fields, not hledger+fields.+In the example below, there\[aq]s both a CSV field and a hledger field+named amount1, but %amount1 always means the CSV field, not the hledger+field:+.IP+.nf+\f[C]+# Name the third CSV field \[dq]amount1\[dq]+fields date,description,amount1++# Set hledger\[aq]s amount1 to the CSV amount1 field followed by USD+amount1 %amount1 USD++# Set comment to the CSV amount1 (not the amount1 assigned above)+comment %amount1+\f[R]+.fi+.PP+Here, since there\[aq]s no CSV amount1 field, %amount1 will produce a+literal \[dq]amount1\[dq]:+.IP+.nf+\f[C]+fields date,description,csvamount+amount1 %csvamount USD+# Can\[aq]t interpolate amount1 here+comment %amount1+\f[R]+.fi+.PP+When there are multiple field assignments to the same hledger field,+only the last one takes effect.+Here, comment\[aq]s value will be be B, or C if \[dq]something\[dq] is+matched, but never A:+.IP+.nf+\f[C]+comment A+comment B+if something+ comment C+\f[R]+.fi+.SS How CSV rules are evaluated+.PP+Here\[aq]s how to think of CSV rules being evaluated (if you really need+to).+First,+.IP \[bu] 2+\f[C]include\f[R] - all includes are inlined, from top to bottom, depth+first.+(At each include point the file is inlined and scanned for further+includes, recursively, before proceeding.)+.PP+Then \[dq]global\[dq] rules are evaluated, top to bottom.+If a rule is repeated, the last one wins:+.IP \[bu] 2+\f[C]skip\f[R] (at top level)+.IP \[bu] 2+\f[C]date-format\f[R]+.IP \[bu] 2+\f[C]newest-first\f[R]+.IP \[bu] 2+\f[C]fields\f[R] - names the CSV fields, optionally sets up initial+assignments to hledger fields+.PP+Then for each CSV record in turn:+.IP \[bu] 2+test all \f[C]if\f[R] blocks.+If any of them contain a \f[C]end\f[R] rule, skip all remaining CSV+records.+Otherwise if any of them contain a \f[C]skip\f[R] rule, skip that many+CSV records.+If there are multiple matched \f[C]skip\f[R] rules, the first one wins.+.IP \[bu] 2+collect all field assignments at top level and in matched \f[C]if\f[R]+blocks.+When there are multiple assignments for a field, keep only the last one.+.IP \[bu] 2+compute a value for each hledger field - either the one that was+assigned to it (and interpolate the %CSVFIELDNAME references), or a+default+.IP \[bu] 2+generate a synthetic hledger transaction from these values.+.PP+This is all part of the CSV reader, one of several readers hledger can+use to parse input files.+When all files have been read successfully, the transactions are passed+as input to whichever hledger command the user specified.+++.SH "REPORTING BUGS"+Report bugs at http://bugs.hledger.org+(or on the #hledger IRC channel or hledger mail list)++.SH AUTHORS+Simon Michael <simon@joyful.com> and contributors++.SH COPYRIGHT++Copyright (C) 2007-2019 Simon Michael. .br Released under GNU GPL v3 or later.
embeddedfiles/hledger_csv.info view
@@ -1,384 +1,944 @@ This is hledger_csv.info, produced by makeinfo version 6.5 from stdin. -File: hledger_csv.info, Node: Top, Next: CSV RULES, Up: (dir)--hledger_csv(5) hledger 1.15.2-*****************************--hledger can read CSV (comma-separated value) files as if they were-journal files, automatically converting each CSV record into a-transaction. (To learn about _writing_ CSV, see CSV output.)-- Converting CSV to transactions requires some special conversion-rules. These do several things:-- * they describe the layout and format of the CSV data- * they can customize the generated journal entries using a simple- templating language- * they can add refinements based on patterns in the CSV data, eg- categorizing transactions with more detailed account names.-- When reading a CSV file named 'FILE.csv', hledger looks for a-conversion rules file named 'FILE.csv.rules' in the same directory. You-can override this with the '--rules-file' option. If the rules file-does not exist, hledger will auto-create one with some example rules,-which you'll need to adjust.-- At minimum, the rules file must identify the date and amount fields.-It's often necessary to specify the date format, and the number of-header lines to skip, also. Eg:--fields date, _, _, amount-date-format %d/%m/%Y-skip 1-- A more complete example:--# hledger CSV rules for amazon.com order history--# sample:-# "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"-# "Jul 29, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL"--# skip one header line-skip 1--# name the csv fields (and assign the transaction's date, amount and code)-fields date, _, toorfrom, name, amzstatus, amount, fees, code--# how to parse the date-date-format %b %-d, %Y--# combine two fields to make the description-description %toorfrom %name--# save these fields as tags-comment status:%amzstatus, fees:%fees--# set the base account for all transactions-account1 assets:amazon--# flip the sign on the amount-amount -%amount-- For more examples, see Convert CSV files.--* Menu:--* CSV RULES::-* CSV TIPS::---File: hledger_csv.info, Node: CSV RULES, Next: CSV TIPS, Prev: Top, Up: Top--1 CSV RULES-***********--The following seven kinds of rule can appear in the rules file, in any-order. Blank lines and lines beginning with '#' or ';' are ignored.--* Menu:--* skip::-* date-format::-* field list::-* field assignment::-* conditional block::-* include::-* newest-first::---File: hledger_csv.info, Node: skip, Next: date-format, Up: CSV RULES--1.1 skip-========--'skip'_'N'_-- Skip this number of CSV records at the beginning. You'll need this-whenever your CSV data contains header lines. Eg:--# ignore the first CSV line-skip 1---File: hledger_csv.info, Node: date-format, Next: field list, Prev: skip, Up: CSV RULES--1.2 date-format-===============--'date-format'_'DATEFMT'_-- When your CSV date fields are not formatted like 'YYYY/MM/DD' (or-'YYYY-MM-DD' or 'YYYY.MM.DD'), you'll need to specify the format.-DATEFMT is a strptime-like date parsing pattern, which must parse the-date field values completely. Examples:--# for dates like "11/06/2013":-date-format %m/%d/%Y--# for dates like "6/11/2013" (note the - to make leading zeros optional):-date-format %-d/%-m/%Y--# for dates like "2013-Nov-06":-date-format %Y-%h-%d--# for dates like "11/6/2013 11:32 PM":-date-format %-m/%-d/%Y %l:%M %p---File: hledger_csv.info, Node: field list, Next: field assignment, Prev: date-format, Up: CSV RULES--1.3 field list-==============--'fields'_'FIELDNAME1'_, _'FIELDNAME2'_...-- This (a) names the CSV fields, in order (names may not contain-whitespace; uninteresting names may be left blank), and (b) assigns them-to journal entry fields if you use any of these standard field names:-'date', 'date2', 'status', 'code', 'description', 'comment', 'account1',-'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance',-'balance1', 'balance2'. Eg:--# use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount,-# and give the 7th and 8th fields meaningful names for later reference:-#-# CSV field:-# 1 2 3 4 5 6 7 8-# entry field:-fields date, description, , amount, , , somefield, anotherfield---File: hledger_csv.info, Node: field assignment, Next: conditional block, Prev: field list, Up: CSV RULES--1.4 field assignment-====================--_'ENTRYFIELDNAME'_ _'FIELDVALUE'_-- This sets a journal entry field (one of the standard names above) to-the given text value, which can include CSV field values interpolated by-name ('%CSVFIELDNAME') or 1-based position ('%N'). Eg:--# set the amount to the 4th CSV field with "USD " prepended-amount USD %4--# combine three fields to make a comment (containing two tags)-comment note: %somefield - %anotherfield, date: %1-- Field assignments can be used instead of or in addition to a field-list.-- Note, interpolation strips any outer whitespace, so a CSV value like-'" 1 "' becomes '1' when interpolated (#1051).---File: hledger_csv.info, Node: conditional block, Next: include, Prev: field assignment, Up: CSV RULES--1.5 conditional block-=====================--'if' _'PATTERN'_- _'FIELDASSIGNMENTS'_...-- 'if'-_'PATTERN'_-_'PATTERN'_...- _'FIELDASSIGNMENTS'_...-- This applies one or more field assignments, only to those CSV records-matched by one of the PATTERNs. The patterns are case-insensitive-regular expressions which match anywhere within the whole CSV record-(it's not yet possible to match within a specific field). When there-are multiple patterns they can be written on separate lines, unindented.-The field assignments are on separate lines indented by at least one-space. Examples:--# if the CSV record contains "groceries", set account2 to "expenses:groceries"-if groceries- account2 expenses:groceries--# if the CSV record contains any of these patterns, set account2 and comment as shown-if-monthly service fee-atm transaction fee-banking thru software- account2 expenses:business:banking- comment XXX deductible ? check it---File: hledger_csv.info, Node: include, Next: newest-first, Prev: conditional block, Up: CSV RULES--1.6 include-===========--'include'_'RULESFILE'_-- Include another rules file at this point. 'RULESFILE' is either an-absolute file path or a path relative to the current file's directory.-Eg:--# rules reused with several CSV files-include common.rules---File: hledger_csv.info, Node: newest-first, Prev: include, Up: CSV RULES--1.7 newest-first-================--'newest-first'-- Consider adding this rule if all of the following are true: you might-be processing just one day of data, your CSV records are in reverse-chronological order (newest first), and you care about preserving the-order of same-day transactions. It usually isn't needed, because-hledger autodetects the CSV order, but when all CSV records have the-same date it will assume they are oldest first.---File: hledger_csv.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top--2 CSV TIPS-**********--* Menu:--* CSV ordering::-* CSV accounts::-* CSV amounts::-* CSV balance assertions/assignments::-* Reading multiple CSV files::-* Valid CSV::---File: hledger_csv.info, Node: CSV ordering, Next: CSV accounts, Up: CSV TIPS--2.1 CSV ordering-================--The generated journal entries will be sorted by date. The order of-same-day entries will be preserved (except in the special case where you-might need 'newest-first', see above).---File: hledger_csv.info, Node: CSV accounts, Next: CSV amounts, Prev: CSV ordering, Up: CSV TIPS--2.2 CSV accounts-================--Each journal entry will have two postings, to 'account1' and 'account2'-respectively. It's not yet possible to generate entries with more than-two postings. It's conventional and recommended to use 'account1' for-the account whose CSV we are reading.---File: hledger_csv.info, Node: CSV amounts, Next: CSV balance assertions/assignments, Prev: CSV accounts, Up: CSV TIPS--2.3 CSV amounts-===============--A transaction amount must be set, in one of these ways:-- * with an 'amount' field assignment, which sets the first posting's- amount-- * (When the CSV has debit and credit amounts in separate fields:)- with field assignments for the 'amount-in' and 'amount-out' pseudo- fields (both of them). Whichever one has a value will be used,- with appropriate sign. If both contain a value, it might not work- so well.-- * or implicitly by means of a balance assignment (see below).-- There is some special handling for sign in amounts:-- * If an amount value is parenthesised, it will be de-parenthesised- and sign-flipped.- * If an amount value begins with a double minus sign, those will- cancel out and be removed.-- If the currency/commodity symbol is provided as a separate CSV field,-assign it to the 'currency' pseudo field; the symbol will be prepended-to the amount (TODO: when there is an amount). Or, you can use an-'amount' field assignment for more control, eg:--fields date,description,currency,amount-amount %amount %currency---File: hledger_csv.info, Node: CSV balance assertions/assignments, Next: Reading multiple CSV files, Prev: CSV amounts, Up: CSV TIPS--2.4 CSV balance assertions/assignments-======================================--If the CSV includes a running balance, you can assign that to one of the-pseudo fields 'balance' (or 'balance1') or 'balance2'. This will-generate a balance assertion (or if the amount is left empty, a balance-assignment), on the first or second posting, whenever the running-balance field is non-empty. (TODO: #1000)---File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid CSV, Prev: CSV balance assertions/assignments, Up: CSV TIPS--2.5 Reading multiple CSV files-==============================--You can read multiple CSV files at once using multiple '-f' arguments on-the command line, and hledger will look for a correspondingly-named-rules file for each. Note if you use the '--rules-file' option, this-one rules file will be used for all the CSV files being read.---File: hledger_csv.info, Node: Valid CSV, Prev: Reading multiple CSV files, Up: CSV TIPS--2.6 Valid CSV-=============--hledger follows RFC 4180, with the addition of a customisable separator-character.-- Some things to note:-- When quoting fields,-- * you must use double quotes, not single quotes- * spaces outside the quotes are not allowed.---Tag Table:-Node: Top72-Node: CSV RULES2165-Ref: #csv-rules2273-Node: skip2536-Ref: #skip2630-Node: date-format2802-Ref: #date-format2929-Node: field list3479-Ref: #field-list3616-Node: field assignment4346-Ref: #field-assignment4501-Node: conditional block5125-Ref: #conditional-block5279-Node: include6175-Ref: #include6305-Node: newest-first6536-Ref: #newest-first6650-Node: CSV TIPS7061-Ref: #csv-tips7155-Node: CSV ordering7299-Ref: #csv-ordering7417-Node: CSV accounts7598-Ref: #csv-accounts7736-Node: CSV amounts7990-Ref: #csv-amounts8148-Node: CSV balance assertions/assignments9228-Ref: #csv-balance-assertionsassignments9446-Node: Reading multiple CSV files9767-Ref: #reading-multiple-csv-files9967-Node: Valid CSV10241-Ref: #valid-csv10364+File: hledger_csv.info, Node: Top, Next: EXAMPLES, Up: (dir)++hledger_csv(5) hledger 1.16+***************************++hledger can read CSV (comma-separated value, or character-separated+value) files as if they were journal files, automatically converting+each CSV record into a transaction. (To learn about _writing_ CSV, see+CSV output.)++ We describe each CSV file's format with a corresponding _rules file_.+By default this is named like the CSV file with a '.rules' extension+added. Eg when reading 'FILE.csv', hledger also looks for+'FILE.csv.rules' in the same directory. You can specify a different+rules file with the '--rules-file' option. If a rules file is not+found, hledger will create a sample rules file, which you'll need to+adjust.++ This file contains rules describing the CSV data (header line, fields+layout, date format etc.), and how to construct hledger journal entries+(transactions) from it. Often there will also be a list of conditional+rules for categorising transactions based on their descriptions. Here's+an overview of the CSV rules; these are described more fully below,+after the examples:++*'skip'* skip one or more header lines or matched CSV records+*'fields'* name CSV fields, assign them to hledger fields+*field assign a value to one hledger field, with interpolation+assignment*+*'if'* apply some rules to matched CSV records+*'end'* skip the remaining CSV records+*'date-format'* describe the format of CSV dates+*'newest-first'* disambiguate record order when there's only one date+*'include'* inline another CSV rules file++ There's also a Convert CSV files tutorial on hledger.org.++* Menu:++* EXAMPLES::+* CSV RULES::+* TIPS::+++File: hledger_csv.info, Node: EXAMPLES, Next: CSV RULES, Prev: Top, Up: Top++1 EXAMPLES+**********++Here are some sample hledger CSV rules files. See also the full+collection at:+https://github.com/simonmichael/hledger/tree/master/examples/csv++* Menu:++* Basic::+* Bank of Ireland::+* Amazon::+* Paypal::+++File: hledger_csv.info, Node: Basic, Next: Bank of Ireland, Up: EXAMPLES++1.1 Basic+=========++At minimum, the rules file must identify the date and amount fields, and+often it also specifies the date format and how many header lines there+are. Here's a simple CSV file and a rules file for it:++Date, Description, Id, Amount+12/11/2019, Foo, 123, 10.23++# basic.csv.rules+skip 1+fields date, description, _, amount+date-format %d/%m/%Y++$ hledger print -f basic.csv+2019/11/12 Foo+ expenses:unknown 10.23+ income:unknown -10.23++ Default account names are chosen, since we didn't set them.+++File: hledger_csv.info, Node: Bank of Ireland, Next: Amazon, Prev: Basic, Up: EXAMPLES++1.2 Bank of Ireland+===================++Here's a CSV with two amount fields (Debit and Credit), and a balance+field, which we can use to add balance assertions, which is not+necessary but provides extra error checking:++Date,Details,Debit,Credit,Balance+07/12/2012,LODGMENT 529898,,10.0,131.21+07/12/2012,PAYMENT,5,,126++# bankofireland-checking.csv.rules++# skip the header line+skip++# name the csv fields, and assign some of them as journal entry fields+fields date, description, amount-out, amount-in, balance++# We generate balance assertions by assigning to "balance"+# above, but you may sometimes need to remove these because:+#+# - the CSV balance differs from the true balance, +# by up to 0.0000000000005 in my experience+#+# - it is sometimes calculated based on non-chronological ordering,+# eg when multiple transactions clear on the same day++# date is in UK/Ireland format+date-format %d/%m/%Y++# set the currency+currency EUR++# set the base account for all txns+account1 assets:bank:boi:checking++$ hledger -f bankofireland-checking.csv print+2012/12/07 LODGMENT 529898+ assets:bank:boi:checking EUR10.0 = EUR131.2+ income:unknown EUR-10.0++2012/12/07 PAYMENT+ assets:bank:boi:checking EUR-5.0 = EUR126.0+ expenses:unknown EUR5.0++ The balance assertions don't raise an error above, because we're+reading directly from CSV, but they will be checked if these entries are+imported into a journal file.+++File: hledger_csv.info, Node: Amazon, Next: Paypal, Prev: Bank of Ireland, Up: EXAMPLES++1.3 Amazon+==========++Here we convert amazon.com order history, and use an if block to+generate a third posting if there's a fee. (In practice you'd probably+get this data from your bank instead, but it's an example.)++"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"+"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"+"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"++# amazon-orders.csv.rules++# skip one header line+skip 1++# name the csv fields, and assign the transaction's date, amount and code.+# Avoided the "status" and "amount" hledger field names to prevent confusion.+fields date, _, toorfrom, name, amzstatus, amzamount, fees, code++# how to parse the date+date-format %b %-d, %Y++# combine two fields to make the description+description %toorfrom %name++# save the status as a tag+comment status:%amzstatus++# set the base account for all transactions+account1 assets:amazon+# leave amount1 blank so it can balance the other(s).+# I'm assuming amzamount excludes the fees, don't remember++# set a generic account2+account2 expenses:misc+amount2 %amzamount+# and maybe refine it further:+#include categorisation.rules++# add a third posting for fees, but only if they are non-zero.+# Commas in the data makes counting fields hard, so count from the right instead.+# (Regex translation: "a field containing a non-zero dollar amount, +# immediately before the 1 right-most fields")+if ,\$[1-9][.0-9]+(,[^,]*){1}$+ account3 expenses:fees+ amount3 %fees++$ hledger -f amazon-orders.csv print+2012/07/29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed+ assets:amazon+ expenses:misc $20.00++2012/07/30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed+ assets:amazon+ expenses:misc $25.00+ expenses:fees $1.00+++File: hledger_csv.info, Node: Paypal, Prev: Amazon, Up: EXAMPLES++1.4 Paypal+==========++Here's a real-world rules file for (customised) Paypal CSV, with some+Paypal-specific rules, and a second rules file included:++"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"+"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""+"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""+"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""+"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""+"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""+"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""+"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""++# paypal-custom.csv.rules++# Tips:+# Export from Activity -> Statements -> Custom -> Activity download+# Suggested transaction type: "Balance affecting"+# Paypal's default fields in 2018 were:+# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"+# This rules file assumes the following more detailed fields, configured in "Customize report fields":+# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"++fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note++skip 1++date-format %-m/%-d/%Y++# ignore some paypal events+if+In Progress+Temporary Hold+Update to + skip++# add more fields to the description+description %description_ %itemtitle ++# save some other fields as tags+comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_++# convert to short currency symbols+# Note: in conditional block regexps, the line of csv being matched is+# a synthetic one: the unquoted field values, with commas between them.+if ,USD,+ currency $+if ,EUR,+ currency E+if ,GBP,+ currency P++# generate postings++# the first posting will be the money leaving/entering my paypal account+# (negative means leaving my account, in all amount fields)+account1 assets:online:paypal+amount1 %netamount++# the second posting will be money sent to/received from other party+# (account2 is set below)+amount2 -%grossamount++# if there's a fee (9th field), add a third posting for the money taken by paypal.+# TODO: This regexp fails when fields contain a comma (generates a third posting with zero amount)+if ^([^,]+,){8}[^0]+ account3 expenses:banking:paypal+ amount3 -%feeamount+ comment3 business:++# choose an account for the second posting++# override the default account names:+# if amount (8th field) is positive, it's income (a debit)+if ^([^,]+,){7}[0-9]+ account2 income:unknown+# if negative, it's an expense (a credit)+if ^([^,]+,){7}-+ account2 expenses:unknown++# apply common rules for setting account2 & other tweaks+include common.rules++# apply some overrides specific to this csv++# Transfers from/to bank. These are usually marked Pending, +# which can be disregarded in this case.+if +Bank Account+Bank Deposit to PP Account+ description %type for %referencetxnid %itemtitle+ account2 assets:bank:wf:pchecking+ account1 assets:online:paypal++# Currency conversions+if Currency Conversion+ account2 equity:currency conversion++# common.rules++if+darcs+noble benefactor+ account2 revenues:foss donations:darcshub+ comment2 business:++if+Calm Radio+ account2 expenses:online:apps++if+electronic frontier foundation+Patreon+wikimedia+Advent of Code+ account2 expenses:dues++if Google+ account2 expenses:online:apps+ description google | music++$ hledger -f paypal-custom.csv print+2019/10/01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed+ assets:online:paypal $-6.99 = $-6.99+ expenses:online:apps $6.99++2019/10/01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $6.99 = $0.00+ assets:bank:wf:pchecking $-6.99++2019/10/01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed+ assets:online:paypal $-7.00 = $-7.00+ expenses:dues $7.00++2019/10/01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $7.00 = $0.00+ assets:bank:wf:pchecking $-7.00++2019/10/19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed+ assets:online:paypal $-2.00 = $-2.00+ expenses:dues $2.00+ expenses:banking:paypal ; business:++2019/10/19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $2.00 = $0.00+ assets:bank:wf:pchecking $-2.00++2019/10/22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed+ assets:online:paypal $9.41 = $9.41+ revenues:foss donations:darcshub $-10.00 ; business:+ expenses:banking:paypal $0.59 ; business:+++File: hledger_csv.info, Node: CSV RULES, Next: TIPS, Prev: EXAMPLES, Up: Top++2 CSV RULES+***********++The following kinds of rule can appear in the rules file, in any order.+Blank lines and lines beginning with '#' or ';' are ignored.++* Menu:++* skip::+* fields::+* field assignment::+* if::+* end::+* date-format::+* newest-first::+* include::+++File: hledger_csv.info, Node: skip, Next: fields, Up: CSV RULES++2.1 'skip'+==========++skip N++ The word "skip" followed by a number (or no number, meaning 1) tells+hledger to ignore this many non-empty lines preceding the CSV data.+(Empty/blank lines are skipped automatically.) You'll need this+whenever your CSV data contains header lines.++ It also has a second purpose: it can be used inside if blocks to+ignore certain CSV records (described below).+++File: hledger_csv.info, Node: fields, Next: field assignment, Prev: skip, Up: CSV RULES++2.2 'fields'+============++fields FIELDNAME1, FIELDNAME2, ...++ A fields list (the word "fields" followed by comma-separated field+names) is the quick way to assign CSV field values to hledger fields.+It does two things:++ 1. it names the CSV fields. This is optional, but can be convenient+ later for interpolating them.++ 2. when you use a standard hledger field name, it assigns the CSV+ value to that part of the hledger transaction.++ Here's an example that says "use the 1st, 2nd and 4th fields as the+transaction's date, description and amount; name the last two fields for+later reference; and ignore the others":++fields date, description, , amount, , , somefield, anotherfield++ Field names may not contain whitespace. Fields you don't care about+can be left unnamed. Currently there must be least two items (there+must be at least one comma).++ Here are the standard hledger field/pseudo-field names. For more+about the transaction parts they refer to, see the manual for hledger's+journal format.++* Menu:++* Transaction field names::+* Posting field names::+++File: hledger_csv.info, Node: Transaction field names, Next: Posting field names, Up: fields++2.2.1 Transaction field names+-----------------------------++'date', 'date2', 'status', 'code', 'description', 'comment' can be used+to form the transaction's first line.+++File: hledger_csv.info, Node: Posting field names, Prev: Transaction field names, Up: fields++2.2.2 Posting field names+-------------------------++'accountN', where N is 1 to 9, generates a posting, with that account+name. Most often there are two postings, so you'll want to set+'account1' and 'account2'. If a posting's account name is left unset+but its amount is set, a default account name will be chosen (like+expenses:unknown or income:unknown).++ 'amountN' sets posting N's amount. Or, 'amount' with no N sets+posting 1's. If the CSV has debits and credits in separate fields, use+'amountN-in' and 'amountN-out' instead. Or 'amount-in' and 'amount-out'+with no N for posting 1.++ For convenience and backwards compatibility, if you set the amount of+posting 1 only, a second posting with the negative amount will be+generated automatically. (Unless the account name is parenthesised+indicating an unbalanced posting.)++ If the CSV has the currency symbol in a separate field, you can use+'currencyN' to prepend it to posting N's amount. 'currency' with no N+affects ALL postings.++ 'balanceN' sets a balance assertion amount (or if the posting amount+is left empty, a balance assignment).++ Finally, 'commentN' sets a comment on the Nth posting. Comments can+also contain tags, as usual.++ See TIPS below for more about setting amounts and currency.+++File: hledger_csv.info, Node: field assignment, Next: if, Prev: fields, Up: CSV RULES++2.3 field assignment+====================++HLEDGERFIELDNAME FIELDVALUE++ Instead of or in addition to a fields list, you can use a "field+assignment" rule to set the value of a single hledger field, by writing+its name (any of the standard hledger field names above) followed by a+text value. The value may contain interpolated CSV fields, referenced+by their 1-based position in the CSV record ('%N'), or by the name they+were given in the fields list ('%CSVFIELDNAME'). Some examples:++# set the amount to the 4th CSV field, with " USD" appended+amount %4 USD++# combine three fields to make a comment, containing note: and date: tags+comment note: %somefield - %anotherfield, date: %1++ Interpolation strips outer whitespace (so a CSV value like '" 1 "'+becomes '1' when interpolated) (#1051). See TIPS below for more about+referencing other fields.+++File: hledger_csv.info, Node: if, Next: end, Prev: field assignment, Up: CSV RULES++2.4 'if'+========++if PATTERN+ RULE++if+PATTERN+PATTERN+PATTERN+ RULE+ RULE++ Conditional blocks ("if blocks") are a block of rules that are+applied only to CSV records which match certain patterns. They are+often used for customising account names based on transaction+descriptions.++ A single pattern can be written on the same line as the "if"; or+multiple patterns can be written on the following lines, non-indented.+Multiple patterns are OR'd (any one of them can match). Patterns are+case-insensitive regular expressions which try to match anywhere within+the whole CSV record (POSIX extended regular expressions with some+additions, see https://hledger.org/hledger.html#regular-expressions).+Note the CSV record they see is close to, but not identical to, the one+in the CSV file; enclosing double quotes will be removed, and the+separator character is always comma.++ It's not yet easy to match within a specific field. If the data does+not contain commas, you can hack it with a regular expression like:++# match "foo" in the fourth field+if ^([^,]*,){3}foo++ After the patterns there should be one or more rules to apply, all+indented by at least one space. Three kinds of rule are allowed in+conditional blocks:++ * field assignments (to set a hledger field)+ * skip (to skip the matched CSV record)+ * end (to skip all remaining CSV records).++ Examples:++# if the CSV record contains "groceries", set account2 to "expenses:groceries"+if groceries+ account2 expenses:groceries++# if the CSV record contains any of these patterns, set account2 and comment as shown+if+monthly service fee+atm transaction fee+banking thru software+ account2 expenses:business:banking+ comment XXX deductible ? check it+++File: hledger_csv.info, Node: end, Next: date-format, Prev: if, Up: CSV RULES++2.5 'end'+=========++This rule can be used inside if blocks (only), to make hledger stop+reading this CSV file and move on to the next input file, or to command+execution. Eg:++# ignore everything following the first empty record+if ,,,,+ end+++File: hledger_csv.info, Node: date-format, Next: newest-first, Prev: end, Up: CSV RULES++2.6 'date-format'+=================++date-format DATEFMT++ This is a helper for the 'date' (and 'date2') fields. If your CSV+dates are not formatted like 'YYYY-MM-DD', 'YYYY/MM/DD' or 'YYYY.MM.DD',+you'll need to add a date-format rule describing them with a strptime+date parsing pattern, which must parse the CSV date value completely.+Some examples:++# MM/DD/YY+date-format %m/%d/%y++# D/M/YYYY+# The - makes leading zeros optional.+date-format %-d/%-m/%Y++# YYYY-Mmm-DD+date-format %Y-%h-%d++# M/D/YYYY HH:MM AM some other junk+# Note the time and junk must be fully parsed, though only the date is used.+date-format %-m/%-d/%Y %l:%M %p some other junk++ For the supported strptime syntax, see:+https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime+++File: hledger_csv.info, Node: newest-first, Next: include, Prev: date-format, Up: CSV RULES++2.7 'newest-first'+==================++hledger always sorts the generated transactions by date. Transactions+on the same date should appear in the same order as their CSV records,+as hledger can usually auto-detect whether the CSV's normal order is+oldest first or newest first. But if all of the following are true:++ * the CSV might sometimes contain just one day of data (all records+ having the same date)+ * the CSV records are normally in reverse chronological order (newest+ at the top)+ * and you care about preserving the order of same-day transactions++ then, you should add the 'newest-first' rule as a hint. Eg:++# tell hledger explicitly that the CSV is normally newest first+newest-first+++File: hledger_csv.info, Node: include, Prev: newest-first, Up: CSV RULES++2.8 'include'+=============++include RULESFILE++ This includes the contents of another CSV rules file at this point.+'RULESFILE' is an absolute file path or a path relative to the current+file's directory. This can be useful for sharing common rules between+several rules files, eg:++# someaccount.csv.rules++## someaccount-specific rules+fields date,description,amount+account1 assets:someaccount+account2 expenses:misc++## common rules+include categorisation.rules+++File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top++3 TIPS+******++* Menu:++* Valid CSV::+* Other separator characters::+* Reading multiple CSV files::+* Valid transactions::+* Deduplicating importing::+* Setting amounts::+* Setting currency/commodity::+* Referencing other fields::+* How CSV rules are evaluated::+++File: hledger_csv.info, Node: Valid CSV, Next: Other separator characters, Up: TIPS++3.1 Valid CSV+=============++hledger accepts CSV conforming to RFC 4180. When CSV values are+enclosed in quotes, note:++ * they must be double quotes (not single quotes)+ * spaces outside the quotes are not allowed+++File: hledger_csv.info, Node: Other separator characters, Next: Reading multiple CSV files, Prev: Valid CSV, Up: TIPS++3.2 Other separator characters+==============================++With the '--separator 'CHAR'' option (experimental), hledger will expect+the separator to be CHAR instead of a comma. Ie it will read other+"Character Separated Values" formats, such as TSV (Tab Separated+Values). Note: on the command line, use a real tab character in quotes,+not++$ hledger -f foo.tsv --separator ' ' print+++File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Other separator characters, Up: TIPS++3.3 Reading multiple CSV files+==============================++If you use multiple '-f' options to read multiple CSV files at once,+hledger will look for a correspondingly-named rules file for each CSV+file. But if you use the '--rules-file' option, that rules file will be+used for all the CSV files.+++File: hledger_csv.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: TIPS++3.4 Valid transactions+======================++After reading a CSV file, hledger post-processes and validates the+generated journal entries as it would for a journal file - balancing+them, applying balance assignments, and canonicalising amount styles.+Any errors at this stage will be reported in the usual way, displaying+the problem entry.++ There is one exception: balance assertions, if you have generated+them, will not be checked, since normally these will work only when the+CSV data is part of the main journal. If you do need to check balance+assertions generated from CSV right away, pipe into another hledger:++$ hledger -f file.csv print | hledger -f- print+++File: hledger_csv.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: TIPS++3.5 Deduplicating, importing+============================++When you download a CSV file periodically, eg to get your latest bank+transactions, the new file may overlap with the old one, containing some+of the same records.++ The import command will (a) detect the new transactions, and (b)+append just those transactions to your main journal. It is idempotent,+so you don't have to remember how many times you ran it or with which+version of the CSV. (It keeps state in a hidden '.latest.FILE.csv'+file.) This is the easiest way to import CSV data. Eg:++# download the latest CSV files, then run this command.+# Note, no -f flags needed here.+$ hledger import *.csv [--dry]++ This method works for most CSV files. (Where records have a stable+chronological order, and new records appear only at the new end.)++ A number of other tools and workflows, hledger-specific and+otherwise, exist for converting, deduplicating, classifying and managing+CSV data. See:++ * https://hledger.org -> sidebar -> real world setups+ * https://plaintextaccounting.org -> data import/conversion+++File: hledger_csv.info, Node: Setting amounts, Next: Setting currency/commodity, Prev: Deduplicating importing, Up: TIPS++3.6 Setting amounts+===================++A posting amount can be set in one of these ways:++ * by assigning (with a fields list or field assigment) to 'amountN'+ (posting N's amount) or 'amount' (posting 1's amount)++ * by assigning to 'amountN-in' and 'amountN-out' (or 'amount-in' and+ 'amount-out'). For each CSV record, whichever of these has a+ non-zero value will be used, with appropriate sign. If both+ contain a non-zero value, this may not work.++ * by assigning to 'balanceN' (or 'balance') instead of the above,+ setting the amount indirectly via a balance assignment. If you do+ this the default account name may be wrong, so you should set that+ explicitly.++ There is some special handling for an amount's sign:++ * If an amount value is parenthesised, it will be de-parenthesised+ and sign-flipped.+ * If an amount value begins with a double minus sign, those cancel+ out and are removed.+ * If an amount value begins with a plus sign, that will be removed+++File: hledger_csv.info, Node: Setting currency/commodity, Next: Referencing other fields, Prev: Setting amounts, Up: TIPS++3.7 Setting currency/commodity+==============================++If the currency/commodity symbol is included in the CSV's amount+field(s), you don't have to do anything special.++ If the currency is provided as a separate CSV field, you can either:++ * assign that to 'currency', which adds it to all posting amounts.+ The symbol will prepended to the amount quantity (on the left+ side). If you write a trailing space after the symbol, there will+ be a space between symbol and amount (an exception to the usual+ whitespace stripping).++ * or assign it to 'currencyN' which adds it to posting N's amount+ only.++ * or for more control, construct the amount from symbol and quantity+ using field assignment, eg:++ fields date,description,currency,quantity+ # add currency symbol on the right:+ amount %quantity %currency+++File: hledger_csv.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Setting currency/commodity, Up: TIPS++3.8 Referencing other fields+============================++In field assignments, you can interpolate only CSV fields, not hledger+fields. In the example below, there's both a CSV field and a hledger+field named amount1, but %amount1 always means the CSV field, not the+hledger field:++# Name the third CSV field "amount1"+fields date,description,amount1++# Set hledger's amount1 to the CSV amount1 field followed by USD+amount1 %amount1 USD++# Set comment to the CSV amount1 (not the amount1 assigned above)+comment %amount1++ Here, since there's no CSV amount1 field, %amount1 will produce a+literal "amount1":++fields date,description,csvamount+amount1 %csvamount USD+# Can't interpolate amount1 here+comment %amount1++ When there are multiple field assignments to the same hledger field,+only the last one takes effect. Here, comment's value will be be B, or+C if "something" is matched, but never A:++comment A+comment B+if something+ comment C+++File: hledger_csv.info, Node: How CSV rules are evaluated, Prev: Referencing other fields, Up: TIPS++3.9 How CSV rules are evaluated+===============================++Here's how to think of CSV rules being evaluated (if you really need+to). First,++ * 'include' - all includes are inlined, from top to bottom, depth+ first. (At each include point the file is inlined and scanned for+ further includes, recursively, before proceeding.)++ Then "global" rules are evaluated, top to bottom. If a rule is+repeated, the last one wins:++ * 'skip' (at top level)+ * 'date-format'+ * 'newest-first'+ * 'fields' - names the CSV fields, optionally sets up initial+ assignments to hledger fields++ Then for each CSV record in turn:++ * test all 'if' blocks. If any of them contain a 'end' rule, skip+ all remaining CSV records. Otherwise if any of them contain a+ 'skip' rule, skip that many CSV records. If there are multiple+ matched 'skip' rules, the first one wins.+ * collect all field assignments at top level and in matched 'if'+ blocks. When there are multiple assignments for a field, keep only+ the last one.+ * compute a value for each hledger field - either the one that was+ assigned to it (and interpolate the %CSVFIELDNAME references), or a+ default+ * generate a synthetic hledger transaction from these values.++ This is all part of the CSV reader, one of several readers hledger+can use to parse input files. When all files have been read+successfully, the transactions are passed as input to whichever hledger+command the user specified.+++Tag Table:+Node: Top72+Node: EXAMPLES1829+Ref: #examples1935+Node: Basic2143+Ref: #basic2243+Node: Bank of Ireland2785+Ref: #bank-of-ireland2920+Node: Amazon4383+Ref: #amazon4501+Node: Paypal6434+Ref: #paypal6528+Node: CSV RULES14411+Ref: #csv-rules14520+Node: skip14765+Ref: #skip14858+Node: fields15233+Ref: #fields15355+Node: Transaction field names16422+Ref: #transaction-field-names16582+Node: Posting field names16693+Ref: #posting-field-names16845+Node: field assignment18077+Ref: #field-assignment18213+Node: if19031+Ref: #if19140+Node: end20856+Ref: #end20962+Node: date-format21186+Ref: #date-format21318+Node: newest-first22067+Ref: #newest-first22205+Node: include22888+Ref: #include22996+Node: TIPS23440+Ref: #tips23522+Node: Valid CSV23771+Ref: #valid-csv23890+Node: Other separator characters24082+Ref: #other-separator-characters24270+Node: Reading multiple CSV files24599+Ref: #reading-multiple-csv-files24796+Node: Valid transactions25037+Ref: #valid-transactions25215+Node: Deduplicating importing25843+Ref: #deduplicating-importing26022+Node: Setting amounts27055+Ref: #setting-amounts27224+Node: Setting currency/commodity28210+Ref: #setting-currencycommodity28402+Node: Referencing other fields29205+Ref: #referencing-other-fields29405+Node: How CSV rules are evaluated30302+Ref: #how-csv-rules-are-evaluated30473 End Tag Table
embeddedfiles/hledger_csv.txt view
@@ -7,48 +7,136 @@ CSV - how hledger reads CSV data, and the CSV rules file format DESCRIPTION- hledger can read CSV (comma-separated value) files as if they were- journal files, automatically converting each CSV record into a transac-- tion. (To learn about writing CSV, see CSV output.)+ hledger can read CSV (comma-separated value, or character-separated+ value) files as if they were journal files, automatically converting+ each CSV record into a transaction. (To learn about writing CSV, see+ CSV output.) - Converting CSV to transactions requires some special conversion rules.- These do several things:+ We describe each CSV file's format with a corresponding rules file. By+ default this is named like the CSV file with a .rules extension added.+ Eg when reading FILE.csv, hledger also looks for FILE.csv.rules in the+ same directory. You can specify a different rules file with the+ --rules-file option. If a rules file is not found, hledger will create+ a sample rules file, which you'll need to adjust. - o they describe the layout and format of the CSV data+ This file contains rules describing the CSV data (header line, fields+ layout, date format etc.), and how to construct hledger journal entries+ (transactions) from it. Often there will also be a list of conditional+ rules for categorising transactions based on their descriptions.+ Here's an overview of the CSV rules; these are described more fully be-+ low, after the examples: - o they can customize the generated journal entries using a simple tem-- plating language+ skip skip one or more header+ lines or matched CSV+ records+ fields name CSV fields, assign+ them to hledger fields+ field assignment assign a value to one+ hledger field, with inter-+ polation+ if apply some rules to+ matched CSV records+ end skip the remaining CSV+ records+ date-format describe the format of CSV+ dates+ newest-first disambiguate record order+ when there's only one date+ include inline another CSV rules+ file - o they can add refinements based on patterns in the CSV data, eg cate-- gorizing transactions with more detailed account names.+ There's also a Convert CSV files tutorial on hledger.org. - When reading a CSV file named FILE.csv, hledger looks for a conversion- rules file named FILE.csv.rules in the same directory. You can over-- ride this with the --rules-file option. If the rules file does not ex-- ist, hledger will auto-create one with some example rules, which you'll- need to adjust.+EXAMPLES+ Here are some sample hledger CSV rules files. See also the full col-+ lection at:+ https://github.com/simonmichael/hledger/tree/master/examples/csv - At minimum, the rules file must identify the date and amount fields.- It's often necessary to specify the date format, and the number of- header lines to skip, also. Eg:+ Basic+ At minimum, the rules file must identify the date and amount fields,+ and often it also specifies the date format and how many header lines+ there are. Here's a simple CSV file and a rules file for it: - fields date, _, _, amount+ Date, Description, Id, Amount+ 12/11/2019, Foo, 123, 10.23++ # basic.csv.rules+ skip 1+ fields date, description, _, amount date-format %d/%m/%Y- skip 1 - A more complete example:+ $ hledger print -f basic.csv+ 2019/11/12 Foo+ expenses:unknown 10.23+ income:unknown -10.23 - # hledger CSV rules for amazon.com order history+ Default account names are chosen, since we didn't set them. - # sample:- # "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"- # "Jul 29, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL"+ Bank of Ireland+ Here's a CSV with two amount fields (Debit and Credit), and a balance+ field, which we can use to add balance assertions, which is not neces-+ sary but provides extra error checking: + Date,Details,Debit,Credit,Balance+ 07/12/2012,LODGMENT 529898,,10.0,131.21+ 07/12/2012,PAYMENT,5,,126++ # bankofireland-checking.csv.rules++ # skip the header line+ skip++ # name the csv fields, and assign some of them as journal entry fields+ fields date, description, amount-out, amount-in, balance++ # We generate balance assertions by assigning to "balance"+ # above, but you may sometimes need to remove these because:+ #+ # - the CSV balance differs from the true balance,+ # by up to 0.0000000000005 in my experience+ #+ # - it is sometimes calculated based on non-chronological ordering,+ # eg when multiple transactions clear on the same day++ # date is in UK/Ireland format+ date-format %d/%m/%Y++ # set the currency+ currency EUR++ # set the base account for all txns+ account1 assets:bank:boi:checking++ $ hledger -f bankofireland-checking.csv print+ 2012/12/07 LODGMENT 529898+ assets:bank:boi:checking EUR10.0 = EUR131.2+ income:unknown EUR-10.0++ 2012/12/07 PAYMENT+ assets:bank:boi:checking EUR-5.0 = EUR126.0+ expenses:unknown EUR5.0++ The balance assertions don't raise an error above, because we're read-+ ing directly from CSV, but they will be checked if these entries are+ imported into a journal file.++ Amazon+ Here we convert amazon.com order history, and use an if block to gener-+ ate a third posting if there's a fee. (In practice you'd probably get+ this data from your bank instead, but it's an example.)++ "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"+ "Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"+ "Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"++ # amazon-orders.csv.rules+ # skip one header line skip 1 - # name the csv fields (and assign the transaction's date, amount and code)- fields date, _, toorfrom, name, amzstatus, amount, fees, code+ # name the csv fields, and assign the transaction's date, amount and code.+ # Avoided the "status" and "amount" hledger field names to prevent confusion.+ fields date, _, toorfrom, name, amzstatus, amzamount, fees, code # how to parse the date date-format %b %-d, %Y@@ -56,104 +144,328 @@ # combine two fields to make the description description %toorfrom %name - # save these fields as tags- comment status:%amzstatus, fees:%fees+ # save the status as a tag+ comment status:%amzstatus # set the base account for all transactions account1 assets:amazon+ # leave amount1 blank so it can balance the other(s).+ # I'm assuming amzamount excludes the fees, don't remember - # flip the sign on the amount- amount -%amount+ # set a generic account2+ account2 expenses:misc+ amount2 %amzamount+ # and maybe refine it further:+ #include categorisation.rules - For more examples, see Convert CSV files.+ # add a third posting for fees, but only if they are non-zero.+ # Commas in the data makes counting fields hard, so count from the right instead.+ # (Regex translation: "a field containing a non-zero dollar amount,+ # immediately before the 1 right-most fields")+ if ,\$[1-9][.0-9]+(,[^,]*){1}$+ account3 expenses:fees+ amount3 %fees + $ hledger -f amazon-orders.csv print+ 2012/07/29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed+ assets:amazon+ expenses:misc $20.00++ 2012/07/30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed+ assets:amazon+ expenses:misc $25.00+ expenses:fees $1.00++ Paypal+ Here's a real-world rules file for (customised) Paypal CSV, with some+ Paypal-specific rules, and a second rules file included:++ "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"+ "10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""+ "10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""+ "10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""+ "10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""+ "10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""+ "10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""+ "10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""++ # paypal-custom.csv.rules++ # Tips:+ # Export from Activity -> Statements -> Custom -> Activity download+ # Suggested transaction type: "Balance affecting"+ # Paypal's default fields in 2018 were:+ # "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"+ # This rules file assumes the following more detailed fields, configured in "Customize report fields":+ # "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"++ fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note++ skip 1++ date-format %-m/%-d/%Y++ # ignore some paypal events+ if+ In Progress+ Temporary Hold+ Update to+ skip++ # add more fields to the description+ description %description_ %itemtitle++ # save some other fields as tags+ comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_++ # convert to short currency symbols+ # Note: in conditional block regexps, the line of csv being matched is+ # a synthetic one: the unquoted field values, with commas between them.+ if ,USD,+ currency $+ if ,EUR,+ currency E+ if ,GBP,+ currency P++ # generate postings++ # the first posting will be the money leaving/entering my paypal account+ # (negative means leaving my account, in all amount fields)+ account1 assets:online:paypal+ amount1 %netamount++ # the second posting will be money sent to/received from other party+ # (account2 is set below)+ amount2 -%grossamount++ # if there's a fee (9th field), add a third posting for the money taken by paypal.+ # TODO: This regexp fails when fields contain a comma (generates a third posting with zero amount)+ if ^([^,]+,){8}[^0]+ account3 expenses:banking:paypal+ amount3 -%feeamount+ comment3 business:++ # choose an account for the second posting++ # override the default account names:+ # if amount (8th field) is positive, it's income (a debit)+ if ^([^,]+,){7}[0-9]+ account2 income:unknown+ # if negative, it's an expense (a credit)+ if ^([^,]+,){7}-+ account2 expenses:unknown++ # apply common rules for setting account2 & other tweaks+ include common.rules++ # apply some overrides specific to this csv++ # Transfers from/to bank. These are usually marked Pending,+ # which can be disregarded in this case.+ if+ Bank Account+ Bank Deposit to PP Account+ description %type for %referencetxnid %itemtitle+ account2 assets:bank:wf:pchecking+ account1 assets:online:paypal++ # Currency conversions+ if Currency Conversion+ account2 equity:currency conversion++ # common.rules++ if+ darcs+ noble benefactor+ account2 revenues:foss donations:darcshub+ comment2 business:++ if+ Calm Radio+ account2 expenses:online:apps++ if+ electronic frontier foundation+ Patreon+ wikimedia+ Advent of Code+ account2 expenses:dues++ if Google+ account2 expenses:online:apps+ description google | music++ $ hledger -f paypal-custom.csv print+ 2019/10/01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed+ assets:online:paypal $-6.99 = $-6.99+ expenses:online:apps $6.99++ 2019/10/01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $6.99 = $0.00+ assets:bank:wf:pchecking $-6.99++ 2019/10/01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed+ assets:online:paypal $-7.00 = $-7.00+ expenses:dues $7.00++ 2019/10/01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $7.00 = $0.00+ assets:bank:wf:pchecking $-7.00++ 2019/10/19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed+ assets:online:paypal $-2.00 = $-2.00+ expenses:dues $2.00+ expenses:banking:paypal ; business:++ 2019/10/19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $2.00 = $0.00+ assets:bank:wf:pchecking $-2.00++ 2019/10/22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed+ assets:online:paypal $9.41 = $9.41+ revenues:foss donations:darcshub $-10.00 ; business:+ expenses:banking:paypal $0.59 ; business:+ CSV RULES- The following seven kinds of rule can appear in the rules file, in any- order. Blank lines and lines beginning with # or ; are ignored.+ The following kinds of rule can appear in the rules file, in any order.+ Blank lines and lines beginning with # or ; are ignored. skip- skipN+ skip N - Skip this number of CSV records at the beginning. You'll need this- whenever your CSV data contains header lines. Eg:+ The word "skip" followed by a number (or no number, meaning 1) tells+ hledger to ignore this many non-empty lines preceding the CSV data.+ (Empty/blank lines are skipped automatically.) You'll need this when-+ ever your CSV data contains header lines. - # ignore the first CSV line- skip 1+ It also has a second purpose: it can be used inside if blocks to ignore+ certain CSV records (described below). - date-format- date-formatDATEFMT+ fields+ fields FIELDNAME1, FIELDNAME2, ... - When your CSV date fields are not formatted like YYYY/MM/DD (or YYYY-- MM-DD or YYYY.MM.DD), you'll need to specify the format. DATEFMT is a- strptime-like date parsing pattern, which must parse the date field- values completely. Examples:+ A fields list (the word "fields" followed by comma-separated field+ names) is the quick way to assign CSV field values to hledger fields.+ It does two things: - # for dates like "11/06/2013":- date-format %m/%d/%Y+ 1. it names the CSV fields. This is optional, but can be convenient+ later for interpolating them. - # for dates like "6/11/2013" (note the - to make leading zeros optional):- date-format %-d/%-m/%Y+ 2. when you use a standard hledger field name, it assigns the CSV value+ to that part of the hledger transaction. - # for dates like "2013-Nov-06":- date-format %Y-%h-%d+ Here's an example that says "use the 1st, 2nd and 4th fields as the+ transaction's date, description and amount; name the last two fields+ for later reference; and ignore the others": - # for dates like "11/6/2013 11:32 PM":- date-format %-m/%-d/%Y %l:%M %p+ fields date, description, , amount, , , somefield, anotherfield - field list- fieldsFIELDNAME1, FIELDNAME2...+ Field names may not contain whitespace. Fields you don't care about+ can be left unnamed. Currently there must be least two items (there+ must be at least one comma). - This (a) names the CSV fields, in order (names may not contain white-- space; uninteresting names may be left blank), and (b) assigns them to- journal entry fields if you use any of these standard field names:- date, date2, status, code, description, comment, account1, account2,- amount, amount-in, amount-out, currency, balance, balance1, balance2.- Eg:+ Here are the standard hledger field/pseudo-field names. For more about+ the transaction parts they refer to, see the manual for hledger's jour-+ nal format. - # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount,- # and give the 7th and 8th fields meaningful names for later reference:- #- # CSV field:- # 1 2 3 4 5 6 7 8- # entry field:- fields date, description, , amount, , , somefield, anotherfield+ Transaction field names+ date, date2, status, code, description, comment can be used to form the+ transaction's first line. + Posting field names+ accountN, where N is 1 to 9, generates a posting, with that account+ name. Most often there are two postings, so you'll want to set ac-+ count1 and account2. If a posting's account name is left unset but its+ amount is set, a default account name will be chosen (like expenses:un-+ known or income:unknown).++ amountN sets posting N's amount. Or, amount with no N sets posting+ 1's. If the CSV has debits and credits in separate fields, use+ amountN-in and amountN-out instead. Or amount-in and amount-out with+ no N for posting 1.++ For convenience and backwards compatibility, if you set the amount of+ posting 1 only, a second posting with the negative amount will be gen-+ erated automatically. (Unless the account name is parenthesised indi-+ cating an unbalanced posting.)++ If the CSV has the currency symbol in a separate field, you can use+ currencyN to prepend it to posting N's amount. currency with no N af-+ fects ALL postings.++ balanceN sets a balance assertion amount (or if the posting amount is+ left empty, a balance assignment).++ Finally, commentN sets a comment on the Nth posting. Comments can also+ contain tags, as usual.++ See TIPS below for more about setting amounts and currency.+ field assignment- ENTRYFIELDNAME FIELDVALUE+ HLEDGERFIELDNAME FIELDVALUE - This sets a journal entry field (one of the standard names above) to- the given text value, which can include CSV field values interpolated- by name (%CSVFIELDNAME) or 1-based position (%N). Eg:+ Instead of or in addition to a fields list, you can use a "field as-+ signment" rule to set the value of a single hledger field, by writing+ its name (any of the standard hledger field names above) followed by a+ text value. The value may contain interpolated CSV fields, referenced+ by their 1-based position in the CSV record (%N), or by the name they+ were given in the fields list (%CSVFIELDNAME). Some examples: - # set the amount to the 4th CSV field with "USD " prepended- amount USD %4+ # set the amount to the 4th CSV field, with " USD" appended+ amount %4 USD - # combine three fields to make a comment (containing two tags)+ # combine three fields to make a comment, containing note: and date: tags comment note: %somefield - %anotherfield, date: %1 - Field assignments can be used instead of or in addition to a field- list.+ Interpolation strips outer whitespace (so a CSV value like " 1 " be-+ comes 1 when interpolated) (#1051). See TIPS below for more about ref-+ erencing other fields. - Note, interpolation strips any outer whitespace, so a CSV value like "- 1 " becomes 1 when interpolated (#1051).+ if+ if PATTERN+ RULE - conditional block- if PATTERN- FIELDASSIGNMENTS...+ if+ PATTERN+ PATTERN+ PATTERN+ RULE+ RULE - if- PATTERN- PATTERN...- FIELDASSIGNMENTS...+ Conditional blocks ("if blocks") are a block of rules that are applied+ only to CSV records which match certain patterns. They are often used+ for customising account names based on transaction descriptions. - This applies one or more field assignments, only to those CSV records- matched by one of the PATTERNs. The patterns are case-insensitive reg-- ular expressions which match anywhere within the whole CSV record (it's- not yet possible to match within a specific field). When there are- multiple patterns they can be written on separate lines, unindented.- The field assignments are on separate lines indented by at least one- space. Examples:+ A single pattern can be written on the same line as the "if"; or multi-+ ple patterns can be written on the following lines, non-indented. Mul-+ tiple patterns are OR'd (any one of them can match). Patterns are+ case-insensitive regular expressions which try to match anywhere within+ the whole CSV record (POSIX extended regular expressions with some ad-+ ditions, see https://hledger.org/hledger.html#regular-expressions).+ Note the CSV record they see is close to, but not identical to, the one+ in the CSV file; enclosing double quotes will be removed, and the sepa-+ rator character is always comma. + It's not yet easy to match within a specific field. If the data does+ not contain commas, you can hack it with a regular expression like:++ # match "foo" in the fourth field+ if ^([^,]*,){3}foo++ After the patterns there should be one or more rules to apply, all in-+ dented by at least one space. Three kinds of rule are allowed in con-+ ditional blocks:++ o field assignments (to set a hledger field)++ o skip (to skip the matched CSV record)++ o end (to skip all remaining CSV records).++ Examples:+ # if the CSV record contains "groceries", set account2 to "expenses:groceries" if groceries account2 expenses:groceries@@ -166,95 +478,267 @@ account2 expenses:business:banking comment XXX deductible ? check it - include- includeRULESFILE+ end+ This rule can be used inside if blocks (only), to make hledger stop+ reading this CSV file and move on to the next input file, or to command+ execution. Eg: - Include another rules file at this point. RULESFILE is either an abso-- lute file path or a path relative to the current file's directory. Eg:+ # ignore everything following the first empty record+ if ,,,,+ end - # rules reused with several CSV files- include common.rules+ date-format+ date-format DATEFMT + This is a helper for the date (and date2) fields. If your CSV dates+ are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll+ need to add a date-format rule describing them with a strptime date+ parsing pattern, which must parse the CSV date value completely. Some+ examples:++ # MM/DD/YY+ date-format %m/%d/%y++ # D/M/YYYY+ # The - makes leading zeros optional.+ date-format %-d/%-m/%Y++ # YYYY-Mmm-DD+ date-format %Y-%h-%d++ # M/D/YYYY HH:MM AM some other junk+ # Note the time and junk must be fully parsed, though only the date is used.+ date-format %-m/%-d/%Y %l:%M %p some other junk++ For the supported strptime syntax, see:+ https://hackage.haskell.org/package/time/docs/Data-Time-For-+ mat.html#v:formatTime+ newest-first- newest-first+ hledger always sorts the generated transactions by date. Transactions+ on the same date should appear in the same order as their CSV records,+ as hledger can usually auto-detect whether the CSV's normal order is+ oldest first or newest first. But if all of the following are true: - Consider adding this rule if all of the following are true: you might- be processing just one day of data, your CSV records are in reverse- chronological order (newest first), and you care about preserving the- order of same-day transactions. It usually isn't needed, because- hledger autodetects the CSV order, but when all CSV records have the- same date it will assume they are oldest first.+ o the CSV might sometimes contain just one day of data (all records+ having the same date) -CSV TIPS- CSV ordering- The generated journal entries will be sorted by date. The order of- same-day entries will be preserved (except in the special case where- you might need newest-first, see above).+ o the CSV records are normally in reverse chronological order (newest+ at the top) - CSV accounts- Each journal entry will have two postings, to account1 and account2 re-- spectively. It's not yet possible to generate entries with more than- two postings. It's conventional and recommended to use account1 for- the account whose CSV we are reading.+ o and you care about preserving the order of same-day transactions - CSV amounts- A transaction amount must be set, in one of these ways:+ then, you should add the newest-first rule as a hint. Eg: - o with an amount field assignment, which sets the first posting's- amount+ # tell hledger explicitly that the CSV is normally newest first+ newest-first - o (When the CSV has debit and credit amounts in separate fields:)- with field assignments for the amount-in and amount-out pseudo fields- (both of them). Whichever one has a value will be used, with appropri-- ate sign. If both contain a value, it might not work so well.+ include+ include RULESFILE - o or implicitly by means of a balance assignment (see below).+ This includes the contents of another CSV rules file at this point.+ RULESFILE is an absolute file path or a path relative to the current+ file's directory. This can be useful for sharing common rules between+ several rules files, eg: - There is some special handling for sign in amounts:+ # someaccount.csv.rules - o If an amount value is parenthesised, it will be de-parenthesised and- sign-flipped.+ ## someaccount-specific rules+ fields date,description,amount+ account1 assets:someaccount+ account2 expenses:misc - o If an amount value begins with a double minus sign, those will cancel- out and be removed.+ ## common rules+ include categorisation.rules - If the currency/commodity symbol is provided as a separate CSV field,- assign it to the currency pseudo field; the symbol will be prepended to- the amount (TODO: when there is an amount). Or, you can use an amount- field assignment for more control, eg:+TIPS+ Valid CSV+ hledger accepts CSV conforming to RFC 4180. When CSV values are en-+ closed in quotes, note: - fields date,description,currency,amount- amount %amount %currency+ o they must be double quotes (not single quotes) - CSV balance assertions/assignments- If the CSV includes a running balance, you can assign that to one of- the pseudo fields balance (or balance1) or balance2. This will gener-- ate a balance assertion (or if the amount is left empty, a balance as-- signment), on the first or second posting, whenever the running balance- field is non-empty. (TODO: #1000)+ o spaces outside the quotes are not allowed + Other separator characters+ With the --separator 'CHAR' option (experimental), hledger will expect+ the separator to be CHAR instead of a comma. Ie it will read other+ "Character Separated Values" formats, such as TSV (Tab Separated Val-+ ues). Note: on the command line, use a real tab character in quotes,+ not Eg:++ $ hledger -f foo.tsv --separator ' ' print+ Reading multiple CSV files- You can read multiple CSV files at once using multiple -f arguments on- the command line, and hledger will look for a correspondingly-named- rules file for each. Note if you use the --rules-file option, this one- rules file will be used for all the CSV files being read.+ If you use multiple -f options to read multiple CSV files at once,+ hledger will look for a correspondingly-named rules file for each CSV+ file. But if you use the --rules-file option, that rules file will be+ used for all the CSV files. - Valid CSV- hledger follows RFC 4180, with the addition of a customisable separator- character.+ Valid transactions+ After reading a CSV file, hledger post-processes and validates the gen-+ erated journal entries as it would for a journal file - balancing them,+ applying balance assignments, and canonicalising amount styles. Any+ errors at this stage will be reported in the usual way, displaying the+ problem entry. - Some things to note:+ There is one exception: balance assertions, if you have generated them,+ will not be checked, since normally these will work only when the CSV+ data is part of the main journal. If you do need to check balance as-+ sertions generated from CSV right away, pipe into another hledger: - When quoting fields,+ $ hledger -f file.csv print | hledger -f- print - o you must use double quotes, not single quotes+ Deduplicating, importing+ When you download a CSV file periodically, eg to get your latest bank+ transactions, the new file may overlap with the old one, containing+ some of the same records. - o spaces outside the quotes are not allowed.+ The import command will (a) detect the new transactions, and (b) append+ just those transactions to your main journal. It is idempotent, so you+ don't have to remember how many times you ran it or with which version+ of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This+ is the easiest way to import CSV data. Eg: + # download the latest CSV files, then run this command.+ # Note, no -f flags needed here.+ $ hledger import *.csv [--dry] + This method works for most CSV files. (Where records have a stable+ chronological order, and new records appear only at the new end.) + A number of other tools and workflows, hledger-specific and otherwise,+ exist for converting, deduplicating, classifying and managing CSV data.+ See:++ o https://hledger.org -> sidebar -> real world setups++ o https://plaintextaccounting.org -> data import/conversion++ Setting amounts+ A posting amount can be set in one of these ways:++ o by assigning (with a fields list or field assigment) to amountN+ (posting N's amount) or amount (posting 1's amount)++ o by assigning to amountN-in and amountN-out (or amount-in and amount-+ out). For each CSV record, whichever of these has a non-zero value+ will be used, with appropriate sign. If both contain a non-zero+ value, this may not work.++ o by assigning to balanceN (or balance) instead of the above, setting+ the amount indirectly via a balance assignment. If you do this the+ default account name may be wrong, so you should set that explicitly.++ There is some special handling for an amount's sign:++ o If an amount value is parenthesised, it will be de-parenthesised and+ sign-flipped.++ o If an amount value begins with a double minus sign, those cancel out+ and are removed.++ o If an amount value begins with a plus sign, that will be removed++ Setting currency/commodity+ If the currency/commodity symbol is included in the CSV's amount+ field(s), you don't have to do anything special.++ If the currency is provided as a separate CSV field, you can either:++ o assign that to currency, which adds it to all posting amounts. The+ symbol will prepended to the amount quantity (on the left side). If+ you write a trailing space after the symbol, there will be a space+ between symbol and amount (an exception to the usual whitespace+ stripping).++ o or assign it to currencyN which adds it to posting N's amount only.++ o or for more control, construct the amount from symbol and quantity+ using field assignment, eg:++ fields date,description,currency,quantity+ # add currency symbol on the right:+ amount %quantity %currency++ Referencing other fields+ In field assignments, you can interpolate only CSV fields, not hledger+ fields. In the example below, there's both a CSV field and a hledger+ field named amount1, but %amount1 always means the CSV field, not the+ hledger field:++ # Name the third CSV field "amount1"+ fields date,description,amount1++ # Set hledger's amount1 to the CSV amount1 field followed by USD+ amount1 %amount1 USD++ # Set comment to the CSV amount1 (not the amount1 assigned above)+ comment %amount1++ Here, since there's no CSV amount1 field, %amount1 will produce a lit-+ eral "amount1":++ fields date,description,csvamount+ amount1 %csvamount USD+ # Can't interpolate amount1 here+ comment %amount1++ When there are multiple field assignments to the same hledger field,+ only the last one takes effect. Here, comment's value will be be B, or+ C if "something" is matched, but never A:++ comment A+ comment B+ if something+ comment C++ How CSV rules are evaluated+ Here's how to think of CSV rules being evaluated (if you really need+ to). First,++ o include - all includes are inlined, from top to bottom, depth first.+ (At each include point the file is inlined and scanned for further+ includes, recursively, before proceeding.)++ Then "global" rules are evaluated, top to bottom. If a rule is re-+ peated, the last one wins:++ o skip (at top level)++ o date-format++ o newest-first++ o fields - names the CSV fields, optionally sets up initial assignments+ to hledger fields++ Then for each CSV record in turn:++ o test all if blocks. If any of them contain a end rule, skip all re-+ maining CSV records. Otherwise if any of them contain a skip rule,+ skip that many CSV records. If there are multiple matched skip+ rules, the first one wins.++ o collect all field assignments at top level and in matched if blocks.+ When there are multiple assignments for a field, keep only the last+ one.++ o compute a value for each hledger field - either the one that was as-+ signed to it (and interpolate the %CSVFIELDNAME references), or a de-+ fault++ o generate a synthetic hledger transaction from these values.++ This is all part of the CSV reader, one of several readers hledger can+ use to parse input files. When all files have been read successfully,+ the transactions are passed as input to whichever hledger command the+ user specified.+++ REPORTING BUGS- Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel+ Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -263,12 +747,12 @@ COPYRIGHT- Copyright (C) 2007-2016 Simon Michael.+ Copyright (C) 2007-2019 Simon Michael. Released under GNU GPL v3 or later. SEE ALSO- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) @@ -276,4 +760,4 @@ -hledger 1.15.2 September 2019 hledger_csv(5)+hledger 1.16 December 2019 hledger_csv(5)
embeddedfiles/hledger_journal.5 view
@@ -1,6 +1,6 @@ .\"t -.TH "hledger_journal" "5" "September 2019" "hledger 1.15.2" "hledger User Manuals"+.TH "hledger_journal" "5" "December 2019" "hledger 1.16" "hledger User Manuals" @@ -337,119 +337,134 @@ .SS Amounts .PP After the account name, there is usually an amount.-Important: between account name and amount, there must be \f[B]two or-more spaces\f[R].+(Important: between account name and amount, there must be \f[B]two or+more spaces\f[R].) .PP-Amounts consist of a number and (usually) a currency symbol or commodity-name.-Some examples:+hledger\[aq]s amount format is flexible, supporting several+international formats.+Here are some examples.+Amounts have a number (the \[dq]quantity\[dq]):+.IP+.nf+\f[C]+1+\f[R]+.fi .PP-\f[C]2.00001\f[R]-.PD 0-.P-.PD-\f[C]$1\f[R]-.PD 0-.P-.PD-\f[C]4000 AAPL\f[R]-.PD 0-.P-.PD-\f[C]3 \[dq]green apples\[dq]\f[R]-.PD 0-.P-.PD-\f[C]-$1,000,000.00\f[R]-.PD 0-.P-.PD-\f[C]INR 9,99,99,999.00\f[R]-.PD 0-.P-.PD-\f[C]EUR -2.000.000,00\f[R]-.PD 0-.P-.PD-\f[C]1 999 999.9455\f[R]-.PD 0-.P-.PD-\f[C]EUR 1E3\f[R]-.PD 0-.P-.PD-\f[C]1000E-6s\f[R]+\&..and usually a currency or commodity name (the \[dq]commodity\[dq]).+This is a symbol, word, or phrase, to the left or right of the quantity,+with or without a separating space:+.IP+.nf+\f[C]+$1+4000 AAPL+\f[R]+.fi .PP-As you can see, the amount format is somewhat flexible:-.IP \[bu] 2-amounts are a number (the \[dq]quantity\[dq]) and optionally a currency-symbol/commodity name (the \[dq]commodity\[dq]).-.IP \[bu] 2-the commodity is a symbol, word, or phrase, on the left or right, with-or without a separating space.-If the commodity contains numbers, spaces or non-word punctuation it-must be enclosed in double quotes.-.IP \[bu] 2-negative amounts with a commodity on the left can have the minus sign-before or after it-.IP \[bu] 2-digit groups (thousands, or any other grouping) can be separated by-space or comma or period and should be used as separator between all-groups-.IP \[bu] 2-decimal part can be separated by comma or period and should be different-from digit groups separator-.IP \[bu] 2-scientific E-notation is allowed.-Be careful not to use a digit group separator character in scientific-notation, as it\[aq]s not supported and it might get mistaken for a-decimal point.-(Declaring the digit group separator character explicitly with a-commodity directive will prevent this.)+If the commodity name contains spaces, numbers, or punctuation, it must+be enclosed in double quotes:+.IP+.nf+\f[C]+3 \[dq]no. 42 green apples\[dq]+\f[R]+.fi .PP-You can use any of these variations when recording data.-However, there is some ambiguous way of representing numbers like-\f[C]$1.000\f[R] and \f[C]$1,000\f[R] both may mean either one thousand-or one dollar.-By default hledger will assume that this is sole delimiter is used only-for decimals.-On the other hand commodity format declared prior to that line will help-to resolve that ambiguity differently:+Amounts can be negative.+The minus sign can be written before or after a left-side commodity+symbol: .IP .nf \f[C]+-$1+$-1+\f[R]+.fi+.PP+Scientific E notation is allowed:+.IP+.nf+\f[C]+1E-6+EUR 1E3+\f[R]+.fi+.PP+A decimal mark (decimal point) can be written with a period or a comma:+.IP+.nf+\f[C]+1.23+1,23456780000009+\f[R]+.fi+.SS Digit group marks+.PP+In the integer part of the quantity (left of the decimal mark), groups+of digits can optionally be separated by a \[dq]digit group mark\[dq] -+a space, comma, or period (different from the decimal mark):+.IP+.nf+\f[C]+ $1,000,000.00+ EUR 2.000.000,00+INR 9,99,99,999.00+ 1 000 000.9455+\f[R]+.fi+.PP+Note, a number containing a single group mark and no decimal mark is+ambiguous.+Are these group marks or decimal marks ?+.IP+.nf+\f[C]+1,000+1.000+\f[R]+.fi+.PP+hledger will treat them both as decimal marks by default (cf #793).+If you use digit group marks, to prevent confusion and undetected typos+we recommend you write commodity directives at the top of the file to+explicitly declare the decimal mark (and optionally a digit group mark).+Note, these formats (\[dq]amount styles\[dq]) are specific to each+commodity, so if your data uses multiple formats, hledger can handle it:+.IP+.nf+\f[C] commodity $1,000.00--2017/12/25 New life of Scrooge- expenses:gifts $1,000- assets+commodity EUR 1.000,00+commodity INR 9,99,99,999.00+commodity 1 000 000.9455 \f[R] .fi+.SS Amount display format .PP-Though journal may contain mixed styles to represent amount, when-hledger displays amounts, it will choose a consistent format for each-commodity.-(Except for price amounts, which are always formatted as written).+For each commodity, hledger chooses a consistent format to use when+displaying amounts.+(Except price amounts, which are always displayed as written). The display format is chosen as follows: .IP \[bu] 2-if there is a commodity directive specifying the format, that is used+If there is a commodity directive for the commodity, that format is used+(see examples above). .IP \[bu] 2-otherwise the format is inferred from the first posting amount in that-commodity in the journal, and the precision (number of decimal places)-will be the maximum from all posting amounts in that commmodity+Otherwise the format of the first posting amount in that commodity seen+in the journal is used.+But the number of decimal places (\[dq]precision\[dq]) will be the+maximum from all posting amounts in that commmodity. .IP \[bu] 2-or if there are no such amounts in the journal, a default format is used+Or if there are no such amounts in the journal, a default format is used (like \f[C]$1000.00\f[R]). .PP-Price amounts and amounts in \f[C]D\f[R] directives usually don\[aq]t-affect amount format inference, but in some situations they can do so+Price amounts, and amounts in \f[C]D\f[R] directives don\[aq]t affect+the amount display format directly, but occasionally they can do so indirectly. (Eg when D\[aq]s default commodity is applied to a commodity-less amount, or when an amountless posting is balanced using a price\[aq]s-commodity, or when -V is used.) If you find this causing problems, set-the desired format with a commodity directive.+commodity, or when -V is used.) If you find this causing problems, use a+commodity directive to set the display format. .SS Virtual Postings .PP When you parenthesise the account name in a posting, we call that a@@ -1118,9 +1133,25 @@ .fi .SS Declaring commodities .PP-The \f[C]commodity\f[R] directive declares commodities which may be used-in the journal, and their display format.+The \f[C]commodity\f[R] directive has several functions:+.IP "1." 3+It declares commodities which may be used in the journal.+This is currently not enforced, but can serve as documentation.+.IP "2." 3+It declares what decimal mark character to expect when parsing input -+useful to disambiguate international number formats in your data.+(Without this, hledger will parse both \f[C]1,000\f[R] and+\f[C]1.000\f[R] as 1).+.IP "3." 3+It declares the amount display format to use in output - decimal and+digit group marks, number of decimal places, symbol placement etc. .PP+You are likely to run into one of the problems solved by commodity+directives, sooner or later, so it\[aq]s a good idea to just always use+them to declare your commodities.+.PP+A commodity directive is just the word \f[C]commodity\f[R] followed by+an amount. It may be written on a single line, like this: .IP .nf@@ -1135,8 +1166,8 @@ .fi .PP or on multiple lines, using the \[dq]format\[dq] subdirective.-In this case the commodity symbol appears twice and should be the same-in both places:+(In this case the commodity symbol appears twice and should be the same+in both places.): .IP .nf \f[C]@@ -1147,24 +1178,14 @@ ; thousands, lakhs and crores comma-separated, ; period as decimal point, and two decimal places. commodity INR- format INR 9,99,99,999.00+ format INR 1,00,00,000.00 \f[R] .fi .PP-Declaring commodites may be useful as documentation, but currently we do-not enforce that only declared commodities may be used.-This directive is mainly useful for customising the preferred display-format for a commodity.-.PP-Normally the display format is inferred from journal entries, but this-can be unpredictable; declaring it with a commodity directive overrides-this and removes ambiguity.-Towards this end, amounts in commodity directives must always be written-with a decimal point (a period or comma, followed by 0 or more decimal-digits).-.PP-Commodity directives do not affect how amounts are parsed; the parser-will read multiple formats.+The quantity of the amount does not matter; only the format is+significant.+The number must include a decimal mark: either a period or a comma,+followed by 0 or more decimal digits. .SS Default commodity .PP The \f[C]D\f[R] directive sets a default commodity (and display format),@@ -1579,12 +1600,46 @@ .SS Periodic transactions .PP Periodic transaction rules describe transactions that recur.-They allow you to generate future transactions for forecasting, without-having to write them out explicitly in the journal (with-\f[C]--forecast\f[R]).-Secondly, they also can be used to define budget goals (with-\f[C]--budget\f[R]).+They allow hledger to generate temporary future transactions to help+with forecasting, so you don\[aq]t have to write out each one in the+journal, and it\[aq]s easy to try out different forecasts.+Secondly, they are also used to define the budgets shown in budget+reports. .PP+Periodic transactions can be a little tricky, so before you use them,+read this whole section - or at least these tips:+.IP "1." 3+Two spaces accidentally added or omitted will cause you trouble - read+about this below.+.IP "2." 3+For troubleshooting, show the generated transactions with+\f[C]hledger print --forecast tag:generated\f[R] or+\f[C]hledger register --forecast tag:generated\f[R].+.IP "3." 3+Forecasted transactions will begin only after the last non-forecasted+transaction\[aq]s date.+.IP "4." 3+Forecasted transactions will end 6 months from today, by default.+See below for the exact start/end rules.+.IP "5." 3+period expressions can be tricky.+Their documentation needs improvement, but is worth studying.+.IP "6." 3+Some period expressions with a repeating interval must begin on a+natural boundary of that interval.+Eg in \f[C]weekly from DATE\f[R], DATE must be a monday.+\f[C]\[ti] weekly from 2019/10/1\f[R] (a tuesday) will give an error.+.IP "7." 3+Other period expressions with an interval are automatically expanded to+cover a whole number of that interval.+(This is done to improve reports, but it also affects periodic+transactions.+Yes, it\[aq]s a bit inconsistent with the above.) Eg:+\f[C]\[ti] every 10th day of month from 2020/01\f[R], which is+equivalent to \f[C]\[ti] every 10th day of month from 2020/01/01\f[R],+will be adjusted to start on 2019/12/10.+.SS Periodic rule syntax+.PP A periodic transaction rule looks like a normal journal entry, with the date replaced by a tilde (\f[C]\[ti]\f[R]) followed by a period expression (mnemonic: \f[C]\[ti]\f[R] looks like a recurring sine@@ -1607,7 +1662,7 @@ expression can work (useful or not). They will be relative to today\[aq]s date, unless a Y default year directive is in effect, in which case they will be relative to Y/1/1.-.SS Two spaces after the period expression+.SS Two spaces between period expression and description! .PP If the period expression is followed by a transaction description, these must be separated by \f[B]two or more spaces\f[R].@@ -1625,6 +1680,14 @@ income:acme inc \f[R] .fi+.PP+So,+.IP \[bu] 2+Do write two spaces between your period expression and your transaction+description, if any.+.IP \[bu] 2+Don\[aq]t accidentally write two spaces in the middle of your period+expression. .SS Forecasting with periodic transactions .PP With the \f[C]--forecast\f[R] flag, each periodic transaction rule@@ -1686,8 +1749,8 @@ (and also, a goal of depositing $2000 into checking) every month. Goals and actual performance can then be compared in budget reports. .PP-For more details, see: balance: Budget report and Cookbook: Budgeting-and Forecasting.+For more details, see: balance: Budget report and Budgeting and+Forecasting. .PP .SS Auto postings / transaction modifiers .PP@@ -1829,7 +1892,7 @@ .SH COPYRIGHT -Copyright (C) 2007-2016 Simon Michael.+Copyright (C) 2007-2019 Simon Michael. .br Released under GNU GPL v3 or later.
embeddedfiles/hledger_journal.info view
@@ -4,8 +4,8 @@ File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir) -hledger_journal(5) hledger 1.15.2-*********************************+hledger_journal(5) hledger 1.16+******************************* hledger's usual data source is a plain text file containing journal entries in hledger journal format. This file represents a standard@@ -337,77 +337,109 @@ 1.7 Amounts =========== -After the account name, there is usually an amount. Important: between-account name and amount, there must be *two or more spaces*.+After the account name, there is usually an amount. (Important: between+account name and amount, there must be *two or more spaces*.) - Amounts consist of a number and (usually) a currency symbol or-commodity name. Some examples:+ hledger's amount format is flexible, supporting several international+formats. Here are some examples. Amounts have a number (the+"quantity"): - '2.00001'-'$1'-'4000 AAPL'-'3 "green apples"'-'-$1,000,000.00'-'INR 9,99,99,999.00'-'EUR -2.000.000,00'-'1 999 999.9455'-'EUR 1E3'-'1000E-6s'+1 - As you can see, the amount format is somewhat flexible:+ ..and usually a currency or commodity name (the "commodity"). This+is a symbol, word, or phrase, to the left or right of the quantity, with+or without a separating space: - * amounts are a number (the "quantity") and optionally a currency- symbol/commodity name (the "commodity").- * the commodity is a symbol, word, or phrase, on the left or right,- with or without a separating space. If the commodity contains- numbers, spaces or non-word punctuation it must be enclosed in- double quotes.- * negative amounts with a commodity on the left can have the minus- sign before or after it- * digit groups (thousands, or any other grouping) can be separated by- space or comma or period and should be used as separator between- all groups- * decimal part can be separated by comma or period and should be- different from digit groups separator- * scientific E-notation is allowed. Be careful not to use a digit- group separator character in scientific notation, as it's not- supported and it might get mistaken for a decimal point.- (Declaring the digit group separator character explicitly with a- commodity directive will prevent this.)+$1+4000 AAPL - You can use any of these variations when recording data. However,-there is some ambiguous way of representing numbers like '$1.000' and-'$1,000' both may mean either one thousand or one dollar. By default-hledger will assume that this is sole delimiter is used only for-decimals. On the other hand commodity format declared prior to that-line will help to resolve that ambiguity differently:+ If the commodity name contains spaces, numbers, or punctuation, it+must be enclosed in double quotes: +3 "no. 42 green apples"++ Amounts can be negative. The minus sign can be written before or+after a left-side commodity symbol:++-$1+$-1++ Scientific E notation is allowed:++1E-6+EUR 1E3++ A decimal mark (decimal point) can be written with a period or a+comma:++1.23+1,23456780000009++* Menu:++* Digit group marks::+* Amount display format::+++File: hledger_journal.info, Node: Digit group marks, Next: Amount display format, Up: Amounts++1.7.1 Digit group marks+-----------------------++In the integer part of the quantity (left of the decimal mark), groups+of digits can optionally be separated by a "digit group mark" - a space,+comma, or period (different from the decimal mark):++ $1,000,000.00+ EUR 2.000.000,00+INR 9,99,99,999.00+ 1 000 000.9455++ Note, a number containing a single group mark and no decimal mark is+ambiguous. Are these group marks or decimal marks ?++1,000+1.000++ hledger will treat them both as decimal marks by default (cf #793).+If you use digit group marks, to prevent confusion and undetected typos+we recommend you write commodity directives at the top of the file to+explicitly declare the decimal mark (and optionally a digit group mark).+Note, these formats ("amount styles") are specific to each commodity, so+if your data uses multiple formats, hledger can handle it:+ commodity $1,000.00+commodity EUR 1.000,00+commodity INR 9,99,99,999.00+commodity 1 000 000.9455 -2017/12/25 New life of Scrooge- expenses:gifts $1,000- assets++File: hledger_journal.info, Node: Amount display format, Prev: Digit group marks, Up: Amounts - Though journal may contain mixed styles to represent amount, when-hledger displays amounts, it will choose a consistent format for each-commodity. (Except for price amounts, which are always formatted as-written). The display format is chosen as follows:+1.7.2 Amount display format+--------------------------- - * if there is a commodity directive specifying the format, that is- used- * otherwise the format is inferred from the first posting amount in- that commodity in the journal, and the precision (number of decimal- places) will be the maximum from all posting amounts in that- commmodity- * or if there are no such amounts in the journal, a default format is+For each commodity, hledger chooses a consistent format to use when+displaying amounts. (Except price amounts, which are always displayed+as written). The display format is chosen as follows:++ * If there is a commodity directive for the commodity, that format is+ used (see examples above).++ * Otherwise the format of the first posting amount in that commodity+ seen in the journal is used. But the number of decimal places+ ("precision") will be the maximum from all posting amounts in that+ commmodity.++ * Or if there are no such amounts in the journal, a default format is used (like '$1000.00'). - Price amounts and amounts in 'D' directives usually don't affect-amount format inference, but in some situations they can do so-indirectly. (Eg when D's default commodity is applied to a-commodity-less amount, or when an amountless posting is balanced using a-price's commodity, or when -V is used.) If you find this causing-problems, set the desired format with a commodity directive.+ Price amounts, and amounts in 'D' directives don't affect the amount+display format directly, but occasionally they can do so indirectly.+(Eg when D's default commodity is applied to a commodity-less amount, or+when an amountless posting is balanced using a price's commodity, or+when -V is used.) If you find this causing problems, use a commodity+directive to set the display format. File: hledger_journal.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT@@ -991,11 +1023,27 @@ 1.14.4 Declaring commodities ---------------------------- -The 'commodity' directive declares commodities which may be used in the-journal, and their display format.+The 'commodity' directive has several functions: - It may be written on a single line, like this:+ 1. It declares commodities which may be used in the journal. This is+ currently not enforced, but can serve as documentation. + 2. It declares what decimal mark character to expect when parsing+ input - useful to disambiguate international number formats in your+ data. (Without this, hledger will parse both '1,000' and '1.000'+ as 1).++ 3. It declares the amount display format to use in output - decimal+ and digit group marks, number of decimal places, symbol placement+ etc.++ You are likely to run into one of the problems solved by commodity+directives, sooner or later, so it's a good idea to just always use them+to declare your commodities.++ A commodity directive is just the word 'commodity' followed by an+amount. It may be written on a single line, like this:+ ; commodity EXAMPLEAMOUNT ; display AAAA amounts with the symbol on the right, space-separated,@@ -1003,9 +1051,9 @@ ; separating thousands with comma. commodity 1,000.0000 AAAA - or on multiple lines, using the "format" subdirective. In this case+ or on multiple lines, using the "format" subdirective. (In this case the commodity symbol appears twice and should be the same in both-places:+places.): ; commodity SYMBOL ; format EXAMPLEAMOUNT@@ -1014,21 +1062,11 @@ ; thousands, lakhs and crores comma-separated, ; period as decimal point, and two decimal places. commodity INR- format INR 9,99,99,999.00-- Declaring commodites may be useful as documentation, but currently we-do not enforce that only declared commodities may be used. This-directive is mainly useful for customising the preferred display format-for a commodity.-- Normally the display format is inferred from journal entries, but-this can be unpredictable; declaring it with a commodity directive-overrides this and removes ambiguity. Towards this end, amounts in-commodity directives must always be written with a decimal point (a-period or comma, followed by 0 or more decimal digits).+ format INR 1,00,00,000.00 - Commodity directives do not affect how amounts are parsed; the parser-will read multiple formats.+ The quantity of the amount does not matter; only the format is+significant. The number must include a decimal mark: either a period or+a comma, followed by 0 or more decimal digits. File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives@@ -1412,12 +1450,52 @@ ========================== Periodic transaction rules describe transactions that recur. They allow-you to generate future transactions for forecasting, without having to-write them out explicitly in the journal (with '--forecast'). Secondly,-they also can be used to define budget goals (with '--budget').+hledger to generate temporary future transactions to help with+forecasting, so you don't have to write out each one in the journal, and+it's easy to try out different forecasts. Secondly, they are also used+to define the budgets shown in budget reports. - A periodic transaction rule looks like a normal journal entry, with-the date replaced by a tilde ('~') followed by a period expression+ Periodic transactions can be a little tricky, so before you use them,+read this whole section - or at least these tips:++ 1. Two spaces accidentally added or omitted will cause you trouble -+ read about this below.+ 2. For troubleshooting, show the generated transactions with 'hledger+ print --forecast tag:generated' or 'hledger register --forecast+ tag:generated'.+ 3. Forecasted transactions will begin only after the last+ non-forecasted transaction's date.+ 4. Forecasted transactions will end 6 months from today, by default.+ See below for the exact start/end rules.+ 5. period expressions can be tricky. Their documentation needs+ improvement, but is worth studying.+ 6. Some period expressions with a repeating interval must begin on a+ natural boundary of that interval. Eg in 'weekly from DATE', DATE+ must be a monday. '~ weekly from 2019/10/1' (a tuesday) will give+ an error.+ 7. Other period expressions with an interval are automatically+ expanded to cover a whole number of that interval. (This is done+ to improve reports, but it also affects periodic transactions.+ Yes, it's a bit inconsistent with the above.) Eg: '~ every 10th+ day of month from 2020/01', which is equivalent to '~ every 10th+ day of month from 2020/01/01', will be adjusted to start on+ 2019/12/10.++* Menu:++* Periodic rule syntax::+* Two spaces between period expression and description!::+* Forecasting with periodic transactions::+* Budgeting with periodic transactions::+++File: hledger_journal.info, Node: Periodic rule syntax, Next: Two spaces between period expression and description!, Up: Periodic transactions++1.15.1 Periodic rule syntax+---------------------------++A periodic transaction rule looks like a normal journal entry, with the+date replaced by a tilde ('~') followed by a period expression (mnemonic: '~' looks like a recurring sine wave.): ~ monthly@@ -1433,17 +1511,11 @@ date, unless a Y default year directive is in effect, in which case they will be relative to Y/1/1. -* Menu:--* Two spaces after the period expression::-* Forecasting with periodic transactions::-* Budgeting with periodic transactions::- -File: hledger_journal.info, Node: Two spaces after the period expression, Next: Forecasting with periodic transactions, Up: Periodic transactions+File: hledger_journal.info, Node: Two spaces between period expression and description!, Next: Forecasting with periodic transactions, Prev: Periodic rule syntax, Up: Periodic transactions -1.15.1 Two spaces after the period expression----------------------------------------------+1.15.2 Two spaces between period expression and description!+------------------------------------------------------------ If the period expression is followed by a transaction description, these must be separated by *two or more spaces*. This helps hledger know@@ -1457,10 +1529,17 @@ assets:bank:checking $1500 income:acme inc + So,++ * Do write two spaces between your period expression and your+ transaction description, if any.+ * Don't accidentally write two spaces in the middle of your period+ expression.+ -File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces after the period expression, Up: Periodic transactions+File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces between period expression and description!, Up: Periodic transactions -1.15.2 Forecasting with periodic transactions+1.15.3 Forecasting with periodic transactions --------------------------------------------- With the '--forecast' flag, each periodic transaction rule generates@@ -1513,7 +1592,7 @@ File: hledger_journal.info, Node: Budgeting with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions -1.15.3 Budgeting with periodic transactions+1.15.4 Budgeting with periodic transactions ------------------------------------------- With the '--budget' flag, currently supported by the balance command,@@ -1523,8 +1602,8 @@ checking) every month. Goals and actual performance can then be compared in budget reports. - For more details, see: balance: Budget report and Cookbook: Budgeting-and Forecasting.+ For more details, see: balance: Budget report and Budgeting and+Forecasting. File: hledger_journal.info, Node: Auto postings / transaction modifiers, Prev: Periodic transactions, Up: FILE FORMAT@@ -1668,113 +1747,119 @@ Tag Table: Node: Top76-Node: FILE FORMAT2356-Ref: #file-format2480-Node: Transactions2783-Ref: #transactions2904-Node: Postings3588-Ref: #postings3715-Node: Dates4710-Ref: #dates4825-Node: Simple dates4890-Ref: #simple-dates5016-Node: Secondary dates5382-Ref: #secondary-dates5536-Node: Posting dates7099-Ref: #posting-dates7228-Node: Status8600-Ref: #status8720-Node: Description10428-Ref: #description10566-Node: Payee and note10886-Ref: #payee-and-note11000-Node: Account names11335-Ref: #account-names11478-Node: Amounts11965-Ref: #amounts12101-Node: Virtual Postings15118-Ref: #virtual-postings15277-Node: Balance Assertions16497-Ref: #balance-assertions16672-Node: Assertions and ordering17631-Ref: #assertions-and-ordering17817-Node: Assertions and included files18517-Ref: #assertions-and-included-files18758-Node: Assertions and multiple -f options19091-Ref: #assertions-and-multiple--f-options19345-Node: Assertions and commodities19477-Ref: #assertions-and-commodities19707-Node: Assertions and prices20863-Ref: #assertions-and-prices21075-Node: Assertions and subaccounts21515-Ref: #assertions-and-subaccounts21742-Node: Assertions and virtual postings22066-Ref: #assertions-and-virtual-postings22306-Node: Assertions and precision22448-Ref: #assertions-and-precision22639-Node: Balance Assignments22906-Ref: #balance-assignments23087-Node: Balance assignments and prices24252-Ref: #balance-assignments-and-prices24424-Node: Transaction prices24648-Ref: #transaction-prices24817-Node: Comments27083-Ref: #comments27217-Node: Tags28387-Ref: #tags28505-Node: Directives29898-Ref: #directives30041-Node: Comment blocks35649-Ref: #comment-blocks35794-Node: Including other files35970-Ref: #including-other-files36150-Node: Default year36558-Ref: #default-year36727-Node: Declaring commodities37134-Ref: #declaring-commodities37317-Node: Default commodity38746-Ref: #default-commodity38922-Node: Market prices39556-Ref: #market-prices39721-Node: Declaring accounts40562-Ref: #declaring-accounts40738-Node: Account comments41663-Ref: #account-comments41826-Node: Account subdirectives42221-Ref: #account-subdirectives42416-Node: Account types42729-Ref: #account-types42913-Node: Account display order44555-Ref: #account-display-order44725-Node: Rewriting accounts45854-Ref: #rewriting-accounts46039-Node: Basic aliases46775-Ref: #basic-aliases46921-Node: Regex aliases47625-Ref: #regex-aliases47797-Node: Combining aliases48515-Ref: #combining-aliases48693-Node: end aliases49969-Ref: #end-aliases50117-Node: Default parent account50218-Ref: #default-parent-account50384-Node: Periodic transactions51268-Ref: #periodic-transactions51466-Node: Two spaces after the period expression52592-Ref: #two-spaces-after-the-period-expression52837-Node: Forecasting with periodic transactions53322-Ref: #forecasting-with-periodic-transactions53612-Node: Budgeting with periodic transactions55638-Ref: #budgeting-with-periodic-transactions55877-Node: Auto postings / transaction modifiers56336-Ref: #auto-postings-transaction-modifiers56547-Node: Auto postings and dates58776-Ref: #auto-postings-and-dates59033-Node: Auto postings and transaction balancing / inferred amounts / balance assertions59208-Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions59583-Node: Auto posting tags59961-Ref: #auto-posting-tags60200-Node: EDITOR SUPPORT60865-Ref: #editor-support60983+Node: FILE FORMAT2352+Ref: #file-format2476+Node: Transactions2779+Ref: #transactions2900+Node: Postings3584+Ref: #postings3711+Node: Dates4706+Ref: #dates4821+Node: Simple dates4886+Ref: #simple-dates5012+Node: Secondary dates5378+Ref: #secondary-dates5532+Node: Posting dates7095+Ref: #posting-dates7224+Node: Status8596+Ref: #status8716+Node: Description10424+Ref: #description10562+Node: Payee and note10882+Ref: #payee-and-note10996+Node: Account names11331+Ref: #account-names11474+Node: Amounts11961+Ref: #amounts12097+Node: Digit group marks13030+Ref: #digit-group-marks13179+Node: Amount display format14117+Ref: #amount-display-format14274+Node: Virtual Postings15299+Ref: #virtual-postings15458+Node: Balance Assertions16678+Ref: #balance-assertions16853+Node: Assertions and ordering17812+Ref: #assertions-and-ordering17998+Node: Assertions and included files18698+Ref: #assertions-and-included-files18939+Node: Assertions and multiple -f options19272+Ref: #assertions-and-multiple--f-options19526+Node: Assertions and commodities19658+Ref: #assertions-and-commodities19888+Node: Assertions and prices21044+Ref: #assertions-and-prices21256+Node: Assertions and subaccounts21696+Ref: #assertions-and-subaccounts21923+Node: Assertions and virtual postings22247+Ref: #assertions-and-virtual-postings22487+Node: Assertions and precision22629+Ref: #assertions-and-precision22820+Node: Balance Assignments23087+Ref: #balance-assignments23268+Node: Balance assignments and prices24433+Ref: #balance-assignments-and-prices24605+Node: Transaction prices24829+Ref: #transaction-prices24998+Node: Comments27264+Ref: #comments27398+Node: Tags28568+Ref: #tags28686+Node: Directives30079+Ref: #directives30222+Node: Comment blocks35830+Ref: #comment-blocks35975+Node: Including other files36151+Ref: #including-other-files36331+Node: Default year36739+Ref: #default-year36908+Node: Declaring commodities37315+Ref: #declaring-commodities37498+Node: Default commodity39159+Ref: #default-commodity39335+Node: Market prices39969+Ref: #market-prices40134+Node: Declaring accounts40975+Ref: #declaring-accounts41151+Node: Account comments42076+Ref: #account-comments42239+Node: Account subdirectives42634+Ref: #account-subdirectives42829+Node: Account types43142+Ref: #account-types43326+Node: Account display order44968+Ref: #account-display-order45138+Node: Rewriting accounts46267+Ref: #rewriting-accounts46452+Node: Basic aliases47188+Ref: #basic-aliases47334+Node: Regex aliases48038+Ref: #regex-aliases48210+Node: Combining aliases48928+Ref: #combining-aliases49106+Node: end aliases50382+Ref: #end-aliases50530+Node: Default parent account50631+Ref: #default-parent-account50797+Node: Periodic transactions51681+Ref: #periodic-transactions51879+Node: Periodic rule syntax53751+Ref: #periodic-rule-syntax53957+Node: Two spaces between period expression and description!54661+Ref: #two-spaces-between-period-expression-and-description54980+Node: Forecasting with periodic transactions55664+Ref: #forecasting-with-periodic-transactions55969+Node: Budgeting with periodic transactions57995+Ref: #budgeting-with-periodic-transactions58234+Node: Auto postings / transaction modifiers58683+Ref: #auto-postings-transaction-modifiers58894+Node: Auto postings and dates61123+Ref: #auto-postings-and-dates61380+Node: Auto postings and transaction balancing / inferred amounts / balance assertions61555+Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61930+Node: Auto posting tags62308+Ref: #auto-posting-tags62547+Node: EDITOR SUPPORT63212+Ref: #editor-support63330 End Tag Table
embeddedfiles/hledger_journal.txt view
@@ -246,83 +246,93 @@ Account names can be aliased. Amounts- After the account name, there is usually an amount. Important: between- account name and amount, there must be two or more spaces.+ After the account name, there is usually an amount. (Important: be-+ tween account name and amount, there must be two or more spaces.) - Amounts consist of a number and (usually) a currency symbol or commod-- ity name. Some examples:+ hledger's amount format is flexible, supporting several international+ formats. Here are some examples. Amounts have a number (the "quan-+ tity"): - 2.00001- $1- 4000 AAPL- 3 "green apples"- -$1,000,000.00- INR 9,99,99,999.00- EUR -2.000.000,00- 1 999 999.9455- EUR 1E3- 1000E-6s+ 1 - As you can see, the amount format is somewhat flexible:+ ..and usually a currency or commodity name (the "commodity"). This is+ a symbol, word, or phrase, to the left or right of the quantity, with+ or without a separating space: - o amounts are a number (the "quantity") and optionally a currency sym-- bol/commodity name (the "commodity").+ $1+ 4000 AAPL - o the commodity is a symbol, word, or phrase, on the left or right,- with or without a separating space. If the commodity contains num-- bers, spaces or non-word punctuation it must be enclosed in double- quotes.+ If the commodity name contains spaces, numbers, or punctuation, it must+ be enclosed in double quotes: - o negative amounts with a commodity on the left can have the minus sign- before or after it+ 3 "no. 42 green apples" - o digit groups (thousands, or any other grouping) can be separated by- space or comma or period and should be used as separator between all- groups+ Amounts can be negative. The minus sign can be written before or after+ a left-side commodity symbol: - o decimal part can be separated by comma or period and should be dif-- ferent from digit groups separator+ -$1+ $-1 - o scientific E-notation is allowed. Be careful not to use a digit- group separator character in scientific notation, as it's not sup-- ported and it might get mistaken for a decimal point. (Declaring the- digit group separator character explicitly with a commodity directive- will prevent this.)+ Scientific E notation is allowed: - You can use any of these variations when recording data. However,- there is some ambiguous way of representing numbers like $1.000 and- $1,000 both may mean either one thousand or one dollar. By default- hledger will assume that this is sole delimiter is used only for deci-- mals. On the other hand commodity format declared prior to that line- will help to resolve that ambiguity differently:+ 1E-6+ EUR 1E3 - commodity $1,000.00+ A decimal mark (decimal point) can be written with a period or a comma: - 2017/12/25 New life of Scrooge- expenses:gifts $1,000- assets+ 1.23+ 1,23456780000009 - Though journal may contain mixed styles to represent amount, when- hledger displays amounts, it will choose a consistent format for each- commodity. (Except for price amounts, which are always formatted as- written). The display format is chosen as follows:+ Digit group marks+ In the integer part of the quantity (left of the decimal mark), groups+ of digits can optionally be separated by a "digit group mark" - a+ space, comma, or period (different from the decimal mark): - o if there is a commodity directive specifying the format, that is used+ $1,000,000.00+ EUR 2.000.000,00+ INR 9,99,99,999.00+ 1 000 000.9455 - o otherwise the format is inferred from the first posting amount in- that commodity in the journal, and the precision (number of decimal- places) will be the maximum from all posting amounts in that commmod-- ity+ Note, a number containing a single group mark and no decimal mark is+ ambiguous. Are these group marks or decimal marks ? - o or if there are no such amounts in the journal, a default format is+ 1,000+ 1.000++ hledger will treat them both as decimal marks by default (cf #793). If+ you use digit group marks, to prevent confusion and undetected typos we+ recommend you write commodity directives at the top of the file to ex-+ plicitly declare the decimal mark (and optionally a digit group mark).+ Note, these formats ("amount styles") are specific to each commodity,+ so if your data uses multiple formats, hledger can handle it:++ commodity $1,000.00+ commodity EUR 1.000,00+ commodity INR 9,99,99,999.00+ commodity 1 000 000.9455++ Amount display format+ For each commodity, hledger chooses a consistent format to use when+ displaying amounts. (Except price amounts, which are always displayed+ as written). The display format is chosen as follows:++ o If there is a commodity directive for the commodity, that format is+ used (see examples above).++ o Otherwise the format of the first posting amount in that commodity+ seen in the journal is used. But the number of decimal places ("pre-+ cision") will be the maximum from all posting amounts in that comm-+ modity.++ o Or if there are no such amounts in the journal, a default format is used (like $1000.00). - Price amounts and amounts in D directives usually don't affect amount- format inference, but in some situations they can do so indirectly.- (Eg when D's default commodity is applied to a commodity-less amount,- or when an amountless posting is balanced using a price's commodity, or- when -V is used.) If you find this causing problems, set the desired- format with a commodity directive.+ Price amounts, and amounts in D directives don't affect the amount dis-+ play format directly, but occasionally they can do so indirectly. (Eg+ when D's default commodity is applied to a commodity-less amount, or+ when an amountless posting is balanced using a price's commodity, or+ when -V is used.) If you find this causing problems, use a commodity+ directive to set the display format. Virtual Postings When you parenthesise the account name in a posting, we call that a@@ -667,11 +677,6 @@ account any document account names, de- all entries in all text clare account types & dis- files, before or play order after----- alias end rewrite account names following in- aliases line/included en- tries until end of@@ -727,6 +732,8 @@ file.) display how to display amounts of a commodity in reports (symbol side style and spacing, digit groups, decimal separator, decimal places)++ directive which entries and (when there are multiple files) which files scope are affected by a directive @@ -781,9 +788,23 @@ assets Declaring commodities- The commodity directive declares commodities which may be used in the- journal, and their display format.+ The commodity directive has several functions: + 1. It declares commodities which may be used in the journal. This is+ currently not enforced, but can serve as documentation.++ 2. It declares what decimal mark character to expect when parsing input+ - useful to disambiguate international number formats in your data.+ (Without this, hledger will parse both 1,000 and 1.000 as 1).++ 3. It declares the amount display format to use in output - decimal and+ digit group marks, number of decimal places, symbol placement etc.++ You are likely to run into one of the problems solved by commodity di-+ rectives, sooner or later, so it's a good idea to just always use them+ to declare your commodities.++ A commodity directive is just the word commodity followed by an amount. It may be written on a single line, like this: ; commodity EXAMPLEAMOUNT@@ -793,9 +814,9 @@ ; separating thousands with comma. commodity 1,000.0000 AAAA - or on multiple lines, using the "format" subdirective. In this case+ or on multiple lines, using the "format" subdirective. (In this case the commodity symbol appears twice and should be the same in both- places:+ places.): ; commodity SYMBOL ; format EXAMPLEAMOUNT@@ -804,21 +825,11 @@ ; thousands, lakhs and crores comma-separated, ; period as decimal point, and two decimal places. commodity INR- format INR 9,99,99,999.00-- Declaring commodites may be useful as documentation, but currently we- do not enforce that only declared commodities may be used. This direc-- tive is mainly useful for customising the preferred display format for- a commodity.-- Normally the display format is inferred from journal entries, but this- can be unpredictable; declaring it with a commodity directive overrides- this and removes ambiguity. Towards this end, amounts in commodity di-- rectives must always be written with a decimal point (a period or- comma, followed by 0 or more decimal digits).+ format INR 1,00,00,000.00 - Commodity directives do not affect how amounts are parsed; the parser- will read multiple formats.+ The quantity of the amount does not matter; only the format is signifi-+ cant. The number must include a decimal mark: either a period or a+ comma, followed by 0 or more decimal digits. Default commodity The D directive sets a default commodity (and display format), to be@@ -1129,10 +1140,43 @@ Periodic transactions Periodic transaction rules describe transactions that recur. They al-- low you to generate future transactions for forecasting, without having- to write them out explicitly in the journal (with --forecast). Sec-- ondly, they also can be used to define budget goals (with --budget).+ low hledger to generate temporary future transactions to help with+ forecasting, so you don't have to write out each one in the journal,+ and it's easy to try out different forecasts. Secondly, they are also+ used to define the budgets shown in budget reports. + Periodic transactions can be a little tricky, so before you use them,+ read this whole section - or at least these tips:++ 1. Two spaces accidentally added or omitted will cause you trouble -+ read about this below.++ 2. For troubleshooting, show the generated transactions with hledger+ print --forecast tag:generated or hledger register --forecast+ tag:generated.++ 3. Forecasted transactions will begin only after the last non-fore-+ casted transaction's date.++ 4. Forecasted transactions will end 6 months from today, by default.+ See below for the exact start/end rules.++ 5. period expressions can be tricky. Their documentation needs im-+ provement, but is worth studying.++ 6. Some period expressions with a repeating interval must begin on a+ natural boundary of that interval. Eg in weekly from DATE, DATE+ must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an+ error.++ 7. Other period expressions with an interval are automatically expanded+ to cover a whole number of that interval. (This is done to improve+ reports, but it also affects periodic transactions. Yes, it's a bit+ inconsistent with the above.) Eg: ~ every 10th day of month from+ 2020/01, which is equivalent to ~ every 10th day of month from+ 2020/01/01, will be adjusted to start on 2019/12/10.++ Periodic rule syntax A periodic transaction rule looks like a normal journal entry, with the date replaced by a tilde (~) followed by a period expression (mnemonic: ~ looks like a recurring sine wave.):@@ -1150,7 +1194,7 @@ date, unless a Y default year directive is in effect, in which case they will be relative to Y/1/1. - Two spaces after the period expression+ Two spaces between period expression and description! If the period expression is followed by a transaction description, these must be separated by two or more spaces. This helps hledger know where the period expression ends, so that descriptions can not acciden-@@ -1163,6 +1207,14 @@ assets:bank:checking $1500 income:acme inc + So,++ o Do write two spaces between your period expression and your transac-+ tion description, if any.++ o Don't accidentally write two spaces in the middle of your period ex-+ pression.+ Forecasting with periodic transactions With the --forecast flag, each periodic transaction rule generates fu- ture transactions recurring at the specified interval. These are not@@ -1220,8 +1272,8 @@ checking) every month. Goals and actual performance can then be com- pared in budget reports. - For more details, see: balance: Budget report and Cookbook: Budgeting- and Forecasting.+ For more details, see: balance: Budget report and Budgeting and Fore-+ casting. Auto postings / transaction modifiers Transaction modifier rules, AKA auto posting rules, describe changes to@@ -1349,7 +1401,7 @@ COPYRIGHT- Copyright (C) 2007-2016 Simon Michael.+ Copyright (C) 2007-2019 Simon Michael. Released under GNU GPL v3 or later. @@ -1362,4 +1414,4 @@ -hledger 1.15.2 September 2019 hledger_journal(5)+hledger 1.16 December 2019 hledger_journal(5)
embeddedfiles/hledger_timeclock.5 view
@@ -1,5 +1,5 @@ -.TH "hledger_timeclock" "5" "September 2019" "hledger 1.15.2" "hledger User Manuals"+.TH "hledger_timeclock" "5" "December 2019" "hledger 1.16" "hledger User Manuals" @@ -80,7 +80,7 @@ .SH COPYRIGHT -Copyright (C) 2007-2016 Simon Michael.+Copyright (C) 2007-2019 Simon Michael. .br Released under GNU GPL v3 or later.
embeddedfiles/hledger_timeclock.info view
@@ -4,8 +4,8 @@ File: hledger_timeclock.info, Node: Top, Up: (dir) -hledger_timeclock(5) hledger 1.15.2-***********************************+hledger_timeclock(5) hledger 1.16+********************************* hledger can read timeclock files. As with Ledger, these are (a subset of) timeclock.el's format, containing clock-in and clock-out entries as
embeddedfiles/hledger_timeclock.txt view
@@ -65,7 +65,7 @@ COPYRIGHT- Copyright (C) 2007-2016 Simon Michael.+ Copyright (C) 2007-2019 Simon Michael. Released under GNU GPL v3 or later. @@ -78,4 +78,4 @@ -hledger 1.15.2 September 2019 hledger_timeclock(5)+hledger 1.16 December 2019 hledger_timeclock(5)
embeddedfiles/hledger_timedot.5 view
@@ -1,5 +1,5 @@ -.TH "hledger_timedot" "5" "September 2019" "hledger 1.15.2" "hledger User Manuals"+.TH "hledger_timedot" "5" "December 2019" "hledger 1.16" "hledger User Manuals" @@ -142,7 +142,7 @@ .SH COPYRIGHT -Copyright (C) 2007-2016 Simon Michael.+Copyright (C) 2007-2019 Simon Michael. .br Released under GNU GPL v3 or later.
embeddedfiles/hledger_timedot.info view
@@ -4,8 +4,8 @@ File: hledger_timedot.info, Node: Top, Next: FILE FORMAT, Up: (dir) -hledger_timedot(5) hledger 1.15.2-*********************************+hledger_timedot(5) hledger 1.16+******************************* Timedot is a plain text format for logging dated, categorised quantities (of time, usually), supported by hledger. It is convenient for@@ -111,7 +111,7 @@ Tag Table: Node: Top76-Node: FILE FORMAT812-Ref: #file-format913+Node: FILE FORMAT808+Ref: #file-format909 End Tag Table
embeddedfiles/hledger_timedot.txt view
@@ -111,7 +111,7 @@ COPYRIGHT- Copyright (C) 2007-2016 Simon Michael.+ Copyright (C) 2007-2019 Simon Michael. Released under GNU GPL v3 or later. @@ -124,4 +124,4 @@ -hledger 1.15.2 September 2019 hledger_timedot(5)+hledger 1.16 December 2019 hledger_timedot(5)
hledger.1 view
@@ -1,6 +1,6 @@ .\"t -.TH "hledger" "1" "September 2019" "hledger 1.15.2" "hledger User Manuals"+.TH "hledger" "1" "December 2019" "hledger 1.16" "hledger User Manuals" @@ -30,8 +30,8 @@ Tested on unix, mac, windows, hledger aims to be a reliable, practical tool for daily use. .PP-This is hledger\[cq]s command-line interface (there are also curses and-web interfaces).+This is hledger\[cq]s command-line interface (there are also terminal+and web interfaces). Its basic function is to read a plain text file describing financial transactions (in accounting terms, a general journal) and print useful reports on standard output, or export them as CSV.@@ -829,7 +829,7 @@ l. T{ \f[C]-p \[dq]weekly from 2009/1/1 to 2009/4/1\[dq]\f[R] -- starts on-2008/12/29, closest preceeding Monday+2008/12/29, closest preceding Monday T} T{ \f[C]-p \[dq]monthly in 2008/11/25\[dq]\f[R] -- starts on 2018/11/01@@ -863,7 +863,7 @@ boundaries on 2008/01/01, 2008/03/01, ... T} T{-\f[C]-p \[dq]every 2 weeks\[dq]\f[R] -- starts on closest preceeding+\f[C]-p \[dq]every 2 weeks\[dq]\f[R] -- starts on closest preceding Monday T} T{@@ -2083,6 +2083,41 @@ .PP Flat-mode balance reports, which normally show exclusive balances, show inclusive balances at the depth limit.+.SS Percentages+.PP+With \f[C]-%\f[R] or \f[C]--percent\f[R], balance reports show each+account\[aq]s value expressed as a percentage of the column\[aq]s total.+This is useful to get an overview of the relative sizes of account+balances.+For example to obtain an overview of expenses:+.IP+.nf+\f[C]+$ hledger balance expenses -%+ 100.0 % expenses+ 50.0 % food+ 50.0 % supplies+--------------------+ 100.0 %+\f[R]+.fi+.PP+Note that \f[C]--tree\f[R] does not have an effect on \f[C]-%\f[R].+The percentages are always relative to the total sum of each column,+they are never relative to the parent account.+.PP+Since the percentages are relative to the columns sum, it is usually not+useful to calculate percentages if the signs of the amounts are mixed.+Although the results are technically correct, they are most likely+useless.+Especially in a balance report that sums up to zero (eg+\f[C]hledger balance -B\f[R]) all percentage values will be zero.+.PP+This flag does not work if the report contains any mixed commodity+accounts.+If there are mixed commodity accounts in the report be sure to use+\f[C]-V\f[R] or \f[C]-B\f[R] to coerce the report into using a single+commodity. .SS Multicolumn balance report .PP Multicolumn or tabular balance reports are a very useful hledger@@ -2510,6 +2545,8 @@ you need for a balance sheet; note this means it ignores report begin dates (and \f[C]-T/--row-total\f[R], since summing end balances generally does not make sense).+Instead of absolute values percentages can be displayed with+\f[C]-%\f[R]. .PP This command also supports output destination and output format selection.@@ -2591,6 +2628,8 @@ Normally cashflow shows changes in assets per period, though as with multicolumn balance reports you can alter the report mode with \f[C]--change\f[R]/\f[C]--cumulative\f[R]/\f[C]--historical\f[R].+Instead of absolute values percentages can be displayed with+\f[C]-%\f[R]. .PP This command also supports output destination and output format selection.@@ -2820,7 +2859,7 @@ \f[C] $ hledger help Please choose a manual by typing \[dq]hledger help MANUAL\[dq] (a substring is ok).-Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot+Manuals: hledger hledger-ui hledger-web journal csv timeclock timedot \f[R] .fi .IP@@ -2852,6 +2891,8 @@ Read new transactions added to each FILE since last run, and add them to the main journal file. Or with --dry-run, just print the transactions that would be added.+Or with --catchup, just mark all of the FILEs\[aq] transactions as+imported, without actually importing any. .PP The input files are specified as arguments - no need to write -f before each one.@@ -2940,6 +2981,8 @@ Normally incomestatement shows revenues/expenses per period, though as with multicolumn balance reports you can alter the report mode with \f[C]--change\f[R]/\f[C]--cumulative\f[R]/\f[C]--historical\f[R].+Instead of absolute values percentages can be displayed with+\f[C]-%\f[R]. .PP This command also supports output destination and output format selection.@@ -2986,6 +3029,7 @@ With --inverted-costs, also print inverse prices based on transaction prices. Prices (and postings providing prices) can be filtered by a query.+Price amounts are always displayed with their full precision. .SS print .PP print, txns, p@@ -3551,22 +3595,28 @@ .PD Run built-in unit tests. .PP-This command runs the unit tests built in to hledger-lib and hledger,-printing test names and results on stdout.+This command runs the unit tests built in to hledger and hledger-lib,+printing the results on stdout. If any test fails, the exit code will be non-zero. .PP-Test names include a group prefix.-If a (exact, case sensitive) group prefix, or a full test name is-provided as the first argument, only that group or test is run.+This is mainly used by hledger developers, but you can also use it to+sanity-check the installed hledger executable on your platform.+All tests are expected to pass - if you ever see a failure, please+report as a bug! .PP-If a numeric second argument is provided, it will set the randomness-seed, for repeatable results from tests using randomness (currently none-of them).+This command also accepts tasty test runner options, written after a --+(double hyphen).+Eg to run only the tests in Hledger.Data.Amount, with ANSI colour codes+disabled:+.IP+.nf+\f[C]+$ hledger test -- -pData.Amount --color=never+\f[R]+.fi .PP-This is mainly used by developers, but it\[aq]s nice to be able to-sanity-check your installed hledger executable at any time.-All tests are expected to pass - if you ever see otherwise, something-has gone wrong, please report a bug!+For help on these, see https://github.com/feuerbach/tasty#options+(\f[C]-- --help\f[R] currently doesn\[aq]t show them). .SH ADD-ON COMMANDS .PP hledger also searches for external add-on commands, and will include@@ -3602,12 +3652,9 @@ .SS Official add-ons .PP These are maintained and released along with hledger.-.SS api-.PP-hledger-api serves hledger data as a JSON web API. .SS ui .PP-hledger-ui provides an efficient curses-style interface.+hledger-ui provides an efficient terminal interface. .SS web .PP hledger-web provides a simple web interface.@@ -3621,7 +3668,7 @@ one journal file and another. .SS iadd .PP-hledger-iadd is a curses-style, more interactive replacement for the add+hledger-iadd is a more interactive, terminal UI replacement for the add command. .SS interest .PP@@ -3634,7 +3681,7 @@ .SS Experimental add-ons .PP These are available in source form in the hledger repo\[aq]s bin/-directory; installing them is pretty easy.+directory. They may be less mature and documented than built-in commands. Reading and tweaking these is a good way to start making your own! .SS autosync@@ -3784,7 +3831,7 @@ .SH COPYRIGHT -Copyright (C) 2007-2016 Simon Michael.+Copyright (C) 2007-2019 Simon Michael. .br Released under GNU GPL v3 or later.
hledger.cabal view
@@ -4,10 +4,10 @@ -- -- see: https://github.com/sol/hpack ----- hash: f839c60877b230c5cb9cffe709ab8f7f6d770f16c15c68c25b3aed3cc0c65bb0+-- hash: f608f8976e44e104fc5fc49a65b2a01b1873a5f23f8b58be36335deec8c4549e name: hledger-version: 1.15.2+version: 1.16 synopsis: Command-line interface for the hledger accounting tool description: This is hledger's command-line interface. Its basic function is to read a plain text file describing@@ -16,7 +16,7 @@ hledger is a cross-platform program for tracking money, time, or any other commodity, using double-entry accounting and a simple, editable file format. It is inspired by and largely compatible- with ledger(1). hledger provides command-line, curses and web+ with ledger(1). hledger provides command-line, terminal and web interfaces, and aims to be a reliable, practical tool for daily use. category: Finance, Console@@ -27,12 +27,12 @@ maintainer: Simon Michael <simon@joyful.com> license: GPL-3 license-file: LICENSE-tested-with: GHC==7.10.3, GHC==8.0.2, GHC==8.2.2, GHC==8.4.3, GHC==8.6.5+tested-with: GHC==8.0.2, GHC==8.2.2, GHC==8.4.3, GHC==8.6.5, GHC==8.8.1 build-type: Simple extra-source-files: CHANGES.md README.md- test/test.hs+ test/unittest.hs bench/10000x1000x10.journal hledger.1 hledger.txt@@ -40,9 +40,6 @@ embeddedfiles/hledger.1 embeddedfiles/hledger.txt embeddedfiles/hledger.info- embeddedfiles/hledger-api.1- embeddedfiles/hledger-api.txt- embeddedfiles/hledger-api.info embeddedfiles/hledger-ui.1 embeddedfiles/hledger-ui.txt embeddedfiles/hledger-ui.info@@ -112,6 +109,7 @@ Hledger.Cli.CliOptions Hledger.Cli.DocFiles Hledger.Cli.Utils+ Hledger.Cli.Anon Hledger.Cli.Version Hledger.Cli.Commands Hledger.Cli.Commands.Accounts@@ -146,24 +144,23 @@ other-modules: Paths_hledger ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path- cpp-options: -DVERSION="1.15.2"+ cpp-options: -DVERSION="1.16" build-depends: Decimal , Diff , ansi-terminal >=0.6.2.3- , base >=4.8 && <4.13- , base-compat-batteries >=0.10.1 && <0.11+ , base >=4.9 && <4.14+ , base-compat-batteries >=0.10.1 && <0.12 , bytestring , cmdargs >=0.10 , containers , data-default >=0.5 , directory- , easytest >=0.2.1 && <0.3 , extra >=1.6.3 , filepath , hashable >=1.2.4 , haskeline >=0.6- , hledger-lib >=1.15.2 && <1.16+ , hledger-lib >=1.16 && <1.17 , lucid , math-functions >=0.2.0.0 , megaparsec >=7.0.0 && <8@@ -178,6 +175,7 @@ , shakespeare >=2.0.2.2 , split >=0.1 , tabular >=0.2+ , tasty >=1.2.3 , temporary , text >=0.11 , time >=1.5@@ -199,23 +197,22 @@ hs-source-dirs: app ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path- cpp-options: -DVERSION="1.15.2"+ cpp-options: -DVERSION="1.16" build-depends: Decimal , ansi-terminal >=0.6.2.3- , base >=4.8 && <4.13- , base-compat-batteries >=0.10.1 && <0.11+ , base >=4.9 && <4.14+ , base-compat-batteries >=0.10.1 && <0.12 , bytestring , cmdargs >=0.10 , containers , data-default >=0.5 , directory- , easytest >=0.2.1 && <0.3 , extra >=1.6.3 , filepath , haskeline >=0.6 , hledger- , hledger-lib >=1.15.2 && <1.16+ , hledger-lib >=1.16 && <1.17 , math-functions >=0.2.0.0 , megaparsec >=7.0.0 && <8 , mtl@@ -229,6 +226,7 @@ , shakespeare >=2.0.2.2 , split >=0.1 , tabular >=0.2+ , tasty >=1.2.3 , temporary , text >=0.11 , time >=1.5@@ -245,31 +243,28 @@ ghc-options: -threaded default-language: Haskell2010 -test-suite test+test-suite unittest type: exitcode-stdio-1.0- main-is: test.hs- other-modules:- Paths_hledger+ main-is: unittest.hs hs-source-dirs: test ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path- cpp-options: -DVERSION="1.15.2"+ cpp-options: -DVERSION="1.16" build-depends: Decimal , ansi-terminal >=0.6.2.3- , base >=4.8 && <4.13- , base-compat-batteries >=0.10.1 && <0.11+ , base >=4.9 && <4.14+ , base-compat-batteries >=0.10.1 && <0.12 , bytestring , cmdargs >=0.10 , containers , data-default >=0.5 , directory- , easytest >=0.2.1 && <0.3 , extra >=1.6.3 , filepath , haskeline >=0.6 , hledger- , hledger-lib >=1.15.2 && <1.16+ , hledger-lib >=1.16 && <1.17 , math-functions >=0.2.0.0 , megaparsec >=7.0.0 && <8 , mtl@@ -283,9 +278,8 @@ , shakespeare >=2.0.2.2 , split >=0.1 , tabular >=0.2+ , tasty >=1.2.3 , temporary- , test-framework- , test-framework-hunit , text >=0.11 , time >=1.5 , timeit@@ -302,28 +296,25 @@ benchmark bench type: exitcode-stdio-1.0 main-is: bench.hs- other-modules:- Paths_hledger hs-source-dirs: bench ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path build-depends: Decimal , ansi-terminal >=0.6.2.3- , base >=4.8 && <4.13- , base-compat-batteries >=0.10.1 && <0.11+ , base >=4.9 && <4.14+ , base-compat-batteries >=0.10.1 && <0.12 , bytestring , cmdargs >=0.10 , containers , criterion , data-default >=0.5 , directory- , easytest >=0.2.1 && <0.3 , extra >=1.6.3 , filepath , haskeline >=0.6 , hledger- , hledger-lib >=1.15.2 && <1.16+ , hledger-lib >=1.16 && <1.17 , html , math-functions >=0.2.0.0 , megaparsec >=7.0.0 && <8@@ -338,6 +329,7 @@ , shakespeare >=2.0.2.2 , split >=0.1 , tabular >=0.2+ , tasty >=1.2.3 , temporary , text >=0.11 , time >=1.5@@ -347,6 +339,7 @@ , utf8-string >=0.3.5 , utility-ht >=0.0.13 , wizards >=1.0+ buildable: False if (!(os(windows))) && (flag(terminfo)) build-depends: terminfo
hledger.info view
@@ -3,16 +3,16 @@ File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir) -hledger(1) hledger 1.15.2-*************************+hledger(1) hledger 1.16+*********************** -This is hledger's command-line interface (there are also curses and web-interfaces). Its basic function is to read a plain text file describing-financial transactions (in accounting terms, a general journal) and-print useful reports on standard output, or export them as CSV. hledger-can also read some other file formats such as CSV files, translating-them to journal format. Additionally, hledger lists other hledger-*-executables found in the user's $PATH and can invoke them as+This is hledger's command-line interface (there are also terminal and+web interfaces). Its basic function is to read a plain text file+describing financial transactions (in accounting terms, a general+journal) and print useful reports on standard output, or export them as+CSV. hledger can also read some other file formats such as CSV files,+translating them to journal format. Additionally, hledger lists other+hledger-* executables found in the user's $PATH and can invoke them as subcommands. hledger reads data from one or more files in hledger journal,@@ -628,7 +628,7 @@ For example: -'-p "weekly from 2009/1/1 to 2009/4/1"' - starts on 2008/12/29, closest preceeding Monday+'-p "weekly from 2009/1/1 to 2009/4/1"' - starts on 2008/12/29, closest preceding Monday '-p "monthly in 2008/11/25"' - starts on 2018/11/01 '-p "quarterly from 2009-05-05 to 2009-06-01"' - starts on 2009/04/01, ends on 2009/06/30, which are first and last days of Q2 2009 '-p "yearly from 2009-12-29"' - starts on 2009/01/01, first day of 2009@@ -643,7 +643,7 @@ Examples: '-p "bimonthly from 2008"' - periods will have boundaries on 2008/01/01, 2008/03/01, ...-'-p "every 2 weeks"' - starts on closest preceeding Monday+'-p "every 2 weeks"' - starts on closest preceding Monday '-p "every 5 month from 2009/03"' - periods will have boundaries on 2009/03/01, 2009/08/01, ... If you want intervals that start on arbitrary day of your choosing@@ -1498,6 +1498,7 @@ * Colour support:: * Flat mode:: * Depth limited balance reports::+* Percentages:: * Multicolumn balance report:: * Budget report:: * Output format::@@ -1639,7 +1640,7 @@ $1 supplies -File: hledger.info, Node: Depth limited balance reports, Next: Multicolumn balance report, Prev: Flat mode, Up: balance+File: hledger.info, Node: Depth limited balance reports, Next: Percentages, Prev: Flat mode, Up: balance 4.4.5 Depth limited balance reports -----------------------------------@@ -1658,9 +1659,41 @@ show inclusive balances at the depth limit. -File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Depth limited balance reports, Up: balance+File: hledger.info, Node: Percentages, Next: Multicolumn balance report, Prev: Depth limited balance reports, Up: balance -4.4.6 Multicolumn balance report+4.4.6 Percentages+-----------------++With '-%' or '--percent', balance reports show each account's value+expressed as a percentage of the column's total. This is useful to get+an overview of the relative sizes of account balances. For example to+obtain an overview of expenses:++$ hledger balance expenses -%+ 100.0 % expenses+ 50.0 % food+ 50.0 % supplies+--------------------+ 100.0 %++ Note that '--tree' does not have an effect on '-%'. The percentages+are always relative to the total sum of each column, they are never+relative to the parent account.++ Since the percentages are relative to the columns sum, it is usually+not useful to calculate percentages if the signs of the amounts are+mixed. Although the results are technically correct, they are most+likely useless. Especially in a balance report that sums up to zero (eg+'hledger balance -B') all percentage values will be zero.++ This flag does not work if the report contains any mixed commodity+accounts. If there are mixed commodity accounts in the report be sure+to use '-V' or '-B' to coerce the report into using a single commodity.+++File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Percentages, Up: balance++4.4.7 Multicolumn balance report -------------------------------- Multicolumn or tabular balance reports are a very useful hledger@@ -1777,7 +1810,7 @@ File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance -4.4.7 Budget report+4.4.8 Budget report ------------------- With '--budget', extra columns are displayed showing budget goals for@@ -1900,7 +1933,7 @@ File: hledger.info, Node: Nested budgets, Up: Budget report -4.4.7.1 Nested budgets+4.4.8.1 Nested budgets ...................... You can add budgets to any account in your account hierarchy. If you@@ -1985,7 +2018,7 @@ ----------------------------------------++------------------------------- || 0 [ 0] -4.4.8 Output format+4.4.9 Output format ------------------- The balance command supports output destination and output format@@ -2034,7 +2067,8 @@ balancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates (and '-T/--row-total', since summing end balances generally does not make-sense).+sense). Instead of absolute values percentages can be displayed with+'-%'. This command also supports output destination and output format selection.@@ -2108,7 +2142,8 @@ With a reporting interval, multiple columns will be shown, one for each report period. Normally cashflow shows changes in assets per period, though as with multicolumn balance reports you can alter the-report mode with '--change'/'--cumulative'/'--historical'.+report mode with '--change'/'--cumulative'/'--historical'. Instead of+absolute values percentages can be displayed with '-%'. This command also supports output destination and output format selection.@@ -2320,7 +2355,7 @@ $ hledger help Please choose a manual by typing "hledger help MANUAL" (a substring is ok).-Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot+Manuals: hledger hledger-ui hledger-web journal csv timeclock timedot $ hledger help h --man @@ -2347,7 +2382,8 @@ import Read new transactions added to each FILE since last run, and add them to the main journal file. Or with -dry-run, just print the transactions-that would be added.+that would be added. Or with -catchup, just mark all of the FILEs'+transactions as imported, without actually importing any. The input files are specified as arguments - no need to write -f before each one. So eg to add new transactions from all CSV files to@@ -2427,7 +2463,8 @@ With a reporting interval, multiple columns will be shown, one for each report period. Normally incomestatement shows revenues/expenses per period, though as with multicolumn balance reports you can alter the-report mode with '--change'/'--cumulative'/'--historical'.+report mode with '--change'/'--cumulative'/'--historical'. Instead of+absolute values percentages can be displayed with '-%'. This command also supports output destination and output format selection.@@ -2476,6 +2513,7 @@ synthetic market prices based on transaction prices. With -inverted-costs, also print inverse prices based on transaction prices. Prices (and postings providing prices) can be filtered by a query.+Price amounts are always displayed with their full precision. File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS@@ -2970,23 +3008,24 @@ test Run built-in unit tests. - This command runs the unit tests built in to hledger-lib and hledger,-printing test names and results on stdout. If any test fails, the exit-code will be non-zero.+ This command runs the unit tests built in to hledger and hledger-lib,+printing the results on stdout. If any test fails, the exit code will+be non-zero. - Test names include a group prefix. If a (exact, case sensitive)-group prefix, or a full test name is provided as the first argument,-only that group or test is run.+ This is mainly used by hledger developers, but you can also use it to+sanity-check the installed hledger executable on your platform. All+tests are expected to pass - if you ever see a failure, please report as+a bug! - If a numeric second argument is provided, it will set the randomness-seed, for repeatable results from tests using randomness (currently none-of them).+ This command also accepts tasty test runner options, written after a+- (double hyphen). Eg to run only the tests in Hledger.Data.Amount,+with ANSI colour codes disabled: - This is mainly used by developers, but it's nice to be able to-sanity-check your installed hledger executable at any time. All tests-are expected to pass - if you ever see otherwise, something has gone-wrong, please report a bug!+$ hledger test -- -pData.Amount --color=never + For help on these, see https://github.com/feuerbach/tasty#options+('-- --help' currently doesn't show them).+ File: hledger.info, Node: ADD-ON COMMANDS, Prev: COMMANDS, Up: Top @@ -3036,30 +3075,21 @@ * Menu: -* api:: * ui:: * web:: -File: hledger.info, Node: api, Next: ui, Up: Official add-ons--5.1.1 api------------hledger-api serves hledger data as a JSON web API.---File: hledger.info, Node: ui, Next: web, Prev: api, Up: Official add-ons+File: hledger.info, Node: ui, Next: web, Up: Official add-ons -5.1.2 ui+5.1.1 ui -------- -hledger-ui provides an efficient curses-style interface.+hledger-ui provides an efficient terminal interface. File: hledger.info, Node: web, Prev: ui, Up: Official add-ons -5.1.3 web+5.1.2 web --------- hledger-web provides a simple web interface.@@ -3092,7 +3122,7 @@ 5.2.2 iadd ---------- -hledger-iadd is a curses-style, more interactive replacement for the add+hledger-iadd is a more interactive, terminal UI replacement for the add command. @@ -3119,10 +3149,9 @@ 5.3 Experimental add-ons ======================== -These are available in source form in the hledger repo's bin/ directory;-installing them is pretty easy. They may be less mature and documented-than built-in commands. Reading and tweaking these is a good way to-start making your own!+These are available in source form in the hledger repo's bin/ directory.+They may be less mature and documented than built-in commands. Reading+and tweaking these is a good way to start making your own! * Menu: @@ -3160,179 +3189,179 @@ Tag Table: Node: Top68-Node: EXAMPLES1889-Ref: #examples1989-Node: OPTIONS3635-Ref: #options3737-Node: General options4136-Ref: #general-options4261-Node: Command options6915-Ref: #command-options7066-Node: Command arguments7464-Ref: #command-arguments7618-Node: Argument files7739-Ref: #argument-files7915-Node: Special characters in arguments and queries8181-Ref: #special-characters-in-arguments-and-queries8415-Node: More escaping8866-Ref: #more-escaping9028-Node: Even more escaping9324-Ref: #even-more-escaping9518-Node: Less escaping10189-Ref: #less-escaping10351-Node: Command line tips10596-Ref: #command-line-tips10782-Node: Unicode characters11159-Ref: #unicode-characters11315-Node: Input files12727-Ref: #input-files12863-Node: Smart dates14792-Ref: #smart-dates14933-Node: Report start & end date16339-Ref: #report-start-end-date16511-Node: Report intervals17935-Ref: #report-intervals18100-Node: Period expressions18490-Ref: #period-expressions18650-Node: Depth limiting22607-Ref: #depth-limiting22751-Node: Pivoting23093-Ref: #pivoting23216-Node: Valuation24892-Ref: #valuation25021-Node: -B Cost25201-Ref: #b-cost25312-Node: -V Market value25510-Ref: #v-market-value25684-Node: -X Market value in specified commodity27116-Ref: #x-market-value-in-specified-commodity27355-Node: --value Flexible valuation27531-Ref: #value-flexible-valuation27757-Node: Effect of --value on reports31947-Ref: #effect-of---value-on-reports32163-Node: Combining -B -V -X --value37094-Ref: #combining--b--v--x---value37277-Node: Output destination37313-Ref: #output-destination37465-Node: Output format37748-Ref: #output-format37900-Node: Regular expressions38285-Ref: #regular-expressions38422-Node: QUERIES39783-Ref: #queries39885-Node: COMMANDS43847-Ref: #commands43959-Node: accounts45023-Ref: #accounts45121-Node: activity45820-Ref: #activity45930-Node: add46313-Ref: #add46412-Node: balance49157-Ref: #balance49268-Node: Classic balance report50710-Ref: #classic-balance-report50883-Node: Customising the classic balance report52252-Ref: #customising-the-classic-balance-report52480-Node: Colour support54556-Ref: #colour-support54723-Node: Flat mode54896-Ref: #flat-mode55044-Node: Depth limited balance reports55457-Ref: #depth-limited-balance-reports55657-Node: Multicolumn balance report56113-Ref: #multicolumn-balance-report56311-Node: Budget report61625-Ref: #budget-report61768-Node: Nested budgets66970-Ref: #nested-budgets67082-Ref: #output-format-170562-Node: balancesheet70640-Ref: #balancesheet70776-Node: balancesheetequity72091-Ref: #balancesheetequity72240-Node: cashflow72801-Ref: #cashflow72929-Node: check-dates73957-Ref: #check-dates74084-Node: check-dupes74363-Ref: #check-dupes74487-Node: close74780-Ref: #close74894-Node: commodities78481-Ref: #commodities78608-Node: descriptions78690-Ref: #descriptions78818-Node: diff78999-Ref: #diff79105-Node: files80152-Ref: #files80252-Node: help80399-Ref: #help80499-Node: import81592-Ref: #import81706-Node: Importing balance assignments82494-Ref: #importing-balance-assignments82642-Node: incomestatement83291-Ref: #incomestatement83424-Node: notes84760-Ref: #notes84873-Node: payees84999-Ref: #payees85105-Node: prices85263-Ref: #prices85369-Node: print85648-Ref: #print85758-Node: print-unique90251-Ref: #print-unique90377-Node: register90662-Ref: #register90789-Node: Custom register output94961-Ref: #custom-register-output95090-Node: register-match96352-Ref: #register-match96486-Node: rewrite96837-Ref: #rewrite96952-Node: Re-write rules in a file98807-Ref: #re-write-rules-in-a-file98941-Node: Diff output format100151-Ref: #diff-output-format100320-Node: rewrite vs print --auto101412-Ref: #rewrite-vs.-print---auto101591-Node: roi102147-Ref: #roi102245-Node: stats103257-Ref: #stats103356-Node: tags104144-Ref: #tags104242-Node: test104536-Ref: #test104620-Node: ADD-ON COMMANDS105381-Ref: #add-on-commands105491-Node: Official add-ons106779-Ref: #official-add-ons106919-Node: api107007-Ref: #api107096-Node: ui107148-Ref: #ui107247-Node: web107305-Ref: #web107394-Node: Third party add-ons107440-Ref: #third-party-add-ons107615-Ref: #diff-1107774-Node: iadd107873-Ref: #iadd107983-Node: interest108066-Ref: #interest108187-Node: irr108282-Ref: #irr108380-Node: Experimental add-ons108511-Ref: #experimental-add-ons108663-Node: autosync108944-Ref: #autosync109055-Node: chart109294-Ref: #chart109413-Node: check109484-Ref: #check109586+Node: EXAMPLES1887+Ref: #examples1987+Node: OPTIONS3633+Ref: #options3735+Node: General options4134+Ref: #general-options4259+Node: Command options6913+Ref: #command-options7064+Node: Command arguments7462+Ref: #command-arguments7616+Node: Argument files7737+Ref: #argument-files7913+Node: Special characters in arguments and queries8179+Ref: #special-characters-in-arguments-and-queries8413+Node: More escaping8864+Ref: #more-escaping9026+Node: Even more escaping9322+Ref: #even-more-escaping9516+Node: Less escaping10187+Ref: #less-escaping10349+Node: Command line tips10594+Ref: #command-line-tips10780+Node: Unicode characters11157+Ref: #unicode-characters11313+Node: Input files12725+Ref: #input-files12861+Node: Smart dates14790+Ref: #smart-dates14931+Node: Report start & end date16337+Ref: #report-start-end-date16509+Node: Report intervals17933+Ref: #report-intervals18098+Node: Period expressions18488+Ref: #period-expressions18648+Node: Depth limiting22603+Ref: #depth-limiting22747+Node: Pivoting23089+Ref: #pivoting23212+Node: Valuation24888+Ref: #valuation25017+Node: -B Cost25197+Ref: #b-cost25308+Node: -V Market value25506+Ref: #v-market-value25680+Node: -X Market value in specified commodity27112+Ref: #x-market-value-in-specified-commodity27351+Node: --value Flexible valuation27527+Ref: #value-flexible-valuation27753+Node: Effect of --value on reports31943+Ref: #effect-of---value-on-reports32159+Node: Combining -B -V -X --value37090+Ref: #combining--b--v--x---value37273+Node: Output destination37309+Ref: #output-destination37461+Node: Output format37744+Ref: #output-format37896+Node: Regular expressions38281+Ref: #regular-expressions38418+Node: QUERIES39779+Ref: #queries39881+Node: COMMANDS43843+Ref: #commands43955+Node: accounts45019+Ref: #accounts45117+Node: activity45816+Ref: #activity45926+Node: add46309+Ref: #add46408+Node: balance49153+Ref: #balance49264+Node: Classic balance report50722+Ref: #classic-balance-report50895+Node: Customising the classic balance report52264+Ref: #customising-the-classic-balance-report52492+Node: Colour support54568+Ref: #colour-support54735+Node: Flat mode54908+Ref: #flat-mode55056+Node: Depth limited balance reports55469+Ref: #depth-limited-balance-reports55654+Node: Percentages56110+Ref: #percentages56276+Node: Multicolumn balance report57413+Ref: #multicolumn-balance-report57593+Node: Budget report62907+Ref: #budget-report63050+Node: Nested budgets68252+Ref: #nested-budgets68364+Ref: #output-format-171844+Node: balancesheet71922+Ref: #balancesheet72058+Node: balancesheetequity73441+Ref: #balancesheetequity73590+Node: cashflow74151+Ref: #cashflow74279+Node: check-dates75375+Ref: #check-dates75502+Node: check-dupes75781+Ref: #check-dupes75905+Node: close76198+Ref: #close76312+Node: commodities79899+Ref: #commodities80026+Node: descriptions80108+Ref: #descriptions80236+Node: diff80417+Ref: #diff80523+Node: files81570+Ref: #files81670+Node: help81817+Ref: #help81917+Node: import82998+Ref: #import83112+Node: Importing balance assignments84005+Ref: #importing-balance-assignments84153+Node: incomestatement84802+Ref: #incomestatement84935+Node: notes86339+Ref: #notes86452+Node: payees86578+Ref: #payees86684+Node: prices86842+Ref: #prices86948+Node: print87289+Ref: #print87399+Node: print-unique91892+Ref: #print-unique92018+Node: register92303+Ref: #register92430+Node: Custom register output96602+Ref: #custom-register-output96731+Node: register-match97993+Ref: #register-match98127+Node: rewrite98478+Ref: #rewrite98593+Node: Re-write rules in a file100448+Ref: #re-write-rules-in-a-file100582+Node: Diff output format101792+Ref: #diff-output-format101961+Node: rewrite vs print --auto103053+Ref: #rewrite-vs.-print---auto103232+Node: roi103788+Ref: #roi103886+Node: stats104898+Ref: #stats104997+Node: tags105785+Ref: #tags105883+Node: test106177+Ref: #test106261+Node: ADD-ON COMMANDS107008+Ref: #add-on-commands107118+Node: Official add-ons108406+Ref: #official-add-ons108546+Node: ui108626+Ref: #ui108713+Node: web108767+Ref: #web108856+Node: Third party add-ons108902+Ref: #third-party-add-ons109077+Ref: #diff-1109236+Node: iadd109335+Ref: #iadd109445+Node: interest109527+Ref: #interest109648+Node: irr109743+Ref: #irr109841+Node: Experimental add-ons109972+Ref: #experimental-add-ons110124+Node: autosync110372+Ref: #autosync110483+Node: chart110722+Ref: #chart110841+Node: check110912+Ref: #check111014 End Tag Table
hledger.txt view
@@ -19,12 +19,12 @@ Tested on unix, mac, windows, hledger aims to be a reliable, practical tool for daily use. - This is hledger's command-line interface (there are also curses and web- interfaces). Its basic function is to read a plain text file describ-- ing financial transactions (in accounting terms, a general journal) and- print useful reports on standard output, or export them as CSV.- hledger can also read some other file formats such as CSV files, trans-- lating them to journal format. Additionally, hledger lists other+ This is hledger's command-line interface (there are also terminal and+ web interfaces). Its basic function is to read a plain text file de-+ scribing financial transactions (in accounting terms, a general jour-+ nal) and print useful reports on standard output, or export them as+ CSV. hledger can also read some other file formats such as CSV files,+ translating them to journal format. Additionally, hledger lists other hledger-* executables found in the user's $PATH and can invoke them as subcommands. @@ -558,7 +558,7 @@ -p "weekly from 2009/1/1 to 2009/4/1" -- starts on 2008/12/29, closest pre-- ceeding Monday+ ceding Monday -p "monthly in 2008/11/25" -- starts on 2018/11/01 -p "quarterly from 2009-05-05 to@@ -581,7 +581,7 @@ will have boundaries on 2008/01/01, 2008/03/01, ... -p "every 2 weeks" -- starts on closest- preceeding Monday+ preceding Monday -p "every 5 month from 2009/03" -- pe- riods will have boundaries on 2009/03/01, 2009/08/01, ...@@ -1454,18 +1454,45 @@ Flat-mode balance reports, which normally show exclusive balances, show inclusive balances at the depth limit. + Percentages+ With -% or --percent, balance reports show each account's value ex-+ pressed as a percentage of the column's total. This is useful to get+ an overview of the relative sizes of account balances. For example to+ obtain an overview of expenses:++ $ hledger balance expenses -%+ 100.0 % expenses+ 50.0 % food+ 50.0 % supplies+ --------------------+ 100.0 %++ Note that --tree does not have an effect on -%. The percentages are+ always relative to the total sum of each column, they are never rela-+ tive to the parent account.++ Since the percentages are relative to the columns sum, it is usually+ not useful to calculate percentages if the signs of the amounts are+ mixed. Although the results are technically correct, they are most+ likely useless. Especially in a balance report that sums up to zero+ (eg hledger balance -B) all percentage values will be zero.++ This flag does not work if the report contains any mixed commodity ac-+ counts. If there are mixed commodity accounts in the report be sure to+ use -V or -B to coerce the report into using a single commodity.+ Multicolumn balance report- Multicolumn or tabular balance reports are a very useful hledger fea-- ture, and usually the preferred style. They share many of the above- features, but they show the report as a table, with columns represent-- ing time periods. This mode is activated by providing a reporting in-+ Multicolumn or tabular balance reports are a very useful hledger fea-+ ture, and usually the preferred style. They share many of the above+ features, but they show the report as a table, with columns represent-+ ing time periods. This mode is activated by providing a reporting in- terval. - There are three types of multicolumn balance report, showing different+ There are three types of multicolumn balance report, showing different information: 1. By default: each column shows the sum of postings in that period, ie- the account's change of balance in that period. This is useful eg+ the account's change of balance in that period. This is useful eg for a monthly income statement: $ hledger balance --quarterly income expenses -E@@ -1481,7 +1508,7 @@ || $-1 $1 0 0 2. With --cumulative: each column shows the ending balance for that pe-- riod, accumulating the changes across periods, starting from 0 at+ riod, accumulating the changes across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative@@ -1497,8 +1524,8 @@ || $-1 0 0 0 3. With --historical/-H: each column shows the actual historical ending- balance for that period, accumulating the changes across periods,- starting from the actual balance at the report start date. This is+ balance for that period, accumulating the changes across periods,+ starting from the actual balance at the report start date. This is useful eg for a multi-period balance sheet, and when you are showing only the data after a certain start date: @@ -1517,26 +1544,26 @@ Note that --cumulative or --historical/-H disable --row-total/-T, since summing end balances generally does not make sense. - Multicolumn balance reports display accounts in flat mode by default;+ Multicolumn balance reports display accounts in flat mode by default; to see the hierarchy, use --tree. - With a reporting interval (like --quarterly above), the report- start/end dates will be adjusted if necessary so that they encompass+ With a reporting interval (like --quarterly above), the report+ start/end dates will be adjusted if necessary so that they encompass the displayed report periods. This is so that the first and last peri- ods will be "full" and comparable to the others. - The -E/--empty flag does two things in multicolumn balance reports:+ The -E/--empty flag does two things in multicolumn balance reports: first, the report will show all columns within the specified report pe-- riod (without -E, leading and trailing columns with all zeroes are not- shown). Second, all accounts which existed at the report start date- will be considered, not just the ones with activity during the report- period (use -E to include low-activity accounts which would otherwise+ riod (without -E, leading and trailing columns with all zeroes are not+ shown). Second, all accounts which existed at the report start date+ will be considered, not just the ones with activity during the report+ period (use -E to include low-activity accounts which would otherwise would be omitted). The -T/--row-total flag adds an additional column showing the total for each row. - The -A/--average flag adds a column showing the average value in each+ The -A/--average flag adds a column showing the average value in each row. Here's an example of all three:@@ -1560,20 +1587,20 @@ Limitations: In multicolumn reports the -V/--value flag uses the market price on the- report end date, for all columns (not the price on each column's end+ report end date, for all columns (not the price on each column's end date). - Eliding of boring parent accounts in tree mode, as in the classic bal-+ Eliding of boring parent accounts in tree mode, as in the classic bal- ance report, is not yet supported in multicolumn reports. Budget report- With --budget, extra columns are displayed showing budget goals for- each account and period, if any. Budget goals are defined by periodic+ With --budget, extra columns are displayed showing budget goals for+ each account and period, if any. Budget goals are defined by periodic transactions. This is very useful for comparing planned and actual in-- come, expenses, time usage, etc. --budget is most often combined with+ come, expenses, time usage, etc. --budget is most often combined with a report interval. - For example, you can take average monthly expenses in the common ex-+ For example, you can take average monthly expenses in the common ex- pense categories to construct a minimal monthly budget: ;; Budget@@ -1620,25 +1647,25 @@ Note this is different from a normal balance report in several ways: - o Only accounts with budget goals during the report period are shown,+ o Only accounts with budget goals during the report period are shown, by default. - o In each column, in square brackets after the actual amount, budgeted+ o In each column, in square brackets after the actual amount, budgeted amounts are shown, along with the percentage of budget used. - o All parent accounts are always shown, even in flat mode. Eg assets,+ o All parent accounts are always shown, even in flat mode. Eg assets, assets:bank, and expenses above. - o Amounts always include all subaccounts, budgeted or unbudgeted, even+ o Amounts always include all subaccounts, budgeted or unbudgeted, even in flat mode. This means that the numbers displayed will not always add up! Eg above,- the expenses actual amount includes the gifts and supplies transac-- tions, but the expenses:gifts and expenses:supplies accounts are not+ the expenses actual amount includes the gifts and supplies transac-+ tions, but the expenses:gifts and expenses:supplies accounts are not shown, as they have no budget amounts declared. - This can be confusing. When you need to make things clearer, use the- -E/--empty flag, which will reveal all accounts including unbudgeted+ This can be confusing. When you need to make things clearer, use the+ -E/--empty flag, which will reveal all accounts including unbudgeted ones, giving the full picture. Eg: $ hledger balance -M --budget --empty@@ -1680,12 +1707,12 @@ For more examples, see Budgeting and Forecasting. Nested budgets- You can add budgets to any account in your account hierarchy. If you+ You can add budgets to any account in your account hierarchy. If you have budgets on both parent account and some of its children, then bud-- get(s) of the child account(s) would be added to the budget of their+ get(s) of the child account(s) would be added to the budget of their parent, much like account balances behave. - In the most simple case this means that once you add a budget to any+ In the most simple case this means that once you add a budget to any account, all its parents would have budget as well. To illustrate this, consider the following budget:@@ -1695,13 +1722,13 @@ expenses:personal:electronics $100.00 liabilities - With this, monthly budget for electronics is defined to be $100 and- budget for personal expenses is an additional $1000, which implicity+ With this, monthly budget for electronics is defined to be $100 and+ budget for personal expenses is an additional $1000, which implicity means that budget for both expenses:personal and expenses is $1100. - Transactions in expenses:personal:electronics will be counted both to-+ Transactions in expenses:personal:electronics will be counted both to- wards its $100 budget and $1100 of expenses:personal , and transactions- in any other subaccount of expenses:personal would be counted towards+ in any other subaccount of expenses:personal would be counted towards only towards the budget of expenses:personal. For example, let's consider these transactions:@@ -1727,9 +1754,9 @@ expenses:personal $30.00 liabilities - As you can see, we have transactions in expenses:personal:electron-- ics:upgrades and expenses:personal:train tickets, and since both of- these accounts are without explicitly defined budget, these transac-+ As you can see, we have transactions in expenses:personal:electron-+ ics:upgrades and expenses:personal:train tickets, and since both of+ these accounts are without explicitly defined budget, these transac- tions would be counted towards budgets of expenses:personal:electronics and expenses:personal accordingly: @@ -1745,7 +1772,7 @@ -------------------------------++------------------------------- || 0 [ 0] - And with --empty, we can get a better picture of budget allocation and+ And with --empty, we can get a better picture of budget allocation and consumption: $ hledger balance --budget -M --empty@@ -1763,17 +1790,17 @@ || 0 [ 0] Output format- The balance command supports output destination and output format se-+ The balance command supports output destination and output format se- lection. balancesheet balancesheet, bs This command displays a simple balance sheet, showing historical ending- balances of asset and liability accounts (ignoring any report begin- date). It assumes that these accounts are under a top-level asset or+ balances of asset and liability accounts (ignoring any report begin+ date). It assumes that these accounts are under a top-level asset or liability account (case insensitive, plural forms also allowed). - Note this report shows all account balances with normal positive sign+ Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). @@ -1799,12 +1826,13 @@ 0 With a reporting interval, multiple columns will be shown, one for each- report period. As with multicolumn balance reports, you can alter the- report mode with --change/--cumulative/--historical. Normally bal-- ancesheet shows historical ending balances, which is what you need for- a balance sheet; note this means it ignores report begin dates (and- -T/--row-total, since summing end balances generally does not make- sense).+ report period. As with multicolumn balance reports, you can alter the+ report mode with --change/--cumulative/--historical. Normally bal-+ ancesheet shows historical ending balances, which is what you need for+ a balance sheet; note this means it ignores report begin dates (and+ -T/--row-total, since summing end balances generally does not make+ sense). Instead of absolute values percentages can be displayed with+ -%. This command also supports output destination and output format selec- tion.@@ -1868,79 +1896,80 @@ With a reporting interval, multiple columns will be shown, one for each report period. Normally cashflow shows changes in assets per period, though as with multicolumn balance reports you can alter the report- mode with --change/--cumulative/--historical.+ mode with --change/--cumulative/--historical. Instead of absolute val-+ ues percentages can be displayed with -%. - This command also supports output destination and output format selec-+ This command also supports output destination and output format selec- tion. check-dates check-dates- Check that transactions are sorted by increasing date. With --date2,- checks secondary dates instead. With --strict, dates must also be- unique. With a query, only matched transactions' dates are checked.+ Check that transactions are sorted by increasing date. With --date2,+ checks secondary dates instead. With --strict, dates must also be+ unique. With a query, only matched transactions' dates are checked. Reads the default journal file, or another specified with -f. check-dupes check-dupes- Reports account names having the same leaf but different prefixes. In- other words, two or more leaves that are categorized differently.+ Reports account names having the same leaf but different prefixes. In+ other words, two or more leaves that are categorized differently. Reads the default journal file, or another specified as an argument. An example: http://stefanorodighiero.net/software/hledger-dupes.html close close, equity- Prints a "closing balances" transaction and an "opening balances"+ Prints a "closing balances" transaction and an "opening balances" transaction that bring account balances to and from zero, respectively. Useful for bringing asset/liability balances forward into a new journal- file, or for closing out revenues/expenses to retained earnings at the+ file, or for closing out revenues/expenses to retained earnings at the end of a period. - The closing transaction transfers balances to "equity:closing bal-- ances". The opening transaction transfers balances from "equity:open-+ The closing transaction transfers balances to "equity:closing bal-+ ances". The opening transaction transfers balances from "equity:open- ing balances". You can choose to print just one of the transactions by using the --opening or --closing flag. If you split your journal files by time (eg yearly), you will typically- run this command at the end of the year, and save the closing transac-- tion as last entry of the old file, and the opening transaction as the- first entry of the new file. This makes the files self contained, so- that correct balances are reported no matter which of them are loaded.- Ie, if you load just one file, the balances are initialised correctly;- or if you load several files, the redundant closing/opening transac-- tions cancel each other out. (They will show up in print or register- reports; you can exclude them with a query like not:desc:'(open-+ run this command at the end of the year, and save the closing transac-+ tion as last entry of the old file, and the opening transaction as the+ first entry of the new file. This makes the files self contained, so+ that correct balances are reported no matter which of them are loaded.+ Ie, if you load just one file, the balances are initialised correctly;+ or if you load several files, the redundant closing/opening transac-+ tions cancel each other out. (They will show up in print or register+ reports; you can exclude them with a query like not:desc:'(open- ing|closing) balances'.) If you're running a business, you might also use this command to "close- the books" at the end of an accounting period, transferring income- statement account balances to retained earnings. (You may want to+ the books" at the end of an accounting period, transferring income+ statement account balances to retained earnings. (You may want to change the equity account name to something like "equity:retained earn- ings".) - By default, the closing transaction is dated yesterday, the balances- are calculated as of end of yesterday, and the opening transaction is- dated today. To close on some other date, use: hledger close -e OPEN-- INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019.+ By default, the closing transaction is dated yesterday, the balances+ are calculated as of end of yesterday, and the opening transaction is+ dated today. To close on some other date, use: hledger close -e OPEN-+ INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. You can also use -p or date:PERIOD (any starting date is ignored). - Both transactions will include balance assertions for the closed/re-+ Both transactions will include balance assertions for the closed/re- opened accounts. You probably shouldn't use status or realness filters- (like -C or -R or status:) with this command, or the generated balance- assertions will depend on these flags. Likewise, if you run this com-- mand with --auto, the balance assertions will probably always require+ (like -C or -R or status:) with this command, or the generated balance+ assertions will depend on these flags. Likewise, if you run this com-+ mand with --auto, the balance assertions will probably always require --auto. - When account balances have cost information (transaction prices), the- closing/opening transactions will preserve it, so that eg balance -B+ When account balances have cost information (transaction prices), the+ closing/opening transactions will preserve it, so that eg balance -B reports will not be affected. Examples: - Carrying asset/liability balances into a new file for 2019, all from+ Carrying asset/liability balances into a new file for 2019, all from command line: - Warning: we use >> here to append; be careful not to type a single >+ Warning: we use >> here to append; be careful not to type a single > which would wipe your journal! $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal@@ -1989,18 +2018,18 @@ diff diff- Compares a particular account's transactions in two input files. It+ 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. More precisely, for each posting affecting this account in either file,- it looks for a corresponding posting in the other file which posts the- same amount to the same account (ignoring date, description, etc.)+ it looks for a corresponding posting in the other file which posts the+ same amount to the same account (ignoring date, description, etc.) Since postings not transactions are compared, this also works when mul- tiple bank transactions have been combined into a single journal entry. This is useful eg if you have downloaded an account's transactions from- your bank (eg as CSV data). When hledger and your bank disagree about+ your bank (eg as CSV data). When hledger and your bank disagree about the account balance, you can compare the bank data with your journal to find out the cause. @@ -2018,27 +2047,27 @@ files files- List all files included in the journal. With a REGEX argument, only+ List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. help help Show any of the hledger manuals. - The help command displays any of the main hledger manuals, in one of- several ways. Run it with no argument to list the manuals, or provide+ The help command displays any of the main hledger manuals, in one of+ several ways. Run it with no argument to list the manuals, or provide a full or partial manual name to select one. - hledger manuals are available in several formats. hledger help will- use the first of these display methods that it finds: info, man,- $PAGER, less, stdout (or when non-interactive, just stdout). You can+ hledger manuals are available in several formats. hledger help will+ use the first of these display methods that it finds: info, man,+ $PAGER, less, stdout (or when non-interactive, just stdout). You can force a particular viewer with the --info, --man, --pager, --cat flags. Examples: $ hledger help Please choose a manual by typing "hledger help MANUAL" (a substring is ok).- Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot+ Manuals: hledger hledger-ui hledger-web journal csv timeclock timedot $ hledger help h --man @@ -2058,9 +2087,10 @@ import import- Read new transactions added to each FILE since last run, and add them- to the main journal file. Or with --dry-run, just print the transac-- tions that would be added.+ Read new transactions added to each FILE since last run, and add them+ to the main journal file. Or with --dry-run, just print the transac-+ tions that would be added. Or with --catchup, just mark all of the+ FILEs' transactions as imported, without actually importing any. The input files are specified as arguments - no need to write -f before each one. So eg to add new transactions from all CSV files to the main@@ -2126,9 +2156,10 @@ With a reporting interval, multiple columns will be shown, one for each report period. Normally incomestatement shows revenues/expenses per period, though as with multicolumn balance reports you can alter the- report mode with --change/--cumulative/--historical.+ report mode with --change/--cumulative/--historical. Instead of abso-+ lute values percentages can be displayed with -%. - This command also supports output destination and output format selec-+ This command also supports output destination and output format selec- tion. notes@@ -2156,10 +2187,11 @@ prices prices- Print market price directives from the journal. With --costs, also- print synthetic market prices based on transaction prices. With --in-- verted-costs, also print inverse prices based on transaction prices.- Prices (and postings providing prices) can be filtered by a query.+ Print market price directives from the journal. With --costs, also+ print synthetic market prices based on transaction prices. With --in-+ verted-costs, also print inverse prices based on transaction prices.+ Prices (and postings providing prices) can be filtered by a query.+ Price amounts are always displayed with their full precision. print print, txns, p@@ -2577,46 +2609,47 @@ test Run built-in unit tests. - This command runs the unit tests built in to hledger-lib and hledger,- printing test names and results on stdout. If any test fails, the exit- code will be non-zero.+ This command runs the unit tests built in to hledger and hledger-lib,+ printing the results on stdout. If any test fails, the exit code will+ be non-zero. - Test names include a group prefix. If a (exact, case sensitive) group- prefix, or a full test name is provided as the first argument, only- that group or test is run.+ This is mainly used by hledger developers, but you can also use it to+ sanity-check the installed hledger executable on your platform. All+ tests are expected to pass - if you ever see a failure, please report+ as a bug! - If a numeric second argument is provided, it will set the randomness- seed, for repeatable results from tests using randomness (currently- none of them).+ This command also accepts tasty test runner options, written after a --+ (double hyphen). Eg to run only the tests in Hledger.Data.Amount, with+ ANSI colour codes disabled: - This is mainly used by developers, but it's nice to be able to sanity-- check your installed hledger executable at any time. All tests are ex-- pected to pass - if you ever see otherwise, something has gone wrong,- please report a bug!+ $ hledger test -- -pData.Amount --color=never + For help on these, see https://github.com/feuerbach/tasty#options (--+ --help currently doesn't show them).+ ADD-ON COMMANDS- hledger also searches for external add-on commands, and will include+ hledger also searches for external add-on commands, and will include these in the commands list. These are programs or scripts in your PATH- whose name starts with hledger- and ends with a recognised file exten-+ whose name starts with hledger- and ends with a recognised file exten- sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). - Add-ons can be invoked like any hledger command, but there are a few+ Add-ons can be invoked like any hledger command, but there are a few things to be aware of. Eg if the hledger-web add-on is installed, - o hledger -h web shows hledger's help, while hledger web -h shows+ o hledger -h web shows hledger's help, while hledger web -h shows hledger-web's help. - o Flags specific to the add-on must have a preceding -- to hide them- from hledger. So hledger web --serve --port 9000 will be rejected;+ o Flags specific to the add-on must have a preceding -- to hide them+ from hledger. So hledger web --serve --port 9000 will be rejected; you must use hledger web -- --serve --port 9000. o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - Add-ons are a relatively easy way to add local features or experiment- with new ideas. They can be written in any language, but haskell- scripts have a big advantage: they can use the same hledger (and- haskell) library functions that built-in commands do, for command-line+ Add-ons are a relatively easy way to add local features or experiment+ with new ideas. They can be written in any language, but haskell+ scripts have a big advantage: they can use the same hledger (and+ haskell) library functions that built-in commands do, for command-line options, journal parsing, reporting, etc. Here are some hledger add-ons available:@@ -2624,17 +2657,14 @@ Official add-ons These are maintained and released along with hledger. - api- hledger-api serves hledger data as a JSON web API.- ui- hledger-ui provides an efficient curses-style interface.+ hledger-ui provides an efficient terminal interface. web hledger-web provides a simple web interface. Third party add-ons- These are maintained separately, and usually updated shortly after a+ These are maintained separately, and usually updated shortly after a hledger release. diff@@ -2642,8 +2672,8 @@ journal file and another. iadd- hledger-iadd is a curses-style, more interactive replacement for the- add command.+ hledger-iadd is a more interactive, terminal UI replacement for the add+ command. interest hledger-interest generates interest transactions for an account accord-@@ -2654,10 +2684,9 @@ count, but it's superseded now by the built-in roi command. Experimental add-ons- These are available in source form in the hledger repo's bin/ direc-- tory; installing them is pretty easy. They may be less mature and doc-- umented than built-in commands. Reading and tweaking these is a good- way to start making your own!+ These are available in source form in the hledger repo's bin/ direc-+ tory. They may be less mature and documented than built-in commands.+ Reading and tweaking these is a good way to start making your own! autosync hledger-autosync is a symbolic link for easily running ledger-autosync,@@ -2777,7 +2806,7 @@ COPYRIGHT- Copyright (C) 2007-2016 Simon Michael.+ Copyright (C) 2007-2019 Simon Michael. Released under GNU GPL v3 or later. @@ -2790,4 +2819,4 @@ -hledger 1.15.2 September 2019 hledger(1)+hledger 1.16 December 2019 hledger(1)
− test/test.hs
@@ -1,8 +0,0 @@-{--Run hledger's (and hledger-lib's) unit tests as a cabal test suite,-by running the test command with no options.--}--import Hledger.Cli--main = testcmd defcliopts (error "journal-less command tried to use the journal")
+ test/unittest.hs view
@@ -0,0 +1,13 @@+{-+Run the hledger package's unit tests using the tasty test runner+(by running the test command limited to Hledger.Cli tests).+-}++-- cabal missing-home-modules workaround from hledger-lib, seems not needed here+-- {-# LANGUAGE PackageImports #-}+-- import "hledger" Hledger.Cli (tests_Hledger_Cli)+import Hledger.Cli (tests_Hledger_Cli)++import Test.Tasty (defaultMain)++main = defaultMain tests_Hledger_Cli