Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hpdeifel/hledger-iadd

A terminal UI as drop-in replacement for hledger add.
https://github.com/hpdeifel/hledger-iadd

curses finance haskell hledger ledger plaintext-accounting tui ui

Last synced: 3 days ago
JSON representation

A terminal UI as drop-in replacement for hledger add.

Host: GitHub
URL: https://github.com/hpdeifel/hledger-iadd
Owner: hpdeifel
License: bsd-3-clause
Created: 2015-10-07T22:00:14.000Z (about 9 years ago)
Default Branch: master
Last Pushed: 2024-11-20T16:22:07.000Z (23 days ago)
Last Synced: 2024-12-03T21:03:17.958Z (10 days ago)
Topics: curses, finance, haskell, hledger, ledger, plaintext-accounting, tui, ui
Language: Haskell
Size: 331 KB
Stars: 84
Watchers: 5
Forks: 8
Open Issues: 28
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
- License: LICENSE

Awesome Lists containing this project

awesome-hledger - hledger-iadd - Very convenient tool to add transactions to hledger journal. (Add/Edit Transactions)

README

# hledger-iadd

An interactive terminal UI as drop-in replacement for `hledger add`.

![Screencast](doc/screencast.gif)

## 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](#configuration-file)).

- 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 german `d.m.y`.

Also see the user guide under [Usage](#usage).

## Installation
### Latest release
#### Archlinux

For Archlinux users, an [AUR package](https://aur.archlinux.org/packages/hledger-iadd-bin) 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](https://www.youtube.com/watch?v=ZuCT9EzryaI)*

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 as `y/m/d` to the
journal regardless of this option).
- `--completion-engine`: Algorithm for account name completion. Can
be `substrings` or `fuzzy`.
- `--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:

1. Date?
2. Description?
3. Account name?
4. Amount?
5. The last two questions are repeated until you enter the empty account
6. 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](https://hledger.org/journal.html#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:

```lisp
; 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 name
- `fuzzy`: 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.

[stack]: https://github.com/commercialhaskell/stack
[haskell platform]: https://www.haskell.org/platform/
[BSD3]: https://opensource.org/licenses/BSD-3-Clause
[GPLv3]: https://www.gnu.org/licenses/gpl-3.0.en.html