mirror of
https://github.com/simonmichael/hledger.git
synced 2025-01-08 11:49:44 +03:00
imp: doc: show flags help in manuals
Each CMD.md file now contains a snapshot of the flags help as rendered by --help. For now these must be updated manually.
This commit is contained in:
parent
9a7ba1ecab
commit
c787286844
@ -13,6 +13,7 @@ related utilities used by hledger commands.
|
||||
{-# LANGUAGE TemplateHaskell #-}
|
||||
{-# LANGUAGE TypeFamilies #-}
|
||||
{-# LANGUAGE TypeOperators #-}
|
||||
{-# LANGUAGE NamedFieldPuns #-}
|
||||
|
||||
module Hledger.Cli.CliOptions (
|
||||
progname,
|
||||
@ -58,7 +59,8 @@ module Hledger.Cli.CliOptions (
|
||||
rawOptsToCliOpts,
|
||||
outputFormats,
|
||||
defaultOutputFormat,
|
||||
CommandDoc,
|
||||
CommandHelpStr,
|
||||
parseCommandHelp,
|
||||
|
||||
-- possibly these should move into argsToCliOpts
|
||||
-- * CLI option accessors
|
||||
@ -87,7 +89,7 @@ import qualified Control.Exception as C
|
||||
import Control.Monad (when)
|
||||
import Data.Char
|
||||
import Data.Default
|
||||
import Data.Either (fromRight, isRight)
|
||||
import Data.Either (isRight)
|
||||
import Data.List.Extra (groupSortOn, intercalate, isInfixOf, nubSort)
|
||||
import qualified Data.List.NonEmpty as NE (NonEmpty, fromList, head, nonEmpty)
|
||||
import Data.List.Split (splitOn)
|
||||
@ -396,23 +398,33 @@ addonCommandMode nam = (defCommandMode [nam]) {
|
||||
}
|
||||
}
|
||||
|
||||
-- | A command's name, optional official abbreviation, and help preamble & postamble,
|
||||
-- as a specially formatted single string. Used to generate the CLI help, and also
|
||||
-- the command's doc in the hledger manual. See parseCommandHelp for the format.
|
||||
type CommandHelpStr = String
|
||||
|
||||
-- | A command's documentation. Used both as part of CLI help, and as
|
||||
-- part of the hledger manual. See parseCommandDoc.
|
||||
type CommandDoc = String
|
||||
-- part of the hledger manual. See parseCommandHelpStr.
|
||||
data CommandHelp = CommandHelp {
|
||||
cmdName :: Name -- the official command name
|
||||
,mcmdShortName :: Maybe Name -- optional official name abbreviation
|
||||
,cmdHelpPreamble :: String -- help preamble, shown before flags help
|
||||
,cmdHelpPostamble :: String -- help postamble, shown after flags help
|
||||
} deriving (Show)
|
||||
|
||||
-- | 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 :: CommandDoc -> [Flag RawOpts] -> [(String, [Flag RawOpts])]
|
||||
hledgerCommandMode :: CommandHelpStr -> [Flag RawOpts] -> [(String, [Flag RawOpts])]
|
||||
-> [Flag RawOpts] -> ([Arg RawOpts], Maybe (Arg RawOpts)) -> Mode RawOpts
|
||||
hledgerCommandMode doc unnamedflaggroup namedflaggroups hiddenflaggroup argsdescr =
|
||||
case parseCommandDoc doc of
|
||||
Nothing -> error' $ "Could not parse command doc:\n"++doc++"\n" -- PARTIAL:
|
||||
Just (names, shorthelp, longhelplines) ->
|
||||
(defCommandMode names) {
|
||||
modeHelp = shorthelp
|
||||
,modeHelpSuffix = longhelplines
|
||||
hledgerCommandMode helpstr unnamedflaggroup namedflaggroups hiddenflaggroup argsdescr =
|
||||
case parseCommandHelp helpstr of
|
||||
Nothing -> error' $ "Could not parse command doc:\n"++helpstr++"\n" -- PARTIAL:
|
||||
Just CommandHelp{cmdName, mcmdShortName, cmdHelpPreamble, cmdHelpPostamble} ->
|
||||
(defCommandMode $ cmdName : maybeToList mcmdShortName) {
|
||||
modeHelp = cmdHelpPreamble
|
||||
,modeHelpSuffix = lines cmdHelpPostamble
|
||||
,modeGroupFlags = Group {
|
||||
groupUnnamed = unnamedflaggroup
|
||||
,groupNamed = namedflaggroups
|
||||
@ -421,36 +433,45 @@ hledgerCommandMode doc unnamedflaggroup namedflaggroups hiddenflaggroup argsdesc
|
||||
,modeArgs = argsdescr
|
||||
}
|
||||
|
||||
-- | Parse a command's help text file (Somecommand.txt).
|
||||
-- This is generated from the command's doc source file (Somecommand.md)
|
||||
-- by Shake cmdhelp, and it should be formatted as follows:
|
||||
-- | Parse a command's help text file (@Somecommand.txt@).
|
||||
-- This is generated by @Shake cmdhelp@ from the command's doc source (@Somecommand.md@).
|
||||
-- @Somecommand.md@ should be formatted as follows:
|
||||
--
|
||||
-- - First line: main command name
|
||||
-- - First line: main command name, as a markdown heading.
|
||||
--
|
||||
-- - Third line: command aliases, comma-and-space separated, in parentheses (optional)
|
||||
-- - Optional parenthesised third line: an official abbreviation of the command name.
|
||||
--
|
||||
-- - Fifth or third line to the line containing just _FLAGS (or end of file): short command help
|
||||
-- - From third or fifth line to a @```flags@ line: the command help preamble.
|
||||
-- Usually one sentence or paragraph; any blank lines will not be rendered.
|
||||
--
|
||||
-- - Any lines after _FLAGS: long command help
|
||||
-- - A fenced code block beginning with @```flags@, containing a @Flags:@ line,
|
||||
-- followed by a snapshot of the command-specific flags help as generated by cmdargs
|
||||
-- or "none" if there are no command-specific flags.
|
||||
-- This should contain no blank lines (no extra newlines in the cmdargs command mode help strings).
|
||||
-- This is shown as-is in manuals, and regenerated at runtime for --help output.
|
||||
--
|
||||
-- The CLI --help displays the short help, the flags help generated by cmdargs,
|
||||
-- then the long help (which some day we might make optional again).
|
||||
-- The manual displays the short help, then the long help (but not the flags list).
|
||||
-- - Any remaining lines: the command help postamble.
|
||||
--
|
||||
parseCommandDoc :: CommandDoc -> Maybe ([Name], String, [String])
|
||||
parseCommandDoc t =
|
||||
-- (Note the difference between
|
||||
-- @Somecommand.md@, which is the markdown source file, and
|
||||
-- @Somecommand.txt@, which is the plain text file generated by @Shake cmdhelp@,
|
||||
-- which this function parses.)
|
||||
--
|
||||
parseCommandHelp :: CommandHelpStr -> Maybe CommandHelp
|
||||
parseCommandHelp t =
|
||||
case lines t of
|
||||
[] -> Nothing
|
||||
(l1:_:l3:ls) -> Just (cmdname:cmdaliases, shorthelp, longhelplines)
|
||||
(l1:_:l3:ls) -> Just $ CommandHelp cmdname (Just cmdalias) preamble postamble
|
||||
where
|
||||
cmdname = strip l1
|
||||
(cmdaliases, rest) =
|
||||
cmdname = l1
|
||||
(cmdalias, rest) =
|
||||
if "(" `isPrefixOf` l3 && ")" `isSuffixOf` l3
|
||||
then (words $ filter (/=',') $ drop 1 $ init l3, ls)
|
||||
then (drop 1 $ init l3, ls)
|
||||
else ([], l3:ls)
|
||||
(shorthelpls, longhelpls) = break (== "_FLAGS") $ dropWhile (=="") rest
|
||||
shorthelp = unlines $ reverse $ dropWhile null $ reverse shorthelpls
|
||||
longhelplines = dropWhile null $ drop 1 longhelpls
|
||||
(preamblels, rest2) = break (== "Flags:") $ dropWhile null rest
|
||||
postamblels = dropWhile null $ dropWhile (not.null) rest2
|
||||
preamble = unlines $ reverse $ dropWhile null $ reverse preamblels
|
||||
postamble = unlines postamblels
|
||||
_ -> Nothing -- error' "misformatted command help text file"
|
||||
|
||||
-- | Get a mode's usage message as a nicely wrapped string.
|
||||
@ -497,15 +518,6 @@ s `withAliases` as = s ++ " (" ++ intercalate ", " as ++ ")"
|
||||
-- s `withAliases` as = s ++ " (aliases: " ++ intercalate ", " as ++ ")"
|
||||
|
||||
|
||||
-- help_postscript = [
|
||||
-- -- "DATES can be Y/M/D or smart dates like \"last month\"."
|
||||
-- -- ,"PATTERNS are regular"
|
||||
-- -- ,"expressions which filter by account name. Prefix a pattern with desc: to"
|
||||
-- -- ,"filter by transaction description instead, prefix with not: to negate it."
|
||||
-- -- ,"When using both, not: comes last."
|
||||
-- ]
|
||||
|
||||
|
||||
-- CliOpts
|
||||
|
||||
-- | Command line options, used in the @hledger@ package and above.
|
||||
@ -569,8 +581,8 @@ rawOptsToCliOpts rawopts = do
|
||||
currentDay <- getCurrentDay
|
||||
let day = case maybestringopt "today" rawopts of
|
||||
Nothing -> currentDay
|
||||
Just d -> fromRight (error' $ "Unable to parse date \"" ++ d ++ "\"") $ -- PARTIAL:
|
||||
fromEFDay <$> fixSmartDateStrEither' currentDay (T.pack d)
|
||||
Just d -> either (const err) fromEFDay $ fixSmartDateStrEither' currentDay (T.pack d)
|
||||
where err = error' $ "Unable to parse date \"" ++ d ++ "\""
|
||||
let iopts = rawOptsToInputOpts day rawopts
|
||||
rspec <- either error' pure $ rawOptsToReportSpec day rawopts -- PARTIAL:
|
||||
mcolumns <- readMay <$> getEnvSafe "COLUMNS"
|
||||
|
@ -1,8 +1,23 @@
|
||||
## accounts
|
||||
## accounts
|
||||
|
||||
List account names.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
-u --used show only accounts used by transactions
|
||||
-d --declared show only accounts declared by account directive
|
||||
--unused show only accounts declared but not used
|
||||
--undeclared show only accounts used but not declared
|
||||
--types also show account types when known
|
||||
--positions also show where accounts were declared
|
||||
--directives show as account directives, for use in journals
|
||||
--find find the first account matched by the first
|
||||
argument (a case-insensitive infix regexp or
|
||||
account name)
|
||||
-l --flat show accounts as a flat list (default)
|
||||
-t --tree show accounts as a tree
|
||||
--drop=N flat mode: omit N leading account name parts
|
||||
```
|
||||
|
||||
This command lists account names.
|
||||
By default it shows all known accounts, either used in transactions or declared with account directives.
|
||||
|
@ -2,7 +2,10 @@
|
||||
|
||||
Show an ascii barchart of posting counts per interval.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
no command-specific flags
|
||||
```
|
||||
|
||||
The activity command displays an ascii histogram showing transaction
|
||||
counts by day, week, month or other reporting interval (by day is the
|
||||
|
@ -2,7 +2,10 @@
|
||||
|
||||
Record new transactions with interactive prompting in the console.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--no-new-accounts don't allow creating new accounts
|
||||
```
|
||||
|
||||
Many hledger users edit their journals directly with a text editor, or generate them from CSV.
|
||||
For more interactive data entry, there is the `add` command,
|
||||
|
@ -5,7 +5,20 @@
|
||||
Show the transactions and running balances in one account,
|
||||
with each transaction on one line.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--txn-dates filter strictly by transaction date, not posting
|
||||
date. Warning: this can show a wrong running
|
||||
balance.
|
||||
--no-elide don't show only 2 commodities per amount
|
||||
-w --width=N set output width (default: terminal width or
|
||||
$COLUMNS). -wN,M sets description width as well.
|
||||
--align-all guarantee alignment across all lines (slower)
|
||||
-O --output-format=FMT select the output format. Supported formats:
|
||||
txt, html, csv, tsv, json.
|
||||
-o --output-file=FILE write output to FILE. A file extension matching
|
||||
one of the above formats selects that format.
|
||||
```
|
||||
|
||||
`aregister` shows the overall transactions affecting a particular account (and
|
||||
any subaccounts). Each report line represents one transaction in this account.
|
||||
|
@ -5,7 +5,64 @@
|
||||
A flexible, general purpose "summing" report that shows accounts with some kind of numeric data.
|
||||
This can be balance changes per period, end balances, budget performance, unrealised capital gains, etc.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--sum show sum of posting amounts (default)
|
||||
--budget[=DESCPAT] show sum of posting amounts together with budget
|
||||
goals defined by periodic
|
||||
transactions. With a DESCPAT argument (must be
|
||||
separated by = not space),
|
||||
use only periodic transactions with matching
|
||||
description
|
||||
(case insensitive substring match).
|
||||
--valuechange show total change of value of period-end
|
||||
historical balances (caused by deposits,
|
||||
withdrawals, market price fluctuations)
|
||||
--gain show unrealised capital gain/loss (historical
|
||||
balance value minus cost basis)
|
||||
--count show the count of postings
|
||||
--change accumulate amounts from column start to column
|
||||
end (in multicolumn reports, default)
|
||||
--cumulative accumulate amounts from report start (specified
|
||||
by e.g. -b/--begin) to column end
|
||||
-H --historical accumulate amounts from journal start to column
|
||||
end (includes postings before report start date)
|
||||
-l --flat show accounts as a flat list (default). Amounts
|
||||
exclude subaccount amounts, except where the
|
||||
account is depth-clipped.
|
||||
-t --tree show accounts as a tree. Amounts include
|
||||
subaccount amounts.
|
||||
--drop=N omit N leading account name parts (in flat mode)
|
||||
--declared include non-parent declared accounts (best used
|
||||
with -E)
|
||||
-A --average show a row average column (in multicolumn
|
||||
reports)
|
||||
-r --related show postings' siblings instead
|
||||
-T --row-total show a row total column (in multicolumn reports)
|
||||
--summary-only display only row summaries (e.g. row total,
|
||||
average) (in multicolumn reports)
|
||||
-N --no-total omit the final total row
|
||||
--no-elide don't squash boring parent accounts (in tree
|
||||
mode)
|
||||
--format=FORMATSTR use this custom line format (in simple reports)
|
||||
-S --sort-amount sort by amount instead of account code/name (in
|
||||
flat mode). With multiple columns, sorts by the row
|
||||
total, or by row average if that is displayed.
|
||||
-% --percent express values in percentage of each column's
|
||||
total
|
||||
--invert display all amounts with reversed sign
|
||||
--transpose transpose rows and columns
|
||||
--layout=ARG how to lay out multi-commodity amounts and the
|
||||
overall table:
|
||||
'wide[,WIDTH]': commodities on one line
|
||||
'tall' : commodities on separate lines
|
||||
'bare' : commodity symbols in one column
|
||||
'tidy' : every attribute in its own column
|
||||
-O --output-format=FMT select the output format. Supported formats:
|
||||
txt, html, csv, tsv, json.
|
||||
-o --output-file=FILE write output to FILE. A file extension matching
|
||||
one of the above formats selects that format.
|
||||
```
|
||||
|
||||
`balance` is one of hledger's oldest and most versatile commands,
|
||||
for listing account balances, balance changes, values, value changes and more,
|
||||
|
@ -5,7 +5,52 @@
|
||||
Show the end balances in asset and liability accounts.
|
||||
Amounts are shown with normal positive sign, as in conventional financial statements.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--sum show sum of posting amounts (default)
|
||||
--valuechange show total change of period-end historical
|
||||
balance value (caused by deposits, withdrawals,
|
||||
market price fluctuations)
|
||||
--gain show unrealised capital gain/loss (historical
|
||||
balance value minus cost basis)
|
||||
--budget show sum of posting amounts compared to budget
|
||||
goals defined by periodic transactions
|
||||
--change accumulate amounts from column start to column
|
||||
end (in multicolumn reports)
|
||||
--cumulative accumulate amounts from report start (specified
|
||||
by e.g. -b/--begin) to column end
|
||||
-H --historical accumulate amounts from journal start to column
|
||||
end (includes postings before report start date)
|
||||
(default)
|
||||
-l --flat show accounts as a flat list (default). Amounts
|
||||
exclude subaccount amounts, except where the
|
||||
account is depth-clipped.
|
||||
-t --tree show accounts as a tree. Amounts include
|
||||
subaccount amounts.
|
||||
--drop=N flat mode: omit N leading account name parts
|
||||
--declared include non-parent declared accounts (best used
|
||||
with -E)
|
||||
-A --average show a row average column (in multicolumn
|
||||
reports)
|
||||
-T --row-total show a row total column (in multicolumn reports)
|
||||
--summary-only display only row summaries (e.g. row total,
|
||||
average) (in multicolumn reports)
|
||||
-N --no-total omit the final total row
|
||||
--no-elide don't squash boring parent accounts (in tree
|
||||
mode)
|
||||
--format=FORMATSTR use this custom line format (in simple reports)
|
||||
-S --sort-amount sort by amount instead of account code/name
|
||||
-% --percent express values in percentage of each column's
|
||||
total
|
||||
--layout=ARG how to show multi-commodity amounts:
|
||||
'wide[,WIDTH]': all commodities on one line
|
||||
'tall' : each commodity on a new line
|
||||
'bare' : bare numbers, symbols in a column
|
||||
-O --output-format=FMT select the output format. Supported formats:
|
||||
txt, html, csv, tsv, json.
|
||||
-o --output-file=FILE write output to FILE. A file extension matching
|
||||
one of the above formats selects that format.
|
||||
```
|
||||
|
||||
This command displays a [balance sheet](https://en.wikipedia.org/wiki/Balance_sheet),
|
||||
showing historical ending balances of asset and liability accounts.
|
||||
|
@ -7,7 +7,52 @@ showing historical ending balances of asset, liability and equity accounts.
|
||||
Amounts are shown with normal positive sign, as in conventional
|
||||
financial statements.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--sum show sum of posting amounts (default)
|
||||
--valuechange show total change of period-end historical
|
||||
balance value (caused by deposits, withdrawals,
|
||||
market price fluctuations)
|
||||
--gain show unrealised capital gain/loss (historical
|
||||
balance value minus cost basis)
|
||||
--budget show sum of posting amounts compared to budget
|
||||
goals defined by periodic transactions
|
||||
--change accumulate amounts from column start to column
|
||||
end (in multicolumn reports)
|
||||
--cumulative accumulate amounts from report start (specified
|
||||
by e.g. -b/--begin) to column end
|
||||
-H --historical accumulate amounts from journal start to column
|
||||
end (includes postings before report start date)
|
||||
(default)
|
||||
-l --flat show accounts as a flat list (default). Amounts
|
||||
exclude subaccount amounts, except where the
|
||||
account is depth-clipped.
|
||||
-t --tree show accounts as a tree. Amounts include
|
||||
subaccount amounts.
|
||||
--drop=N flat mode: omit N leading account name parts
|
||||
--declared include non-parent declared accounts (best used
|
||||
with -E)
|
||||
-A --average show a row average column (in multicolumn
|
||||
reports)
|
||||
-T --row-total show a row total column (in multicolumn reports)
|
||||
--summary-only display only row summaries (e.g. row total,
|
||||
average) (in multicolumn reports)
|
||||
-N --no-total omit the final total row
|
||||
--no-elide don't squash boring parent accounts (in tree
|
||||
mode)
|
||||
--format=FORMATSTR use this custom line format (in simple reports)
|
||||
-S --sort-amount sort by amount instead of account code/name
|
||||
-% --percent express values in percentage of each column's
|
||||
total
|
||||
--layout=ARG how to show multi-commodity amounts:
|
||||
'wide[,WIDTH]': all commodities on one line
|
||||
'tall' : each commodity on a new line
|
||||
'bare' : bare numbers, symbols in a column
|
||||
-O --output-format=FMT select the output format. Supported formats:
|
||||
txt, html, csv, tsv, json.
|
||||
-o --output-file=FILE write output to FILE. A file extension matching
|
||||
one of the above formats selects that format.
|
||||
```
|
||||
|
||||
This report shows accounts declared with the `Asset`, `Cash`, `Liability` or `Equity` type
|
||||
(see [account types](https://hledger.org/hledger.html#account-types)).
|
||||
@ -58,4 +103,4 @@ This command also supports the
|
||||
The output formats supported are
|
||||
`txt`, `csv`, `tsv`, `html`, and `json`.
|
||||
|
||||
[accounting equation]: https://plaintextaccounting.org/FAQ#what-is-the-accounting-equation
|
||||
[accounting equation]: https://plaintextaccounting.org/FAQ#what-is-the-accounting-equation
|
||||
|
@ -7,7 +7,51 @@ showing the inflows and outflows affecting "cash" (ie, liquid, easily convertibl
|
||||
Amounts are shown with normal positive sign, as in conventional
|
||||
financial statements.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--sum show sum of posting amounts (default)
|
||||
--valuechange show total change of period-end historical
|
||||
balance value (caused by deposits, withdrawals,
|
||||
market price fluctuations)
|
||||
--gain show unrealised capital gain/loss (historical
|
||||
balance value minus cost basis)
|
||||
--budget show sum of posting amounts compared to budget
|
||||
goals defined by periodic transactions
|
||||
--change accumulate amounts from column start to column
|
||||
end (in multicolumn reports) (default)
|
||||
--cumulative accumulate amounts from report start (specified
|
||||
by e.g. -b/--begin) to column end
|
||||
-H --historical accumulate amounts from journal start to column
|
||||
end (includes postings before report start date)
|
||||
-l --flat show accounts as a flat list (default). Amounts
|
||||
exclude subaccount amounts, except where the
|
||||
account is depth-clipped.
|
||||
-t --tree show accounts as a tree. Amounts include
|
||||
subaccount amounts.
|
||||
--drop=N flat mode: omit N leading account name parts
|
||||
--declared include non-parent declared accounts (best used
|
||||
with -E)
|
||||
-A --average show a row average column (in multicolumn
|
||||
reports)
|
||||
-T --row-total show a row total column (in multicolumn reports)
|
||||
--summary-only display only row summaries (e.g. row total,
|
||||
average) (in multicolumn reports)
|
||||
-N --no-total omit the final total row
|
||||
--no-elide don't squash boring parent accounts (in tree
|
||||
mode)
|
||||
--format=FORMATSTR use this custom line format (in simple reports)
|
||||
-S --sort-amount sort by amount instead of account code/name
|
||||
-% --percent express values in percentage of each column's
|
||||
total
|
||||
--layout=ARG how to show multi-commodity amounts:
|
||||
'wide[,WIDTH]': all commodities on one line
|
||||
'tall' : each commodity on a new line
|
||||
'bare' : bare numbers, symbols in a column
|
||||
-O --output-format=FMT select the output format. Supported formats:
|
||||
txt, html, csv, tsv, json.
|
||||
-o --output-file=FILE write output to FILE. A file extension matching
|
||||
one of the above formats selects that format.
|
||||
```
|
||||
|
||||
This report shows accounts declared with the `Cash` type
|
||||
(see [account types](https://hledger.org/hledger.html#account-types)).
|
||||
|
@ -2,7 +2,10 @@
|
||||
|
||||
Check for various kinds of errors in your data.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
no command-specific flags
|
||||
```
|
||||
|
||||
hledger provides a number of built-in correctness checks to help validate your data and prevent errors.
|
||||
Some are run automatically, some when you enable `--strict` mode;
|
||||
|
@ -7,7 +7,37 @@ migrating balances to a new journal file, retaining earnings into equity, consol
|
||||
Like `print`, it prints valid journal entries.
|
||||
You can append or copy these to your journal file(s) when you are happy with how they look.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--migrate[=NEW] show closing and opening transactions, for Asset
|
||||
and Liability accounts by default, tagged for easy
|
||||
matching. The tag's default value can be overridden
|
||||
by providing NEW.
|
||||
--close[=NEW] (default) show a closing transaction
|
||||
--open[=NEW] show an opening transaction
|
||||
--assign[=NEW] show opening balance assignments
|
||||
--assert[=NEW] show closing balance assertions
|
||||
--retain[=NEW] show a retain earnings transaction, for Revenue
|
||||
and Expense accounts by default
|
||||
-x --explicit show all amounts explicitly
|
||||
--show-costs show amounts with different costs separately
|
||||
--interleaved show source and destination postings together
|
||||
--assertion-type=TYPE =, ==, =* or ==*
|
||||
--close-desc=DESC set closing transaction's description
|
||||
--close-acct=ACCT set closing transaction's destination account
|
||||
--open-desc=DESC set opening transaction's description
|
||||
--open-acct=ACCT set opening transaction's source account
|
||||
--round=TYPE how much rounding or padding should be done when
|
||||
displaying amounts ?
|
||||
none - show original decimal digits,
|
||||
as in journal
|
||||
soft - just add or remove decimal zeros
|
||||
to match precision (default)
|
||||
hard - round posting amounts to precision
|
||||
(can unbalance transactions)
|
||||
all - also round cost amounts to precision
|
||||
(can unbalance transactions)
|
||||
```
|
||||
|
||||
`close` currently has six modes, selected by a single mode flag:
|
||||
|
||||
|
@ -2,7 +2,10 @@
|
||||
|
||||
List the codes seen in transactions, in the order parsed.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
no command-specific flags
|
||||
```
|
||||
|
||||
This command prints the value of each transaction's code field, in the
|
||||
order transactions were parsed. The transaction code is an optional
|
||||
|
@ -2,4 +2,8 @@
|
||||
|
||||
List all commodity/currency symbols used or declared in the journal.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
no command-specific flags
|
||||
```
|
||||
|
||||
|
@ -2,7 +2,11 @@
|
||||
|
||||
Play demos of hledger usage in the terminal, if asciinema is installed.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
-s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 is
|
||||
double, etc (default: 2))
|
||||
```
|
||||
|
||||
Run this command with no argument to list the demos.
|
||||
To play a demo, write its number or a prefix or substring of its title.
|
||||
|
@ -2,7 +2,10 @@
|
||||
|
||||
List the unique descriptions that appear in transactions.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
no command-specific flags
|
||||
```
|
||||
|
||||
This command lists the unique descriptions that appear in transactions,
|
||||
in alphabetic order.
|
||||
|
@ -16,7 +16,10 @@ from your bank (eg as CSV data). When hledger and your bank disagree
|
||||
about the account balance, you can compare the bank data with your
|
||||
journal to find out the cause.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
no command-specific flags
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
|
@ -3,4 +3,7 @@
|
||||
List all files included in the journal. With a REGEX argument,
|
||||
only file names matching the regular expression (case sensitive) are shown.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
no command-specific flags
|
||||
```
|
||||
|
@ -3,7 +3,13 @@
|
||||
Show the hledger user manual with `info`, `man`, or a pager.
|
||||
With a (case insensitive) TOPIC argument, try to open it at that section heading.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
-i show the manual with info
|
||||
-m show the manual with man
|
||||
-p show the manual with $PAGER or less
|
||||
(less is always used if TOPIC is specified)
|
||||
```
|
||||
|
||||
This command shows the hledger manual built in to your hledger executable.
|
||||
It can be useful when offline, or when you prefer the terminal to a web browser,
|
||||
|
@ -2,7 +2,11 @@
|
||||
|
||||
Import new transactions from one or more data files to the main journal.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--catchup just mark all transactions as already imported
|
||||
--dry-run just show the transactions to be imported
|
||||
```
|
||||
|
||||
This command detects new transactions in each FILE argument since it was last run,
|
||||
and appends them to the main journal.
|
||||
|
@ -5,7 +5,51 @@
|
||||
Show revenue inflows and expense outflows during the report period.
|
||||
Amounts are shown with normal positive sign, as in conventional financial statements.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--sum show sum of posting amounts (default)
|
||||
--valuechange show total change of period-end historical
|
||||
balance value (caused by deposits, withdrawals,
|
||||
market price fluctuations)
|
||||
--gain show unrealised capital gain/loss (historical
|
||||
balance value minus cost basis)
|
||||
--budget show sum of posting amounts compared to budget
|
||||
goals defined by periodic transactions
|
||||
--change accumulate amounts from column start to column
|
||||
end (in multicolumn reports) (default)
|
||||
--cumulative accumulate amounts from report start (specified
|
||||
by e.g. -b/--begin) to column end
|
||||
-H --historical accumulate amounts from journal start to column
|
||||
end (includes postings before report start date)
|
||||
-l --flat show accounts as a flat list (default). Amounts
|
||||
exclude subaccount amounts, except where the
|
||||
account is depth-clipped.
|
||||
-t --tree show accounts as a tree. Amounts include
|
||||
subaccount amounts.
|
||||
--drop=N flat mode: omit N leading account name parts
|
||||
--declared include non-parent declared accounts (best used
|
||||
with -E)
|
||||
-A --average show a row average column (in multicolumn
|
||||
reports)
|
||||
-T --row-total show a row total column (in multicolumn reports)
|
||||
--summary-only display only row summaries (e.g. row total,
|
||||
average) (in multicolumn reports)
|
||||
-N --no-total omit the final total row
|
||||
--no-elide don't squash boring parent accounts (in tree
|
||||
mode)
|
||||
--format=FORMATSTR use this custom line format (in simple reports)
|
||||
-S --sort-amount sort by amount instead of account code/name
|
||||
-% --percent express values in percentage of each column's
|
||||
total
|
||||
--layout=ARG how to show multi-commodity amounts:
|
||||
'wide[,WIDTH]': all commodities on one line
|
||||
'tall' : each commodity on a new line
|
||||
'bare' : bare numbers, symbols in a column
|
||||
-O --output-format=FMT select the output format. Supported formats:
|
||||
txt, html, csv, tsv, json.
|
||||
-o --output-file=FILE write output to FILE. A file extension matching
|
||||
one of the above formats selects that format.
|
||||
```
|
||||
|
||||
This command displays an [income statement](http://en.wikipedia.org/wiki/Income_statement),
|
||||
showing revenues and expenses during one or more periods.
|
||||
|
@ -2,7 +2,10 @@
|
||||
|
||||
List the unique notes that appear in transactions.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
no command-specific flags
|
||||
```
|
||||
|
||||
This command lists the unique notes that appear in transactions,
|
||||
in alphabetic order.
|
||||
|
@ -2,7 +2,11 @@
|
||||
|
||||
List the unique payee/payer names that appear in transactions.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--declared show payees declared with payee directives
|
||||
--used show payees referenced by transactions
|
||||
```
|
||||
|
||||
This command lists unique payee/payer names which have been
|
||||
declared with payee directives (--declared),
|
||||
|
@ -14,4 +14,8 @@ it will show the same prices used internally to calculate value reports.
|
||||
But if in doubt, you can inspect those directly by running the value report
|
||||
with --debug=2.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--show-reverse also show the prices inferred by reversing known
|
||||
prices
|
||||
```
|
||||
|
@ -2,7 +2,30 @@
|
||||
|
||||
Show full journal entries, representing transactions.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
-x --explicit show all amounts explicitly
|
||||
--show-costs show transaction prices even with conversion
|
||||
postings
|
||||
--round=TYPE how much rounding or padding should be done when
|
||||
displaying amounts ?
|
||||
none - show original decimal digits,
|
||||
as in journal
|
||||
soft - just add or remove decimal zeros
|
||||
to match precision (default)
|
||||
hard - round posting amounts to precision
|
||||
(can unbalance transactions)
|
||||
all - also round cost amounts to precision
|
||||
(can unbalance transactions)
|
||||
--new show only newer-dated transactions added in each
|
||||
file since last run
|
||||
-m --match=DESC fuzzy search for one recent transaction with
|
||||
description closest to DESC
|
||||
-O --output-format=FMT select the output format. Supported formats:
|
||||
txt, beancount, csv, tsv, json, sql.
|
||||
-o --output-file=FILE write output to FILE. A file extension matching
|
||||
one of the above formats selects that format.
|
||||
```
|
||||
|
||||
The print command displays full journal entries (transactions)
|
||||
from the journal file, sorted by date
|
||||
|
@ -30,44 +30,29 @@ Here are more special features/conventions of command doc files (see
|
||||
|
||||
- The content is pandoc markdown. m4 macros are not supported.
|
||||
|
||||
- In manuals, they are rendered with formatting and hyperlinks when
|
||||
supported by the various output formats.
|
||||
- The format is "hledger command help". Basically there should be
|
||||
a command name and blank line,
|
||||
an optional parenthesised command alias/abbreviation and blank line,
|
||||
a short help preamble,
|
||||
a code block with `flags` class containing a `Flags:` line
|
||||
then the command-specific flags help output (or "none"),
|
||||
and an optional longer help postamble.
|
||||
See parseCommandHelp in ../CliOptions.hs for the exact format.
|
||||
|
||||
- In command line help, they are rendered as plain text, with verbatim
|
||||
blocks unindented, and with lines longer than 78 characters wrapped
|
||||
(unless they contain no spaces).
|
||||
- In manuals, these are rendered with formatting and hyperlinks in
|
||||
output formats which support those.
|
||||
|
||||
- To avoid unsightly line wrapping in command line help, try to keep
|
||||
verbatim examples to at most 78 characters wide. When necessary, we
|
||||
may be forced to cheat and alter command output slightly, eg
|
||||
reducing the width of register's typically 79-wide reports by one.
|
||||
- In --help output, they are rendered
|
||||
|
||||
- The first line should specify the command name and any aliases, as
|
||||
words separated by spaces and/or commas. It should end with a
|
||||
backslash (to force a line break in the output).
|
||||
|
||||
- Short help, about one paragraph in length, should begin on the
|
||||
second line.
|
||||
|
||||
- If the short help is more than one line, its first line should end
|
||||
with a single newline, not two (otherwise it will be displayed with
|
||||
two newlines after each line in command line help).
|
||||
|
||||
- In command line help, the short help is displayed with blank lines
|
||||
removed (paragraphs run together). Blank lines can still be used for
|
||||
markdown formatting though, eg to define a list.
|
||||
|
||||
- After the short help, there should be a paragraph containing just
|
||||
_FLAGS. This marks the end of the short help, and it will be
|
||||
replaced in command line help by the flags list. (Without it, the
|
||||
flags list appears at the end of command line help.) The flags list
|
||||
will not appear in the hledger manual.
|
||||
|
||||
- Long help (as many paragraphs as needed) follows the _FLAGS marker.
|
||||
This often ends with one or more examples.
|
||||
|
||||
|
||||
XXX Command docs with examples wider than 78:
|
||||
close
|
||||
rewrite
|
||||
- as plain text
|
||||
- with blank lines removed from the preamble
|
||||
- with lines longer than 78 characters wrapped (unless they contain no spaces)
|
||||
- with code blocks unindented
|
||||
- with the `flags` code block replaced by dynamically generated flags help
|
||||
(for both command-specific and general flags)
|
||||
|
||||
The postamble often ends with one or more examples.
|
||||
To avoid unsightly line wrapping in command line help, try to keep
|
||||
code blocks to at most 78 characters wide. When necessary, we may be
|
||||
forced to cheat and alter command output slightly, eg reducing the
|
||||
width of register's typically 79-wide reports by one.
|
||||
|
@ -41,7 +41,7 @@ registermode = hledgerCommandMode
|
||||
([flagNone ["cumulative"] (setboolopt "cumulative")
|
||||
"show running total from report start date (default)"
|
||||
,flagNone ["historical","H"] (setboolopt "historical")
|
||||
"show historical running total/balance (includes postings before report start date)\n "
|
||||
"show historical running total/balance (includes postings before report start date)"
|
||||
,flagNone ["average","A"] (setboolopt "average")
|
||||
"show running average of posting amounts instead of total (implies --empty)"
|
||||
,let arg = "DESC" in
|
||||
|
@ -4,7 +4,26 @@
|
||||
|
||||
Show postings and their running total.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--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)
|
||||
-m --match=DESC fuzzy search for one recent posting with
|
||||
description closest to DESC
|
||||
-r --related show postings' siblings instead
|
||||
--invert display all amounts with reversed sign
|
||||
-w --width=N set output width (default: terminal width or
|
||||
$COLUMNS). -wN,M sets description width as well.
|
||||
--align-all guarantee alignment across all lines (slower)
|
||||
-O --output-format=FMT select the output format. Supported formats:
|
||||
txt, csv, tsv, json.
|
||||
-o --output-file=FILE write output to FILE. A file extension matching
|
||||
one of the above formats selects that format.
|
||||
```
|
||||
|
||||
The register command displays matched postings, across all accounts,
|
||||
in date order, with their running total or running historical balance.
|
||||
|
@ -3,7 +3,17 @@
|
||||
Print all transactions, rewriting the postings of matched transactions.
|
||||
For now the only rewrite available is adding new postings, like print --auto.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--add-posting='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.
|
||||
--diff generate diff suitable as an input for
|
||||
patch tool
|
||||
```
|
||||
|
||||
This is a start at a generic rewriter of transaction entries.
|
||||
It reads the default journal and prints the transactions, like print,
|
||||
|
@ -3,7 +3,14 @@
|
||||
Shows the time-weighted (TWR) and money-weighted (IRR) rate of return
|
||||
on your investments.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--cashflow show all amounts that were used to compute
|
||||
returns
|
||||
--investment=QUERY query to select your investment transactions
|
||||
--profit-loss=QUERY --pnl query to select profit-and-loss or
|
||||
appreciation/valuation transactions
|
||||
```
|
||||
|
||||
At a minimum, you need to supply a query (which could be just an
|
||||
account name) to select your investment(s) with `--inv`, and another
|
||||
|
@ -2,7 +2,11 @@
|
||||
|
||||
Show journal and performance statistics.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
-v --verbose show more detailed output
|
||||
-o --output-file=FILE write output to FILE.
|
||||
```
|
||||
|
||||
The stats command shows summary information for the whole journal, or
|
||||
a matched part of it. With a [reporting interval](#reporting-interval),
|
||||
|
@ -4,7 +4,12 @@ List the tags used in the journal, or their values.
|
||||
|
||||
<!-- same section name as Journal > Tags, if reordering these update all #tags[-1] links -->
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
--values list tag values instead of tag names
|
||||
--parsed show tags/values in the order they were parsed,
|
||||
including duplicates
|
||||
```
|
||||
|
||||
This command lists the tag names used in the journal,
|
||||
whether on transactions, postings, or account declarations.
|
||||
|
@ -2,7 +2,10 @@
|
||||
|
||||
Run built-in unit tests.
|
||||
|
||||
_FLAGS
|
||||
```flags
|
||||
Flags:
|
||||
no command-specific flags
|
||||
```
|
||||
|
||||
This command runs the unit tests built in to hledger and hledger-lib,
|
||||
printing the results on stdout. If any test fails, the exit code will
|
||||
|
@ -44,7 +44,7 @@ import Hledger.Cli.Utils (unsupportedOutputFormatError, writeOutputLazyText)
|
||||
-- it should be added to or subtracted from the grand total.
|
||||
--
|
||||
data CompoundBalanceCommandSpec = CompoundBalanceCommandSpec {
|
||||
cbcdoc :: CommandDoc, -- ^ the command's name(s) and documentation
|
||||
cbcdoc :: CommandHelpStr, -- ^ the command's name(s) and documentation
|
||||
cbctitle :: String, -- ^ overall report title
|
||||
cbcqueries :: [CBCSubreportSpec DisplayName], -- ^ subreport details
|
||||
cbcaccum :: BalanceAccumulation -- ^ how to accumulate balances (per-period, cumulative, historical)
|
||||
@ -64,7 +64,7 @@ compoundBalanceCommandMode CompoundBalanceCommandSpec{..} =
|
||||
,flagNone ["gain"] (setboolopt "gain")
|
||||
"show unrealised capital gain/loss (historical balance value minus cost basis)"
|
||||
,flagNone ["budget"] (setboolopt "budget")
|
||||
"show sum of posting amounts compared to budget goals defined by periodic transactions\n "
|
||||
"show sum of posting amounts compared to budget goals defined by periodic transactions"
|
||||
|
||||
,flagNone ["change"] (setboolopt "change")
|
||||
("accumulate amounts from column start to column end (in multicolumn reports)"
|
||||
@ -74,7 +74,7 @@ compoundBalanceCommandMode CompoundBalanceCommandSpec{..} =
|
||||
++ defaultMarker Cumulative)
|
||||
,flagNone ["historical","H"] (setboolopt "historical")
|
||||
("accumulate amounts from journal start to column end (includes postings before report start date)"
|
||||
++ defaultMarker Historical ++ "\n ")
|
||||
++ defaultMarker Historical)
|
||||
]
|
||||
++ flattreeflags True ++
|
||||
[flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts"
|
||||
|
Loading…
Reference in New Issue
Block a user