diff --git a/CHANGES b/CHANGES --- a/CHANGES +++ b/CHANGES @@ -1,5 +1,13 @@ -User-visible changes in hledger-ui. -See also the hledger and project change logs. +User-visible changes in hledger-ui. See also hledger, hledger-lib. + + +# 1.5 (2017/12/31) + +* fix help -> view manual (on posix platforms) #623 + +* support -V/--value, --forecast, --auto + +* remove upper bounds on all but hledger* and base (experimental) # 1.4 (2017/9/30) diff --git a/Hledger/UI/AccountsScreen.hs b/Hledger/UI/AccountsScreen.hs --- a/Hledger/UI/AccountsScreen.hs +++ b/Hledger/UI/AccountsScreen.hs @@ -82,14 +82,8 @@ q = queryFromOpts d ropts - -- maybe convert balances to market value - convert | value_ ropts' = balanceReportValue j valuedate - | otherwise = id - where - valuedate = fromMaybe d $ queryEndDate False q - -- run the report - (items,_total) = convert $ report ropts' q j + (items,_total) = report ropts' q j where -- still using the old balanceReport for change reports as it -- does not include every account from before the report period diff --git a/Hledger/UI/Main.hs b/Hledger/UI/Main.hs --- a/Hledger/UI/Main.hs +++ b/Hledger/UI/Main.hs @@ -71,15 +71,18 @@ | "binary-filename" `inRawOpts` (rawopts_ $ cliopts_ opts) = putStrLn (binaryfilename progname) | otherwise = withJournalDoUICommand opts runBrickUi --- XXX withJournalDo specialised for UIOpts +-- TODO fix nasty duplication of withJournalDo withJournalDoUICommand :: UIOpts -> (UIOpts -> Journal -> IO ()) -> IO () withJournalDoUICommand uopts@UIOpts{cliopts_=copts} cmd = do journalpath <- journalFilePathFromOpts copts ej <- readJournalFilesWithOpts (inputopts_ copts) journalpath - let fn = cmd uopts . - pivotByOpts copts . - anonymiseByOpts copts . - journalApplyAliases (aliasesFromOpts copts) + let fn = cmd uopts + . pivotByOpts copts + . anonymiseByOpts copts + . journalApplyAliases (aliasesFromOpts copts) + <=< journalApplyValue (reportopts_ copts) + <=< journalAddForecast copts + . generateAutomaticPostings (reportopts_ copts) either error' fn ej runBrickUi :: UIOpts -> Journal -> IO () diff --git a/Hledger/UI/UIUtils.hs b/Hledger/UI/UIUtils.hs --- a/Hledger/UI/UIUtils.hs +++ b/Hledger/UI/UIUtils.hs @@ -13,23 +13,21 @@ import Brick.Widgets.Dialog import Brick.Widgets.Edit import Brick.Widgets.List +import Control.Monad.IO.Class import Data.List import Data.Maybe import Data.Monoid import Graphics.Vty (Event(..),Key(..),Modifier(..),Color,Attr,currentAttr) import Lens.Micro.Platform -import System.Process +import System.Environment import Hledger hiding (Color) import Hledger.Cli (CliOpts(rawopts_)) +import Hledger.Cli.DocFiles import Hledger.UI.UITypes import Hledger.UI.UIState -runInfo = runCommand "hledger-ui --info" >>= waitForProcess -runMan = runCommand "hledger-ui --man" >>= waitForProcess -runHelp = runCommand "hledger-ui --help | less" >>= waitForProcess - -- ui -- | Draw the help dialog, called when help mode is active. @@ -63,9 +61,9 @@ ,renderKey ("q", "quit") ,str " " ,str "MANUAL" - ,str "from help dialog:" - ,renderKey ("t", "text") - ,renderKey ("m", "man page") + ,str "choose format:" + ,renderKey ("p", "pager") + ,renderKey ("m", "man") ,renderKey ("i", "info") ] ,padLeftRight 1 $ @@ -124,13 +122,15 @@ statusstyle = min 3 $ fromMaybe 1 $ maybeintopt "status-toggles" $ rawopts_ copts -- | Event handler used when help mode is active. +-- May invoke $PAGER, less, man or info, which is likely to fail on MS Windows, TODO. helpHandle :: UIState -> BrickEvent Name AppEvent -> EventM Name (Next UIState) -helpHandle ui ev = +helpHandle ui ev = do + pagerprog <- liftIO $ fromMaybe "less" <$> lookupEnv "PAGER" case ev of VtyEvent e | e `elem` (moveLeftEvents ++ [EvKey KEsc [], EvKey (KChar '?') []]) -> continue $ setMode Normal ui - VtyEvent (EvKey (KChar 't') []) -> suspendAndResume $ runHelp >> return ui' - VtyEvent (EvKey (KChar 'm') []) -> suspendAndResume $ runMan >> return ui' - VtyEvent (EvKey (KChar 'i') []) -> suspendAndResume $ runInfo >> return ui' + VtyEvent (EvKey (KChar 'p') []) -> suspendAndResume $ runPagerForTopic pagerprog "hledger-ui" >> return ui' + VtyEvent (EvKey (KChar 'm') []) -> suspendAndResume $ runManForTopic "hledger-ui" >> return ui' + VtyEvent (EvKey (KChar 'i') []) -> suspendAndResume $ runInfoForTopic "hledger-ui" >> return ui' _ -> continue ui where ui' = setMode Normal ui diff --git a/doc/hledger-ui.1 b/doc/hledger-ui.1 deleted file mode 100644 --- a/doc/hledger-ui.1 +++ /dev/null @@ -1,470 +0,0 @@ - -.TH "hledger\-ui" "1" "September 2017" "hledger\-ui 1.4" "hledger User Manuals" - - - -.SH NAME -.PP -hledger\-ui \- curses\-style interface for the hledger accounting tool -.SH SYNOPSIS -.PP -\f[C]hledger\-ui\ [OPTIONS]\ [QUERYARGS]\f[] -.PD 0 -.P -.PD -\f[C]hledger\ ui\ \-\-\ [OPTIONS]\ [QUERYARGS]\f[] -.SH DESCRIPTION -.PP -hledger is a cross\-platform program for tracking money, time, or any -other commodity, using double\-entry accounting and a simple, editable -file format. -hledger is inspired by and largely compatible with ledger(1). -.PP -hledger\-ui is hledger\[aq]s curses\-style interface, providing an -efficient full\-window text UI for viewing accounts and transactions, -and some limited data entry capability. -It is easier than hledger\[aq]s command\-line interface, and sometimes -quicker and more convenient than the web interface. -.PP -Like hledger, it reads data from one or more files in hledger journal, -timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or -\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, -perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). -For more about this see hledger(1), hledger_journal(5) etc. -.SH OPTIONS -.PP -Note: if invoking hledger\-ui as a hledger subcommand, write -\f[C]\-\-\f[] before options as shown above. -.PP -Any QUERYARGS are interpreted as a hledger search query which filters -the data. -.TP -.B \f[C]\-\-watch\f[] -watch for data and date changes and reload automatically -.RS -.RE -.TP -.B \f[C]\-\-theme=default|terminal|greenterm\f[] -use this custom display theme -.RS -.RE -.TP -.B \f[C]\-\-register=ACCTREGEX\f[] -start in the (first) matched account\[aq]s register screen -.RS -.RE -.TP -.B \f[C]\-\-change\f[] -show period balances (changes) at startup instead of historical balances -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show full account names, unindented -.RS -.RE -.PP -hledger input options: -.TP -.B \f[C]\-f\ FILE\ \-\-file=FILE\f[] -use a different input file. -For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or -\f[C]$HOME/.hledger.journal\f[]) -.RS -.RE -.TP -.B \f[C]\-\-rules\-file=RULESFILE\f[] -Conversion rules file to use when reading CSV (default: FILE.rules) -.RS -.RE -.TP -.B \f[C]\-\-alias=OLD=NEW\f[] -rename accounts named OLD to NEW -.RS -.RE -.TP -.B \f[C]\-\-anon\f[] -anonymize accounts and payees -.RS -.RE -.TP -.B \f[C]\-\-pivot\ FIELDNAME\f[] -use some other field or tag for the account name -.RS -.RE -.TP -.B \f[C]\-I\ \-\-ignore\-assertions\f[] -ignore any failing balance assertions -.RS -.RE -.PP -hledger reporting options: -.TP -.B \f[C]\-b\ \-\-begin=DATE\f[] -include postings/txns on or after this date -.RS -.RE -.TP -.B \f[C]\-e\ \-\-end=DATE\f[] -include postings/txns before this date -.RS -.RE -.TP -.B \f[C]\-D\ \-\-daily\f[] -multiperiod/multicolumn report by day -.RS -.RE -.TP -.B \f[C]\-W\ \-\-weekly\f[] -multiperiod/multicolumn report by week -.RS -.RE -.TP -.B \f[C]\-M\ \-\-monthly\f[] -multiperiod/multicolumn report by month -.RS -.RE -.TP -.B \f[C]\-Q\ \-\-quarterly\f[] -multiperiod/multicolumn report by quarter -.RS -.RE -.TP -.B \f[C]\-Y\ \-\-yearly\f[] -multiperiod/multicolumn report by year -.RS -.RE -.TP -.B \f[C]\-p\ \-\-period=PERIODEXP\f[] -set start date, end date, and/or reporting interval all at once -(overrides the flags above) -.RS -.RE -.TP -.B \f[C]\-\-date2\f[] -match the secondary date instead (see command help for other effects) -.RS -.RE -.TP -.B \f[C]\-U\ \-\-unmarked\f[] -include only unmarked postings/txns (can combine with \-P or \-C) -.RS -.RE -.TP -.B \f[C]\-P\ \-\-pending\f[] -include only pending postings/txns -.RS -.RE -.TP -.B \f[C]\-C\ \-\-cleared\f[] -include only cleared postings/txns -.RS -.RE -.TP -.B \f[C]\-R\ \-\-real\f[] -include only non\-virtual postings -.RS -.RE -.TP -.B \f[C]\-NUM\ \-\-depth=NUM\f[] -hide/aggregate accounts or postings more than NUM levels deep -.RS -.RE -.TP -.B \f[C]\-E\ \-\-empty\f[] -show items with zero amount, normally hidden -.RS -.RE -.TP -.B \f[C]\-B\ \-\-cost\f[] -convert amounts to their cost at transaction time (using the transaction -price, if any) -.RS -.RE -.TP -.B \f[C]\-V\ \-\-value\f[] -convert amounts to their market value on the report end date (using the -most recent applicable market price, if any) -.RS -.RE -.PP -When a reporting option appears more than once in the command line, the -last one takes precedence. -.PP -Some reporting options can also be written as query arguments. -.PP -hledger help options: -.TP -.B \f[C]\-h\ \-\-help\f[] -show general usage (or after COMMAND, command usage) -.RS -.RE -.TP -.B \f[C]\-\-version\f[] -show version -.RS -.RE -.TP -.B \f[C]\-\-debug[=N]\f[] -show debug output (levels 1\-9, default: 1) -.RS -.RE -.PP -A \@FILE argument will be expanded to the contents of FILE, which should -contain one command line option/argument per line. -(To prevent this, insert a \f[C]\-\-\f[] argument before.) -.SH KEYS -.PP -\f[C]?\f[] shows a help dialog listing all keys. -(Some of these also appear in the quick help at the bottom of each -screen.) Press \f[C]?\f[] again (or \f[C]ESCAPE\f[], or \f[C]LEFT\f[]) -to close it. -The following keys work on most screens: -.PP -The cursor keys navigate: \f[C]right\f[] (or \f[C]enter\f[]) goes -deeper, \f[C]left\f[] returns to the previous screen, -\f[C]up\f[]/\f[C]down\f[]/\f[C]page\ up\f[]/\f[C]page\ down\f[]/\f[C]home\f[]/\f[C]end\f[] -move up and down through lists. -Vi\-style (\f[C]h\f[]/\f[C]j\f[]/\f[C]k\f[]/\f[C]l\f[]) and Emacs\-style -(\f[C]CTRL\-p\f[]/\f[C]CTRL\-n\f[]/\f[C]CTRL\-f\f[]/\f[C]CTRL\-b\f[]) -movement keys are also supported. -A tip: movement speed is limited by your keyboard repeat rate, to move -faster you may want to adjust it. -(If you\[aq]re on a mac, the Karabiner app is one way to do that.) -.PP -With shift pressed, the cursor keys adjust the report period, limiting -the transactions to be shown (by default, all are shown). -\f[C]shift\-down/up\f[] steps downward and upward through these standard -report period durations: year, quarter, month, week, day. -Then, \f[C]shift\-left/right\f[] moves to the previous/next period. -\f[C]t\f[] sets the report period to today. -With the \f[C]\-\-watch\f[] option, when viewing a "current" period (the -current day, week, month, quarter, or year), the period will move -automatically to track the current date. -To set a non\-standard period, you can use \f[C]/\f[] and a -\f[C]date:\f[] query. -.PP -\f[C]/\f[] lets you set a general filter query limiting the data shown, -using the same query terms as in hledger and hledger\-web. -While editing the query, you can use CTRL\-a/e/d/k, BS, cursor keys; -press \f[C]ENTER\f[] to set it, or \f[C]ESCAPE\f[]to cancel. -There are also keys for quickly adjusting some common filters like -account depth and transaction status (see below). -\f[C]BACKSPACE\f[] or \f[C]DELETE\f[] removes all filters, showing all -transactions. -.PP -\f[C]ESCAPE\f[] removes all filters and jumps back to the top screen. -Or, it cancels a minibuffer edit or help dialog in progress. -.PP -\f[C]CTRL\-l\f[] redraws the screen and centers the selection if -possible (selections near the top won\[aq]t be centered, since we -don\[aq]t scroll above the top). -.PP -\f[C]g\f[] reloads from the data file(s) and updates the current screen -and any previous screens. -(With large files, this could cause a noticeable pause.) -.PP -\f[C]I\f[] toggles balance assertion checking. -Disabling balance assertions temporarily can be useful for -troubleshooting. -.PP -\f[C]a\f[] runs command\-line hledger\[aq]s add command, and reloads the -updated file. -This allows some basic data entry. -.PP -\f[C]E\f[] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default -(\f[C]emacsclient\ \-a\ ""\ \-nw\f[]) on the journal file. -With some editors (emacs, vi), the cursor will be positioned at the -current transaction when invoked from the register and transaction -screens, and at the error location (if possible) when invoked from the -error screen. -.PP -\f[C]q\f[] quits the application. -.PP -Additional screen\-specific keys are described below. -.SH SCREENS -.SS Accounts screen -.PP -This is normally the first screen displayed. -It lists accounts and their balances, like hledger\[aq]s balance -command. -By default, it shows all accounts and their latest ending balances -(including the balances of subaccounts). -if you specify a query on the command line, it shows just the matched -accounts and the balances from matched transactions. -.PP -Account names are normally indented to show the hierarchy (tree mode). -To see less detail, set a depth limit by pressing a number key, -\f[C]1\f[] to \f[C]9\f[]. -\f[C]0\f[] shows even less detail, collapsing all accounts to a single -total. -\f[C]\-\f[] and \f[C]+\f[] (or \f[C]=\f[]) decrease and increase the -depth limit. -To remove the depth limit, set it higher than the maximum account depth, -or press \f[C]ESCAPE\f[]. -.PP -\f[C]F\f[] toggles flat mode, in which accounts are shown as a flat -list, with their full names. -In this mode, account balances exclude subaccounts, except for accounts -at the depth limit (as with hledger\[aq]s balance command). -.PP -\f[C]H\f[] toggles between showing historical balances or period -balances. -Historical balances (the default) are ending balances at the end of the -report period, taking into account all transactions before that date -(filtered by the filter query if any), including transactions before the -start of the report period. -In other words, historical balances are what you would see on a bank -statement for that account (unless disturbed by a filter query). -Period balances ignore transactions before the report start date, so -they show the change in balance during the report period. -They are more useful eg when viewing a time log. -.PP -\f[C]U\f[] toggles filtering by unmarked status, including or excluding -unmarked postings in the balances. -Similarly, \f[C]P\f[] toggles pending postings, and \f[C]C\f[] toggles -cleared postings. -(By default, balances include all postings; if you activate one or two -status filters, only those postings are included; and if you activate -all three, the filter is removed.) -.PP -\f[C]R\f[] toggles real mode, in which virtual postings are ignored. -.PP -\f[C]Z\f[] toggles nonzero mode, in which only accounts with nonzero -balances are shown (hledger\-ui shows zero items by default, unlike -command\-line hledger). -.PP -Press \f[C]right\f[] or \f[C]enter\f[] to view an account\[aq]s -transactions register. -.SS Register screen -.PP -This screen shows the transactions affecting a particular account, like -a check register. -Each line represents one transaction and shows: -.IP \[bu] 2 -the other account(s) involved, in abbreviated form. -(If there are both real and virtual postings, it shows only the accounts -affected by real postings.) -.IP \[bu] 2 -the overall change to the current account\[aq]s balance; positive for an -inflow to this account, negative for an outflow. -.IP \[bu] 2 -the running historical total or period total for the current account, -after the transaction. -This can be toggled with \f[C]H\f[]. -Similar to the accounts screen, the historical total is affected by -transactions (filtered by the filter query) before the report start -date, while the period total is not. -If the historical total is not disturbed by a filter query, it will be -the running historical balance you would see on a bank register for the -current account. -.PP -If the accounts screen was in tree mode, the register screen will -include transactions from both the current account and its subaccounts. -If the accounts screen was in flat mode, and a non\-depth\-clipped -account was selected, the register screen will exclude transactions from -subaccounts. -In other words, the register always shows the transactions responsible -for the period balance shown on the accounts screen. -As on the accounts screen, this can be toggled with \f[C]F\f[]. -.PP -\f[C]U\f[] toggles filtering by unmarked status, showing or hiding -unmarked transactions. -Similarly, \f[C]P\f[] toggles pending transactions, and \f[C]C\f[] -toggles cleared transactions. -(By default, transactions with all statuses are shown; if you activate -one or two status filters, only those transactions are shown; and if you -activate all three, the filter is removed.)q -.PP -\f[C]R\f[] toggles real mode, in which virtual postings are ignored. -.PP -\f[C]Z\f[] toggles nonzero mode, in which only transactions posting a -nonzero change are shown (hledger\-ui shows zero items by default, -unlike command\-line hledger). -.PP -Press \f[C]right\f[] (or \f[C]enter\f[]) to view the selected -transaction in detail. -.SS Transaction screen -.PP -This screen shows a single transaction, as a general journal entry, -similar to hledger\[aq]s print command and journal format -(hledger_journal(5)). -.PP -The transaction\[aq]s date(s) and any cleared flag, transaction code, -description, comments, along with all of its account postings are shown. -Simple transactions have two postings, but there can be more (or in -certain cases, fewer). -.PP -\f[C]up\f[] and \f[C]down\f[] will step through all transactions listed -in the previous account register screen. -In the title bar, the numbers in parentheses show your position within -that account register. -They will vary depending on which account register you came from -(remember most transactions appear in multiple account registers). -The #N number preceding them is the transaction\[aq]s position within -the complete unfiltered journal, which is a more stable id (at least -until the next reload). -.SS Error screen -.PP -This screen will appear if there is a problem, such as a parse error, -when you press g to reload. -Once you have fixed the problem, press g again to reload and resume -normal operation. -(Or, you can press escape to cancel the reload attempt.) -.SH ENVIRONMENT -.PP -\f[B]COLUMNS\f[] The screen width to use. -Default: the full terminal width. -.PP -\f[B]LEDGER_FILE\f[] The journal file path when not specified with -\f[C]\-f\f[]. -Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps -\f[C]C:/Users/USER/.hledger.journal\f[]). -.SH FILES -.PP -Reads data from one or more files in hledger journal, timeclock, -timedot, or CSV format specified with \f[C]\-f\f[], or -\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, -perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). -.SH BUGS -.PP -The need to precede options with \f[C]\-\-\f[] when invoked from hledger -is awkward. -.PP -\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-ui can\[aq]t read from stdin). -.PP -\f[C]\-V\f[] affects only the accounts screen. -.PP -When you press \f[C]g\f[], the current and all previous screens are -regenerated, which may cause a noticeable pause with large files. -Also there is no visual indication that this is in progress. -.PP -\f[C]\-\-watch\f[] is not yet fully robust. -It works well for normal usage, but many file changes in a short time -(eg saving the file thousands of times with an editor macro) can cause -problems at least on OSX. -Symptoms include: unresponsive UI, periodic resetting of the cursor -position, momentary display of parse errors, high CPU usage eventually -subsiding, and possibly a small but persistent build\-up of CPU usage -until the program is restarted. - - -.SH "REPORTING BUGS" -Report bugs at http://bugs.hledger.org -(or on the #hledger IRC channel or hledger mail list) - -.SH AUTHORS -Simon Michael and contributors - -.SH COPYRIGHT - -Copyright (C) 2007-2016 Simon Michael. -.br -Released under GNU GPL v3 or later. - -.SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), -hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), -ledger(1) - -http://hledger.org diff --git a/doc/hledger-ui.1.info b/doc/hledger-ui.1.info deleted file mode 100644 --- a/doc/hledger-ui.1.info +++ /dev/null @@ -1,383 +0,0 @@ -This is hledger-ui.1.info, produced by makeinfo version 6.0 from stdin. - - -File: hledger-ui.1.info, Node: Top, Next: OPTIONS, Up: (dir) - -hledger-ui(1) hledger-ui 1.4 -**************************** - -hledger-ui is hledger's curses-style interface, providing an efficient -full-window text UI for viewing accounts and transactions, and some -limited data entry capability. It is easier than hledger's command-line -interface, and sometimes quicker and more convenient than the web -interface. - - Like hledger, it reads data from one or more files in hledger -journal, timeclock, timedot, or CSV format specified with '-f', or -'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps -'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), -hledger_journal(5) etc. -* Menu: - -* OPTIONS:: -* KEYS:: -* SCREENS:: - - -File: hledger-ui.1.info, Node: OPTIONS, Next: KEYS, Prev: Top, Up: Top - -1 OPTIONS -********* - -Note: if invoking hledger-ui as a hledger subcommand, write '--' before -options as shown above. - - Any QUERYARGS are interpreted as a hledger search query which filters -the data. - -'--watch' - - watch for data and date changes and reload automatically -'--theme=default|terminal|greenterm' - - use this custom display theme -'--register=ACCTREGEX' - - start in the (first) matched account's register screen -'--change' - - show period balances (changes) at startup instead of historical - balances -'--flat' - - show full account names, unindented - - hledger input options: - -'-f FILE --file=FILE' - - use a different input file. For stdin, use - (default: - '$LEDGER_FILE' or '$HOME/.hledger.journal') -'--rules-file=RULESFILE' - - Conversion rules file to use when reading CSV (default: FILE.rules) -'--alias=OLD=NEW' - - rename accounts named OLD to NEW -'--anon' - - anonymize accounts and payees -'--pivot FIELDNAME' - - use some other field or tag for the account name -'-I --ignore-assertions' - - ignore any failing balance assertions - - hledger reporting options: - -'-b --begin=DATE' - - include postings/txns on or after this date -'-e --end=DATE' - - include postings/txns before this date -'-D --daily' - - multiperiod/multicolumn report by day -'-W --weekly' - - multiperiod/multicolumn report by week -'-M --monthly' - - multiperiod/multicolumn report by month -'-Q --quarterly' - - multiperiod/multicolumn report by quarter -'-Y --yearly' - - multiperiod/multicolumn report by year -'-p --period=PERIODEXP' - - set start date, end date, and/or reporting interval all at once - (overrides the flags above) -'--date2' - - match the secondary date instead (see command help for other - effects) -'-U --unmarked' - - include only unmarked postings/txns (can combine with -P or -C) -'-P --pending' - - include only pending postings/txns -'-C --cleared' - - include only cleared postings/txns -'-R --real' - - include only non-virtual postings -'-NUM --depth=NUM' - - hide/aggregate accounts or postings more than NUM levels deep -'-E --empty' - - show items with zero amount, normally hidden -'-B --cost' - - convert amounts to their cost at transaction time (using the - transaction price, if any) -'-V --value' - - convert amounts to their market value on the report end date (using - the most recent applicable market price, if any) - - When a reporting option appears more than once in the command line, -the last one takes precedence. - - Some reporting options can also be written as query arguments. - - hledger help options: - -'-h --help' - - show general usage (or after COMMAND, command usage) -'--version' - - show version -'--debug[=N]' - - show debug output (levels 1-9, default: 1) - - A @FILE argument will be expanded to the contents of FILE, which -should contain one command line option/argument per line. (To prevent -this, insert a '--' argument before.) - - -File: hledger-ui.1.info, Node: KEYS, Next: SCREENS, Prev: OPTIONS, Up: Top - -2 KEYS -****** - -'?' shows a help dialog listing all keys. (Some of these also appear in -the quick help at the bottom of each screen.) Press '?' again (or -'ESCAPE', or 'LEFT') to close it. The following keys work on most -screens: - - The cursor keys navigate: 'right' (or 'enter') goes deeper, 'left' -returns to the previous screen, 'up'/'down'/'page up'/'page -down'/'home'/'end' move up and down through lists. Vi-style -('h'/'j'/'k'/'l') and Emacs-style ('CTRL-p'/'CTRL-n'/'CTRL-f'/'CTRL-b') -movement keys are also supported. A tip: movement speed is limited by -your keyboard repeat rate, to move faster you may want to adjust it. -(If you're on a mac, the Karabiner app is one way to do that.) - - With shift pressed, the cursor keys adjust the report period, -limiting the transactions to be shown (by default, all are shown). -'shift-down/up' steps downward and upward through these standard report -period durations: year, quarter, month, week, day. Then, -'shift-left/right' moves to the previous/next period. 't' sets the -report period to today. With the '--watch' option, when viewing a -"current" period (the current day, week, month, quarter, or year), the -period will move automatically to track the current date. To set a -non-standard period, you can use '/' and a 'date:' query. - - '/' lets you set a general filter query limiting the data shown, -using the same query terms as in hledger and hledger-web. While editing -the query, you can use CTRL-a/e/d/k, BS, cursor keys; press 'ENTER' to -set it, or 'ESCAPE'to cancel. There are also keys for quickly adjusting -some common filters like account depth and transaction status (see -below). 'BACKSPACE' or 'DELETE' removes all filters, showing all -transactions. - - 'ESCAPE' removes all filters and jumps back to the top screen. Or, -it cancels a minibuffer edit or help dialog in progress. - - 'CTRL-l' redraws the screen and centers the selection if possible -(selections near the top won't be centered, since we don't scroll above -the top). - - 'g' reloads from the data file(s) and updates the current screen and -any previous screens. (With large files, this could cause a noticeable -pause.) - - 'I' toggles balance assertion checking. Disabling balance assertions -temporarily can be useful for troubleshooting. - - 'a' runs command-line hledger's add command, and reloads the updated -file. This allows some basic data entry. - - 'E' runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default ('emacsclient --a "" -nw') on the journal file. With some editors (emacs, vi), the -cursor will be positioned at the current transaction when invoked from -the register and transaction screens, and at the error location (if -possible) when invoked from the error screen. - - 'q' quits the application. - - Additional screen-specific keys are described below. - - -File: hledger-ui.1.info, Node: SCREENS, Prev: KEYS, Up: Top - -3 SCREENS -********* - -* Menu: - -* Accounts screen:: -* Register screen:: -* Transaction screen:: -* Error screen:: - - -File: hledger-ui.1.info, Node: Accounts screen, Next: Register screen, Up: SCREENS - -3.1 Accounts screen -=================== - -This is normally the first screen displayed. It lists accounts and -their balances, like hledger's balance command. By default, it shows -all accounts and their latest ending balances (including the balances of -subaccounts). if you specify a query on the command line, it shows just -the matched accounts and the balances from matched transactions. - - Account names are normally indented to show the hierarchy (tree -mode). To see less detail, set a depth limit by pressing a number key, -'1' to '9'. '0' shows even less detail, collapsing all accounts to a -single total. '-' and '+' (or '=') decrease and increase the depth -limit. To remove the depth limit, set it higher than the maximum -account depth, or press 'ESCAPE'. - - 'F' toggles flat mode, in which accounts are shown as a flat list, -with their full names. In this mode, account balances exclude -subaccounts, except for accounts at the depth limit (as with hledger's -balance command). - - 'H' toggles between showing historical balances or period balances. -Historical balances (the default) are ending balances at the end of the -report period, taking into account all transactions before that date -(filtered by the filter query if any), including transactions before the -start of the report period. In other words, historical balances are -what you would see on a bank statement for that account (unless -disturbed by a filter query). Period balances ignore transactions -before the report start date, so they show the change in balance during -the report period. They are more useful eg when viewing a time log. - - 'U' toggles filtering by unmarked status, including or excluding -unmarked postings in the balances. Similarly, 'P' toggles pending -postings, and 'C' toggles cleared postings. (By default, balances -include all postings; if you activate one or two status filters, only -those postings are included; and if you activate all three, the filter -is removed.) - - 'R' toggles real mode, in which virtual postings are ignored. - - 'Z' toggles nonzero mode, in which only accounts with nonzero -balances are shown (hledger-ui shows zero items by default, unlike -command-line hledger). - - Press 'right' or 'enter' to view an account's transactions register. - - -File: hledger-ui.1.info, Node: Register screen, Next: Transaction screen, Prev: Accounts screen, Up: SCREENS - -3.2 Register screen -=================== - -This screen shows the transactions affecting a particular account, like -a check register. Each line represents one transaction and shows: - - * the other account(s) involved, in abbreviated form. (If there are - both real and virtual postings, it shows only the accounts affected - by real postings.) - - * the overall change to the current account's balance; positive for - an inflow to this account, negative for an outflow. - - * the running historical total or period total for the current - account, after the transaction. This can be toggled with 'H'. - Similar to the accounts screen, the historical total is affected by - transactions (filtered by the filter query) before the report start - date, while the period total is not. If the historical total is - not disturbed by a filter query, it will be the running historical - balance you would see on a bank register for the current account. - - If the accounts screen was in tree mode, the register screen will -include transactions from both the current account and its subaccounts. -If the accounts screen was in flat mode, and a non-depth-clipped account -was selected, the register screen will exclude transactions from -subaccounts. In other words, the register always shows the transactions -responsible for the period balance shown on the accounts screen. As on -the accounts screen, this can be toggled with 'F'. - - 'U' toggles filtering by unmarked status, showing or hiding unmarked -transactions. Similarly, 'P' toggles pending transactions, and 'C' -toggles cleared transactions. (By default, transactions with all -statuses are shown; if you activate one or two status filters, only -those transactions are shown; and if you activate all three, the filter -is removed.)q - - 'R' toggles real mode, in which virtual postings are ignored. - - 'Z' toggles nonzero mode, in which only transactions posting a -nonzero change are shown (hledger-ui shows zero items by default, unlike -command-line hledger). - - Press 'right' (or 'enter') to view the selected transaction in -detail. - - -File: hledger-ui.1.info, Node: Transaction screen, Next: Error screen, Prev: Register screen, Up: SCREENS - -3.3 Transaction screen -====================== - -This screen shows a single transaction, as a general journal entry, -similar to hledger's print command and journal format -(hledger_journal(5)). - - The transaction's date(s) and any cleared flag, transaction code, -description, comments, along with all of its account postings are shown. -Simple transactions have two postings, but there can be more (or in -certain cases, fewer). - - 'up' and 'down' will step through all transactions listed in the -previous account register screen. In the title bar, the numbers in -parentheses show your position within that account register. They will -vary depending on which account register you came from (remember most -transactions appear in multiple account registers). The #N number -preceding them is the transaction's position within the complete -unfiltered journal, which is a more stable id (at least until the next -reload). - - -File: hledger-ui.1.info, Node: Error screen, Prev: Transaction screen, Up: SCREENS - -3.4 Error screen -================ - -This screen will appear if there is a problem, such as a parse error, -when you press g to reload. Once you have fixed the problem, press g -again to reload and resume normal operation. (Or, you can press escape -to cancel the reload attempt.) - - -Tag Table: -Node: Top73 -Node: OPTIONS825 -Ref: #options924 -Node: KEYS3861 -Ref: #keys3958 -Node: SCREENS6754 -Ref: #screens6841 -Node: Accounts screen6931 -Ref: #accounts-screen7061 -Node: Register screen9291 -Ref: #register-screen9448 -Node: Transaction screen11522 -Ref: #transaction-screen11682 -Node: Error screen12552 -Ref: #error-screen12676 - -End Tag Table diff --git a/doc/hledger-ui.1.txt b/doc/hledger-ui.1.txt deleted file mode 100644 --- a/doc/hledger-ui.1.txt +++ /dev/null @@ -1,376 +0,0 @@ - -hledger-ui(1) hledger User Manuals hledger-ui(1) - - - -NAME - hledger-ui - curses-style interface for the hledger accounting tool - -SYNOPSIS - hledger-ui [OPTIONS] [QUERYARGS] - hledger ui -- [OPTIONS] [QUERYARGS] - -DESCRIPTION - hledger is a cross-platform program for tracking money, time, or any - other commodity, using double-entry accounting and a simple, editable - file format. hledger is inspired by and largely compatible with - ledger(1). - - hledger-ui is hledger's curses-style interface, providing an efficient - full-window text UI for viewing accounts and transactions, and some - limited data entry capability. It is easier than hledger's com- - mand-line interface, and sometimes quicker and more convenient than the - web interface. - - Like hledger, it reads data from one or more files in hledger journal, - timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, - or $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). For more about this see hledger(1), - hledger_journal(5) etc. - -OPTIONS - Note: if invoking hledger-ui as a hledger subcommand, write -- before - options as shown above. - - Any QUERYARGS are interpreted as a hledger search query which filters - the data. - - --watch - watch for data and date changes and reload automatically - - --theme=default|terminal|greenterm - use this custom display theme - - --register=ACCTREGEX - start in the (first) matched account's register screen - - --change - show period balances (changes) at startup instead of historical - balances - - --flat show full account names, unindented - - hledger input options: - - -f FILE --file=FILE - use a different input file. For stdin, use - (default: - $LEDGER_FILE or $HOME/.hledger.journal) - - --rules-file=RULESFILE - Conversion rules file to use when reading CSV (default: - FILE.rules) - - --alias=OLD=NEW - rename accounts named OLD to NEW - - --anon anonymize accounts and payees - - --pivot FIELDNAME - use some other field or tag for the account name - - -I --ignore-assertions - ignore any failing balance assertions - - hledger reporting options: - - -b --begin=DATE - include postings/txns on or after this date - - -e --end=DATE - include postings/txns before this date - - -D --daily - multiperiod/multicolumn report by day - - -W --weekly - multiperiod/multicolumn report by week - - -M --monthly - multiperiod/multicolumn report by month - - -Q --quarterly - multiperiod/multicolumn report by quarter - - -Y --yearly - multiperiod/multicolumn report by year - - -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once - (overrides the flags above) - - --date2 - match the secondary date instead (see command help for other - effects) - - -U --unmarked - include only unmarked postings/txns (can combine with -P or -C) - - -P --pending - include only pending postings/txns - - -C --cleared - include only cleared postings/txns - - -R --real - include only non-virtual postings - - -NUM --depth=NUM - hide/aggregate accounts or postings more than NUM levels deep - - -E --empty - show items with zero amount, normally hidden - - -B --cost - convert amounts to their cost at transaction time (using the - transaction price, if any) - - -V --value - convert amounts to their market value on the report end date - (using the most recent applicable market price, if any) - - When a reporting option appears more than once in the command line, the - last one takes precedence. - - Some reporting options can also be written as query arguments. - - hledger help options: - - -h --help - show general usage (or after COMMAND, command usage) - - --version - show version - - --debug[=N] - show debug output (levels 1-9, default: 1) - - A @FILE argument will be expanded to the contents of FILE, which should - contain one command line option/argument per line. (To prevent this, - insert a -- argument before.) - -KEYS - ? shows a help dialog listing all keys. (Some of these also appear in - the quick help at the bottom of each screen.) Press ? again (or ESCAPE, - or LEFT) to close it. The following keys work on most screens: - - The cursor keys navigate: right (or enter) goes deeper, left returns to - the previous screen, up/down/page up/page down/home/end move up and - down through lists. Vi-style (h/j/k/l) and Emacs-style - (CTRL-p/CTRL-n/CTRL-f/CTRL-b) movement keys are also supported. A tip: - movement speed is limited by your keyboard repeat rate, to move faster - you may want to adjust it. (If you're on a mac, the Karabiner app is - one way to do that.) - - With shift pressed, the cursor keys adjust the report period, limiting - the transactions to be shown (by default, all are shown). - shift-down/up steps downward and upward through these standard report - period durations: year, quarter, month, week, day. Then, - shift-left/right moves to the previous/next period. t sets the report - period to today. With the --watch option, when viewing a "current" - period (the current day, week, month, quarter, or year), the period - will move automatically to track the current date. To set a non-stan- - dard period, you can use / and a date: query. - - / lets you set a general filter query limiting the data shown, using - the same query terms as in hledger and hledger-web. While editing the - query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set - it, or ESCAPEto cancel. There are also keys for quickly adjusting some - common filters like account depth and transaction status (see below). - BACKSPACE or DELETE removes all filters, showing all transactions. - - ESCAPE removes all filters and jumps back to the top screen. Or, it - cancels a minibuffer edit or help dialog in progress. - - CTRL-l redraws the screen and centers the selection if possible (selec- - tions near the top won't be centered, since we don't scroll above the - top). - - g reloads from the data file(s) and updates the current screen and any - previous screens. (With large files, this could cause a noticeable - pause.) - - I toggles balance assertion checking. Disabling balance assertions - temporarily can be useful for troubleshooting. - - a runs command-line hledger's add command, and reloads the updated - file. This allows some basic data entry. - - E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac- - sclient -a "" -nw) on the journal file. With some editors (emacs, vi), - the cursor will be positioned at the current transaction when invoked - from the register and transaction screens, and at the error location - (if possible) when invoked from the error screen. - - q quits the application. - - Additional screen-specific keys are described below. - -SCREENS - Accounts screen - This is normally the first screen displayed. It lists accounts and - their balances, like hledger's balance command. By default, it shows - all accounts and their latest ending balances (including the balances - of subaccounts). if you specify a query on the command line, it shows - just the matched accounts and the balances from matched transactions. - - Account names are normally indented to show the hierarchy (tree mode). - To see less detail, set a depth limit by pressing a number key, 1 to 9. - 0 shows even less detail, collapsing all accounts to a single total. - - and + (or =) decrease and increase the depth limit. To remove the - depth limit, set it higher than the maximum account depth, or press - ESCAPE. - - F toggles flat mode, in which accounts are shown as a flat list, with - their full names. In this mode, account balances exclude subaccounts, - except for accounts at the depth limit (as with hledger's balance com- - mand). - - H toggles between showing historical balances or period balances. His- - torical balances (the default) are ending balances at the end of the - report period, taking into account all transactions before that date - (filtered by the filter query if any), including transactions before - the start of the report period. In other words, historical balances - are what you would see on a bank statement for that account (unless - disturbed by a filter query). Period balances ignore transactions - before the report start date, so they show the change in balance during - the report period. They are more useful eg when viewing a time log. - - U toggles filtering by unmarked status, including or excluding unmarked - postings in the balances. Similarly, P toggles pending postings, and C - toggles cleared postings. (By default, balances include all postings; - if you activate one or two status filters, only those postings are - included; and if you activate all three, the filter is removed.) - - R toggles real mode, in which virtual postings are ignored. - - Z toggles nonzero mode, in which only accounts with nonzero balances - are shown (hledger-ui shows zero items by default, unlike command-line - hledger). - - Press right or enter to view an account's transactions register. - - Register screen - This screen shows the transactions affecting a particular account, like - a check register. Each line represents one transaction and shows: - - o the other account(s) involved, in abbreviated form. (If there are - both real and virtual postings, it shows only the accounts affected - by real postings.) - - o the overall change to the current account's balance; positive for an - inflow to this account, negative for an outflow. - - o the running historical total or period total for the current account, - after the transaction. This can be toggled with H. Similar to the - accounts screen, the historical total is affected by transactions - (filtered by the filter query) before the report start date, while - the period total is not. If the historical total is not disturbed by - a filter query, it will be the running historical balance you would - see on a bank register for the current account. - - If the accounts screen was in tree mode, the register screen will - include transactions from both the current account and its subaccounts. - If the accounts screen was in flat mode, and a non-depth-clipped - account was selected, the register screen will exclude transactions - from subaccounts. In other words, the register always shows the trans- - actions responsible for the period balance shown on the accounts - screen. As on the accounts screen, this can be toggled with F. - - U toggles filtering by unmarked status, showing or hiding unmarked - transactions. Similarly, P toggles pending transactions, and C toggles - cleared transactions. (By default, transactions with all statuses are - shown; if you activate one or two status filters, only those transac- - tions are shown; and if you activate all three, the filter is - removed.)q - - R toggles real mode, in which virtual postings are ignored. - - Z toggles nonzero mode, in which only transactions posting a nonzero - change are shown (hledger-ui shows zero items by default, unlike com- - mand-line hledger). - - Press right (or enter) to view the selected transaction in detail. - - Transaction screen - This screen shows a single transaction, as a general journal entry, - similar to hledger's print command and journal format (hledger_jour- - nal(5)). - - The transaction's date(s) and any cleared flag, transaction code, - description, comments, along with all of its account postings are - shown. Simple transactions have two postings, but there can be more - (or in certain cases, fewer). - - up and down will step through all transactions listed in the previous - account register screen. In the title bar, the numbers in parentheses - show your position within that account register. They will vary - depending on which account register you came from (remember most trans- - actions appear in multiple account registers). The #N number preceding - them is the transaction's position within the complete unfiltered jour- - nal, which is a more stable id (at least until the next reload). - - Error screen - This screen will appear if there is a problem, such as a parse error, - when you press g to reload. Once you have fixed the problem, press g - again to reload and resume normal operation. (Or, you can press escape - to cancel the reload attempt.) - -ENVIRONMENT - COLUMNS The screen width to use. Default: the full terminal width. - - LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- - nal). - -FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps - C:/Users/USER/.hledger.journal). - -BUGS - The need to precede options with -- when invoked from hledger is awk- - ward. - - -f- doesn't work (hledger-ui can't read from stdin). - - -V affects only the accounts screen. - - When you press g, the current and all previous screens are regenerated, - which may cause a noticeable pause with large files. Also there is no - visual indication that this is in progress. - - --watch is not yet fully robust. It works well for normal usage, but - many file changes in a short time (eg saving the file thousands of - times with an editor macro) can cause problems at least on OSX. Symp- - toms include: unresponsive UI, periodic resetting of the cursor posi- - tion, momentary display of parse errors, high CPU usage eventually sub- - siding, and possibly a small but persistent build-up of CPU usage until - the program is restarted. - - - -REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel - or hledger mail list) - - -AUTHORS - Simon Michael and contributors - - -COPYRIGHT - Copyright (C) 2007-2016 Simon Michael. - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), - hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- - dot(5), ledger(1) - - http://hledger.org - - - -hledger-ui 1.4 September 2017 hledger-ui(1) diff --git a/hledger-ui.1 b/hledger-ui.1 new file mode 100644 --- /dev/null +++ b/hledger-ui.1 @@ -0,0 +1,485 @@ + +.TH "hledger\-ui" "1" "December 2017" "hledger\-ui 1.5" "hledger User Manuals" + + + +.SH NAME +.PP +hledger\-ui \- curses\-style interface for the hledger accounting tool +.SH SYNOPSIS +.PP +\f[C]hledger\-ui\ [OPTIONS]\ [QUERYARGS]\f[] +.PD 0 +.P +.PD +\f[C]hledger\ ui\ \-\-\ [OPTIONS]\ [QUERYARGS]\f[] +.SH DESCRIPTION +.PP +hledger is a cross\-platform program for tracking money, time, or any +other commodity, using double\-entry accounting and a simple, editable +file format. +hledger is inspired by and largely compatible with ledger(1). +.PP +hledger\-ui is hledger's curses\-style interface, providing an efficient +full\-window text UI for viewing accounts and transactions, and some +limited data entry capability. +It is easier than hledger's command\-line interface, and sometimes +quicker and more convenient than the web interface. +.PP +Like hledger, it reads data from one or more files in hledger journal, +timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or +\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, +perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). +For more about this see hledger(1), hledger_journal(5) etc. +.SH OPTIONS +.PP +Note: if invoking hledger\-ui as a hledger subcommand, write +\f[C]\-\-\f[] before options as shown above. +.PP +Any QUERYARGS are interpreted as a hledger search query which filters +the data. +.TP +.B \f[C]\-\-watch\f[] +watch for data and date changes and reload automatically +.RS +.RE +.TP +.B \f[C]\-\-theme=default|terminal|greenterm\f[] +use this custom display theme +.RS +.RE +.TP +.B \f[C]\-\-register=ACCTREGEX\f[] +start in the (first) matched account's register screen +.RS +.RE +.TP +.B \f[C]\-\-change\f[] +show period balances (changes) at startup instead of historical balances +.RS +.RE +.TP +.B \f[C]\-\-flat\f[] +show full account names, unindented +.RS +.RE +.PP +hledger input options: +.TP +.B \f[C]\-f\ FILE\ \-\-file=FILE\f[] +use a different input file. +For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or +\f[C]$HOME/.hledger.journal\f[]) +.RS +.RE +.TP +.B \f[C]\-\-rules\-file=RULESFILE\f[] +Conversion rules file to use when reading CSV (default: FILE.rules) +.RS +.RE +.TP +.B \f[C]\-\-alias=OLD=NEW\f[] +rename accounts named OLD to NEW +.RS +.RE +.TP +.B \f[C]\-\-anon\f[] +anonymize accounts and payees +.RS +.RE +.TP +.B \f[C]\-\-pivot\ FIELDNAME\f[] +use some other field or tag for the account name +.RS +.RE +.TP +.B \f[C]\-I\ \-\-ignore\-assertions\f[] +ignore any failing balance assertions +.RS +.RE +.PP +hledger reporting options: +.TP +.B \f[C]\-b\ \-\-begin=DATE\f[] +include postings/txns on or after this date +.RS +.RE +.TP +.B \f[C]\-e\ \-\-end=DATE\f[] +include postings/txns before this date +.RS +.RE +.TP +.B \f[C]\-D\ \-\-daily\f[] +multiperiod/multicolumn report by day +.RS +.RE +.TP +.B \f[C]\-W\ \-\-weekly\f[] +multiperiod/multicolumn report by week +.RS +.RE +.TP +.B \f[C]\-M\ \-\-monthly\f[] +multiperiod/multicolumn report by month +.RS +.RE +.TP +.B \f[C]\-Q\ \-\-quarterly\f[] +multiperiod/multicolumn report by quarter +.RS +.RE +.TP +.B \f[C]\-Y\ \-\-yearly\f[] +multiperiod/multicolumn report by year +.RS +.RE +.TP +.B \f[C]\-p\ \-\-period=PERIODEXP\f[] +set start date, end date, and/or reporting interval all at once using +period expressions syntax (overrides the flags above) +.RS +.RE +.TP +.B \f[C]\-\-date2\f[] +match the secondary date instead (see command help for other effects) +.RS +.RE +.TP +.B \f[C]\-U\ \-\-unmarked\f[] +include only unmarked postings/txns (can combine with \-P or \-C) +.RS +.RE +.TP +.B \f[C]\-P\ \-\-pending\f[] +include only pending postings/txns +.RS +.RE +.TP +.B \f[C]\-C\ \-\-cleared\f[] +include only cleared postings/txns +.RS +.RE +.TP +.B \f[C]\-R\ \-\-real\f[] +include only non\-virtual postings +.RS +.RE +.TP +.B \f[C]\-NUM\ \-\-depth=NUM\f[] +hide/aggregate accounts or postings more than NUM levels deep +.RS +.RE +.TP +.B \f[C]\-E\ \-\-empty\f[] +show items with zero amount, normally hidden +.RS +.RE +.TP +.B \f[C]\-B\ \-\-cost\f[] +convert amounts to their cost at transaction time (using the transaction +price, if any) +.RS +.RE +.TP +.B \f[C]\-V\ \-\-value\f[] +convert amounts to their market value on the report end date (using the +most recent applicable market price, if any) +.RS +.RE +.TP +.B \f[C]\-\-auto\f[] +apply automated posting rules to modify transactions. +.RS +.RE +.TP +.B \f[C]\-\-forecast\f[] +apply periodic transaction rules to generate future transactions, to 6 +months from now or report end date. +.RS +.RE +.PP +When a reporting option appears more than once in the command line, the +last one takes precedence. +.PP +Some reporting options can also be written as query arguments. +.PP +hledger help options: +.TP +.B \f[C]\-h\ \-\-help\f[] +show general usage (or after COMMAND, command usage) +.RS +.RE +.TP +.B \f[C]\-\-version\f[] +show version +.RS +.RE +.TP +.B \f[C]\-\-debug[=N]\f[] +show debug output (levels 1\-9, default: 1) +.RS +.RE +.PP +A \@FILE argument will be expanded to the contents of FILE, which should +contain one command line option/argument per line. +(To prevent this, insert a \f[C]\-\-\f[] argument before.) +.SH KEYS +.PP +\f[C]?\f[] shows a help dialog listing all keys. +(Some of these also appear in the quick help at the bottom of each +screen.) Press \f[C]?\f[] again (or \f[C]ESCAPE\f[], or \f[C]LEFT\f[]) +to close it. +The following keys work on most screens: +.PP +The cursor keys navigate: \f[C]right\f[] (or \f[C]enter\f[]) goes +deeper, \f[C]left\f[] returns to the previous screen, +\f[C]up\f[]/\f[C]down\f[]/\f[C]page\ up\f[]/\f[C]page\ down\f[]/\f[C]home\f[]/\f[C]end\f[] +move up and down through lists. +Vi\-style (\f[C]h\f[]/\f[C]j\f[]/\f[C]k\f[]/\f[C]l\f[]) and Emacs\-style +(\f[C]CTRL\-p\f[]/\f[C]CTRL\-n\f[]/\f[C]CTRL\-f\f[]/\f[C]CTRL\-b\f[]) +movement keys are also supported. +A tip: movement speed is limited by your keyboard repeat rate, to move +faster you may want to adjust it. +(If you're on a mac, the Karabiner app is one way to do that.) +.PP +With shift pressed, the cursor keys adjust the report period, limiting +the transactions to be shown (by default, all are shown). +\f[C]shift\-down/up\f[] steps downward and upward through these standard +report period durations: year, quarter, month, week, day. +Then, \f[C]shift\-left/right\f[] moves to the previous/next period. +\f[C]t\f[] sets the report period to today. +With the \f[C]\-\-watch\f[] option, when viewing a \[lq]current\[rq] +period (the current day, week, month, quarter, or year), the period will +move automatically to track the current date. +To set a non\-standard period, you can use \f[C]/\f[] and a +\f[C]date:\f[] query. +.PP +\f[C]/\f[] lets you set a general filter query limiting the data shown, +using the same query terms as in hledger and hledger\-web. +While editing the query, you can use CTRL\-a/e/d/k, BS, cursor keys; +press \f[C]ENTER\f[] to set it, or \f[C]ESCAPE\f[]to cancel. +There are also keys for quickly adjusting some common filters like +account depth and transaction status (see below). +\f[C]BACKSPACE\f[] or \f[C]DELETE\f[] removes all filters, showing all +transactions. +.PP +\f[C]ESCAPE\f[] removes all filters and jumps back to the top screen. +Or, it cancels a minibuffer edit or help dialog in progress. +.PP +\f[C]CTRL\-l\f[] redraws the screen and centers the selection if +possible (selections near the top won't be centered, since we don't +scroll above the top). +.PP +\f[C]g\f[] reloads from the data file(s) and updates the current screen +and any previous screens. +(With large files, this could cause a noticeable pause.) +.PP +\f[C]I\f[] toggles balance assertion checking. +Disabling balance assertions temporarily can be useful for +troubleshooting. +.PP +\f[C]a\f[] runs command\-line hledger's add command, and reloads the +updated file. +This allows some basic data entry. +.PP +\f[C]A\f[] is like \f[C]a\f[], but runs the hledger\-iadd tool, which +provides a curses\-style interface. +This key will be available if \f[C]hledger\-iadd\f[] is installed in +$PATH. +.PP +\f[C]E\f[] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default +(\f[C]emacsclient\ \-a\ ""\ \-nw\f[]) on the journal file. +With some editors (emacs, vi), the cursor will be positioned at the +current transaction when invoked from the register and transaction +screens, and at the error location (if possible) when invoked from the +error screen. +.PP +\f[C]q\f[] quits the application. +.PP +Additional screen\-specific keys are described below. +.SH SCREENS +.SS Accounts screen +.PP +This is normally the first screen displayed. +It lists accounts and their balances, like hledger's balance command. +By default, it shows all accounts and their latest ending balances +(including the balances of subaccounts). +if you specify a query on the command line, it shows just the matched +accounts and the balances from matched transactions. +.PP +Account names are normally indented to show the hierarchy (tree mode). +To see less detail, set a depth limit by pressing a number key, +\f[C]1\f[] to \f[C]9\f[]. +\f[C]0\f[] shows even less detail, collapsing all accounts to a single +total. +\f[C]\-\f[] and \f[C]+\f[] (or \f[C]=\f[]) decrease and increase the +depth limit. +To remove the depth limit, set it higher than the maximum account depth, +or press \f[C]ESCAPE\f[]. +.PP +\f[C]F\f[] toggles flat mode, in which accounts are shown as a flat +list, with their full names. +In this mode, account balances exclude subaccounts, except for accounts +at the depth limit (as with hledger's balance command). +.PP +\f[C]H\f[] toggles between showing historical balances or period +balances. +Historical balances (the default) are ending balances at the end of the +report period, taking into account all transactions before that date +(filtered by the filter query if any), including transactions before the +start of the report period. +In other words, historical balances are what you would see on a bank +statement for that account (unless disturbed by a filter query). +Period balances ignore transactions before the report start date, so +they show the change in balance during the report period. +They are more useful eg when viewing a time log. +.PP +\f[C]U\f[] toggles filtering by unmarked status, including or excluding +unmarked postings in the balances. +Similarly, \f[C]P\f[] toggles pending postings, and \f[C]C\f[] toggles +cleared postings. +(By default, balances include all postings; if you activate one or two +status filters, only those postings are included; and if you activate +all three, the filter is removed.) +.PP +\f[C]R\f[] toggles real mode, in which virtual postings are ignored. +.PP +\f[C]Z\f[] toggles nonzero mode, in which only accounts with nonzero +balances are shown (hledger\-ui shows zero items by default, unlike +command\-line hledger). +.PP +Press \f[C]right\f[] or \f[C]enter\f[] to view an account's transactions +register. +.SS Register screen +.PP +This screen shows the transactions affecting a particular account, like +a check register. +Each line represents one transaction and shows: +.IP \[bu] 2 +the other account(s) involved, in abbreviated form. +(If there are both real and virtual postings, it shows only the accounts +affected by real postings.) +.IP \[bu] 2 +the overall change to the current account's balance; positive for an +inflow to this account, negative for an outflow. +.IP \[bu] 2 +the running historical total or period total for the current account, +after the transaction. +This can be toggled with \f[C]H\f[]. +Similar to the accounts screen, the historical total is affected by +transactions (filtered by the filter query) before the report start +date, while the period total is not. +If the historical total is not disturbed by a filter query, it will be +the running historical balance you would see on a bank register for the +current account. +.PP +If the accounts screen was in tree mode, the register screen will +include transactions from both the current account and its subaccounts. +If the accounts screen was in flat mode, and a non\-depth\-clipped +account was selected, the register screen will exclude transactions from +subaccounts. +In other words, the register always shows the transactions responsible +for the period balance shown on the accounts screen. +As on the accounts screen, this can be toggled with \f[C]F\f[]. +.PP +\f[C]U\f[] toggles filtering by unmarked status, showing or hiding +unmarked transactions. +Similarly, \f[C]P\f[] toggles pending transactions, and \f[C]C\f[] +toggles cleared transactions. +(By default, transactions with all statuses are shown; if you activate +one or two status filters, only those transactions are shown; and if you +activate all three, the filter is removed.)q +.PP +\f[C]R\f[] toggles real mode, in which virtual postings are ignored. +.PP +\f[C]Z\f[] toggles nonzero mode, in which only transactions posting a +nonzero change are shown (hledger\-ui shows zero items by default, +unlike command\-line hledger). +.PP +Press \f[C]right\f[] (or \f[C]enter\f[]) to view the selected +transaction in detail. +.SS Transaction screen +.PP +This screen shows a single transaction, as a general journal entry, +similar to hledger's print command and journal format +(hledger_journal(5)). +.PP +The transaction's date(s) and any cleared flag, transaction code, +description, comments, along with all of its account postings are shown. +Simple transactions have two postings, but there can be more (or in +certain cases, fewer). +.PP +\f[C]up\f[] and \f[C]down\f[] will step through all transactions listed +in the previous account register screen. +In the title bar, the numbers in parentheses show your position within +that account register. +They will vary depending on which account register you came from +(remember most transactions appear in multiple account registers). +The #N number preceding them is the transaction's position within the +complete unfiltered journal, which is a more stable id (at least until +the next reload). +.SS Error screen +.PP +This screen will appear if there is a problem, such as a parse error, +when you press g to reload. +Once you have fixed the problem, press g again to reload and resume +normal operation. +(Or, you can press escape to cancel the reload attempt.) +.SH ENVIRONMENT +.PP +\f[B]COLUMNS\f[] The screen width to use. +Default: the full terminal width. +.PP +\f[B]LEDGER_FILE\f[] The journal file path when not specified with +\f[C]\-f\f[]. +Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps +\f[C]C:/Users/USER/.hledger.journal\f[]). +.SH FILES +.PP +Reads data from one or more files in hledger journal, timeclock, +timedot, or CSV format specified with \f[C]\-f\f[], or +\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, +perhaps \f[C]C:/Users/USER/.hledger.journal\f[]). +.SH BUGS +.PP +The need to precede options with \f[C]\-\-\f[] when invoked from hledger +is awkward. +.PP +\f[C]\-f\-\f[] doesn't work (hledger\-ui can't read from stdin). +.PP +\f[C]\-V\f[] affects only the accounts screen. +.PP +When you press \f[C]g\f[], the current and all previous screens are +regenerated, which may cause a noticeable pause with large files. +Also there is no visual indication that this is in progress. +.PP +\f[C]\-\-watch\f[] is not yet fully robust. +It works well for normal usage, but many file changes in a short time +(eg saving the file thousands of times with an editor macro) can cause +problems at least on OSX. +Symptoms include: unresponsive UI, periodic resetting of the cursor +position, momentary display of parse errors, high CPU usage eventually +subsiding, and possibly a small but persistent build\-up of CPU usage +until the program is restarted. + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org +(or on the #hledger IRC channel or hledger mail list) + +.SH AUTHORS +Simon Michael and contributors + +.SH COPYRIGHT + +Copyright (C) 2007-2016 Simon Michael. +.br +Released under GNU GPL v3 or later. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1), +hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5), +ledger(1) + +http://hledger.org diff --git a/hledger-ui.cabal b/hledger-ui.cabal --- a/hledger-ui.cabal +++ b/hledger-ui.cabal @@ -1,9 +1,11 @@ --- This file has been generated from package.yaml by hpack version 0.17.1. +-- This file has been generated from package.yaml by hpack version 0.20.0. -- -- see: https://github.com/sol/hpack +-- +-- hash: 0415bc39f4fbc4cec62ff37e03c0ff513b23cd4825310c799a42177cd9245f1e name: hledger-ui -version: 1.4 +version: 1.5 synopsis: Curses-style user interface for the hledger accounting tool description: This is hledger's curses-style interface. It is simpler and more convenient for browsing data than the command-line interface, @@ -32,9 +34,9 @@ README data-files: - doc/hledger-ui.1 - doc/hledger-ui.1.info - doc/hledger-ui.1.txt + hledger-ui.1 + hledger-ui.info + hledger-ui.txt source-repository head type: git @@ -50,39 +52,39 @@ hs-source-dirs: ./. ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans - cpp-options: -DVERSION="1.4" + cpp-options: -DVERSION="1.5" build-depends: - hledger >= 1.4 && < 1.5 - , hledger-lib >= 1.4 && < 1.5 - , ansi-terminal >= 0.6.2.3 && < 0.8 + HUnit + , ansi-terminal >=0.6.2.3 , async - , base >= 4.8 && < 5 - , base-compat >= 0.8.1 - , cmdargs >= 0.8 + , base >=4.8 && <5 + , base-compat >=0.8.1 + , cmdargs >=0.8 , containers , data-default , directory , filepath - , fsnotify >= 0.2 && < 0.3 - , HUnit - , microlens >= 0.4 && < 0.5 - , microlens-platform >= 0.2.3.1 && < 0.4 - , megaparsec >=5.0 && < 6.2 + , fsnotify >=0.2 + , hledger >=1.5 && <1.6 + , hledger-lib >=1.5 && <1.6 + , megaparsec >=5.0 + , microlens >=0.4 + , microlens-platform >=0.2.3.1 , pretty-show >=1.6.4 - , process >= 1.2 - , safe >= 0.2 - , split >= 0.1 && < 0.3 - , text >= 1.2 && < 1.3 - , text-zipper >= 0.4 && < 0.11 - , time >= 1.5 + , process >=1.2 + , safe >=0.2 + , split >=0.1 + , text >=1.2 + , text-zipper >=0.4 + , time >=1.5 , transformers , vector if os(windows) buildable: False else build-depends: - brick >= 0.12 && < 0.25 - , vty >= 5.5 && < 5.18 + brick >=0.12 + , vty >=5.5 if flag(threaded) ghc-options: -threaded other-modules: @@ -98,4 +100,5 @@ Hledger.UI.UIState Hledger.UI.UITypes Hledger.UI.UIUtils + Paths_hledger_ui default-language: Haskell2010 diff --git a/hledger-ui.info b/hledger-ui.info new file mode 100644 --- /dev/null +++ b/hledger-ui.info @@ -0,0 +1,394 @@ +This is hledger-ui.info, produced by makeinfo version 6.5 from stdin. + + +File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir) + +hledger-ui(1) hledger-ui 1.5 +**************************** + +hledger-ui is hledger's curses-style interface, providing an efficient +full-window text UI for viewing accounts and transactions, and some +limited data entry capability. It is easier than hledger's command-line +interface, and sometimes quicker and more convenient than the web +interface. + + Like hledger, it reads data from one or more files in hledger +journal, timeclock, timedot, or CSV format specified with '-f', or +'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps +'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), +hledger_journal(5) etc. +* Menu: + +* OPTIONS:: +* KEYS:: +* SCREENS:: + + +File: hledger-ui.info, Node: OPTIONS, Next: KEYS, Prev: Top, Up: Top + +1 OPTIONS +********* + +Note: if invoking hledger-ui as a hledger subcommand, write '--' before +options as shown above. + + Any QUERYARGS are interpreted as a hledger search query which filters +the data. + +'--watch' + + watch for data and date changes and reload automatically +'--theme=default|terminal|greenterm' + + use this custom display theme +'--register=ACCTREGEX' + + start in the (first) matched account's register screen +'--change' + + show period balances (changes) at startup instead of historical + balances +'--flat' + + show full account names, unindented + + hledger input options: + +'-f FILE --file=FILE' + + use a different input file. For stdin, use - (default: + '$LEDGER_FILE' or '$HOME/.hledger.journal') +'--rules-file=RULESFILE' + + Conversion rules file to use when reading CSV (default: FILE.rules) +'--alias=OLD=NEW' + + rename accounts named OLD to NEW +'--anon' + + anonymize accounts and payees +'--pivot FIELDNAME' + + use some other field or tag for the account name +'-I --ignore-assertions' + + ignore any failing balance assertions + + hledger reporting options: + +'-b --begin=DATE' + + include postings/txns on or after this date +'-e --end=DATE' + + include postings/txns before this date +'-D --daily' + + multiperiod/multicolumn report by day +'-W --weekly' + + multiperiod/multicolumn report by week +'-M --monthly' + + multiperiod/multicolumn report by month +'-Q --quarterly' + + multiperiod/multicolumn report by quarter +'-Y --yearly' + + multiperiod/multicolumn report by year +'-p --period=PERIODEXP' + + set start date, end date, and/or reporting interval all at once + using period expressions syntax (overrides the flags above) +'--date2' + + match the secondary date instead (see command help for other + effects) +'-U --unmarked' + + include only unmarked postings/txns (can combine with -P or -C) +'-P --pending' + + include only pending postings/txns +'-C --cleared' + + include only cleared postings/txns +'-R --real' + + include only non-virtual postings +'-NUM --depth=NUM' + + hide/aggregate accounts or postings more than NUM levels deep +'-E --empty' + + show items with zero amount, normally hidden +'-B --cost' + + convert amounts to their cost at transaction time (using the + transaction price, if any) +'-V --value' + + convert amounts to their market value on the report end date (using + the most recent applicable market price, if any) +'--auto' + + apply automated posting rules to modify transactions. +'--forecast' + + apply periodic transaction rules to generate future transactions, + to 6 months from now or report end date. + + When a reporting option appears more than once in the command line, +the last one takes precedence. + + Some reporting options can also be written as query arguments. + + hledger help options: + +'-h --help' + + show general usage (or after COMMAND, command usage) +'--version' + + show version +'--debug[=N]' + + show debug output (levels 1-9, default: 1) + + A @FILE argument will be expanded to the contents of FILE, which +should contain one command line option/argument per line. (To prevent +this, insert a '--' argument before.) + + +File: hledger-ui.info, Node: KEYS, Next: SCREENS, Prev: OPTIONS, Up: Top + +2 KEYS +****** + +'?' shows a help dialog listing all keys. (Some of these also appear in +the quick help at the bottom of each screen.) Press '?' again (or +'ESCAPE', or 'LEFT') to close it. The following keys work on most +screens: + + The cursor keys navigate: 'right' (or 'enter') goes deeper, 'left' +returns to the previous screen, 'up'/'down'/'page up'/'page +down'/'home'/'end' move up and down through lists. Vi-style +('h'/'j'/'k'/'l') and Emacs-style ('CTRL-p'/'CTRL-n'/'CTRL-f'/'CTRL-b') +movement keys are also supported. A tip: movement speed is limited by +your keyboard repeat rate, to move faster you may want to adjust it. +(If you're on a mac, the Karabiner app is one way to do that.) + + With shift pressed, the cursor keys adjust the report period, +limiting the transactions to be shown (by default, all are shown). +'shift-down/up' steps downward and upward through these standard report +period durations: year, quarter, month, week, day. Then, +'shift-left/right' moves to the previous/next period. 't' sets the +report period to today. With the '--watch' option, when viewing a +"current" period (the current day, week, month, quarter, or year), the +period will move automatically to track the current date. To set a +non-standard period, you can use '/' and a 'date:' query. + + '/' lets you set a general filter query limiting the data shown, +using the same query terms as in hledger and hledger-web. While editing +the query, you can use CTRL-a/e/d/k, BS, cursor keys; press 'ENTER' to +set it, or 'ESCAPE'to cancel. There are also keys for quickly adjusting +some common filters like account depth and transaction status (see +below). 'BACKSPACE' or 'DELETE' removes all filters, showing all +transactions. + + 'ESCAPE' removes all filters and jumps back to the top screen. Or, +it cancels a minibuffer edit or help dialog in progress. + + 'CTRL-l' redraws the screen and centers the selection if possible +(selections near the top won't be centered, since we don't scroll above +the top). + + 'g' reloads from the data file(s) and updates the current screen and +any previous screens. (With large files, this could cause a noticeable +pause.) + + 'I' toggles balance assertion checking. Disabling balance assertions +temporarily can be useful for troubleshooting. + + 'a' runs command-line hledger's add command, and reloads the updated +file. This allows some basic data entry. + + 'A' is like 'a', but runs the hledger-iadd tool, which provides a +curses-style interface. This key will be available if 'hledger-iadd' is +installed in $PATH. + + 'E' runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default ('emacsclient +-a "" -nw') on the journal file. With some editors (emacs, vi), the +cursor will be positioned at the current transaction when invoked from +the register and transaction screens, and at the error location (if +possible) when invoked from the error screen. + + 'q' quits the application. + + Additional screen-specific keys are described below. + + +File: hledger-ui.info, Node: SCREENS, Prev: KEYS, Up: Top + +3 SCREENS +********* + +* Menu: + +* Accounts screen:: +* Register screen:: +* Transaction screen:: +* Error screen:: + + +File: hledger-ui.info, Node: Accounts screen, Next: Register screen, Up: SCREENS + +3.1 Accounts screen +=================== + +This is normally the first screen displayed. It lists accounts and +their balances, like hledger's balance command. By default, it shows +all accounts and their latest ending balances (including the balances of +subaccounts). if you specify a query on the command line, it shows just +the matched accounts and the balances from matched transactions. + + Account names are normally indented to show the hierarchy (tree +mode). To see less detail, set a depth limit by pressing a number key, +'1' to '9'. '0' shows even less detail, collapsing all accounts to a +single total. '-' and '+' (or '=') decrease and increase the depth +limit. To remove the depth limit, set it higher than the maximum +account depth, or press 'ESCAPE'. + + 'F' toggles flat mode, in which accounts are shown as a flat list, +with their full names. In this mode, account balances exclude +subaccounts, except for accounts at the depth limit (as with hledger's +balance command). + + 'H' toggles between showing historical balances or period balances. +Historical balances (the default) are ending balances at the end of the +report period, taking into account all transactions before that date +(filtered by the filter query if any), including transactions before the +start of the report period. In other words, historical balances are +what you would see on a bank statement for that account (unless +disturbed by a filter query). Period balances ignore transactions +before the report start date, so they show the change in balance during +the report period. They are more useful eg when viewing a time log. + + 'U' toggles filtering by unmarked status, including or excluding +unmarked postings in the balances. Similarly, 'P' toggles pending +postings, and 'C' toggles cleared postings. (By default, balances +include all postings; if you activate one or two status filters, only +those postings are included; and if you activate all three, the filter +is removed.) + + 'R' toggles real mode, in which virtual postings are ignored. + + 'Z' toggles nonzero mode, in which only accounts with nonzero +balances are shown (hledger-ui shows zero items by default, unlike +command-line hledger). + + Press 'right' or 'enter' to view an account's transactions register. + + +File: hledger-ui.info, Node: Register screen, Next: Transaction screen, Prev: Accounts screen, Up: SCREENS + +3.2 Register screen +=================== + +This screen shows the transactions affecting a particular account, like +a check register. Each line represents one transaction and shows: + + * the other account(s) involved, in abbreviated form. (If there are + both real and virtual postings, it shows only the accounts affected + by real postings.) + + * the overall change to the current account's balance; positive for + an inflow to this account, negative for an outflow. + + * the running historical total or period total for the current + account, after the transaction. This can be toggled with 'H'. + Similar to the accounts screen, the historical total is affected by + transactions (filtered by the filter query) before the report start + date, while the period total is not. If the historical total is + not disturbed by a filter query, it will be the running historical + balance you would see on a bank register for the current account. + + If the accounts screen was in tree mode, the register screen will +include transactions from both the current account and its subaccounts. +If the accounts screen was in flat mode, and a non-depth-clipped account +was selected, the register screen will exclude transactions from +subaccounts. In other words, the register always shows the transactions +responsible for the period balance shown on the accounts screen. As on +the accounts screen, this can be toggled with 'F'. + + 'U' toggles filtering by unmarked status, showing or hiding unmarked +transactions. Similarly, 'P' toggles pending transactions, and 'C' +toggles cleared transactions. (By default, transactions with all +statuses are shown; if you activate one or two status filters, only +those transactions are shown; and if you activate all three, the filter +is removed.)q + + 'R' toggles real mode, in which virtual postings are ignored. + + 'Z' toggles nonzero mode, in which only transactions posting a +nonzero change are shown (hledger-ui shows zero items by default, unlike +command-line hledger). + + Press 'right' (or 'enter') to view the selected transaction in +detail. + + +File: hledger-ui.info, Node: Transaction screen, Next: Error screen, Prev: Register screen, Up: SCREENS + +3.3 Transaction screen +====================== + +This screen shows a single transaction, as a general journal entry, +similar to hledger's print command and journal format +(hledger_journal(5)). + + The transaction's date(s) and any cleared flag, transaction code, +description, comments, along with all of its account postings are shown. +Simple transactions have two postings, but there can be more (or in +certain cases, fewer). + + 'up' and 'down' will step through all transactions listed in the +previous account register screen. In the title bar, the numbers in +parentheses show your position within that account register. They will +vary depending on which account register you came from (remember most +transactions appear in multiple account registers). The #N number +preceding them is the transaction's position within the complete +unfiltered journal, which is a more stable id (at least until the next +reload). + + +File: hledger-ui.info, Node: Error screen, Prev: Transaction screen, Up: SCREENS + +3.4 Error screen +================ + +This screen will appear if there is a problem, such as a parse error, +when you press g to reload. Once you have fixed the problem, press g +again to reload and resume normal operation. (Or, you can press escape +to cancel the reload attempt.) + + +Tag Table: +Node: Top71 +Node: OPTIONS821 +Ref: #options918 +Node: KEYS4087 +Ref: #keys4182 +Node: SCREENS7141 +Ref: #screens7226 +Node: Accounts screen7316 +Ref: #accounts-screen7444 +Node: Register screen9674 +Ref: #register-screen9829 +Node: Transaction screen11903 +Ref: #transaction-screen12061 +Node: Error screen12931 +Ref: #error-screen13053 + +End Tag Table diff --git a/hledger-ui.txt b/hledger-ui.txt new file mode 100644 --- /dev/null +++ b/hledger-ui.txt @@ -0,0 +1,386 @@ + +hledger-ui(1) hledger User Manuals hledger-ui(1) + + + +NAME + hledger-ui - curses-style interface for the hledger accounting tool + +SYNOPSIS + hledger-ui [OPTIONS] [QUERYARGS] + hledger ui -- [OPTIONS] [QUERYARGS] + +DESCRIPTION + hledger is a cross-platform program for tracking money, time, or any + other commodity, using double-entry accounting and a simple, editable + file format. hledger is inspired by and largely compatible with + ledger(1). + + hledger-ui is hledger's curses-style interface, providing an efficient + full-window text UI for viewing accounts and transactions, and some + limited data entry capability. It is easier than hledger's com- + mand-line interface, and sometimes quicker and more convenient than the + web interface. + + Like hledger, it reads data from one or more files in hledger journal, + timeclock, timedot, or CSV format specified with -f, or $LEDGER_FILE, + or $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). For more about this see hledger(1), + hledger_journal(5) etc. + +OPTIONS + Note: if invoking hledger-ui as a hledger subcommand, write -- before + options as shown above. + + Any QUERYARGS are interpreted as a hledger search query which filters + the data. + + --watch + watch for data and date changes and reload automatically + + --theme=default|terminal|greenterm + use this custom display theme + + --register=ACCTREGEX + start in the (first) matched account's register screen + + --change + show period balances (changes) at startup instead of historical + balances + + --flat show full account names, unindented + + hledger input options: + + -f FILE --file=FILE + use a different input file. For stdin, use - (default: + $LEDGER_FILE or $HOME/.hledger.journal) + + --rules-file=RULESFILE + Conversion rules file to use when reading CSV (default: + FILE.rules) + + --alias=OLD=NEW + rename accounts named OLD to NEW + + --anon anonymize accounts and payees + + --pivot FIELDNAME + use some other field or tag for the account name + + -I --ignore-assertions + ignore any failing balance assertions + + hledger reporting options: + + -b --begin=DATE + include postings/txns on or after this date + + -e --end=DATE + include postings/txns before this date + + -D --daily + multiperiod/multicolumn report by day + + -W --weekly + multiperiod/multicolumn report by week + + -M --monthly + multiperiod/multicolumn report by month + + -Q --quarterly + multiperiod/multicolumn report by quarter + + -Y --yearly + multiperiod/multicolumn report by year + + -p --period=PERIODEXP + set start date, end date, and/or reporting interval all at once + using period expressions syntax (overrides the flags above) + + --date2 + match the secondary date instead (see command help for other + effects) + + -U --unmarked + include only unmarked postings/txns (can combine with -P or -C) + + -P --pending + include only pending postings/txns + + -C --cleared + include only cleared postings/txns + + -R --real + include only non-virtual postings + + -NUM --depth=NUM + hide/aggregate accounts or postings more than NUM levels deep + + -E --empty + show items with zero amount, normally hidden + + -B --cost + convert amounts to their cost at transaction time (using the + transaction price, if any) + + -V --value + convert amounts to their market value on the report end date + (using the most recent applicable market price, if any) + + --auto apply automated posting rules to modify transactions. + + --forecast + apply periodic transaction rules to generate future transac- + tions, to 6 months from now or report end date. + + When a reporting option appears more than once in the command line, the + last one takes precedence. + + Some reporting options can also be written as query arguments. + + hledger help options: + + -h --help + show general usage (or after COMMAND, command usage) + + --version + show version + + --debug[=N] + show debug output (levels 1-9, default: 1) + + A @FILE argument will be expanded to the contents of FILE, which should + contain one command line option/argument per line. (To prevent this, + insert a -- argument before.) + +KEYS + ? shows a help dialog listing all keys. (Some of these also appear in + the quick help at the bottom of each screen.) Press ? again (or ESCAPE, + or LEFT) to close it. The following keys work on most screens: + + The cursor keys navigate: right (or enter) goes deeper, left returns to + the previous screen, up/down/page up/page down/home/end move up and + down through lists. Vi-style (h/j/k/l) and Emacs-style + (CTRL-p/CTRL-n/CTRL-f/CTRL-b) movement keys are also supported. A tip: + movement speed is limited by your keyboard repeat rate, to move faster + you may want to adjust it. (If you're on a mac, the Karabiner app is + one way to do that.) + + With shift pressed, the cursor keys adjust the report period, limiting + the transactions to be shown (by default, all are shown). + shift-down/up steps downward and upward through these standard report + period durations: year, quarter, month, week, day. Then, + shift-left/right moves to the previous/next period. t sets the report + period to today. With the --watch option, when viewing a "current" + period (the current day, week, month, quarter, or year), the period + will move automatically to track the current date. To set a non-stan- + dard period, you can use / and a date: query. + + / lets you set a general filter query limiting the data shown, using + the same query terms as in hledger and hledger-web. While editing the + query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set + it, or ESCAPEto cancel. There are also keys for quickly adjusting some + common filters like account depth and transaction status (see below). + BACKSPACE or DELETE removes all filters, showing all transactions. + + ESCAPE removes all filters and jumps back to the top screen. Or, it + cancels a minibuffer edit or help dialog in progress. + + CTRL-l redraws the screen and centers the selection if possible (selec- + tions near the top won't be centered, since we don't scroll above the + top). + + g reloads from the data file(s) and updates the current screen and any + previous screens. (With large files, this could cause a noticeable + pause.) + + I toggles balance assertion checking. Disabling balance assertions + temporarily can be useful for troubleshooting. + + a runs command-line hledger's add command, and reloads the updated + file. This allows some basic data entry. + + A is like a, but runs the hledger-iadd tool, which provides a + curses-style interface. This key will be available if hledger-iadd is + installed in $PATH. + + E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac- + sclient -a "" -nw) on the journal file. With some editors (emacs, vi), + the cursor will be positioned at the current transaction when invoked + from the register and transaction screens, and at the error location + (if possible) when invoked from the error screen. + + q quits the application. + + Additional screen-specific keys are described below. + +SCREENS + Accounts screen + This is normally the first screen displayed. It lists accounts and + their balances, like hledger's balance command. By default, it shows + all accounts and their latest ending balances (including the balances + of subaccounts). if you specify a query on the command line, it shows + just the matched accounts and the balances from matched transactions. + + Account names are normally indented to show the hierarchy (tree mode). + To see less detail, set a depth limit by pressing a number key, 1 to 9. + 0 shows even less detail, collapsing all accounts to a single total. - + and + (or =) decrease and increase the depth limit. To remove the + depth limit, set it higher than the maximum account depth, or press + ESCAPE. + + F toggles flat mode, in which accounts are shown as a flat list, with + their full names. In this mode, account balances exclude subaccounts, + except for accounts at the depth limit (as with hledger's balance com- + mand). + + H toggles between showing historical balances or period balances. His- + torical balances (the default) are ending balances at the end of the + report period, taking into account all transactions before that date + (filtered by the filter query if any), including transactions before + the start of the report period. In other words, historical balances + are what you would see on a bank statement for that account (unless + disturbed by a filter query). Period balances ignore transactions + before the report start date, so they show the change in balance during + the report period. They are more useful eg when viewing a time log. + + U toggles filtering by unmarked status, including or excluding unmarked + postings in the balances. Similarly, P toggles pending postings, and C + toggles cleared postings. (By default, balances include all postings; + if you activate one or two status filters, only those postings are + included; and if you activate all three, the filter is removed.) + + R toggles real mode, in which virtual postings are ignored. + + Z toggles nonzero mode, in which only accounts with nonzero balances + are shown (hledger-ui shows zero items by default, unlike command-line + hledger). + + Press right or enter to view an account's transactions register. + + Register screen + This screen shows the transactions affecting a particular account, like + a check register. Each line represents one transaction and shows: + + o the other account(s) involved, in abbreviated form. (If there are + both real and virtual postings, it shows only the accounts affected + by real postings.) + + o the overall change to the current account's balance; positive for an + inflow to this account, negative for an outflow. + + o the running historical total or period total for the current account, + after the transaction. This can be toggled with H. Similar to the + accounts screen, the historical total is affected by transactions + (filtered by the filter query) before the report start date, while + the period total is not. If the historical total is not disturbed by + a filter query, it will be the running historical balance you would + see on a bank register for the current account. + + If the accounts screen was in tree mode, the register screen will + include transactions from both the current account and its subaccounts. + If the accounts screen was in flat mode, and a non-depth-clipped + account was selected, the register screen will exclude transactions + from subaccounts. In other words, the register always shows the trans- + actions responsible for the period balance shown on the accounts + screen. As on the accounts screen, this can be toggled with F. + + U toggles filtering by unmarked status, showing or hiding unmarked + transactions. Similarly, P toggles pending transactions, and C toggles + cleared transactions. (By default, transactions with all statuses are + shown; if you activate one or two status filters, only those transac- + tions are shown; and if you activate all three, the filter is + removed.)q + + R toggles real mode, in which virtual postings are ignored. + + Z toggles nonzero mode, in which only transactions posting a nonzero + change are shown (hledger-ui shows zero items by default, unlike com- + mand-line hledger). + + Press right (or enter) to view the selected transaction in detail. + + Transaction screen + This screen shows a single transaction, as a general journal entry, + similar to hledger's print command and journal format (hledger_jour- + nal(5)). + + The transaction's date(s) and any cleared flag, transaction code, + description, comments, along with all of its account postings are + shown. Simple transactions have two postings, but there can be more + (or in certain cases, fewer). + + up and down will step through all transactions listed in the previous + account register screen. In the title bar, the numbers in parentheses + show your position within that account register. They will vary + depending on which account register you came from (remember most trans- + actions appear in multiple account registers). The #N number preceding + them is the transaction's position within the complete unfiltered jour- + nal, which is a more stable id (at least until the next reload). + + Error screen + This screen will appear if there is a problem, such as a parse error, + when you press g to reload. Once you have fixed the problem, press g + again to reload and resume normal operation. (Or, you can press escape + to cancel the reload attempt.) + +ENVIRONMENT + COLUMNS The screen width to use. Default: the full terminal width. + + LEDGER_FILE The journal file path when not specified with -f. Default: + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + nal). + +FILES + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps + C:/Users/USER/.hledger.journal). + +BUGS + The need to precede options with -- when invoked from hledger is awk- + ward. + + -f- doesn't work (hledger-ui can't read from stdin). + + -V affects only the accounts screen. + + When you press g, the current and all previous screens are regenerated, + which may cause a noticeable pause with large files. Also there is no + visual indication that this is in progress. + + --watch is not yet fully robust. It works well for normal usage, but + many file changes in a short time (eg saving the file thousands of + times with an editor macro) can cause problems at least on OSX. Symp- + toms include: unresponsive UI, periodic resetting of the cursor posi- + tion, momentary display of parse errors, high CPU usage eventually sub- + siding, and possibly a small but persistent build-up of CPU usage until + the program is restarted. + + + +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AUTHORS + Simon Michael and contributors + + +COPYRIGHT + Copyright (C) 2007-2016 Simon Michael. + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + +hledger-ui 1.5 December 2017 hledger-ui(1)