simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-09-18 17:57:11 +03:00
Code Issues Projects Releases Wiki Activity

imp: doc: show flags help in manuals

Browse Source 
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:
Simon Michael 2024-06-03 15:26:20 -10:00
parent 9a7ba1ecab
commit c787286844
33 changed files with 525 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

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

19
hledger/Hledger/Cli/Commands/Accounts.md
View File

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

5
hledger/Hledger/Cli/Commands/Activity.md
View File

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

5
hledger/Hledger/Cli/Commands/Add.md
View File

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

15
hledger/Hledger/Cli/Commands/Aregister.md
View File

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

59
hledger/Hledger/Cli/Commands/Balance.md
View File

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

47
hledger/Hledger/Cli/Commands/Balancesheet.md
View File

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

49
hledger/Hledger/Cli/Commands/Balancesheetequity.md
View File

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

46
hledger/Hledger/Cli/Commands/Cashflow.md
View File

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

5
hledger/Hledger/Cli/Commands/Check.md
View File

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

32
hledger/Hledger/Cli/Commands/Close.md
View File

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

5
hledger/Hledger/Cli/Commands/Codes.md
View File

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

6
hledger/Hledger/Cli/Commands/Commodities.md
View File

@ -2,4 +2,8 @@
List all commodity/currency symbols used or declared in the journal.
_FLAGS
```flags
Flags:
no command-specific flags
```

6
hledger/Hledger/Cli/Commands/Demo.md
View File

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

5
hledger/Hledger/Cli/Commands/Descriptions.md
View File

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

5
hledger/Hledger/Cli/Commands/Diff.md
View File

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

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

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

8
hledger/Hledger/Cli/Commands/Help.md
View File

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

6
hledger/Hledger/Cli/Commands/Import.md
View File

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

46
hledger/Hledger/Cli/Commands/Incomestatement.md
View File

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

5
hledger/Hledger/Cli/Commands/Notes.md
View File

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

6
hledger/Hledger/Cli/Commands/Payees.md
View File

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

6
hledger/Hledger/Cli/Commands/Prices.md
View File

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

25
hledger/Hledger/Cli/Commands/Print.md
View File

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

59
hledger/Hledger/Cli/Commands/README.md
View File

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

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

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

21
hledger/Hledger/Cli/Commands/Register.md
View File

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

12
hledger/Hledger/Cli/Commands/Rewrite.md
View File

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

9
hledger/Hledger/Cli/Commands/Roi.md
View File

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

6
hledger/Hledger/Cli/Commands/Stats.md
View File

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

7
hledger/Hledger/Cli/Commands/Tags.md
View File

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

5
hledger/Hledger/Cli/Commands/Test.md
View File

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

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

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