diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs index bc8b96fce..08431fe40 100644 --- a/hledger/Hledger/Cli/CliOptions.hs +++ b/hledger/Hledger/Cli/CliOptions.hs @@ -40,6 +40,7 @@ module Hledger.Cli.CliOptions ( outputFormats, defaultOutputFormat, defaultBalanceLineFormat, + CommandDoc, -- possibly these should move into argsToCliOpts -- * CLI option accessors @@ -235,14 +236,18 @@ addonCommandMode name = (defCommandMode [name]) { } } +-- | A command's documentation. Used both as part of CLI help, and as +-- part of the hledger manual. See parseCommandDoc. +type CommandDoc = String + -- | Build a cmdarg mode for a hledger command, -- from a help template and flag/argument specifications. -- Reduces boilerplate a little, though the complicated cmdargs -- flag and argument specs are still required. -hledgerCommandMode :: HelpTemplate -> [Flag RawOpts] -> [(String, [Flag RawOpts])] +hledgerCommandMode :: CommandDoc -> [Flag RawOpts] -> [(String, [Flag RawOpts])] -> [Flag RawOpts] -> ([Arg RawOpts], Maybe (Arg RawOpts)) -> Mode RawOpts hledgerCommandMode tmpl unnamedflaggroup namedflaggroups hiddenflaggroup argsdescr = - case parseHelpTemplate tmpl of + case parseCommandDoc tmpl of Nothing -> error' $ "Could not parse help template:\n"++tmpl++"\n" Just (names, shorthelp, longhelplines) -> (defCommandMode names) { @@ -256,10 +261,6 @@ hledgerCommandMode tmpl unnamedflaggroup namedflaggroups hiddenflaggroup argsdes ,modeArgs = argsdescr } --- | A command's documentation. Used both as part of CLI help, and as --- part of the hledger manual. See parseHelpTemplate. -type HelpTemplate = String - -- | Parse a command's documentation, as follows: -- -- - First line: the command name then any aliases, as one or more space or comma-separated words @@ -273,8 +274,8 @@ type HelpTemplate = String -- optional again). The manual displays the short help followed by -- the long help, with no flags list. -- -parseHelpTemplate :: HelpTemplate -> Maybe ([Name], String, [String]) -parseHelpTemplate t = +parseCommandDoc :: CommandDoc -> Maybe ([Name], String, [String]) +parseCommandDoc t = case lines t of [] -> Nothing (l:ls) -> Just (names, shorthelp, longhelplines) diff --git a/hledger/Hledger/Cli/Commands.hs b/hledger/Hledger/Cli/Commands.hs index f4edfd832..de2381cd9 100644 --- a/hledger/Hledger/Cli/Commands.hs +++ b/hledger/Hledger/Cli/Commands.hs @@ -5,6 +5,7 @@ hledger's built-in commands, and helpers for printing the commands list. {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE CPP #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands ( findCommand @@ -222,18 +223,7 @@ commandsFromCommandsList s = -- The test command, defined here for easy access to other modules' tests. testmode = hledgerCommandMode - [here| test -Run the unit tests built in to hledger-lib and hledger, -printing results on stdout and exiting with success or failure. - -If a scope argument is provided, only tests in that (exact, case-sensitive) -scope are run. - -If a numeric second argument is provided, it will set the randomness seed, -for any tests which use randomness. - -FLAGS - |] + $(hereFileRelative "Hledger/Cli/Commands/Test.md") [] [generalflagsgroup3] [] diff --git a/hledger/Hledger/Cli/Commands/Balancesheet.hs b/hledger/Hledger/Cli/Commands/Balancesheet.hs index 252ec5eec..a000a6b83 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheet.hs +++ b/hledger/Hledger/Cli/Commands/Balancesheet.hs @@ -1,4 +1,5 @@ -{-# LANGUAGE QuasiQuotes, RecordWildCards #-} +{-# LANGUAGE RecordWildCards #-} +{-# LANGUAGE TemplateHaskell #-} {-| The @balancesheet@ command prints a simple balance sheet. @@ -10,7 +11,6 @@ module Hledger.Cli.Commands.Balancesheet ( ,balancesheet ) where -import Data.String.Here import System.Console.CmdArgs.Explicit import Hledger @@ -18,18 +18,7 @@ import Hledger.Cli.CliOptions import Hledger.Cli.CompoundBalanceCommand balancesheetSpec = CompoundBalanceCommandSpec { - cbcname = "balancesheet", - cbcaliases = ["bs"], - cbchelp = [here| -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 `liability` -account (case insensitive, plural forms also allowed). - -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). - |], + cbcdoc = ($(hereFileRelative "Hledger/Cli/Commands/Balancesheet.md")), cbctitle = "Balance Sheet", cbcqueries = [ CBCSubreportSpec{ diff --git a/hledger/Hledger/Cli/Commands/Balancesheet.md b/hledger/Hledger/Cli/Commands/Balancesheet.md new file mode 100644 index 000000000..0174f0d7c --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Balancesheet.md @@ -0,0 +1,46 @@ +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 `liability` +account (case insensitive, plural forms also allowed). + +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). + +_FLAGS_ + +Example: + +```shell +$ hledger balancesheet +Balance Sheet + +Assets: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Total: +-------------------- + 0 +``` + +With a [reporting interval](#reporting-interval), multiple columns +will be shown, one for each report period. +As with [multicolumn balance reports](#multicolumn-balance-reports), +you can alter the report mode with `--change`/`--cumulative`/`--historical`. +Normally balancesheet shows historical ending balances, which is what +you need for a balance sheet; note this means it ignores report begin +dates. + +This command also supports +[output destination](/manual.html#output-destination) and +[output format](/manual.html#output-format) selection. diff --git a/hledger/Hledger/Cli/Commands/Balancesheetequity.hs b/hledger/Hledger/Cli/Commands/Balancesheetequity.hs index 130c1fd1f..d33542a65 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheetequity.hs +++ b/hledger/Hledger/Cli/Commands/Balancesheetequity.hs @@ -1,4 +1,5 @@ {-# LANGUAGE QuasiQuotes, RecordWildCards #-} +{-# LANGUAGE TemplateHaskell #-} {-| The @balancesheetequity@ command prints a simple balance sheet. @@ -10,7 +11,6 @@ module Hledger.Cli.Commands.Balancesheetequity ( ,balancesheetequity ) where -import Data.String.Here import System.Console.CmdArgs.Explicit import Hledger @@ -18,17 +18,7 @@ import Hledger.Cli.CliOptions import Hledger.Cli.CompoundBalanceCommand balancesheetequitySpec = CompoundBalanceCommandSpec { - cbcname = "balancesheetequity", - cbcaliases = ["bse"], - cbchelp = [here|This command displays a simple balance sheet, showing historical ending -balances of asset, liability and equity accounts (ignoring any report begin date). -It assumes that these accounts are under a top-level `asset`, `liability` and `equity` -account (plural forms also allowed). - -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). - |], + cbcdoc = ($(hereFileRelative "Hledger/Cli/Commands/Balancesheetequity.md")), cbctitle = "Balance Sheet With Equity", cbcqueries = [ CBCSubreportSpec{ diff --git a/hledger/Hledger/Cli/Commands/Balancesheetequity.md b/hledger/Hledger/Cli/Commands/Balancesheetequity.md new file mode 100644 index 000000000..a221f8604 --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Balancesheetequity.md @@ -0,0 +1,32 @@ +balancesheetequity, bse\ +Just like [balancesheet](#balancesheet), but also reports Equity +(which it assumes is under a top-level `equity` account). + +_FLAGS_ + +Example: +```shell +$ hledger balancesheetequity +Balance Sheet With Equity + +Assets: + $-2 assets + $1 bank:saving + $-3 cash +-------------------- + $-2 + +Liabilities: + $1 liabilities:debts +-------------------- + $1 + +Equity: + $1 equity:owner +-------------------- + $1 + +Total: +-------------------- + 0 +``` diff --git a/hledger/Hledger/Cli/Commands/Cashflow.hs b/hledger/Hledger/Cli/Commands/Cashflow.hs index b3d590661..6bc34aa9d 100644 --- a/hledger/Hledger/Cli/Commands/Cashflow.hs +++ b/hledger/Hledger/Cli/Commands/Cashflow.hs @@ -1,4 +1,5 @@ {-# LANGUAGE QuasiQuotes, RecordWildCards #-} +{-# LANGUAGE TemplateHaskell #-} {-| The @cashflow@ command prints a simplified cashflow statement. It just @@ -13,7 +14,6 @@ module Hledger.Cli.Commands.Cashflow ( ,cashflow ) where -import Data.String.Here import System.Console.CmdArgs.Explicit import Hledger @@ -21,18 +21,7 @@ import Hledger.Cli.CliOptions import Hledger.Cli.CompoundBalanceCommand cashflowSpec = CompoundBalanceCommandSpec { - cbcname = "cashflow", - cbcaliases = ["cf"], - cbchelp = [here| -This command displays a simple cashflow statement, showing changes -in "cash" accounts. It assumes that these accounts are under a top-level -`asset` account (case insensitive, plural forms also allowed) and do not -contain `receivable` or `A/R` in their name. - -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). - |], + cbcdoc = ($(hereFileRelative "Hledger/Cli/Commands/Cashflow.md")), cbctitle = "Cashflow Statement", cbcqueries = [ CBCSubreportSpec{ diff --git a/hledger/Hledger/Cli/Commands/Cashflow.md b/hledger/Hledger/Cli/Commands/Cashflow.md new file mode 100644 index 000000000..308b04e9d --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Cashflow.md @@ -0,0 +1,37 @@ +cashflow, cf\ +This command displays a simple cashflow statement, showing changes +in "cash" accounts. It assumes that these accounts are under a top-level +`asset` account (case insensitive, plural forms also allowed) and do not +contain `receivable` or `A/R` in their name. +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). + +_FLAGS_ + +Example: +```shell +$ hledger cashflow +Cashflow Statement + +Cash flows: + $-1 assets + $1 bank:saving + $-2 cash +-------------------- + $-1 + +Total: +-------------------- + $-1 +``` + +With a [reporting interval](#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](#multicolumn-balance-reports) +you can alter the report mode with `--change`/`--cumulative`/`--historical`. + +This command also supports +[output destination](/manual.html#output-destination) and +[output format](/manual.html#output-format) selection. diff --git a/hledger/Hledger/Cli/Commands/Checkdates.hs b/hledger/Hledger/Cli/Commands/Checkdates.hs index 903fab5ab..f380559f7 100755 --- a/hledger/Hledger/Cli/Commands/Checkdates.hs +++ b/hledger/Hledger/Cli/Commands/Checkdates.hs @@ -1,27 +1,19 @@ -{-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE NoOverloadedStrings #-} -- prevent trouble if turned on in ghci +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Checkdates ( checkdatesmode ,checkdates ) where -import Data.String.Here import Hledger import Hledger.Cli.CliOptions import System.Console.CmdArgs.Explicit import Text.Printf --- checkdatesmode :: Mode RawOpts +checkdatesmode :: Mode RawOpts checkdatesmode = hledgerCommandMode - [here| 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. -Reads the default journal file, or another specified with -f. -FLAGS - |] + ($(hereFileRelative "Hledger/Cli/Commands/Checkdates.md")) [flagNone ["strict"] (\opts -> setboolopt "strict" opts) "makes date comparing strict"] [generalflagsgroup1] [] diff --git a/hledger/Hledger/Cli/Commands/Checkdates.md b/hledger/Hledger/Cli/Commands/Checkdates.md new file mode 100644 index 000000000..5aa8fbe5b --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Checkdates.md @@ -0,0 +1,8 @@ +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. +Reads the default journal file, or another specified with -f. + +_FLAGS_ diff --git a/hledger/Hledger/Cli/Commands/Checkdupes.hs b/hledger/Hledger/Cli/Commands/Checkdupes.hs index d9b0c1199..abecf905e 100755 --- a/hledger/Hledger/Cli/Commands/Checkdupes.hs +++ b/hledger/Hledger/Cli/Commands/Checkdupes.hs @@ -1,4 +1,4 @@ -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Checkdupes ( checkdupesmode @@ -8,7 +8,6 @@ where import Data.Function import Data.List -import Data.String.Here import qualified Data.Text as T import Hledger import Hledger.Cli.CliOptions @@ -17,12 +16,7 @@ import Text.Printf checkdupesmode :: Mode RawOpts checkdupesmode = hledgerCommandMode - [here| check-dupes -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 - |] + ($(hereFileRelative "Hledger/Cli/Commands/Checkdupes.md")) [] [generalflagsgroup1] [] diff --git a/hledger/Hledger/Cli/Commands/Checkdupes.md b/hledger/Hledger/Cli/Commands/Checkdupes.md new file mode 100644 index 000000000..dc0ce538b --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Checkdupes.md @@ -0,0 +1,8 @@ +check-dupes\ +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. + +_FLAGS_ + +An example: http://stefanorodighiero.net/software/hledger-dupes.html diff --git a/hledger/Hledger/Cli/Commands/Files.hs b/hledger/Hledger/Cli/Commands/Files.hs index c9a9c70c9..c1770041c 100644 --- a/hledger/Hledger/Cli/Commands/Files.hs +++ b/hledger/Hledger/Cli/Commands/Files.hs @@ -5,6 +5,7 @@ The @files@ command lists included files. -} {-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Files ( filesmode @@ -12,9 +13,7 @@ module Hledger.Cli.Commands.Files ( ) where import Data.List --- import Data.Text (Text) import Safe -import System.Console.CmdArgs.Explicit as C import Hledger import Prelude hiding (putStrLn) @@ -23,19 +22,12 @@ import Hledger.Cli.CliOptions -- | Command line options for this command. -filesmode = (defCommandMode $ ["files"] ) { - modeHelp = "show names of included files" - ,modeHelpSuffix = [ - "This command lists names of all files included in the parsed journal(s)." - ,"With REGEX argument will list only files matching regular expression (case sensitive)." - ] - ,modeGroupFlags = C.Group { - groupUnnamed = [] - ,groupHidden = [] - ,groupNamed = [generalflagsgroup2] - } - ,modeArgs= ([], Just $ argsFlag "[REGEX]") - } +filesmode = hledgerCommandMode + ($(hereFileRelative "Hledger/Cli/Commands/Files.md")) + [] + [generalflagsgroup2] + [] + ([], Just $ argsFlag "[REGEX]") -- | The files command. files :: CliOpts -> Journal -> IO () diff --git a/hledger/Hledger/Cli/Commands/Files.md b/hledger/Hledger/Cli/Commands/Files.md new file mode 100644 index 000000000..95e6ac358 --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Files.md @@ -0,0 +1,5 @@ +files\ +List all files included in the journal. With a REGEX argument, +only file names matching the regular expression (case sensitive) are shown. + +_FLAGS_ diff --git a/hledger/Hledger/Cli/Commands/Help.hs b/hledger/Hledger/Cli/Commands/Help.hs index b6341c665..c5b2b2952 100644 --- a/hledger/Hledger/Cli/Commands/Help.hs +++ b/hledger/Hledger/Cli/Commands/Help.hs @@ -6,8 +6,9 @@ The help command. --TODO rename manuals --TODO substring matching -{-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE PackageImports #-} +{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Help ( @@ -19,36 +20,32 @@ module Hledger.Cli.Commands.Help ( import Prelude () import "base-compat-batteries" Prelude.Compat import Data.Char +import Data.String.Here import Data.List import Data.Maybe -import Data.String.Here import Safe import System.Console.CmdArgs.Explicit import System.Environment import System.IO +import Hledger.Utils (hereFileRelative) import Hledger.Data.RawOptions import Hledger.Data.Types import Hledger.Cli.CliOptions import Hledger.Cli.DocFiles --import Hledger.Utils.Debug -helpmode = (defCommandMode $ ["help"] ++ aliases) { - modeHelp = "show any of the hledger manuals, choosing the most suitable viewer (info, man, a pager, or stdout). With no argument, list the manuals." `withAliases` aliases - ,modeGroupFlags = Group { - groupUnnamed = [ - flagNone ["info"] (setboolopt "info") "show the manual with info" - ,flagNone ["man"] (setboolopt "man") "show the manual with man" - ,flagNone ["pager"] (setboolopt "pager") "show the manual with $PAGER or less" - ,flagNone ["cat"] (setboolopt "cat") "show the manual on stdout" - ,flagNone ["help","h"] (setboolopt "help") "show this help" - ] - ,groupHidden = [] - ,groupNamed = [] - } - ,modeArgs = ([], Just $ argsFlag "[MANUAL]") -} - where aliases = [] +helpmode = hledgerCommandMode + ($(hereFileRelative "Hledger/Cli/Commands/Help.md")) + [flagNone ["info"] (setboolopt "info") "show the manual with info" + ,flagNone ["man"] (setboolopt "man") "show the manual with man" + ,flagNone ["pager"] (setboolopt "pager") "show the manual with $PAGER or less" + ,flagNone ["cat"] (setboolopt "cat") "show the manual on stdout" + ,flagNone ["help","h"] (setboolopt "help") "show this help" + ] + [] + [] + ([], Just $ argsFlag "[MANUAL]") -- | List or display one of the hledger manuals in various formats. -- You can select a docs viewer with one of the `--info`, `--man`, `--pager`, `--cat` flags. diff --git a/hledger/Hledger/Cli/Commands/Help.md b/hledger/Hledger/Cli/Commands/Help.md new file mode 100644 index 000000000..1a2ff1191 --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Help.md @@ -0,0 +1,38 @@ +help\ +Show any of the hledger manuals. + +_FLAGS_ + +The `help` command displays any of the main [hledger manuals](/docs.html), 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 force a particular viewer with the `--info`, `--man`, `--pager`, `--cat` flags. + +Examples: + +```shell +$ 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 +``` + +```shell +$ hledger help h --man + +hledger(1) hledger User Manuals hledger(1) + +NAME + hledger - a command-line accounting tool + +SYNOPSIS + hledger [-f FILE] COMMAND [OPTIONS] [ARGS] + hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] + hledger + +DESCRIPTION + hledger is a cross-platform program for tracking money, time, or any +... +``` diff --git a/hledger/Hledger/Cli/Commands/Import.hs b/hledger/Hledger/Cli/Commands/Import.hs index 3e6b21c7f..78c5e6e4b 100755 --- a/hledger/Hledger/Cli/Commands/Import.hs +++ b/hledger/Hledger/Cli/Commands/Import.hs @@ -1,5 +1,5 @@ {-# LANGUAGE OverloadedStrings #-} -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Import ( importmode @@ -10,7 +10,6 @@ where import Control.Monad import Data.List import Data.Ord -import Data.String.Here import Hledger import Hledger.Cli.CliOptions import Hledger.Cli.Commands.Add (journalAddTransaction) @@ -19,18 +18,7 @@ import System.Console.CmdArgs.Explicit import Text.Printf importmode = hledgerCommandMode - [here| 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. - -Input files are provided as arguments, or glob patterns. So eg to add new -transactions from all CSV files to the main journal: hledger import *.csv - -New transactions are detected like print --new (using .latest.FILE state files) - -FLAGS - |] + ($(hereFileRelative "Hledger/Cli/Commands/Import.md")) [flagNone ["dry-run"] (\opts -> setboolopt "dry-run" opts) "just show the transactions to be imported"] [generalflagsgroup1] [] diff --git a/hledger/Hledger/Cli/Commands/Import.md b/hledger/Hledger/Cli/Commands/Import.md new file mode 100644 index 000000000..bd691232b --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Import.md @@ -0,0 +1,21 @@ +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. + +_FLAGS_ + +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 journal, it's just: +`hledger import *.csv` + +New transactions are detected in the same way as print --new: +by assuming transactions are always added to the input files in increasing date order, +and by saving `.latest.FILE` state files. + +The --dry-run output is in journal format, so you can filter it, eg +to see only uncategorised transactions: + +```shell +$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions +``` diff --git a/hledger/Hledger/Cli/Commands/Incomestatement.hs b/hledger/Hledger/Cli/Commands/Incomestatement.hs index 3793e7066..566b35cca 100644 --- a/hledger/Hledger/Cli/Commands/Incomestatement.hs +++ b/hledger/Hledger/Cli/Commands/Incomestatement.hs @@ -10,7 +10,6 @@ module Hledger.Cli.Commands.Incomestatement ( ,incomestatement ) where -import Data.String.Here import System.Console.CmdArgs.Explicit import Hledger @@ -18,18 +17,7 @@ import Hledger.Cli.CliOptions import Hledger.Cli.CompoundBalanceCommand incomestatementSpec = CompoundBalanceCommandSpec { - cbcname = "incomestatement", - cbcaliases = ["is"], - cbchelp = [here| -This command displays a simple income statement, showing revenues -and expenses during a period. It assumes that these accounts are under a -top-level `revenue` or `income` or `expense` account (case insensitive, -plural forms also allowed). - -Note this report shows all account balances with normal positive sign -(like conventional financial statements, unlike balance/print/register) -(experimental). - |], + cbcdoc = ($(hereFileRelative "Hledger/Cli/Commands/Incomestatement.md")), cbctitle = "Income Statement", cbcqueries = [ CBCSubreportSpec{ diff --git a/hledger/Hledger/Cli/Commands/Incomestatement.md b/hledger/Hledger/Cli/Commands/Incomestatement.md new file mode 100644 index 000000000..6096aa19d --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Incomestatement.md @@ -0,0 +1,48 @@ +incomestatement, is\ +This command displays a simple income statement, showing revenues +and expenses during a period. It assumes that these accounts are under a +top-level `revenue` or `income` or `expense` account (case insensitive, +plural forms also allowed). +Note this report shows all account balances with normal positive sign +(like conventional financial statements, unlike balance/print/register) +(experimental). + +_FLAGS_ + +This command displays a simple +[income statement](http://en.wikipedia.org/wiki/Income_statement). It +currently assumes that you have top-level accounts named `income` (or +`revenue`) and `expense` (plural forms also allowed.) + +```shell +$ hledger incomestatement +Income Statement + +Revenues: + $-2 income + $-1 gifts + $-1 salary +-------------------- + $-2 + +Expenses: + $2 expenses + $1 food + $1 supplies +-------------------- + $2 + +Total: +-------------------- + 0 +``` + +With a [reporting interval](#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](#multicolumn-balance-reports) +you can alter the report mode with `--change`/`--cumulative`/`--historical`. + +This command also supports +[output destination](/manual.html#output-destination) and +[output format](/manual.html#output-format) selection. diff --git a/hledger/Hledger/Cli/Commands/Prices.hs b/hledger/Hledger/Cli/Commands/Prices.hs index a64ce5505..627d9c363 100755 --- a/hledger/Hledger/Cli/Commands/Prices.hs +++ b/hledger/Hledger/Cli/Commands/Prices.hs @@ -1,4 +1,4 @@ -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Prices ( pricesmode @@ -8,7 +8,6 @@ where import Data.Maybe import Data.List -import Data.String.Here import qualified Data.Text as T import Data.Time import Hledger @@ -16,12 +15,7 @@ import Hledger.Cli.CliOptions import System.Console.CmdArgs.Explicit pricesmode = hledgerCommandMode - [here| prices -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. - |] + ($(hereFileRelative "Hledger/Cli/Commands/Prices.md")) [flagNone ["costs"] (setboolopt "costs") "print transaction prices from postings" ,flagNone ["inverted-costs"] (setboolopt "inverted-costs") "print transaction inverted prices from postings also"] [generalflagsgroup1] diff --git a/hledger/Hledger/Cli/Commands/Prices.md b/hledger/Hledger/Cli/Commands/Prices.md new file mode 100644 index 000000000..fc8ddd286 --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Prices.md @@ -0,0 +1,7 @@ +prices\ +Print [market price directives](/manual#market-prices) from the journal. +With --costs, also print synthetic market prices based on [transaction prices](/manual#transaction-prices). +With --inverted-costs, also print inverse prices based on transaction prices. +Prices (and postings providing prices) can be filtered by a query. + +_FLAGS_ diff --git a/hledger/Hledger/Cli/Commands/Print.hs b/hledger/Hledger/Cli/Commands/Print.hs index a68adab56..710db4783 100644 --- a/hledger/Hledger/Cli/Commands/Print.hs +++ b/hledger/Hledger/Cli/Commands/Print.hs @@ -5,6 +5,7 @@ A ledger-compatible @print@ command. -} {-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Print ( printmode @@ -25,24 +26,19 @@ import Hledger.Cli.Utils import Hledger.Cli.Commands.Add ( transactionsSimilarTo ) -printmode = (defCommandMode $ ["print"] ++ aliases) { - modeHelp = "show transaction journal entries, sorted by date. With --date2, sort by secondary date instead." `withAliases` aliases - ,modeGroupFlags = Group { - groupUnnamed = [ - let arg = "STR" in - flagReq ["match","m"] (\s opts -> Right $ setopt "match" s opts) arg - ("show the transaction whose description is most similar to "++arg++", and is most recent") - ,flagNone ["explicit","x"] (setboolopt "explicit") - "show all amounts explicitly" - ,flagNone ["new"] (setboolopt "new") - "show only newer-dated transactions added in each file since last run" - ] - ++ outputflags - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } - where aliases = ["p","txns"] +printmode = hledgerCommandMode + ($(hereFileRelative "Hledger/Cli/Commands/Print.md")) + [let arg = "STR" in + flagReq ["match","m"] (\s opts -> Right $ setopt "match" s opts) arg + ("show the transaction whose description is most similar to "++arg++", and is most recent") + ,flagNone ["explicit","x"] (setboolopt "explicit") + "show all amounts explicitly" + ,flagNone ["new"] (setboolopt "new") + "show only newer-dated transactions added in each file since last run" + ] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") -- | Print journal transactions in standard format. print' :: CliOpts -> Journal -> IO () diff --git a/hledger/Hledger/Cli/Commands/Print.md b/hledger/Hledger/Cli/Commands/Print.md new file mode 100644 index 000000000..dd9c679e9 --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Print.md @@ -0,0 +1,96 @@ +print, txns, p\ +Show transaction journal entries, sorted by date. + +_FLAGS_ + +The print command displays full journal entries (transactions) from +the journal file in date order, tidily formatted. +With --date2, transactions are sorted by secondary date instead. + +print's output is always a valid [hledger journal](/journal.html). +It preserves all transaction information, but it does not preserve +directives or inter-transaction comments + +```shell +$ hledger print +2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + +2008/06/01 gift + assets:bank:checking $1 + income:gifts $-1 + +2008/06/02 save + assets:bank:saving $1 + assets:bank:checking $-1 + +2008/06/03 * eat & shop + expenses:food $1 + expenses:supplies $1 + assets:cash $-2 + +2008/12/31 * pay off + liabilities:debts $1 + assets:bank:checking $-1 +``` + +Normally, the journal entry's explicit or implicit amount style is preserved. +Ie when an amount is omitted in the journal, it will be omitted in the output. +You can use the `-x`/`--explicit` flag to make all amounts explicit, which can be +useful for troubleshooting or for making your journal more readable and +robust against data entry errors. +Note, `-x` will cause postings with a multi-commodity amount +(these can arise when a multi-commodity transaction has an implicit amount) +will be split into multiple single-commodity postings, for valid journal output. + +With `-B`/`--cost`, amounts with [transaction prices](/journal.html#transaction-prices) +are converted to cost using that price. This can be used for troubleshooting. + +With `-m`/`--match` and a STR argument, print will show at most one transaction: the one +one whose description is most similar to STR, and is most recent. STR should contain at +least two characters. If there is no similar-enough match, no transaction will be shown. + +With `--new`, for each FILE being read, hledger reads (and writes) a special +state file (`.latest.FILE` in the same directory), containing the latest transaction date(s) +that were seen last time FILE was read. When this file is found, only transactions +with newer dates (and new transactions on the latest date) are printed. +This is useful for ignoring already-seen entries in import data, such as downloaded CSV files. +Eg: + +```console +$ hledger -f bank1.csv print --new +# shows transactions added since last print --new on this file +``` + +This assumes that transactions added to FILE always have same or increasing dates, +and that transactions on the same day do not get reordered. +See also the [import](#import) command. + +This command also supports [output destination](/manual.html#output-destination) and [output format](/manual.html#output-format) selection. +Here's an example of print's CSV output: + +```shell +$ hledger print -Ocsv +"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" +"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" +"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" +"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" +"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" +"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" +"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" +"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" +"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" +"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" +``` + +- There is one CSV record per posting, with the parent transaction's fields repeated. +- The "txnidx" (transaction index) field shows which postings belong to the same transaction. + (This number might change if transactions are reordered within the file, + files are parsed/included in a different order, etc.) +- The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. +- The numeric amount is repeated in either the "credit" or "debit" column, for convenience. + (Those names are not accurate in the accounting sense; it just puts negative amounts under + credit and zero or greater amounts under debit.) diff --git a/hledger/Hledger/Cli/Commands/Printunique.hs b/hledger/Hledger/Cli/Commands/Printunique.hs index ec7bc71b1..668e5a86a 100755 --- a/hledger/Hledger/Cli/Commands/Printunique.hs +++ b/hledger/Hledger/Cli/Commands/Printunique.hs @@ -1,6 +1,4 @@ -{-# LANGUAGE QuasiQuotes #-} - -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Printunique ( printuniquemode @@ -10,30 +8,12 @@ where import Data.List import Data.Ord -import Data.String.Here import Hledger import Hledger.Cli.CliOptions import Hledger.Cli.Commands.Print printuniquemode = hledgerCommandMode - [here| print-unique -Print transactions which do not reuse an already-seen description. - -FLAGS - -Example: -```shell -$ cat unique.journal -1/1 test - (acct:one) 1 -2/2 test - (acct:two) 2 -$ LEDGER_FILE=unique.journal hledger print-unique -(-f option not supported) -2015/01/01 test - (acct:one) 1 -``` - |] + ($(hereFileRelative "Hledger/Cli/Commands/Printunique.md")) [] [generalflagsgroup1] [] diff --git a/hledger/Hledger/Cli/Commands/Printunique.md b/hledger/Hledger/Cli/Commands/Printunique.md new file mode 100644 index 000000000..e66f13c71 --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Printunique.md @@ -0,0 +1,18 @@ +print-unique\ +Print transactions which do not reuse an already-seen description. + +_FLAGS_ + +Example: + +```shell +$ cat unique.journal +1/1 test + (acct:one) 1 +2/2 test + (acct:two) 2 +$ LEDGER_FILE=unique.journal hledger print-unique +(-f option not supported) +2015/01/01 test + (acct:one) 1 +``` diff --git a/hledger/Hledger/Cli/Commands/Register.hs b/hledger/Hledger/Cli/Commands/Register.hs index 43105083f..4ed36e349 100644 --- a/hledger/Hledger/Cli/Commands/Register.hs +++ b/hledger/Hledger/Cli/Commands/Register.hs @@ -5,6 +5,7 @@ A ledger-compatible @register@ command. -} {-# LANGUAGE CPP, OverloadedStrings #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Register ( registermode @@ -26,33 +27,28 @@ import Hledger import Hledger.Cli.CliOptions import Hledger.Cli.Utils -registermode = (defCommandMode $ ["register"] ++ aliases) { - modeHelp = "show postings and running total. With --date2, show and sort by secondary date instead." `withAliases` aliases - ,modeGroupFlags = Group { - groupUnnamed = [ - flagNone ["cumulative"] (\opts -> setboolopt "change" opts) - "show running total from report start date (default)" - ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) - "show historical running total/balance (includes postings before report start date)\n " - ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) - "show running average of posting amounts instead of total (implies --empty)" - ,flagNone ["related","r"] (\opts -> setboolopt "related" opts) "show postings' siblings instead" - ,flagReq ["width","w"] (\s opts -> Right $ setopt "width" s opts) "N" - ("set output width (default: " ++ +registermode = hledgerCommandMode + ($(hereFileRelative "Hledger/Cli/Commands/Register.md")) + [flagNone ["cumulative"] (\opts -> setboolopt "change" opts) + "show running total from report start date (default)" + ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) + "show historical running total/balance (includes postings before report start date)\n " + ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) + "show running average of posting amounts instead of total (implies --empty)" + ,flagNone ["related","r"] (\opts -> setboolopt "related" opts) "show postings' siblings instead" + ,flagReq ["width","w"] (\s opts -> Right $ setopt "width" s opts) "N" + ("set output width (default: " ++ #ifdef mingw32_HOST_OS - show defaultWidth + show defaultWidth #else - "terminal width" + "terminal width" #endif - ++ " or $COLUMNS). -wN,M sets description width as well." - ) - ] - ++ outputflags - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } - where aliases = ["r","reg"] + ++ " or $COLUMNS). -wN,M sets description width as well." + ) + ] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") -- | Print a (posting) register report. register :: CliOpts -> Journal -> IO () diff --git a/hledger/Hledger/Cli/Commands/Register.md b/hledger/Hledger/Cli/Commands/Register.md new file mode 100644 index 000000000..47e1a7779 --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Register.md @@ -0,0 +1,112 @@ +register, reg, r\ +Show postings and their running total. + +_FLAGS_ + +The register command displays postings in date order, one per line, +and their running total. This is typically used with a +[query](#queries) selecting a particular account, to see that +account's activity: + +```shell +$ hledger register checking +2008/01/01 income assets:bank:checking $1 $1 +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 +``` + +With --date2, it shows and sorts by secondary date instead. + +The `--historical`/`-H` flag adds the balance from any undisplayed +prior postings to the running total. This is useful when you want to +see only recent activity, with a historically accurate running balance: + +```shell +$ hledger register checking -b 2008/6 --historical +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 +``` + +The `--depth` option limits the amount of sub-account detail displayed. + +The `--average`/`-A` flag shows the running average posting amount +instead of the running total (so, the final number displayed is the +average for the whole report period). This flag implies `--empty` (see below). +It is affected by `--historical`. +It works best when showing just one account and one commodity. + +The `--related`/`-r` flag shows the *other* postings in the transactions +of the postings which would normally be shown. + +With a [reporting interval](#reporting-interval), register shows +summary postings, one per interval, aggregating the postings to each account: + +```shell +$ hledger register --monthly income +2008/01 income:salary $-1 $-1 +2008/06 income:gifts $-1 $-2 +``` +Periods with no activity, and summary postings with a zero amount, are +not shown by default; use the `--empty`/`-E` flag to see them: + +```shell +$ hledger register --monthly income -E +2008/01 income:salary $-1 $-1 +2008/02 0 $-1 +2008/03 0 $-1 +2008/04 0 $-1 +2008/05 0 $-1 +2008/06 income:gifts $-1 $-2 +2008/07 0 $-2 +2008/08 0 $-2 +2008/09 0 $-2 +2008/10 0 $-2 +2008/11 0 $-2 +2008/12 0 $-2 +``` + +Often, you'll want to see just one line per interval. +The `--depth` option helps with this, causing subaccounts to be aggregated: + +```shell +$ hledger register --monthly assets --depth 1h +2008/01 assets $1 $1 +2008/06 assets $-1 0 +2008/12 assets $-1 $-1 +``` + +Note when using report intervals, if you specify start/end dates these +will be adjusted outward if necessary to contain a whole number of +intervals. This ensures that the first and last intervals are full +length and comparable to the others in the report. + +### Custom register output + +register uses the full terminal width by default, except on windows. +You can override this by setting the `COLUMNS` environment variable (not a bash shell variable) +or by using the `--width`/`-w` option. + +The description and account columns normally share the space equally +(about half of (width - 40) each). You can adjust this by adding a +description width as part of --width's argument, comma-separated: +`--width W,D` . Here's a diagram: +``` +<--------------------------------- width (W) ----------------------------------> +date (10) description (D) account (W-41-D) amount (12) balance (12) +DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA +``` +and some examples: +```shell +$ hledger reg # use terminal width (or 80 on windows) +$ hledger reg -w 100 # use width 100 +$ COLUMNS=100 hledger reg # set with one-time environment variable +$ export COLUMNS=100; hledger reg # set till session end (or window resize) +$ hledger reg -w 100,40 # set overall width 100, description width 40 +$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width +``` + +This command also supports +[output destination](/manual.html#output-destination) and +[output format](/manual.html#output-format) selection. diff --git a/hledger/Hledger/Cli/Commands/Registermatch.hs b/hledger/Hledger/Cli/Commands/Registermatch.hs index 1e8e4d515..fe93da49c 100755 --- a/hledger/Hledger/Cli/Commands/Registermatch.hs +++ b/hledger/Hledger/Cli/Commands/Registermatch.hs @@ -1,5 +1,5 @@ {-# LANGUAGE OverloadedStrings #-} -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Registermatch ( registermatchmode @@ -9,24 +9,17 @@ where import Data.Char (toUpper) import Data.List -import Data.String.Here import qualified Data.Text as T import Hledger import Hledger.Cli.CliOptions import Hledger.Cli.Commands.Register registermatchmode = hledgerCommandMode - [here| register-match -Print the one posting whose transaction description is closest to DESC, -in the style of the register command. -If there are multiple equally good matches, it shows the most recent. -Query options (options, not arguments) can be used to restrict the search space. -Helps ledger-autosync detect already-seen transactions when importing. - |] + ($(hereFileRelative "Hledger/Cli/Commands/Registermatch.md")) [] [generalflagsgroup1] [] - ([], Nothing) + ([], Just $ argsFlag "[QUERY]") registermatch :: CliOpts -> Journal -> IO () registermatch opts@CliOpts{rawopts_=rawopts,reportopts_=ropts} j = do diff --git a/hledger/Hledger/Cli/Commands/Registermatch.md b/hledger/Hledger/Cli/Commands/Registermatch.md new file mode 100644 index 000000000..21fc6de5a --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Registermatch.md @@ -0,0 +1,8 @@ +register-match\ +Print the one posting whose transaction description is closest to DESC, +in the style of the register command. +If there are multiple equally good matches, it shows the most recent. +Query options (options, not arguments) can be used to restrict the search space. +Helps ledger-autosync detect already-seen transactions when importing. + +_FLAGS_ diff --git a/hledger/Hledger/Cli/Commands/Rewrite.hs b/hledger/Hledger/Cli/Commands/Rewrite.hs index 216393bcd..57a1b8487 100755 --- a/hledger/Hledger/Cli/Commands/Rewrite.hs +++ b/hledger/Hledger/Cli/Commands/Rewrite.hs @@ -1,5 +1,6 @@ -{-# LANGUAGE OverloadedStrings, LambdaCase, DeriveTraversable, ViewPatterns, QuasiQuotes #-} +{-# LANGUAGE OverloadedStrings, LambdaCase, DeriveTraversable, ViewPatterns #-} {-# LANGUAGE CPP #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Rewrite ( rewritemode @@ -12,7 +13,6 @@ import Control.Monad.Writer #endif import Data.Functor.Identity import Data.List (sortOn, foldl') -import Data.String.Here import qualified Data.Text as T import Hledger import Hledger.Cli.CliOptions @@ -23,146 +23,7 @@ import Text.Megaparsec import qualified Data.Algorithm.Diff as D rewritemode = hledgerCommandMode - [here| rewrite -Print all transactions, rewriting the postings of matched transactions. -For now the only rewrite available is adding new postings, like print --auto. - -FLAGS - -This is a start at a generic rewriter of transaction entries. -It reads the default journal and prints the transactions, like print, -but adds one or more specified postings to any transactions matching QUERY. -The posting amounts can be fixed, or a multiplier of the existing transaction's first posting amount. - -Examples: -``` -hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' -hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' -hledger-rewrite.hs -f rewrites.hledger -``` -rewrites.hledger may consist of entries like: -``` -= ^income amt:<0 date:2017 - (liabilities:tax) *0.33 ; tax on income - (reserve:grocery) *0.25 ; reserve 25% for grocery - (reserve:) *0.25 ; reserve 25% for grocery -``` -Note the single quotes to protect the dollar sign from bash, -and the two spaces between account and amount. - -More: - -```shell -$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... -$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' -$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' -$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' -``` - -Argument for `--add-posting` option is a usual posting of transaction with an -exception for amount specification. More precisely, you can use `'*'` (star -symbol) before the amount to indicate that that this is a factor for an -amount of original matched posting. If the amount includes a commodity name, -the new posting amount will be in the new commodity; otherwise, it will be in -the matched posting amount's commodity. - -#### Re-write rules in a file - -During the run this tool will execute so called -["Automated Transactions"](http://ledger-cli.org/3.0/doc/ledger3.html#Automated-Transactions) -found in any journal it process. I.e instead of specifying this operations in -command line you can put them in a journal file. - -```shell -$ rewrite-rules.journal -``` - -Make contents look like this: - -```journal -= ^income - (liabilities:tax) *.33 - -= expenses:gifts - budget:gifts *-1 - assets:budget *1 -``` - -Note that `'='` (equality symbol) that is used instead of date in transactions -you usually write. It indicates the query by which you want to match the -posting to add new ones. - -```shell -$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal -``` - -This is something similar to the commands pipeline: - -```shell -$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ - | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ - --add-posting 'assets:budget *1' \ - > rewritten-tidy-output.journal -``` - -It is important to understand that relative order of such entries in journal is -important. You can re-use result of previously added postings. - -#### Diff output format - -To use this tool for batch modification of your journal files you may find -useful output in form of unified diff. - -```shell -$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' -``` - -Output might look like: - -```diff ---- /tmp/examples/sample.journal -+++ /tmp/examples/sample.journal -@@ -18,3 +18,4 @@ - 2008/01/01 income -- assets:bank:checking $1 -+ assets:bank:checking $1 - income:salary -+ (liabilities:tax) 0 -@@ -22,3 +23,4 @@ - 2008/06/01 gift -- assets:bank:checking $1 -+ assets:bank:checking $1 - income:gifts -+ (liabilities:tax) 0 -``` - -If you'll pass this through `patch` tool you'll get transactions containing the -posting that matches your query be updated. Note that multiple files might be -update according to list of input files specified via `--file` options and -`include` directives inside of these files. - -Be careful. Whole transaction being re-formatted in a style of output from -`hledger print`. - -See also: - -https://github.com/simonmichael/hledger/issues/99 - -#### rewrite vs. print --auto - -This command predates print --auto, and currently does much the same thing, -but with these differences: - -- with multiple files, rewrite lets rules in any file affect all other files. - print --auto uses standard directive scoping; rules affect only child files. - -- rewrite's query limits which transactions can be rewritten; all are printed. - print --auto's query limits which transactions are printed. - -- rewrite applies rules specified on command line or in the journal. - print --auto applies rules specified in the journal. - - |] + ($(hereFileRelative "Hledger/Cli/Commands/Rewrite.md")) [flagReq ["add-posting"] (\s opts -> Right $ setopt "add-posting" s opts) "'ACCT AMTEXPR'" "add a posting to ACCT, which may be parenthesised. AMTEXPR is either a literal amount, or *N which means the transaction's first matched amount multiplied by N (a decimal number). Two spaces separate ACCT and AMTEXPR." ,flagNone ["diff"] (setboolopt "diff") "generate diff suitable as an input for patch tool" @@ -170,7 +31,6 @@ but with these differences: [generalflagsgroup1] [] ([], Just $ argsFlag "[QUERY] --add-posting \"ACCT AMTEXPR\" ...") ------------------------------------------------------------------------------- -- TODO regex matching and interpolating matched name in replacement -- TODO interpolating match groups in replacement diff --git a/hledger/Hledger/Cli/Commands/Rewrite.md b/hledger/Hledger/Cli/Commands/Rewrite.md new file mode 100644 index 000000000..6c40cc75f --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Rewrite.md @@ -0,0 +1,138 @@ +rewrite\ +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print --auto. + +_FLAGS_ + +This is a start at a generic rewriter of transaction entries. +It reads the default journal and prints the transactions, like print, +but adds one or more specified postings to any transactions matching QUERY. +The posting amounts can be fixed, or a multiplier of the existing transaction's first posting amount. + +Examples: +``` +hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' +hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' +hledger-rewrite.hs -f rewrites.hledger +``` +rewrites.hledger may consist of entries like: +``` += ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery +``` +Note the single quotes to protect the dollar sign from bash, +and the two spaces between account and amount. + +More: + +```shell +$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... +$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' +$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' +$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' +``` + +Argument for `--add-posting` option is a usual posting of transaction with an +exception for amount specification. More precisely, you can use `'*'` (star +symbol) before the amount to indicate that that this is a factor for an +amount of original matched posting. If the amount includes a commodity name, +the new posting amount will be in the new commodity; otherwise, it will be in +the matched posting amount's commodity. + +#### Re-write rules in a file + +During the run this tool will execute so called +["Automated Transactions"](http://ledger-cli.org/3.0/doc/ledger3.html#Automated-Transactions) +found in any journal it process. I.e instead of specifying this operations in +command line you can put them in a journal file. + +```shell +$ rewrite-rules.journal +``` + +Make contents look like this: + +```journal += ^income + (liabilities:tax) *.33 + += expenses:gifts + budget:gifts *-1 + assets:budget *1 +``` + +Note that `'='` (equality symbol) that is used instead of date in transactions +you usually write. It indicates the query by which you want to match the +posting to add new ones. + +```shell +$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal +``` + +This is something similar to the commands pipeline: + +```shell +$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ + | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ + --add-posting 'assets:budget *1' \ + > rewritten-tidy-output.journal +``` + +It is important to understand that relative order of such entries in journal is +important. You can re-use result of previously added postings. + +#### Diff output format + +To use this tool for batch modification of your journal files you may find +useful output in form of unified diff. + +```shell +$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' +``` + +Output might look like: + +```diff +--- /tmp/examples/sample.journal ++++ /tmp/examples/sample.journal +@@ -18,3 +18,4 @@ + 2008/01/01 income +- assets:bank:checking $1 ++ assets:bank:checking $1 + income:salary ++ (liabilities:tax) 0 +@@ -22,3 +23,4 @@ + 2008/06/01 gift +- assets:bank:checking $1 ++ assets:bank:checking $1 + income:gifts ++ (liabilities:tax) 0 +``` + +If you'll pass this through `patch` tool you'll get transactions containing the +posting that matches your query be updated. Note that multiple files might be +update according to list of input files specified via `--file` options and +`include` directives inside of these files. + +Be careful. Whole transaction being re-formatted in a style of output from +`hledger print`. + +See also: + +https://github.com/simonmichael/hledger/issues/99 + +#### rewrite vs. print --auto + +This command predates print --auto, and currently does much the same thing, +but with these differences: + +- with multiple files, rewrite lets rules in any file affect all other files. + print --auto uses standard directive scoping; rules affect only child files. + +- rewrite's query limits which transactions can be rewritten; all are printed. + print --auto's query limits which transactions are printed. + +- rewrite applies rules specified on command line or in the journal. + print --auto applies rules specified in the journal. diff --git a/hledger/Hledger/Cli/Commands/Roi.hs b/hledger/Hledger/Cli/Commands/Roi.hs index b6a89d913..9ef5c28c7 100644 --- a/hledger/Hledger/Cli/Commands/Roi.hs +++ b/hledger/Hledger/Cli/Commands/Roi.hs @@ -1,4 +1,5 @@ -{-# LANGUAGE QuasiQuotes,ParallelListComp,CPP #-} +{-# LANGUAGE ParallelListComp, CPP #-} +{-# LANGUAGE TemplateHaskell #-} {-| The @roi@ command prints internal rate of return and time-weighted rate of return for and investment. @@ -19,7 +20,6 @@ import Data.List import Data.Ord import Numeric.RootFinding import Data.Decimal -import Data.String.Here import System.Console.CmdArgs.Explicit as CmdArgs import Text.Tabular as Tbl @@ -29,31 +29,17 @@ import Hledger import Hledger.Cli.CliOptions -roimode = (defCommandMode $ ["roi"]) { - modeHelp = "shows return on investment for your portfolio." - ,modeHelpSuffix=lines [here| -This command will show you time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. - -Command assumes that you have account(s) that hold nothing but your investments and whenever you record current appraisal/valuation of these investments you offset unrealized profit and loss into account(s) that, again, hold nothing but unrealized profit and loss. - -Any transactions affecting balance of investment account(s) and not originating from unrealized profit and loss account(s) are assumed to be your investments or withdrawals. - -At a minimum, you need to supply query (which could be just an account name) to select your investments with `--inv`, and another query to identify your profit and loss transactions with `--pnl`. - -Command will compute and display internalized rate of return (IRR) and time-weighted rate of return (TWR) for your investments for the time period requested. Both rates of return are annualized before display, regardless of the length of reporting interval. -|] - ,modeGroupFlags = CmdArgs.Group { - groupUnnamed = [ - flagNone ["cashflow"] (setboolopt "cashflow") "show all amounts that were used to compute returns" - , flagReq ["investment"] (\s opts -> Right $ setopt "investment" s opts) "QUERY" - "query to select your investment transactions" - , flagReq ["profit-loss","pnl"] (\s opts -> Right $ setopt "pnl" s opts) "QUERY" - "query to select profit-and-loss or appreciation/valuation transactions" - ] - , groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } +roimode = hledgerCommandMode + ($(hereFileRelative "Hledger/Cli/Commands/Roi.md")) + [flagNone ["cashflow"] (setboolopt "cashflow") "show all amounts that were used to compute returns" + ,flagReq ["investment"] (\s opts -> Right $ setopt "investment" s opts) "QUERY" + "query to select your investment transactions" + ,flagReq ["profit-loss","pnl"] (\s opts -> Right $ setopt "pnl" s opts) "QUERY" + "query to select profit-and-loss or appreciation/valuation transactions" + ] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") -- One reporting span, data OneSpan = OneSpan diff --git a/hledger/Hledger/Cli/Commands/Roi.md b/hledger/Hledger/Cli/Commands/Roi.md new file mode 100644 index 000000000..df4c63d8a --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Roi.md @@ -0,0 +1,23 @@ +roi\ +Shows the time-weighted (TWR) and money-weighted (IRR) rate of return +on your investments. + +_FLAGS_ + +This command assumes that you have account(s) that hold nothing but +your investments and whenever you record current appraisal/valuation +of these investments you offset unrealized profit and loss into +account(s) that, again, hold nothing but unrealized profit and loss. + +Any transactions affecting balance of investment account(s) and not +originating from unrealized profit and loss account(s) are assumed to +be your investments or withdrawals. + +At a minimum, you need to supply a query (which could be just an +account name) to select your investments with `--inv`, and another +query to identify your profit and loss transactions with `--pnl`. + +It will compute and display the internalized rate of return (IRR) and +time-weighted rate of return (TWR) for your investments for the time +period requested. Both rates of return are annualized before display, +regardless of the length of reporting interval. diff --git a/hledger/Hledger/Cli/Commands/Stats.hs b/hledger/Hledger/Cli/Commands/Stats.hs index 25b4ef1c6..67dff52f3 100644 --- a/hledger/Hledger/Cli/Commands/Stats.hs +++ b/hledger/Hledger/Cli/Commands/Stats.hs @@ -5,6 +5,7 @@ Print some statistics for the journal. -} {-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Stats ( statsmode @@ -29,17 +30,13 @@ import Prelude hiding (putStr) import Hledger.Cli.Utils (writeOutput) -statsmode = (defCommandMode $ ["stats"] ++ aliases) { - modeHelp = "show some journal statistics" `withAliases` aliases - ,modeGroupFlags = Group { - groupUnnamed = [ - flagReq ["output-file","o"] (\s opts -> Right $ setopt "output-file" s opts) "FILE" "write output to FILE. A file extension matching one of the above formats selects that format." - ] - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } - where aliases = [] +statsmode = hledgerCommandMode + ($(hereFileRelative "Hledger/Cli/Commands/Stats.md")) + [flagReq ["output-file","o"] (\s opts -> Right $ setopt "output-file" s opts) "FILE" "write output to FILE. A file extension matching one of the above formats selects that format." + ] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") -- like Register.summarisePostings -- | Print various statistics for the journal. diff --git a/hledger/Hledger/Cli/Commands/Stats.md b/hledger/Hledger/Cli/Commands/Stats.md new file mode 100644 index 000000000..6d5678464 --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Stats.md @@ -0,0 +1,28 @@ +stats\ +Show some journal statistics. + +_FLAGS_ + +The stats command displays summary information for the whole journal, or +a matched part of it. With a [reporting interval](#reporting-interval), +it shows a report for each report period. + +Example: + +```shell +$ hledger stats +Main journal file : /src/hledger/examples/sample.journal +Included journal files : +Transactions span : 2008-01-01 to 2009-01-01 (366 days) +Last transaction : 2008-12-31 (2333 days ago) +Transactions : 5 (0.0 per day) +Transactions last 30 days: 0 (0.0 per day) +Transactions last 7 days : 0 (0.0 per day) +Payees/descriptions : 5 +Accounts : 8 (depth 3) +Commodities : 1 ($) +``` + +This command also supports +[output destination](/manual.html#output-destination) and +[output format](/manual.html#output-format) selection. diff --git a/hledger/Hledger/Cli/Commands/Tags.hs b/hledger/Hledger/Cli/Commands/Tags.hs index 665c93933..62c3df668 100755 --- a/hledger/Hledger/Cli/Commands/Tags.hs +++ b/hledger/Hledger/Cli/Commands/Tags.hs @@ -1,5 +1,5 @@ {-# LANGUAGE OverloadedStrings #-} -{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} module Hledger.Cli.Commands.Tags ( tagsmode @@ -8,20 +8,13 @@ module Hledger.Cli.Commands.Tags ( where import Data.List -import Data.String.Here import qualified Data.Text as T import Safe import Hledger import Hledger.Cli.CliOptions tagsmode = hledgerCommandMode - [here| tags -List all the tag names used in the journal. With a TAGREGEX argument, -only tag names matching the regular expression (case insensitive) are shown. -With QUERY arguments, only transactions matching the query are considered. -Reads the default journal file, or another specified with -f. -FLAGS - |] + ($(hereFileRelative "Hledger/Cli/Commands/Tags.md")) [] -- [flagNone ["strict"] (\opts -> setboolopt "strict" opts) "makes date comparing strict"] -- [generalflagsgroup1] [] diff --git a/hledger/Hledger/Cli/Commands/Tags.md b/hledger/Hledger/Cli/Commands/Tags.md new file mode 100644 index 000000000..72ae78b85 --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Tags.md @@ -0,0 +1,6 @@ +tags\ +List all the tag names used in the journal. With a TAGREGEX argument, +only tag names matching the regular expression (case insensitive) are shown. +With QUERY arguments, only transactions matching the query are considered. + +_FLAGS_ diff --git a/hledger/Hledger/Cli/Commands/Test.md b/hledger/Hledger/Cli/Commands/Test.md new file mode 100644 index 000000000..78111ba92 --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Test.md @@ -0,0 +1,21 @@ +test\ +Run built-in unit tests. + +_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. + +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. + +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 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! diff --git a/hledger/Hledger/Cli/CompoundBalanceCommand.hs b/hledger/Hledger/Cli/CompoundBalanceCommand.hs index 92f6638ce..becb1517b 100644 --- a/hledger/Hledger/Cli/CompoundBalanceCommand.hs +++ b/hledger/Hledger/Cli/CompoundBalanceCommand.hs @@ -41,9 +41,7 @@ import Hledger.Cli.Utils (writeOutput) -- it should be added to or subtracted from the grand total. -- data CompoundBalanceCommandSpec = CompoundBalanceCommandSpec { - cbcname :: String, -- ^ command name - cbcaliases :: [String], -- ^ command aliases - cbchelp :: String, -- ^ command line help + cbcdoc :: CommandDoc, -- ^ the command's name(s) and documentation cbctitle :: String, -- ^ overall report title cbcqueries :: [CBCSubreportSpec], -- ^ subreport details cbctype :: BalanceType -- ^ the "balance" type (change, cumulative, historical) @@ -83,37 +81,35 @@ type CompoundBalanceReport = -- | Generate a cmdargs option-parsing mode from a compound balance command -- specification. compoundBalanceCommandMode :: CompoundBalanceCommandSpec -> Mode RawOpts -compoundBalanceCommandMode CompoundBalanceCommandSpec{..} = (defCommandMode $ cbcname : cbcaliases) { - modeHelp = cbchelp `withAliases` cbcaliases - ,modeGroupFlags = C.Group { - groupUnnamed = [ - flagNone ["change"] (\opts -> setboolopt "change" opts) - ("show balance change in each period" ++ defType PeriodChange) - ,flagNone ["cumulative"] (\opts -> setboolopt "cumulative" opts) - ("show balance change accumulated across periods (in multicolumn reports)" - ++ defType CumulativeChange - ) - ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) - ("show historical ending balance in each period (includes postings before report start date)" - ++ defType HistoricalBalance - ) - ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list" - ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" - ,flagNone ["no-total","N"] (\opts -> setboolopt "no-total" opts) "omit the final total row" - ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show accounts as a tree; amounts include subaccounts (default in simple reports)" - ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) "show a row average column (in multicolumn reports)" - ,flagNone ["row-total","T"] (\opts -> setboolopt "row-total" opts) "show a row total column (in multicolumn reports)" - ,flagNone ["no-elide"] (\opts -> setboolopt "no-elide" opts) "don't squash boring parent accounts (in tree mode)" - ,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)" - ,flagNone ["pretty-tables"] (\opts -> setboolopt "pretty-tables" opts) "use unicode when displaying tables" - ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account code/name" - ,outputFormatFlag - ,outputFileFlag - ] - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } +compoundBalanceCommandMode CompoundBalanceCommandSpec{..} = + hledgerCommandMode + cbcdoc + [flagNone ["change"] (\opts -> setboolopt "change" opts) + ("show balance change in each period" ++ defType PeriodChange) + ,flagNone ["cumulative"] (\opts -> setboolopt "cumulative" opts) + ("show balance change accumulated across periods (in multicolumn reports)" + ++ defType CumulativeChange + ) + ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) + ("show historical ending balance in each period (includes postings before report start date)" + ++ defType HistoricalBalance + ) + ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list" + ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" + ,flagNone ["no-total","N"] (\opts -> setboolopt "no-total" opts) "omit the final total row" + ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show accounts as a tree; amounts include subaccounts (default in simple reports)" + ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) "show a row average column (in multicolumn reports)" + ,flagNone ["row-total","T"] (\opts -> setboolopt "row-total" opts) "show a row total column (in multicolumn reports)" + ,flagNone ["no-elide"] (\opts -> setboolopt "no-elide" opts) "don't squash boring parent accounts (in tree mode)" + ,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)" + ,flagNone ["pretty-tables"] (\opts -> setboolopt "pretty-tables" opts) "use unicode when displaying tables" + ,flagNone ["sort-amount","S"] (\opts -> setboolopt "sort-amount" opts) "sort by amount instead of account code/name" + ,outputFormatFlag + ,outputFileFlag + ] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") where defType :: BalanceType -> String defType bt | bt == cbctype = " (default)" diff --git a/hledger/hledger_commands.m4.md b/hledger/hledger_commands.m4.md index 27ddcfdcb..a26f74b44 100644 --- a/hledger/hledger_commands.m4.md +++ b/hledger/hledger_commands.m4.md @@ -16,13 +16,6 @@ Here are all the builtin commands in alphabetical order. See also `hledger` for a more organised command list, and `hledger CMD -h` for detailed command help. - - ## accounts _include_(Hledger/Cli/Commands/Accounts.md) @@ -40,633 +33,83 @@ _include_(Hledger/Cli/Commands/Add.md) _include_({{Hledger/Cli/Commands/Balance.md}}) ## balancesheet - 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 `liability` - account (case insensitive, plural forms also allowed). - Note this report shows all account balances with normal positive sign - (like conventional financial statements, unlike balance/print/register) - (experimental). (bs) -`--change` -: show balance change in each period, instead of historical ending balances - -`--cumulative` -: show balance change accumulated across periods (in multicolumn reports), instead of historical ending balances - -`-H --historical` -: show historical ending balance in each period (includes postings before report start date) (default) - -`--tree` -: show accounts as a tree; amounts include subaccounts (default in simple reports) - -`--flat` -: show accounts as a list; amounts exclude subaccounts except when account is depth-clipped (default in multicolumn reports) - -`-A --average` -: show a row average column (in multicolumn mode) - -`-T --row-total` -: show a row total column (in multicolumn mode) - -`-N --no-total` -: don't show the final total row - -`--drop=N` -: omit N leading account name parts (in flat mode) - -`--no-elide` -: don't squash boring parent accounts (in tree mode) - -`--format=LINEFORMAT` -: in single-column balance reports: use this custom line format - -`--sort-amount` -: sort by amount instead of account code/name - -Example: -```shell -$ hledger balancesheet -Balance Sheet - -Assets: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Liabilities: - $1 liabilities:debts --------------------- - $1 - -Total: --------------------- - 0 -``` - -With a [reporting interval](#reporting-interval), multiple columns -will be shown, one for each report period. -As with [multicolumn balance reports](#multicolumn-balance-reports), -you can alter the report mode with `--change`/`--cumulative`/`--historical`. -Normally balancesheet shows historical ending balances, which is what -you need for a balance sheet; note this means it ignores report begin -dates. - -This command also supports [output destination](/manual.html#output-destination) and [output format](/manual.html#output-format) selection. +_include_({{Hledger/Cli/Commands/Balancesheet.md}}) ## balancesheetequity -Just like [balancesheet](#balancesheet), but also reports Equity -(which it assumes is under a top-level `equity` account). -Example: -```shell -$ hledger balancesheetequity -Balance Sheet With Equity - -Assets: - $-2 assets - $1 bank:saving - $-3 cash --------------------- - $-2 - -Liabilities: - $1 liabilities:debts --------------------- - $1 - -Equity: - $1 equity:owner --------------------- - $1 - -Total: --------------------- - 0 -``` +_include_({{Hledger/Cli/Commands/Balancesheetequity.md}}) ## cashflow - This command displays a simple cashflow statement, showing changes - in "cash" accounts. It assumes that these accounts are under a top-level - `asset` account (case insensitive, plural forms also allowed) and do not - contain `receivable` or `A/R` in their name. - Note this report shows all account balances with normal positive sign - (like conventional financial statements, unlike balance/print/register) - (experimental). (cf) -`--change` -: show balance change in each period (default) - -`--cumulative` -: show balance change accumulated across periods (in multicolumn reports), instead of changes during periods - -`-H --historical` -: show historical ending balance in each period (includes postings before report start date), instead of changes during each period - -`--tree` -: show accounts as a tree; amounts include subaccounts (default in simple reports) - -`--flat` -: show accounts as a list; amounts exclude subaccounts except when account is depth-clipped (default in multicolumn reports) - -`-A --average` -: show a row average column (in multicolumn mode) - -`-T --row-total` -: show a row total column (in multicolumn mode) - -`-N --no-total` -: don't show the final total row (in simple reports) - -`--drop=N` -: omit N leading account name parts (in flat mode) - -`--no-elide` -: don't squash boring parent accounts (in tree mode) - -`--format=LINEFORMAT` -: in single-column balance reports: use this custom line format - -`--sort-amount` -: sort by amount instead of account code/name - -Example: -```shell -$ hledger cashflow -Cashflow Statement - -Cash flows: - $-1 assets - $1 bank:saving - $-2 cash --------------------- - $-1 - -Total: --------------------- - $-1 -``` - -With a [reporting interval](#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](#multicolumn-balance-reports) -you can alter the report mode with `--change`/`--cumulative`/`--historical`. - -This command also supports [output destination](/manual.html#output-destination) and [output format](/manual.html#output-format) selection. +_include_({{Hledger/Cli/Commands/Cashflow.md}}) ## check-dates -Check that transactions are sorted by increasing date. -With a query, only matched transactions' dates are checked. + +_include_({{Hledger/Cli/Commands/check-Dates.md}}) ## check-dupes -Report account names having the same leaf but different prefixes. -An example: http://stefanorodighiero.net/software/hledger-dupes.html + +_include_({{Hledger/Cli/Commands/check-Dupes.md}}) ## close -_include_(Hledger/Cli/Commands/Close.md) +_include_({{Hledger/Cli/Commands/Close.md}}) ## files -List all files included in the journal. With a REGEX argument, -only file names matching the regular expression (case sensitive) are shown. + +_include_({{Hledger/Cli/Commands/Files.md}}) ## help -Show any of the hledger manuals. -The `help` command displays any of the main [hledger manuals](/docs.html), 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 force a particular viewer with the `--info`, `--man`, `--pager`, `--cat` flags. - -_shell_({{ -$ 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 -}}) - -_shell_({{ -$ hledger help h --man - -hledger(1) hledger User Manuals hledger(1) - -NAME - hledger - a command-line accounting tool - -SYNOPSIS - hledger [-f FILE] COMMAND [OPTIONS] [ARGS] - hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS] - hledger - -DESCRIPTION - hledger is a cross-platform program for tracking money, time, or any -... -}}) +_include_({{Hledger/Cli/Commands/Help.md}}) ## import -Read new transactions added to each FILE since last run, and add them to -the main journal file. -`--dry-run` -: just show the transactions to be imported - -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 journal, it's just: -`hledger import *.csv` - -New transactions are detected in the same way as print --new: -by assuming transactions are always added to the input files in increasing date order, -and by saving `.latest.FILE` state files. - -The --dry-run output is in journal format, so you can filter it, eg -to see only uncategorised transactions: -```shell -$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions -``` +_include_({{Hledger/Cli/Commands/Import.md}}) ## incomestatement - This command displays a simple income statement, showing revenues - and expenses during a period. It assumes that these accounts are under a - top-level `revenue` or `income` or `expense` account (case insensitive, - plural forms also allowed). - Note this report shows all account balances with normal positive sign - (like conventional financial statements, unlike balance/print/register) - (experimental). (is) -`--change` -: show balance change in each period (default) - -`--cumulative` -: show balance change accumulated across periods (in multicolumn reports), instead of changes during periods - -`-H --historical` -: show historical ending balance in each period (includes postings before report start date), instead of changes during each period - -`--tree` -: show accounts as a tree; amounts include subaccounts (default in simple reports) - -`--flat` -: show accounts as a list; amounts exclude subaccounts except when account is depth-clipped (default in multicolumn reports) - -`-A --average` -: show a row average column (in multicolumn mode) - -`-T --row-total` -: show a row total column (in multicolumn mode) - -`-N --no-total` -: don't show the final total row - -`--drop=N` -: omit N leading account name parts (in flat mode) - -`--no-elide` -: don't squash boring parent accounts (in tree mode) - -`--format=LINEFORMAT` -: in single-column balance reports: use this custom line format - -`--sort-amount` -: sort by amount instead of account code/name - -This command displays a simple -[income statement](http://en.wikipedia.org/wiki/Income_statement). It -currently assumes that you have top-level accounts named `income` (or -`revenue`) and `expense` (plural forms also allowed.) - -```shell -$ hledger incomestatement -Income Statement - -Revenues: - $-2 income - $-1 gifts - $-1 salary --------------------- - $-2 - -Expenses: - $2 expenses - $1 food - $1 supplies --------------------- - $2 - -Total: --------------------- - 0 -``` - -With a [reporting interval](#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](#multicolumn-balance-reports) -you can alter the report mode with `--change`/`--cumulative`/`--historical`. - -This command also supports [output destination](/manual.html#output-destination) and [output format](/manual.html#output-format) selection. +_include_({{Hledger/Cli/Commands/Incomestatement.md}}) ## prices -Print [market price directives](/manual#market-prices) from the journal. -With --costs, also print synthetic market prices based on [transaction prices](/manual#transaction-prices). -With --inverted-costs, also print inverse prices based on transaction prices. -Prices (and postings providing prices) can be filtered by a query. + +_include_({{Hledger/Cli/Commands/Prices.md}}) ## print -Show transactions from the journal. Aliases: p, txns. -`-m STR --match=STR ` -: show the transaction whose description is most similar to STR, and is most recent - -` --new` -: show only newer-dated transactions added in each file since last run - -`-x --explicit` -: show all amounts explicitly - -`-O FMT --output-format=FMT ` -: select the output format. Supported formats: -txt, csv. - -`-o FILE --output-file=FILE` -: write output to FILE. A file extension matching one of the above formats selects that format. - -```shell -$ hledger print -2008/01/01 income - assets:bank:checking $1 - income:salary $-1 - -2008/06/01 gift - assets:bank:checking $1 - income:gifts $-1 - -2008/06/02 save - assets:bank:saving $1 - assets:bank:checking $-1 - -2008/06/03 * eat & shop - expenses:food $1 - expenses:supplies $1 - assets:cash $-2 - -2008/12/31 * pay off - liabilities:debts $1 - assets:bank:checking $-1 -``` - -The print command displays full journal entries (transactions) from the journal file in date order, tidily formatted. -print's output is always a valid [hledger journal](/journal.html). -It preserves all transaction information, but it does not preserve directives or inter-transaction comments - -Normally, the journal entry's explicit or implicit amount style is preserved. -Ie when an amount is omitted in the journal, it will be omitted in the output. -You can use the `-x`/`--explicit` flag to make all amounts explicit, which can be -useful for troubleshooting or for making your journal more readable and -robust against data entry errors. -Note, `-x` will cause postings with a multi-commodity amount -(these can arise when a multi-commodity transaction has an implicit amount) -will be split into multiple single-commodity postings, for valid journal output. - -With `-B`/`--cost`, amounts with [transaction prices](/journal.html#transaction-prices) -are converted to cost using that price. This can be used for troubleshooting. - -With `-m`/`--match` and a STR argument, print will show at most one transaction: the one -one whose description is most similar to STR, and is most recent. STR should contain at -least two characters. If there is no similar-enough match, no transaction will be shown. - -With `--new`, for each FILE being read, hledger reads (and writes) a special -state file (`.latest.FILE` in the same directory), containing the latest transaction date(s) -that were seen last time FILE was read. When this file is found, only transactions -with newer dates (and new transactions on the latest date) are printed. -This is useful for ignoring already-seen entries in import data, such as downloaded CSV files. -Eg: -```console -$ hledger -f bank1.csv print --new -# shows transactions added since last print --new on this file -``` -This assumes that transactions added to FILE always have same or increasing dates, -and that transactions on the same day do not get reordered. -See also the [import](#import) command. - -This command also supports [output destination](/manual.html#output-destination) and [output format](/manual.html#output-format) selection. -Here's an example of print's CSV output: -```shell -$ hledger print -Ocsv -"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" -"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" -"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" -"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" -"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" -"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" -"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" -"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" -"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" -"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" -"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" -"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" -``` -- There is one CSV record per posting, with the parent transaction's fields repeated. -- The "txnidx" (transaction index) field shows which postings belong to the same transaction. - (This number might change if transactions are reordered within the file, - files are parsed/included in a different order, etc.) -- The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. -- The numeric amount is repeated in either the "credit" or "debit" column, for convenience. - (Those names are not accurate in the accounting sense; it just puts negative amounts under - credit and zero or greater amounts under debit.) +_include_({{Hledger/Cli/Commands/Print.md}}) ## print-unique -Print transactions which do not reuse an already-seen description. + +_include_({{Hledger/Cli/Commands/print-Unique.md}}) ## register -Show postings and their running total. Aliases: r, reg. -`--cumulative` -: show running total from report start date (default) - -`-H --historical` -: show historical running total/balance (includes postings before report start date) - -`-A --average` -: show running average of posting amounts instead of total (implies --empty) - -`-r --related` -: show postings' siblings instead - -`-w N --width=N` -: set output width (default: terminal width or COLUMNS. -wN,M sets description width as well) - -`-O FMT --output-format=FMT ` -: select the output format. Supported formats: -txt, csv. - -`-o FILE --output-file=FILE` -: write output to FILE. A file extension matching one of the above formats selects that format. - -The register command displays postings, one per line, and their -running total. This is typically used with a [query](#queries) -selecting a particular account, to see that account's activity: - -```shell -$ hledger register checking -2008/01/01 income assets:bank:checking $1 $1 -2008/06/01 gift assets:bank:checking $1 $2 -2008/06/02 save assets:bank:checking $-1 $1 -2008/12/31 pay off assets:bank:checking $-1 0 -``` - -The `--historical`/`-H` flag adds the balance from any undisplayed -prior postings to the running total. This is useful when you want to -see only recent activity, with a historically accurate running balance: - -```shell -$ hledger register checking -b 2008/6 --historical -2008/06/01 gift assets:bank:checking $1 $2 -2008/06/02 save assets:bank:checking $-1 $1 -2008/12/31 pay off assets:bank:checking $-1 0 -``` - -The `--depth` option limits the amount of sub-account detail displayed. - -The `--average`/`-A` flag shows the running average posting amount -instead of the running total (so, the final number displayed is the -average for the whole report period). This flag implies `--empty` (see below). -It is affected by `--historical`. -It works best when showing just one account and one commodity. - -The `--related`/`-r` flag shows the *other* postings in the transactions -of the postings which would normally be shown. - -With a [reporting interval](#reporting-interval), register shows -summary postings, one per interval, aggregating the postings to each account: - -```shell -$ hledger register --monthly income -2008/01 income:salary $-1 $-1 -2008/06 income:gifts $-1 $-2 -``` -Periods with no activity, and summary postings with a zero amount, are -not shown by default; use the `--empty`/`-E` flag to see them: - -```shell -$ hledger register --monthly income -E -2008/01 income:salary $-1 $-1 -2008/02 0 $-1 -2008/03 0 $-1 -2008/04 0 $-1 -2008/05 0 $-1 -2008/06 income:gifts $-1 $-2 -2008/07 0 $-2 -2008/08 0 $-2 -2008/09 0 $-2 -2008/10 0 $-2 -2008/11 0 $-2 -2008/12 0 $-2 -``` - -Often, you'll want to see just one line per interval. -The `--depth` option helps with this, causing subaccounts to be aggregated: - -```shell -$ hledger register --monthly assets --depth 1h -2008/01 assets $1 $1 -2008/06 assets $-1 0 -2008/12 assets $-1 $-1 -``` - -Note when using report intervals, if you specify start/end dates these -will be adjusted outward if necessary to contain a whole number of -intervals. This ensures that the first and last intervals are full -length and comparable to the others in the report. - -### Custom register output - -register uses the full terminal width by default, except on windows. -You can override this by setting the `COLUMNS` environment variable (not a bash shell variable) -or by using the `--width`/`-w` option. - -The description and account columns normally share the space equally -(about half of (width - 40) each). You can adjust this by adding a -description width as part of --width's argument, comma-separated: -`--width W,D` . Here's a diagram: -``` -<--------------------------------- width (W) ----------------------------------> -date (10) description (D) account (W-41-D) amount (12) balance (12) -DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA -``` -and some examples: -```shell -$ hledger reg # use terminal width (or 80 on windows) -$ hledger reg -w 100 # use width 100 -$ COLUMNS=100 hledger reg # set with one-time environment variable -$ export COLUMNS=100; hledger reg # set till session end (or window resize) -$ hledger reg -w 100,40 # set overall width 100, description width 40 -$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width -``` - -This command also supports [output destination](/manual.html#output-destination) and [output format](/manual.html#output-format) selection. +_include_({{Hledger/Cli/Commands/Register.md}}) ## register-match -Print the one posting whose transaction description is closest to DESC, -in the style of the register command. -Helps ledger-autosync detect already-seen transactions when importing. + +_include_({{Hledger/Cli/Commands/register-Match.md}}) ## rewrite -Print all transactions, adding custom postings to the matched ones. + +_include_({{Hledger/Cli/Commands/Rewrite.md}}) ## roi -Shows time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. -See `roi --help` for more. + +_include_({{Hledger/Cli/Commands/Roi.md}}) ## stats -Show some journal statistics. -`-o FILE --output-file=FILE` -: write output to FILE. A file extension matching one of the above formats selects that format. - -```shell -$ hledger stats -Main journal file : /src/hledger/examples/sample.journal -Included journal files : -Transactions span : 2008-01-01 to 2009-01-01 (366 days) -Last transaction : 2008-12-31 (2333 days ago) -Transactions : 5 (0.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 5 -Accounts : 8 (depth 3) -Commodities : 1 ($) -``` - -The stats command displays summary information for the whole journal, or -a matched part of it. With a [reporting interval](#reporting-interval), -it shows a report for each report period. - -This command also supports [output destination](/manual.html#output-destination) and [output format](/manual.html#output-format) selection. +_include_({{Hledger/Cli/Commands/Stats.md}}) ## tags -List all the tag names used in the journal. With a TAGREGEX argument, -only tag names matching the regular expression (case insensitive) are shown. -With additional QUERY arguments, only transactions matching the query are considered. + +_include_({{Hledger/Cli/Commands/Tags.md}}) ## test -Run built-in unit tests. -Prints test names and their results on stdout. -If any test fails or gives an error, 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. - -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 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! +_include_({{Hledger/Cli/Commands/Test.md}}) _include_(hledger_addons.m4.md)