550 lines
18 KiB
Plaintext
550 lines
18 KiB
Plaintext
*ledger.txt* Plugin for the ledger filetype.
|
||
|
||
|
||
*ledger* *ledger-plugin*
|
||
|
||
Contents:
|
||
|
||
Commands............|ledger-invoking|
|
||
Source................|ledger-source|
|
||
Usage..................|ledger-usage|
|
||
Tips....................|ledger-tips|
|
||
Reports..............|ledger-reports|
|
||
Settings............|ledger-settings|
|
||
Completion........|ledger-completion|
|
||
License..............|ledger-license|
|
||
|
||
|
||
==============================================================================
|
||
USAGE *ledger-usage*
|
||
|
||
Copy each file to the corresponding directory in your ~/.vim directory or
|
||
install using Pathogen.
|
||
|
||
You can also use a modeline like this in every ledger file:
|
||
|
||
vim:filetype=ledger
|
||
|
||
==============================================================================
|
||
TIPS *ledger-tips*
|
||
|
||
Tips and useful commands
|
||
|
||
* vim-ledger can do syntax-sensitive folding when you set `foldmethod=syntax`
|
||
in the |modeline| of your ledger file. This way transactions can shrink down
|
||
to just one line.
|
||
|
||
* Try account-completion (as explained below). If you use YouCompleteMe, you
|
||
should disable it for Ledger files. Put this in your .vimrc:
|
||
|
||
if exists('g:ycm_filetype_blacklist')
|
||
call extend(g:ycm_filetype_blacklist, { 'ledger': 1 })
|
||
endif
|
||
|
||
* You may use `:make` for syntax checking. It may be convenient to define a
|
||
mapping for the following command:
|
||
|
||
:silent make | redraw! | cwindow
|
||
|
||
It is recommended to set the value of `g:ledger_extra_options` (see below)
|
||
as follows for ledger:
|
||
|
||
let g:ledger_extra_options = '--pedantic --explicit --check-payees'
|
||
|
||
and as follows for hledger:
|
||
|
||
let g:ledger_extra_options = '--strict ordereddates payees uniqueleafnames'
|
||
|
||
to catch most potential problems in your source file.
|
||
|
||
* Remap vim paragraph motion to move by transaction.
|
||
|
||
In vim, the "{" and "}" keystrokes move the cursor up and down by whole
|
||
paragraphs. They can be redefined in ledger files to move by transaction
|
||
instead. Add these lines to .vimrc:
|
||
|
||
au FileType ledger noremap { ?^\d<CR>
|
||
au FileType ledger noremap } /^\d<CR>
|
||
|
||
The default definitions already work in ledger files that separate
|
||
transactions with blank lines.
|
||
|
||
* `:call ledger#transaction_date_set(line('.'), "auxiliary")`
|
||
|
||
will set today's date as the auxiliary date of the current transaction. You
|
||
can use also "primary" or "unshift" in place of "auxiliary". When you pass
|
||
"unshift" the old primary date will be set as the auxiliary date and today's
|
||
date will be set as the new primary date.
|
||
To use a different date pass a date measured in seconds since 1st Jan 1970
|
||
as the third argument.
|
||
|
||
* `:call ledger#transaction_state_set(line('.'), '*')`
|
||
|
||
sets the state of the current transaction to '*'. You can use this in custom
|
||
mappings.
|
||
|
||
* `:call ledger#transaction_state_toggle(line('.'), ' *?!')`
|
||
|
||
will toggle through the provided transaction states. You can map this to
|
||
double-clicking for example:
|
||
|
||
noremap <silent><buffer> <2-LeftMouse>\
|
||
:call ledger#transaction_state_toggle(line('.'), ' *?!')<CR>
|
||
|
||
* `:call ledger#transaction_post_state_set(line('.'), '*')`
|
||
|
||
is similar to ledger#transaction_state_set but can set state of individual
|
||
post.
|
||
|
||
* `:call ledger#transaction_post_state_toggle(line('.'), ' *?!')`
|
||
|
||
is similar to ledger#transaction_state_toggle but can toggle state of
|
||
individual post.
|
||
|
||
* `:LedgerAlign`
|
||
|
||
moves the amount expression of a posting so that the decimal separator is
|
||
aligned at the column specified by g:ledger_align_at. If an amount has no
|
||
decimal point, the imaginary decimal point to the right of the least
|
||
significant digit will align. The command acts on a range, with the default
|
||
being the current line.
|
||
|
||
The decimal separator can be set using `g:ledger_decimal_sep`. The default
|
||
value of `g:ledger_decimal_sep` is `'.'`. More than one possible character
|
||
may be specified and any matches will count, e.g. `'.,'`.
|
||
|
||
By default the alignment is done on the first matching decimal separator.
|
||
This may be changed by setting `g:ledger_align_last` to `v:true`, in which
|
||
case the last possible decimal separator will be used. This is useful for
|
||
mixed-currency ledgers where decimal and thousands separators in different
|
||
currencies may clash and/or aligning on the right hand side of rate
|
||
conversions is desired.
|
||
|
||
See below for the recommended mappings.
|
||
|
||
* `:LedgerAlignBuffer`
|
||
|
||
This command aligns the commodity for each posting in the entire buffer,
|
||
similar to the command `:LedgerAlign`. It differs from manually specifying
|
||
the entire buffer as the range to `:LedgerAlign` or
|
||
`ledger#align_commodity()` by saving and restoring the cursor and window
|
||
position.
|
||
|
||
Due to performance concerns, it is not recommended to call this command
|
||
on large buffers.
|
||
|
||
* `:call ledger#align_amount_at_cursor()`
|
||
|
||
aligns the amount under the cursor and append/prepend the default currency.
|
||
The default currency can be set using `g:ledger_default_commodity`. Whether
|
||
the commodity should be inserted before the amount or appended to it can be
|
||
configured with the boolean flag `g:ledger_commodity_before` (the default
|
||
value is 1). A separator between the commodity and the amount may be set
|
||
using `g:ledger_commodity_sep`.
|
||
|
||
See below for the recommended mappings.
|
||
|
||
* `:call ledger#autocomplete_and_align()`
|
||
|
||
when the cursor is on a number or immediately after it, invokes
|
||
`ledger#align_amount_at_cursor()` to align it and add the default currency;
|
||
otherwise, performs autocompletion. If you define the following mappings in
|
||
your `.vimrc` then you may perform both autocompletion and alignment using
|
||
the <Tab> key:
|
||
|
||
au FileType ledger inoremap <silent> <Tab> \
|
||
<C-r>=ledger#autocomplete_and_align()<CR>
|
||
au FileType ledger vnoremap <silent> <Tab> :LedgerAlign<CR>
|
||
|
||
Alternatively, you may create a file `.vim/after/ftplugin/ledger.vim`
|
||
containing the following definitions:
|
||
|
||
inoremap <silent> <buffer> <Tab> \
|
||
<C-r>=ledger#autocomplete_and_align()<CR>
|
||
vnoremap <silent> <buffer> <Tab> :LedgerAlign<CR>
|
||
|
||
Now, you may type `asset:check<Tab><Space>123.45<Tab>`, and have the
|
||
account name autocompleted and `$123.45` properly aligned (assuming your
|
||
default commodity is set to `'$'`). Or you may press <Tab> in Visual mode
|
||
to align a number of transactions at once.
|
||
|
||
* `:call ledger#entry()`
|
||
|
||
enters a new transaction based on the text in the current line.
|
||
The text in the current line is replaced by the new transaction.
|
||
This is a front end to `ledger entry`.
|
||
|
||
==============================================================================
|
||
REPORTS *ledger-reports*
|
||
|
||
* `:Ledger`
|
||
|
||
Executes an arbitrary Ledger command and sends the output to a new buffer.
|
||
For example:
|
||
|
||
:Ledger bal ^assets ^liab
|
||
|
||
Errors are displayed in a quickfix window. The command offers account and
|
||
payee autocompletion (by pressing <Tab>): every name starting with `@` is
|
||
autocompleted as a payee; any other name is autocompleted as an account.
|
||
|
||
In a report buffer or in the quickfix window, you may press <Tab> to switch
|
||
back to your source file, and you may press `q` to dismiss the current window.
|
||
|
||
There are three highlight groups that are used to color the report:
|
||
|
||
* `LedgerNumber`
|
||
|
||
This is used to color nonnegative numbers.
|
||
|
||
* `LedgerNegativeNumber`
|
||
|
||
This is used to color negative numbers.
|
||
|
||
* `LedgerImproperPerc`
|
||
|
||
This is used to color improper percentages.
|
||
|
||
* `:Balance`
|
||
|
||
Show the pending and cleared balance of a given account below the status
|
||
line. For example:
|
||
|
||
:Balance checking:savings
|
||
|
||
The command offers payee and account autocompletion (see `:Ledger`). The
|
||
account argument is optional: if no argument is given, the first account
|
||
name found in the current line is used.
|
||
|
||
Two highlight groups can be used to customize the colors of the line:
|
||
|
||
* `LedgerCleared`
|
||
|
||
This is used to color the cleared balance.
|
||
|
||
* `LedgerPending`
|
||
|
||
This is used to color the pending balance.
|
||
|
||
* `:Register`
|
||
|
||
Opens an arbitrary register report in the quickfix window. For example:
|
||
|
||
:Register groceries -p 'this month'
|
||
|
||
The command offers account and payee autocompletion (see |:Ledger|). You
|
||
may use the standard quickfix commands to jump from an entry in the register
|
||
report to the corresponding location in the source file. If you use GUI Vim
|
||
or if your terminal has support for the mouse (e.g., iTerm2, or even
|
||
Terminal.app in OS X 10.11 or later), you may also double-click on a line
|
||
number in the quickfix window to jump to the corresponding posting.
|
||
|
||
It is strongly recommended that you add mappings for common quickfix
|
||
commands like `:cprev` and `:cnext`, or that you use T. Pope's Unimpaired
|
||
plugin.
|
||
|
||
* :`Reconcile`
|
||
|
||
Reconcile an account. For example:
|
||
|
||
:Reconcile checking
|
||
|
||
After you press Enter, you will be asked to enter a target amount (use
|
||
Vim's syntax for numbers, not your ledger's format). For example, for a
|
||
checking account, the target amount may be the balance of your latest bank
|
||
statement. The list of uncleared postings appears in the quickfix window.
|
||
The current balance of the account, together with the difference between the
|
||
target amount and the cleared balance, is shown at the bottom of the screen.
|
||
You may use standard quickfix commands to navigate through the postings. You
|
||
may use |ledger#transaction_state_set()| to update a transaction's state.
|
||
Every time you save your file, the balance and the difference from the
|
||
target amount are updated at the bottom of the screen. The goal, of course,
|
||
is to get such difference to zero. You may press `<C-l>` to refresh the
|
||
Reconcile buffer. To finish reconciling an account, simply close the
|
||
quickfix window.
|
||
|
||
There is a highlight group to customize the color of the difference from
|
||
target:
|
||
|
||
* `LedgerTarget`
|
||
|
||
This is used to color the difference between the target amount and the
|
||
cleared balance.
|
||
|
||
==============================================================================
|
||
SETTINGS *ledger-settings*
|
||
|
||
Configuration
|
||
|
||
Include the following let-statements somewhere in your `.vimrc` to modify the
|
||
behaviour of the ledger filetype.
|
||
|
||
=== Ledger / HLedger Configuration ===
|
||
|
||
* Path to the `ledger` executable:
|
||
|
||
let g:ledger_bin = 'ledger'
|
||
|
||
* Whether to use ledger or hledger specific features. Setting this value is
|
||
optional and in most cases will be guessed correctly based on g:ledger_bin,
|
||
but in the event it isn't guessed correctly or you want to use different
|
||
syntax features even with your default tooling setup for the other engine
|
||
this flag can be set to override the value.
|
||
|
||
let g:ledger_is_hledger = v:true
|
||
|
||
* Additional default options for the `ledger` executable:
|
||
|
||
let g:ledger_extra_options = ''
|
||
|
||
* The file to be used to generate reports:
|
||
|
||
let g:ledger_main = '%:p'
|
||
|
||
The default is to use the current file.
|
||
|
||
* Disable automatic detection and use of ledger binary:
|
||
|
||
let g:ledger_no_bin = 1
|
||
|
||
=== Completion Settings ===
|
||
|
||
* To use a custom external system command to generate a list of account names
|
||
for completion, set the following. If g:ledger_bin is set, this will default
|
||
to running that command with arguments to parse the current file using the
|
||
accounts subcommand (works with ledger or hledger), otherwise it will parse
|
||
the postings in the current file itself.
|
||
|
||
let g:ledger_accounts_cmd = 'ledger accounts'
|
||
|
||
* To use a custom external system command to generate a list of descriptions
|
||
for completion, set the following. If g:ledger_bin is set, this will default
|
||
to running that command with arguments to parse the current file using the
|
||
descriptions subcommand (works with ledger or hledger), otherwise it will
|
||
parse the transactions in the current file itself.
|
||
|
||
let g:ledger_descriptions_cmd = 'ledger payees'
|
||
|
||
* If you want account completion based on fuzzy matching instead of the
|
||
default sub-level completion:
|
||
|
||
let g:ledger_fuzzy_account_completion = 1
|
||
|
||
* If you want the account completion to be sorted by level of detail/depth
|
||
instead of alphabetical:
|
||
|
||
let g:ledger_detailed_first = 1
|
||
|
||
* Show only exact matches in completion:
|
||
|
||
let g:ledger_exact_only = 1
|
||
|
||
* Include the original text in completion results:
|
||
|
||
let g:ledger_include_original = 1
|
||
|
||
* Enable spell checking for account names:
|
||
|
||
let g:ledger_accounts_spell = 1
|
||
|
||
=== Alignment and Formatting Settings ===
|
||
|
||
* Specify at which column decimal separators should be aligned:
|
||
|
||
let g:ledger_align_at = 60
|
||
|
||
* Decimal separator for alignment:
|
||
|
||
let g:ledger_decimal_sep = '.'
|
||
|
||
* Specify alignment on first or last matching separator:
|
||
|
||
let g:ledger_align_last = v:false
|
||
|
||
* Default commodity used by `ledger#align_amount_at_cursor()`:
|
||
|
||
let g:ledger_default_commodity = ''
|
||
|
||
* Align on the commodity location instead of the amount:
|
||
|
||
let g:ledger_align_commodity = 1
|
||
|
||
* Flag that tells whether the commodity should be prepended or appended to the
|
||
amount:
|
||
|
||
let g:ledger_commodity_before = 1
|
||
|
||
* String to be put between the commodity and the amount:
|
||
|
||
let g:ledger_commodity_sep = ''
|
||
|
||
* Enable spell checking for commodity symbols:
|
||
|
||
let g:ledger_commodity_spell = 1
|
||
|
||
=== Folding Settings ===
|
||
|
||
* Number of columns that will be used to display the foldtext. Set this when
|
||
you think that the amount is too far off to the right.
|
||
|
||
let g:ledger_maxwidth = 80
|
||
|
||
* String that will be used to fill the space between account name and amount in
|
||
the foldtext. Set this to get some kind of lines or visual aid.
|
||
|
||
let g:ledger_fillstring = ' -'
|
||
|
||
* By default vim will fold ledger transactions, leaving surrounding blank lines
|
||
unfolded. You can use 'g:ledger_fold_blanks' to hide blank lines following a
|
||
transaction.
|
||
|
||
let g:ledger_fold_blanks = 0
|
||
|
||
A value of 0 will disable folding of blank lines, 1 will allow folding of a
|
||
single blank line between transactions; any larger value will enable folding
|
||
unconditionally.
|
||
|
||
Note that only lines containing no trailing spaces are considered for
|
||
folding. You can take advantage of this to disable this feature on a
|
||
case-by-case basis.
|
||
|
||
=== Date Format ===
|
||
|
||
* Format of transaction date:
|
||
|
||
let g:ledger_date_format = '%Y/%m/%d'
|
||
|
||
=== Report Window Settings ===
|
||
|
||
* Position of a report buffer:
|
||
|
||
let g:ledger_winpos = 'B'
|
||
|
||
Use `b` for bottom, `t` for top, `l` for left, `r` for right. Use uppercase letters
|
||
if you want the window to always occupy the full width or height.
|
||
|
||
=== Quickfix Window Settings ===
|
||
|
||
* Flag that tells whether a location list or a quickfix list should be used:
|
||
|
||
let g:ledger_use_location_list = 0
|
||
|
||
The default is to use the quickfix window. Set to 1 to use a location list.
|
||
|
||
* Position of the quickfix/location list:
|
||
|
||
let g:ledger_qf_vertical = 0
|
||
|
||
Set to 1 to open the quickfix window in a vertical split.
|
||
|
||
* Size of the quickfix window:
|
||
|
||
let g:ledger_qf_size = 10
|
||
|
||
This is the number of lines of a horizontal quickfix window, or the number
|
||
of columns of a vertical quickfix window.
|
||
|
||
* Flag to show or hide filenames in the quickfix window:
|
||
|
||
let g:ledger_qf_hide_file = 1
|
||
|
||
Filenames in the quickfix window are hidden by default. Set this to 0
|
||
if you want filenames to be visible.
|
||
|
||
* Format of quickfix register reports (see |:Register|):
|
||
|
||
let g:ledger_qf_register_format =
|
||
\ '%(date) %(justify(payee, 50)) '.
|
||
\ '%(justify(account, 30)) %(justify(amount, 15, -1, true)) '.
|
||
\ '%(justify(total, 15, -1, true))\n'
|
||
|
||
The format is specified using the standard Ledger syntax for --format.
|
||
|
||
* Format of the reconcile quickfix window (see |:Reconcile|):
|
||
|
||
let g:ledger_qf_reconcile_format =
|
||
\ '%(date) %(justify(code, 4)) '.
|
||
\ '%(justify(payee, 50)) %(justify(account, 30)) '.
|
||
\ '%(justify(amount, 15, -1, true))\n'
|
||
|
||
The format is specified using the standard Ledger syntax for --format.
|
||
|
||
Note that Reconcile is only available with Ledger, not HLedger.
|
||
|
||
=== Balance Display Settings ===
|
||
|
||
* Text of the output of the |:Balance| command:
|
||
|
||
let g:ledger_cleared_string = 'Cleared: '
|
||
let g:ledger_pending_string = 'Cleared or pending: '
|
||
let g:ledger_target_string = 'Difference from target: '
|
||
|
||
=== Advanced Settings ===
|
||
|
||
* Enable automatic formatting with the ledger binary (potentially dangerous):
|
||
|
||
let g:ledger_dangerous_formatprg = 1
|
||
|
||
WARNING: This feature can cause data loss when run on non-transaction blocks.
|
||
|
||
==============================================================================
|
||
COMPLETION *ledger-completion*
|
||
|
||
Omni completion is currently implemented for account names only.
|
||
|
||
### Accounts
|
||
|
||
By default, account names are matched by the start of every sub-level. When
|
||
you insert an account name like this:
|
||
|
||
Asse<C-X><C-O>
|
||
|
||
You will get a list of top-level accounts that start like this.
|
||
|
||
Go ahead and try something like:
|
||
|
||
As:Ban:Che<C-X><C-O>
|
||
|
||
When you have an account like this, 'Assets:Bank:Checking' should show up.
|
||
|
||
If fuzzy matching based account completion is enabled, the matches are
|
||
loaded based on string similarity and without regard for the sub-levels.
|
||
|
||
In the previous example, with fuzzy matching enabled, you could load up
|
||
matches by doing something like:
|
||
|
||
Chec<C-X><C-O>
|
||
|
||
Notice that we did not need to write the initial account components.
|
||
|
||
When you want to complete on a virtual transaction, it's currently best
|
||
to keep the cursor in front of the closing bracket. Of course you can
|
||
insert the closing bracket after calling the completion, too.
|
||
|
||
==============================================================================
|
||
LICENSE *ledger-license*
|
||
|
||
https://github.com/ledger/vim-ledger
|
||
|
||
Copyright 2019–2025 Caleb Maclennan
|
||
Copyright 2009–2017 Johann Klähn
|
||
Copyright 2009 Stefan Karrmann
|
||
Copyright 2005 Wolfgang Oertl
|
||
|
||
This program is free software: you can redistribute it and/or modify it
|
||
under the terms of the GNU General Public License as published by the
|
||
Free Software Foundation, either version 2 of the License, or (at your
|
||
option) any later version.
|
||
|
||
This program is distributed in the hope that it will be useful, but
|
||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
|
||
Public License for more details.
|
||
|
||
You should have received a copy of the GNU General Public License along
|
||
with this program. If not, see <https://www.gnu.org/licenses/>.
|
||
|
||
|
||
vim:ts=8 sw=8 noexpandtab tw=78 ft=help:
|
||
|