slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: integrate CLI help & manual for remaining commands

Browse Source 
& rename HelpTemplate -> CommandDoc
This commit is contained in:
Simon Michael 2019-01-28 05:43:49 -08:00
parent 6566ef5fa2
commit 4ee39e039b
41 changed files with 874 additions and 1030 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
hledger/Hledger/Cli/CliOptions.hs
View File

@ -40,6 +40,7 @@ module Hledger.Cli.CliOptions (
outputFormats, outputFormats,
defaultOutputFormat, defaultOutputFormat,
defaultBalanceLineFormat, defaultBalanceLineFormat,
CommandDoc,
-- possibly these should move into argsToCliOpts -- possibly these should move into argsToCliOpts
-- * CLI option accessors -- * 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, -- | Build a cmdarg mode for a hledger command,
-- from a help template and flag/argument specifications. -- from a help template and flag/argument specifications.
-- Reduces boilerplate a little, though the complicated cmdargs -- Reduces boilerplate a little, though the complicated cmdargs
-- flag and argument specs are still required. -- 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 -> [Flag RawOpts] -> ([Arg RawOpts], Maybe (Arg RawOpts)) -> Mode RawOpts
hledgerCommandMode tmpl unnamedflaggroup namedflaggroups hiddenflaggroup argsdescr = hledgerCommandMode tmpl unnamedflaggroup namedflaggroups hiddenflaggroup argsdescr =
case parseHelpTemplate tmpl of case parseCommandDoc tmpl of
Nothing -> error' $ "Could not parse help template:\n"++tmpl++"\n" Nothing -> error' $ "Could not parse help template:\n"++tmpl++"\n"
Just (names, shorthelp, longhelplines) -> Just (names, shorthelp, longhelplines) ->
(defCommandMode names) { (defCommandMode names) {
@ -256,10 +261,6 @@ hledgerCommandMode tmpl unnamedflaggroup namedflaggroups hiddenflaggroup argsdes
,modeArgs = argsdescr ,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: -- | Parse a command's documentation, as follows:
-- --
-- - First line: the command name then any aliases, as one or more space or comma-separated words -- - 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 -- optional again). The manual displays the short help followed by
-- the long help, with no flags list. -- the long help, with no flags list.
-- --
parseHelpTemplate :: HelpTemplate -> Maybe ([Name], String, [String]) parseCommandDoc :: CommandDoc -> Maybe ([Name], String, [String])
parseHelpTemplate t = parseCommandDoc t =
case lines t of case lines t of
[] -> Nothing [] -> Nothing
(l:ls) -> Just (names, shorthelp, longhelplines) (l:ls) -> Just (names, shorthelp, longhelplines)

14
hledger/Hledger/Cli/Commands.hs
View File

@ -5,6 +5,7 @@ hledger's built-in commands, and helpers for printing the commands list.
{-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE QuasiQuotes #-}
{-# LANGUAGE CPP #-} {-# LANGUAGE CPP #-}
{-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands ( module Hledger.Cli.Commands (
findCommand findCommand
@ -222,18 +223,7 @@ commandsFromCommandsList s =
-- The test command, defined here for easy access to other modules' tests. -- The test command, defined here for easy access to other modules' tests.
testmode = hledgerCommandMode testmode = hledgerCommandMode
[here| test $(hereFileRelative "Hledger/Cli/Commands/Test.md")
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
|]
[] []
[generalflagsgroup3] [generalflagsgroup3]
[] []

17
hledger/Hledger/Cli/Commands/Balancesheet.hs
View File

@ -1,4 +1,5 @@
{-# LANGUAGE QuasiQuotes, RecordWildCards #-} {-# LANGUAGE RecordWildCards #-}
{-# LANGUAGE TemplateHaskell #-}
{-| {-|
The @balancesheet@ command prints a simple balance sheet. The @balancesheet@ command prints a simple balance sheet.
@ -10,7 +11,6 @@ module Hledger.Cli.Commands.Balancesheet (
,balancesheet ,balancesheet
) where ) where
import Data.String.Here
import System.Console.CmdArgs.Explicit import System.Console.CmdArgs.Explicit
import Hledger import Hledger
@ -18,18 +18,7 @@ import Hledger.Cli.CliOptions
import Hledger.Cli.CompoundBalanceCommand import Hledger.Cli.CompoundBalanceCommand
balancesheetSpec = CompoundBalanceCommandSpec { balancesheetSpec = CompoundBalanceCommandSpec {
cbcname = "balancesheet", cbcdoc = ($(hereFileRelative "Hledger/Cli/Commands/Balancesheet.md")),
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).
|],
cbctitle = "Balance Sheet", cbctitle = "Balance Sheet",
cbcqueries = [ cbcqueries = [
CBCSubreportSpec{ CBCSubreportSpec{

46
hledger/Hledger/Cli/Commands/Balancesheet.md Normal file
View File

@ -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.

14
hledger/Hledger/Cli/Commands/Balancesheetequity.hs
View File

@ -1,4 +1,5 @@
{-# LANGUAGE QuasiQuotes, RecordWildCards #-} {-# LANGUAGE QuasiQuotes, RecordWildCards #-}
{-# LANGUAGE TemplateHaskell #-}
{-| {-|
The @balancesheetequity@ command prints a simple balance sheet. The @balancesheetequity@ command prints a simple balance sheet.
@ -10,7 +11,6 @@ module Hledger.Cli.Commands.Balancesheetequity (
,balancesheetequity ,balancesheetequity
) where ) where
import Data.String.Here
import System.Console.CmdArgs.Explicit import System.Console.CmdArgs.Explicit
import Hledger import Hledger
@ -18,17 +18,7 @@ import Hledger.Cli.CliOptions
import Hledger.Cli.CompoundBalanceCommand import Hledger.Cli.CompoundBalanceCommand
balancesheetequitySpec = CompoundBalanceCommandSpec { balancesheetequitySpec = CompoundBalanceCommandSpec {
cbcname = "balancesheetequity", cbcdoc = ($(hereFileRelative "Hledger/Cli/Commands/Balancesheetequity.md")),
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).
|],
cbctitle = "Balance Sheet With Equity", cbctitle = "Balance Sheet With Equity",
cbcqueries = [ cbcqueries = [
CBCSubreportSpec{ CBCSubreportSpec{

32
hledger/Hledger/Cli/Commands/Balancesheetequity.md Normal file
View File

@ -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
```

15
hledger/Hledger/Cli/Commands/Cashflow.hs
View File

@ -1,4 +1,5 @@
{-# LANGUAGE QuasiQuotes, RecordWildCards #-} {-# LANGUAGE QuasiQuotes, RecordWildCards #-}
{-# LANGUAGE TemplateHaskell #-}
{-| {-|
The @cashflow@ command prints a simplified cashflow statement. It just The @cashflow@ command prints a simplified cashflow statement. It just
@ -13,7 +14,6 @@ module Hledger.Cli.Commands.Cashflow (
,cashflow ,cashflow
) where ) where
import Data.String.Here
import System.Console.CmdArgs.Explicit import System.Console.CmdArgs.Explicit
import Hledger import Hledger
@ -21,18 +21,7 @@ import Hledger.Cli.CliOptions
import Hledger.Cli.CompoundBalanceCommand import Hledger.Cli.CompoundBalanceCommand
cashflowSpec = CompoundBalanceCommandSpec { cashflowSpec = CompoundBalanceCommandSpec {
cbcname = "cashflow", cbcdoc = ($(hereFileRelative "Hledger/Cli/Commands/Cashflow.md")),
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).
|],
cbctitle = "Cashflow Statement", cbctitle = "Cashflow Statement",
cbcqueries = [ cbcqueries = [
CBCSubreportSpec{ CBCSubreportSpec{

37
hledger/Hledger/Cli/Commands/Cashflow.md Normal file
View File

@ -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.

14
hledger/Hledger/Cli/Commands/Checkdates.hs
View File

@ -1,27 +1,19 @@
{-# LANGUAGE QuasiQuotes #-}
{-# LANGUAGE NoOverloadedStrings #-} -- prevent trouble if turned on in ghci {-# LANGUAGE NoOverloadedStrings #-} -- prevent trouble if turned on in ghci
{-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Checkdates ( module Hledger.Cli.Commands.Checkdates (
checkdatesmode checkdatesmode
,checkdates ,checkdates
) where ) where
import Data.String.Here
import Hledger import Hledger
import Hledger.Cli.CliOptions import Hledger.Cli.CliOptions
import System.Console.CmdArgs.Explicit import System.Console.CmdArgs.Explicit
import Text.Printf import Text.Printf
-- checkdatesmode :: Mode RawOpts checkdatesmode :: Mode RawOpts
checkdatesmode = hledgerCommandMode checkdatesmode = hledgerCommandMode
[here| check-dates ($(hereFileRelative "Hledger/Cli/Commands/Checkdates.md"))
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
|]
[flagNone ["strict"] (\opts -> setboolopt "strict" opts) "makes date comparing strict"] [flagNone ["strict"] (\opts -> setboolopt "strict" opts) "makes date comparing strict"]
[generalflagsgroup1] [generalflagsgroup1]
[] []

8
hledger/Hledger/Cli/Commands/Checkdates.md Normal file
View File

@ -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_

10
hledger/Hledger/Cli/Commands/Checkdupes.hs
View File

@ -1,4 +1,4 @@
{-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Checkdupes ( module Hledger.Cli.Commands.Checkdupes (
checkdupesmode checkdupesmode
@ -8,7 +8,6 @@ where
import Data.Function import Data.Function
import Data.List import Data.List
import Data.String.Here
import qualified Data.Text as T import qualified Data.Text as T
import Hledger import Hledger
import Hledger.Cli.CliOptions import Hledger.Cli.CliOptions
@ -17,12 +16,7 @@ import Text.Printf
checkdupesmode :: Mode RawOpts checkdupesmode :: Mode RawOpts
checkdupesmode = hledgerCommandMode checkdupesmode = hledgerCommandMode
[here| check-dupes ($(hereFileRelative "Hledger/Cli/Commands/Checkdupes.md"))
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
|]
[] []
[generalflagsgroup1] [generalflagsgroup1]
[] []

8
hledger/Hledger/Cli/Commands/Checkdupes.md Normal file
View File

@ -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

22
hledger/Hledger/Cli/Commands/Files.hs
View File

@ -5,6 +5,7 @@ The @files@ command lists included files.
-} -}
{-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Files ( module Hledger.Cli.Commands.Files (
filesmode filesmode
@ -12,9 +13,7 @@ module Hledger.Cli.Commands.Files (
) where ) where
import Data.List import Data.List
-- import Data.Text (Text)
import Safe import Safe
import System.Console.CmdArgs.Explicit as C
import Hledger import Hledger
import Prelude hiding (putStrLn) import Prelude hiding (putStrLn)
@ -23,19 +22,12 @@ import Hledger.Cli.CliOptions
-- | Command line options for this command. -- | Command line options for this command.
filesmode = (defCommandMode $ ["files"] ) { filesmode = hledgerCommandMode
modeHelp = "show names of included files" ($(hereFileRelative "Hledger/Cli/Commands/Files.md"))
,modeHelpSuffix = [ []
"This command lists names of all files included in the parsed journal(s)." [generalflagsgroup2]
,"With REGEX argument will list only files matching regular expression (case sensitive)." []
] ([], Just $ argsFlag "[REGEX]")
,modeGroupFlags = C.Group {
groupUnnamed = []
,groupHidden = []
,groupNamed = [generalflagsgroup2]
}
,modeArgs= ([], Just $ argsFlag "[REGEX]")
}
-- | The files command. -- | The files command.
files :: CliOpts -> Journal -> IO () files :: CliOpts -> Journal -> IO ()

5
hledger/Hledger/Cli/Commands/Files.md Normal file
View File

@ -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_

23
hledger/Hledger/Cli/Commands/Help.hs
View File

@ -6,8 +6,9 @@ The help command.
--TODO rename manuals --TODO rename manuals
--TODO substring matching --TODO substring matching
{-# LANGUAGE QuasiQuotes #-}
{-# LANGUAGE PackageImports #-} {-# LANGUAGE PackageImports #-}
{-# LANGUAGE QuasiQuotes #-}
{-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Help ( module Hledger.Cli.Commands.Help (
@ -19,36 +20,32 @@ module Hledger.Cli.Commands.Help (
import Prelude () import Prelude ()
import "base-compat-batteries" Prelude.Compat import "base-compat-batteries" Prelude.Compat
import Data.Char import Data.Char
import Data.String.Here
import Data.List import Data.List
import Data.Maybe import Data.Maybe
import Data.String.Here
import Safe import Safe
import System.Console.CmdArgs.Explicit import System.Console.CmdArgs.Explicit
import System.Environment import System.Environment
import System.IO import System.IO
import Hledger.Utils (hereFileRelative)
import Hledger.Data.RawOptions import Hledger.Data.RawOptions
import Hledger.Data.Types import Hledger.Data.Types
import Hledger.Cli.CliOptions import Hledger.Cli.CliOptions
import Hledger.Cli.DocFiles import Hledger.Cli.DocFiles
--import Hledger.Utils.Debug --import Hledger.Utils.Debug
helpmode = (defCommandMode $ ["help"] ++ aliases) { helpmode = hledgerCommandMode
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 ($(hereFileRelative "Hledger/Cli/Commands/Help.md"))
,modeGroupFlags = Group { [flagNone ["info"] (setboolopt "info") "show the manual with info"
groupUnnamed = [
flagNone ["info"] (setboolopt "info") "show the manual with info"
,flagNone ["man"] (setboolopt "man") "show the manual with man" ,flagNone ["man"] (setboolopt "man") "show the manual with man"
,flagNone ["pager"] (setboolopt "pager") "show the manual with $PAGER or less" ,flagNone ["pager"] (setboolopt "pager") "show the manual with $PAGER or less"
,flagNone ["cat"] (setboolopt "cat") "show the manual on stdout" ,flagNone ["cat"] (setboolopt "cat") "show the manual on stdout"
,flagNone ["help","h"] (setboolopt "help") "show this help" ,flagNone ["help","h"] (setboolopt "help") "show this help"
] ]
,groupHidden = [] []
,groupNamed = [] []
} ([], Just $ argsFlag "[MANUAL]")
,modeArgs = ([], Just $ argsFlag "[MANUAL]")
}
where aliases = []
-- | List or display one of the hledger manuals in various formats. -- | 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. -- You can select a docs viewer with one of the `--info`, `--man`, `--pager`, `--cat` flags.

38
hledger/Hledger/Cli/Commands/Help.md Normal file
View File

@ -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
...
```

16
hledger/Hledger/Cli/Commands/Import.hs
View File

@ -1,5 +1,5 @@
{-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Import ( module Hledger.Cli.Commands.Import (
importmode importmode
@ -10,7 +10,6 @@ where
import Control.Monad import Control.Monad
import Data.List import Data.List
import Data.Ord import Data.Ord
import Data.String.Here
import Hledger import Hledger
import Hledger.Cli.CliOptions import Hledger.Cli.CliOptions
import Hledger.Cli.Commands.Add (journalAddTransaction) import Hledger.Cli.Commands.Add (journalAddTransaction)
@ -19,18 +18,7 @@ import System.Console.CmdArgs.Explicit
import Text.Printf import Text.Printf
importmode = hledgerCommandMode importmode = hledgerCommandMode
[here| import ($(hereFileRelative "Hledger/Cli/Commands/Import.md"))
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
|]
[flagNone ["dry-run"] (\opts -> setboolopt "dry-run" opts) "just show the transactions to be imported"] [flagNone ["dry-run"] (\opts -> setboolopt "dry-run" opts) "just show the transactions to be imported"]
[generalflagsgroup1] [generalflagsgroup1]
[] []

21
hledger/Hledger/Cli/Commands/Import.md Normal file
View File

@ -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
```

14
hledger/Hledger/Cli/Commands/Incomestatement.hs
View File

@ -10,7 +10,6 @@ module Hledger.Cli.Commands.Incomestatement (
,incomestatement ,incomestatement
) where ) where
import Data.String.Here
import System.Console.CmdArgs.Explicit import System.Console.CmdArgs.Explicit
import Hledger import Hledger
@ -18,18 +17,7 @@ import Hledger.Cli.CliOptions
import Hledger.Cli.CompoundBalanceCommand import Hledger.Cli.CompoundBalanceCommand
incomestatementSpec = CompoundBalanceCommandSpec { incomestatementSpec = CompoundBalanceCommandSpec {
cbcname = "incomestatement", cbcdoc = ($(hereFileRelative "Hledger/Cli/Commands/Incomestatement.md")),
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).
|],
cbctitle = "Income Statement", cbctitle = "Income Statement",
cbcqueries = [ cbcqueries = [
CBCSubreportSpec{ CBCSubreportSpec{

48
hledger/Hledger/Cli/Commands/Incomestatement.md Normal file
View File

@ -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.

10
hledger/Hledger/Cli/Commands/Prices.hs
View File

@ -1,4 +1,4 @@
{-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Prices ( module Hledger.Cli.Commands.Prices (
pricesmode pricesmode
@ -8,7 +8,6 @@ where
import Data.Maybe import Data.Maybe
import Data.List import Data.List
import Data.String.Here
import qualified Data.Text as T import qualified Data.Text as T
import Data.Time import Data.Time
import Hledger import Hledger
@ -16,12 +15,7 @@ import Hledger.Cli.CliOptions
import System.Console.CmdArgs.Explicit import System.Console.CmdArgs.Explicit
pricesmode = hledgerCommandMode pricesmode = hledgerCommandMode
[here| prices ($(hereFileRelative "Hledger/Cli/Commands/Prices.md"))
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.
|]
[flagNone ["costs"] (setboolopt "costs") "print transaction prices from postings" [flagNone ["costs"] (setboolopt "costs") "print transaction prices from postings"
,flagNone ["inverted-costs"] (setboolopt "inverted-costs") "print transaction inverted prices from postings also"] ,flagNone ["inverted-costs"] (setboolopt "inverted-costs") "print transaction inverted prices from postings also"]
[generalflagsgroup1] [generalflagsgroup1]

7
hledger/Hledger/Cli/Commands/Prices.md Normal file
View File

@ -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_

18
hledger/Hledger/Cli/Commands/Print.hs
View File

@ -5,6 +5,7 @@ A ledger-compatible @print@ command.
-} -}
{-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Print ( module Hledger.Cli.Commands.Print (
printmode printmode
@ -25,11 +26,9 @@ import Hledger.Cli.Utils
import Hledger.Cli.Commands.Add ( transactionsSimilarTo ) import Hledger.Cli.Commands.Add ( transactionsSimilarTo )
printmode = (defCommandMode $ ["print"] ++ aliases) { printmode = hledgerCommandMode
modeHelp = "show transaction journal entries, sorted by date. With --date2, sort by secondary date instead." `withAliases` aliases ($(hereFileRelative "Hledger/Cli/Commands/Print.md"))
,modeGroupFlags = Group { [let arg = "STR" in
groupUnnamed = [
let arg = "STR" in
flagReq ["match","m"] (\s opts -> Right $ setopt "match" s opts) arg 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") ("show the transaction whose description is most similar to "++arg++", and is most recent")
,flagNone ["explicit","x"] (setboolopt "explicit") ,flagNone ["explicit","x"] (setboolopt "explicit")
@ -37,12 +36,9 @@ printmode = (defCommandMode $ ["print"] ++ aliases) {
,flagNone ["new"] (setboolopt "new") ,flagNone ["new"] (setboolopt "new")
"show only newer-dated transactions added in each file since last run" "show only newer-dated transactions added in each file since last run"
] ]
++ outputflags [generalflagsgroup1]
,groupHidden = [] []
,groupNamed = [generalflagsgroup1] ([], Just $ argsFlag "[QUERY]")
}
}
where aliases = ["p","txns"]
-- | Print journal transactions in standard format. -- | Print journal transactions in standard format.
print' :: CliOpts -> Journal -> IO () print' :: CliOpts -> Journal -> IO ()

96
hledger/Hledger/Cli/Commands/Print.md Normal file
View File

@ -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.)

24
hledger/Hledger/Cli/Commands/Printunique.hs
View File

@ -1,6 +1,4 @@
{-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE TemplateHaskell #-}
{-# LANGUAGE QuasiQuotes #-}
module Hledger.Cli.Commands.Printunique ( module Hledger.Cli.Commands.Printunique (
printuniquemode printuniquemode
@ -10,30 +8,12 @@ where
import Data.List import Data.List
import Data.Ord import Data.Ord
import Data.String.Here
import Hledger import Hledger
import Hledger.Cli.CliOptions import Hledger.Cli.CliOptions
import Hledger.Cli.Commands.Print import Hledger.Cli.Commands.Print
printuniquemode = hledgerCommandMode printuniquemode = hledgerCommandMode
[here| print-unique ($(hereFileRelative "Hledger/Cli/Commands/Printunique.md"))
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
```
|]
[] []
[generalflagsgroup1] [generalflagsgroup1]
[] []

18
hledger/Hledger/Cli/Commands/Printunique.md Normal file
View File

@ -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
```

18
hledger/Hledger/Cli/Commands/Register.hs
View File

@ -5,6 +5,7 @@ A ledger-compatible @register@ command.
-} -}
{-# LANGUAGE CPP, OverloadedStrings #-} {-# LANGUAGE CPP, OverloadedStrings #-}
{-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Register ( module Hledger.Cli.Commands.Register (
registermode registermode
@ -26,11 +27,9 @@ import Hledger
import Hledger.Cli.CliOptions import Hledger.Cli.CliOptions
import Hledger.Cli.Utils import Hledger.Cli.Utils
registermode = (defCommandMode $ ["register"] ++ aliases) { registermode = hledgerCommandMode
modeHelp = "show postings and running total. With --date2, show and sort by secondary date instead." `withAliases` aliases ($(hereFileRelative "Hledger/Cli/Commands/Register.md"))
,modeGroupFlags = Group { [flagNone ["cumulative"] (\opts -> setboolopt "change" opts)
groupUnnamed = [
flagNone ["cumulative"] (\opts -> setboolopt "change" opts)
"show running total from report start date (default)" "show running total from report start date (default)"
,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts)
"show historical running total/balance (includes postings before report start date)\n " "show historical running total/balance (includes postings before report start date)\n "
@ -47,12 +46,9 @@ registermode = (defCommandMode $ ["register"] ++ aliases) {
++ " or $COLUMNS). -wN,M sets description width as well." ++ " or $COLUMNS). -wN,M sets description width as well."
) )
] ]
++ outputflags [generalflagsgroup1]
,groupHidden = [] []
,groupNamed = [generalflagsgroup1] ([], Just $ argsFlag "[QUERY]")
}
}
where aliases = ["r","reg"]
-- | Print a (posting) register report. -- | Print a (posting) register report.
register :: CliOpts -> Journal -> IO () register :: CliOpts -> Journal -> IO ()

112
hledger/Hledger/Cli/Commands/Register.md Normal file
View File

@ -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.

13
hledger/Hledger/Cli/Commands/Registermatch.hs
View File

@ -1,5 +1,5 @@
{-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Registermatch ( module Hledger.Cli.Commands.Registermatch (
registermatchmode registermatchmode
@ -9,24 +9,17 @@ where
import Data.Char (toUpper) import Data.Char (toUpper)
import Data.List import Data.List
import Data.String.Here
import qualified Data.Text as T import qualified Data.Text as T
import Hledger import Hledger
import Hledger.Cli.CliOptions import Hledger.Cli.CliOptions
import Hledger.Cli.Commands.Register import Hledger.Cli.Commands.Register
registermatchmode = hledgerCommandMode registermatchmode = hledgerCommandMode
[here| register-match ($(hereFileRelative "Hledger/Cli/Commands/Registermatch.md"))
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.
|]
[] []
[generalflagsgroup1] [generalflagsgroup1]
[] []
([], Nothing) ([], Just $ argsFlag "[QUERY]")
registermatch :: CliOpts -> Journal -> IO () registermatch :: CliOpts -> Journal -> IO ()
registermatch opts@CliOpts{rawopts_=rawopts,reportopts_=ropts} j = do registermatch opts@CliOpts{rawopts_=rawopts,reportopts_=ropts} j = do

8
hledger/Hledger/Cli/Commands/Registermatch.md Normal file
View File

@ -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_

146
hledger/Hledger/Cli/Commands/Rewrite.hs
View File

@ -1,5 +1,6 @@
{-# LANGUAGE OverloadedStrings, LambdaCase, DeriveTraversable, ViewPatterns, QuasiQuotes #-} {-# LANGUAGE OverloadedStrings, LambdaCase, DeriveTraversable, ViewPatterns #-}
{-# LANGUAGE CPP #-} {-# LANGUAGE CPP #-}
{-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Rewrite ( module Hledger.Cli.Commands.Rewrite (
rewritemode rewritemode
@ -12,7 +13,6 @@ import Control.Monad.Writer
#endif #endif
import Data.Functor.Identity import Data.Functor.Identity
import Data.List (sortOn, foldl') import Data.List (sortOn, foldl')
import Data.String.Here
import qualified Data.Text as T import qualified Data.Text as T
import Hledger import Hledger
import Hledger.Cli.CliOptions import Hledger.Cli.CliOptions
@ -23,146 +23,7 @@ import Text.Megaparsec
import qualified Data.Algorithm.Diff as D import qualified Data.Algorithm.Diff as D
rewritemode = hledgerCommandMode rewritemode = hledgerCommandMode
[here| rewrite ($(hereFileRelative "Hledger/Cli/Commands/Rewrite.md"))
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.
|]
[flagReq ["add-posting"] (\s opts -> Right $ setopt "add-posting" s opts) "'ACCT AMTEXPR'" [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." "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" ,flagNone ["diff"] (setboolopt "diff") "generate diff suitable as an input for patch tool"
@ -170,7 +31,6 @@ but with these differences:
[generalflagsgroup1] [generalflagsgroup1]
[] []
([], Just $ argsFlag "[QUERY] --add-posting \"ACCT AMTEXPR\" ...") ([], Just $ argsFlag "[QUERY] --add-posting \"ACCT AMTEXPR\" ...")
------------------------------------------------------------------------------
-- TODO regex matching and interpolating matched name in replacement -- TODO regex matching and interpolating matched name in replacement
-- TODO interpolating match groups in replacement -- TODO interpolating match groups in replacement

138
hledger/Hledger/Cli/Commands/Rewrite.md Normal file
View File

@ -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.

34
hledger/Hledger/Cli/Commands/Roi.hs
View File

@ -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. 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 Data.Ord
import Numeric.RootFinding import Numeric.RootFinding
import Data.Decimal import Data.Decimal
import Data.String.Here
import System.Console.CmdArgs.Explicit as CmdArgs import System.Console.CmdArgs.Explicit as CmdArgs
import Text.Tabular as Tbl import Text.Tabular as Tbl
@ -29,31 +29,17 @@ import Hledger
import Hledger.Cli.CliOptions import Hledger.Cli.CliOptions
roimode = (defCommandMode $ ["roi"]) { roimode = hledgerCommandMode
modeHelp = "shows return on investment for your portfolio." ($(hereFileRelative "Hledger/Cli/Commands/Roi.md"))
,modeHelpSuffix=lines [here| [flagNone ["cashflow"] (setboolopt "cashflow") "show all amounts that were used to compute returns"
This command will show you time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. ,flagReq ["investment"] (\s opts -> Right $ setopt "investment" s opts) "QUERY"
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" "query to select your investment transactions"
, flagReq ["profit-loss","pnl"] (\s opts -> Right $ setopt "pnl" s opts) "QUERY" ,flagReq ["profit-loss","pnl"] (\s opts -> Right $ setopt "pnl" s opts) "QUERY"
"query to select profit-and-loss or appreciation/valuation transactions" "query to select profit-and-loss or appreciation/valuation transactions"
] ]
, groupHidden = [] [generalflagsgroup1]
,groupNamed = [generalflagsgroup1] []
} ([], Just $ argsFlag "[QUERY]")
}
-- One reporting span, -- One reporting span,
data OneSpan = OneSpan data OneSpan = OneSpan

23
hledger/Hledger/Cli/Commands/Roi.md Normal file
View File

@ -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.

17
hledger/Hledger/Cli/Commands/Stats.hs
View File

@ -5,6 +5,7 @@ Print some statistics for the journal.
-} -}
{-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Stats ( module Hledger.Cli.Commands.Stats (
statsmode statsmode
@ -29,17 +30,13 @@ import Prelude hiding (putStr)
import Hledger.Cli.Utils (writeOutput) import Hledger.Cli.Utils (writeOutput)
statsmode = (defCommandMode $ ["stats"] ++ aliases) { statsmode = hledgerCommandMode
modeHelp = "show some journal statistics" `withAliases` aliases ($(hereFileRelative "Hledger/Cli/Commands/Stats.md"))
,modeGroupFlags = Group { [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."
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 = [] [generalflagsgroup1]
,groupNamed = [generalflagsgroup1] []
} ([], Just $ argsFlag "[QUERY]")
}
where aliases = []
-- like Register.summarisePostings -- like Register.summarisePostings
-- | Print various statistics for the journal. -- | Print various statistics for the journal.

28
hledger/Hledger/Cli/Commands/Stats.md Normal file
View File

@ -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.

11
hledger/Hledger/Cli/Commands/Tags.hs
View File

@ -1,5 +1,5 @@
{-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes #-} {-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Tags ( module Hledger.Cli.Commands.Tags (
tagsmode tagsmode
@ -8,20 +8,13 @@ module Hledger.Cli.Commands.Tags (
where where
import Data.List import Data.List
import Data.String.Here
import qualified Data.Text as T import qualified Data.Text as T
import Safe import Safe
import Hledger import Hledger
import Hledger.Cli.CliOptions import Hledger.Cli.CliOptions
tagsmode = hledgerCommandMode tagsmode = hledgerCommandMode
[here| tags ($(hereFileRelative "Hledger/Cli/Commands/Tags.md"))
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
|]
[] -- [flagNone ["strict"] (\opts -> setboolopt "strict" opts) "makes date comparing strict"] -- [] -- [flagNone ["strict"] (\opts -> setboolopt "strict" opts) "makes date comparing strict"] --
[generalflagsgroup1] [generalflagsgroup1]
[] []

6
hledger/Hledger/Cli/Commands/Tags.md Normal file
View File

@ -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_

21
hledger/Hledger/Cli/Commands/Test.md Normal file
View File

@ -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!

20
hledger/Hledger/Cli/CompoundBalanceCommand.hs
View File

@ -41,9 +41,7 @@ import Hledger.Cli.Utils (writeOutput)
-- it should be added to or subtracted from the grand total. -- it should be added to or subtracted from the grand total.
-- --
data CompoundBalanceCommandSpec = CompoundBalanceCommandSpec { data CompoundBalanceCommandSpec = CompoundBalanceCommandSpec {
cbcname :: String, -- ^ command name cbcdoc :: CommandDoc, -- ^ the command's name(s) and documentation
cbcaliases :: [String], -- ^ command aliases
cbchelp :: String, -- ^ command line help
cbctitle :: String, -- ^ overall report title cbctitle :: String, -- ^ overall report title
cbcqueries :: [CBCSubreportSpec], -- ^ subreport details cbcqueries :: [CBCSubreportSpec], -- ^ subreport details
cbctype :: BalanceType -- ^ the "balance" type (change, cumulative, historical) cbctype :: BalanceType -- ^ the "balance" type (change, cumulative, historical)
@ -83,11 +81,10 @@ type CompoundBalanceReport =
-- | Generate a cmdargs option-parsing mode from a compound balance command -- | Generate a cmdargs option-parsing mode from a compound balance command
-- specification. -- specification.
compoundBalanceCommandMode :: CompoundBalanceCommandSpec -> Mode RawOpts compoundBalanceCommandMode :: CompoundBalanceCommandSpec -> Mode RawOpts
compoundBalanceCommandMode CompoundBalanceCommandSpec{..} = (defCommandMode $ cbcname : cbcaliases) { compoundBalanceCommandMode CompoundBalanceCommandSpec{..} =
modeHelp = cbchelp `withAliases` cbcaliases hledgerCommandMode
,modeGroupFlags = C.Group { cbcdoc
groupUnnamed = [ [flagNone ["change"] (\opts -> setboolopt "change" opts)
flagNone ["change"] (\opts -> setboolopt "change" opts)
("show balance change in each period" ++ defType PeriodChange) ("show balance change in each period" ++ defType PeriodChange)
,flagNone ["cumulative"] (\opts -> setboolopt "cumulative" opts) ,flagNone ["cumulative"] (\opts -> setboolopt "cumulative" opts)
("show balance change accumulated across periods (in multicolumn reports)" ("show balance change accumulated across periods (in multicolumn reports)"
@ -110,10 +107,9 @@ compoundBalanceCommandMode CompoundBalanceCommandSpec{..} = (defCommandMode $ cb
,outputFormatFlag ,outputFormatFlag
,outputFileFlag ,outputFileFlag
] ]
,groupHidden = [] [generalflagsgroup1]
,groupNamed = [generalflagsgroup1] []
} ([], Just $ argsFlag "[QUERY]")
}
where where
defType :: BalanceType -> String defType :: BalanceType -> String
defType bt | bt == cbctype = " (default)" defType bt | bt == cbctype = " (default)"

615
hledger/hledger_commands.m4.md
View File

@ -16,13 +16,6 @@ Here are all the builtin commands in alphabetical order.
See also `hledger` for a more organised command list, See also `hledger` for a more organised command list,
and `hledger CMD -h` for detailed command help. and `hledger CMD -h` for detailed command help.
<!--
---
comment:
for each command: name, synopsis, description, examples.
...
-->
## accounts ## accounts
_include_(Hledger/Cli/Commands/Accounts.md) _include_(Hledger/Cli/Commands/Accounts.md)
@ -40,633 +33,83 @@ _include_(Hledger/Cli/Commands/Add.md)
_include_({{Hledger/Cli/Commands/Balance.md}}) _include_({{Hledger/Cli/Commands/Balance.md}})
## balancesheet ## 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` _include_({{Hledger/Cli/Commands/Balancesheet.md}})
: 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.
## balancesheetequity ## balancesheetequity
Just like [balancesheet](#balancesheet), but also reports Equity
(which it assumes is under a top-level `equity` account).
Example: _include_({{Hledger/Cli/Commands/Balancesheetequity.md}})
```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
```
## cashflow ## 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` _include_({{Hledger/Cli/Commands/Cashflow.md}})
: 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.
## check-dates ## 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 ## 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 ## close
_include_(Hledger/Cli/Commands/Close.md) _include_({{Hledger/Cli/Commands/Close.md}})
## files ## 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 ## help
Show any of the hledger manuals.
The `help` command displays any of the main [hledger manuals](/docs.html), in one of several ways. _include_({{Hledger/Cli/Commands/Help.md}})
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
...
}})
## import ## import
Read new transactions added to each FILE since last run, and add them to
the main journal file.
`--dry-run` _include_({{Hledger/Cli/Commands/Import.md}})
: 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
```
## incomestatement ## 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` _include_({{Hledger/Cli/Commands/Incomestatement.md}})
: 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.
## prices ## 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). _include_({{Hledger/Cli/Commands/Prices.md}})
With --inverted-costs, also print inverse prices based on transaction prices.
Prices (and postings providing prices) can be filtered by a query.
## print ## print
Show transactions from the journal. Aliases: p, txns.
`-m STR --match=STR ` _include_({{Hledger/Cli/Commands/Print.md}})
: 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.)
## print-unique ## print-unique
Print transactions which do not reuse an already-seen description.
_include_({{Hledger/Cli/Commands/print-Unique.md}})
## register ## register
Show postings and their running total. Aliases: r, reg.
`--cumulative` _include_({{Hledger/Cli/Commands/Register.md}})
: 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.
## register-match ## register-match
Print the one posting whose transaction description is closest to DESC,
in the style of the register command. _include_({{Hledger/Cli/Commands/register-Match.md}})
Helps ledger-autosync detect already-seen transactions when importing.
## rewrite ## rewrite
Print all transactions, adding custom postings to the matched ones.
_include_({{Hledger/Cli/Commands/Rewrite.md}})
## roi ## 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 ## stats
Show some journal statistics.
`-o FILE --output-file=FILE` _include_({{Hledger/Cli/Commands/Stats.md}})
: 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.
## tags ## 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. _include_({{Hledger/Cli/Commands/Tags.md}})
With additional QUERY arguments, only transactions matching the query are considered.
## test ## test
Run built-in unit tests.
Prints test names and their results on stdout. _include_({{Hledger/Cli/Commands/Test.md}})
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_addons.m4.md) _include_(hledger_addons.m4.md)