hledger-iadd
A terminal UI as drop-in replacement for hledger add
https://github.com/hpdeifel/hledger-iadd#readme
LTS Haskell 22.39: | 1.3.20 |
Stackage Nightly 2024-10-31: | 1.3.21@rev:2 |
Latest on Hackage: | 1.3.21@rev:2 |
hledger-iadd-1.3.21@sha256:75669c7fe9ed7407e69747daef5fc376198c4d6b17d39ab51f00446fe79afcbb,5360
Module documentation for 1.3.21
- AmountParser
- Brick
- Brick.Widgets
- Brick.Widgets.BetterDialog
- Brick.Widgets.Border
- Brick.Widgets.CommentDialog
- Brick.Widgets.Edit
- Brick.Widgets.HelpMessage
- Brick.Widgets.List
- Brick.Widgets.WrappedText
- Brick.Widgets
- ConfigParser
- Data
- Data.Time
- DateParser
- Model
- View
hledger-iadd
An interactive terminal UI as drop-in replacement for hledger add
.
Features
This project improves in the following ways on hledger’s add
command:
-
Interactive as-you-type completion for account names and descriptions with optional fuzzy matching (see below).
-
Integrated calculator: Amounts can be written as simple sums with real-time feedback on the result.
-
All actions while entering a transaction can be undone
-
Configurable format for date input. Instead of
y/m/d
it is also possible to use other formats like the germand.m.y
.
Also see the user guide under Usage.
Installation
Latest release
Archlinux
For Archlinux users, an AUR package with a binary built by me (@hpdeifel)
is available. If you want to compile hledger-iadd
yourself, use one of the
following installation methods.
stack
The easiest method would be stack: Install the stack program and type:
stack install --resolver=lts hledger-iadd-1.3.14
This downloads and builds hledger-iadd
and all it’s Haskell
dependencies. After that, it copys the resulting binary to
~/.local/bin
. See stack --help
for more options. You may get asked
to install the GHC Haskell compiler locally. To do that, type stack setup
.
cabal
First, install the GHC Haskell compiler and the cabal install
,
alex
and happy
build tools, possibly from your distribution or the
haskell platform. Type
cabal install --bindir ~/bin hledger-iadd
to install the binary in ~/bin
.
Development version
To install the development version, clone the git repository first:
git clone https://github.com/hpdeifel/hledger-iadd.git
cd hledger-iadd
stack
The easiest method would be stack: Install the stack program and type:
stack install
To build and install all Haskell dependencies locally and install
hledger-iadd
to ~/.local/bin
. See stack --help
for more options.
You may get asked to install the GHC Haskell compiler locally. To do
that, type stack setup
.
Cabal
First, install the GHC Haskell compiler and the cabal install
,
alex
and happy
build tools, possibly from your distribution or the
haskell platform.
Since cabal
builds regularly break in non-isolated environments, the
recommended next step is to create a cabal sandbox where all
dependencies will be installed in:
cd hledger-iadd
cabal sandbox init
You can now download and install all dependencies locally with
cabal install --only-dependencies
And finally you’re ready to build and install hledger-iadd
:
cabal configure --bindir ~/bin
cabal build
cabal copy
Usage
YouTube video demonstrating basic interactions
You can start the program either with
hledger iadd
or simply hledger-iadd
.
The following command line options are available:
-f/--file/
: Path to the journal file. (Default:~/.hledger.journal
)--date-format
: Format for parsing dates. (Default:[[%y/]%m/]%d
, the usual ledger date format). Brackets can be used to specify optional parts. E.g the german date format would be%d[.[%m[.[%y]]]]
. (Dates are written asy/m/d
to the journal regardless of this option).--completion-engine
: Algorithm for account name completion. Can besubstrings
orfuzzy
.--dump-default-config
: Print the example config file to stdout and exit
The UI is partitioned in 4 regions:
Current Transaction (view of your work in progress)
---------------------------------------------------
Question: [ text area ]
---------------------------------------------------
Context information (e.g. list of accounts)
---------------------------------------------------
Message area
For each transaction, you will get asked the following questions in order:
- Date?
- Description?
- Account name?
- Amount?
- The last two questions are repeated until you enter the empty account
- Do you want to add this transaction to the journal?
To accept the default answer, immediately press Return at a promt.
While you type, the context area shows possible completions. Pressing Return answers the question with the currently selected completion. You can select differnt completions with C-n and C-p.
The following keyboard shortcuts are available:
Key | Function |
---|---|
C-c, C-d | Quit the program without saving the current transaction |
Esc | Abort the current transaction or exit when at toplevel |
Ret | Accept the currently selected answer |
Alt-Ret | Accept the current answer verbatim from the text area, ignoring the selection |
C-z | Undo the last action |
Tab | Insert the currently selected answer into the text area |
C-n,↓ | Select the next context item |
C-p,↑ | Select the previous context item |
; | Edit comment for current prompt |
Alt-; | Edit transaction comment |
F1,Alt-? | Show help dialog |
Default Currency
To make entry easier it is recommended that you set a default commodity
in your ledger file if you haven’t already done so.
That way when entering amounts, hledger-iadd
will add the symbols for you.
You can do this by adding a line like below to the top of your ledger file:
; sets the default commodity symbol and placement, thousands separator, and decimal symbol
D $1,000.00
Configuration File
hledger-iadd
is optionally configurable through a configuration file
in ${XDG_CONFIG_HOME}/hledger-iadd/config.conf
. This file consists
of simple
key = value
assignments on individual lines with whitespace or comments starting
with #
between them. The default config can be obtained by
passing --dump-default-config
to hledger-iadd
.
The following options are currently available:
file
: Path to the journal file.date-format
: The date format. See the documentation for--date-format
for details.completion-engine
: Algorithm used to find completions for account names. Possible values are:substrings
: Every word in the search string has to occur somewhere in the account namefuzzy
: All letters from the search string have to appear in the name in the same order
License
The code of hledger-iadd
is released under the BSD3 license, but
since hledger-lib
– the library that hledger-iadd
uses – is
licensed under the GPLv3, the terms of the GPL apply to the compiled
and linked binary.
Changes
1.3.21 [2024-04-20]
- dependencies: Bump brick and vty versions
- Update to hledger-lib 1.33
1.3.20 [2024-01-10]
- feature: Make ‘Y/n’ prompts case-insensitive
- dependencies: Update to hledger-lib 1.32
- dependencies: Allow megaparsec 9.6
1.3.19 [2023-09-15]
- dependencies: Update to hledger-lib 1.31
- dependencies: Allow megaparsec 9.5
1.3.18 [2023-04-05]
- dependencies: Update to hledger-lib 1.29
- dependencies: Update to brick 1.5
1.3.17 [2022-03-15]
- dependencies: Support brick 0.68
- dependencies: Allow hledger-lib 1.25
- dependencies: Allow megaparsec 9.2
1.3.16 [2021-09-22]
- dependencies: Support (and require) hledger-lib-1.23
- dependencies: Allow megaparsec 9.1
1.3.15 [2021-07-08]
- dependencies: Support (and require) hledger-lib-1.22
- dependencies: Drop support for GHC <8.6 completely
1.3.14 [2021-03-13]
- bugfix: Fix test failures
- bugfix: Fix amount suggestion in some circumstances
- dependencies: Remove GHC 8.0, 8.2 and 8.4 from list of officially supported compilers. They might still work
1.3.13 [2021-03-10]
- dependencies: Support (and require) hledger-lib-1.21
- dependencies: Support megaparsec-9
1.3.12 [2020-08-31]
- dependencies: Fix tests build with hledger-lib-1.19
1.3.11 [2020-06-04]
- bugfix: Fix check for balanced transactions in the presence of commodities.
- dependencies: Fix build with hledger-lib-1.18
1.3.10 [2020-01-14]
- dependencies: Support megaparsec-8
1.3.9 [2019-03-02]
- dependencies: Port to hledger-lib-1.14
- Add AUR packaging
1.3.8
- dependencies: Port to hledger-lib-1.13
1.3.7
- feature: Add abbreviated days of the week to date completion (e.g.
mon
,tue
, etc) - dependencies: Port to hledger-lib-1.12 and megaparsec-7
- dependencies: Support GHC-8.6
- dependencies: Switch stack builds to ghc 8.4 by default
1.3.6
- bugfix: Use local time instead of UTC everywhere
1.3.5
- Fix build with hledger-lib 1.9.1
1.3.4
- Fix test suite build with hledger-lib 1.9
1.3.3
- Support new dependencies
- Raise lower bound on hledger-lib to 1.5
1.3.2
- Highlight currently constructed transaction
- Fix build with GHC 8.4
- Support new dependencies
- Drop dependency on text-format
1.3.1
- Support brick <= 0.32
- Support megaparsec <= 6.4
1.3.0
- Detect duplicate transactions and warn about them
- Add empty line before transactions when writing to journal
- Don’t elide the last amount in transactions
- Support account directive for account completion
- Bugfixes and dependency bumps
1.2.6
- Fix build with hledger-lib >= 1.3.1
- Support for megaparsec-6.1
- Support for brick <= 0.24
- Fix test suite with ghc 8.2
1.2.5
- Fix broken release tarball
1.2.4
- Support for megaparsec-6.0
1.2.3
- Support for brick-0.20
- Restore compatibility with brick-0.17
- Support for hledger-lib-1.3
1.2.2
- Support for megaparsec-5.3.0
- Bump brick dependency to 0.19
1.2.1
- Support for hledger-lib-1.2
- Minor documentation fixes
1.2
- Add support for comments (bound to
;
) - Restore previous text input on undo
- Bump text-zipper dependency to 0.10
1.1.4
- Sort account names by frequency for completion
- Bind Home/End im entry field
- Bump brick and vty dependencies
1.1.3
- Add more emacs/readline like keybindings in entry field (
C-f
/C-b
,M-f
/M-b
,M-Del
/C-w
,M-d
) - Fix account suggestion order to be more like
hledger add
1.1.2
- Respect ${LEDGER_FILE} environment variable
- Add –version command
- Bump brick dependency to 0.15.2
- Bump hledger-lib dependency to 1.1
- Bind C-u to ‘delete to beginning of line’
1.1.1
- bugfix: Show cursor in empty entry widget
- bugfix: Correctly execute
--help
and--dump-default-config
in the presence of syntax errors in the config file
1.1
- Add a configuration file for persistent settings
- Disallow unbalanced transactions
- Order postings naturally and omit balancing amounts in transaction preview (thanks Tristan Hume)
- Suggest account based on last transaction if no similar transaction is found (thanks Tristan Hume)
- Make completed dates as recent as possible (thanks Thorsten Wißmann)
- Optional fuzzy matching via config option “completion-engine” (thanks Tristan Hume)
- Add Ctrl-d as new keybinding for ‘quit’
- Make ESC quit at the toplevel
- Various bug fixes
1.0
- Initial release