An interactive terminal UI as drop-in replacement for hledger add
.
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.
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.
The easiest method would be stack: Install the stack program and type:
stack install --resolver=lts hledger-iadd-1.3.21
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
.
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
.
To install the development version, clone the git repository first:
git clone https://github.com/hpdeifel/hledger-iadd.git
cd hledger-iadd
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
.
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
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 |
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
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
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.