dklrt/dklrt.texi

\input texinfo @c -*-texinfo-*-

@c %**start of header
@setfilename dklrt.info
@settitle Ledger Recurring Transactions 1.00
@c %**end of header

@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex vr cp

@c Before release, run C-u C-c C-u C-a
@c (texinfo-all-menus-update with a prefix arg). This
@c updates the node pointers, which texinfmt.el needs.

@copying
This manual is for emacs package dklrt version 1.00.

Copyright @copyright{} 2010–2013 David Keegan.

May be redistributed under the terms of the Free Software
Foundation GNU Free Documentation Licence.
@end copying

@dircategory Emacs misc features
@direntry
* Ledger Recurring Transactions: (dklrt).
@end direntry

@documentencoding UTF-8

@iftex
@finalout
@end iftex

@macro dkcmditem{key, key2, command}
@item @kbd{\key\}@tie{} (@kbd{\key2\}) (@code{\command\})
@end macro

@macro dkcmd{key, key2, command}
@kbd{\key\}@tie{} (@kbd{\key2\}) (@code{\command\})
@end macro

@macro dkcmdidx{key, key2, command}
@kindex \key\
@kindex \key2\
@findex \command\
@kbd{\key\}@tie{} (@kbd{\key2\}) (@code{\command\})
@end macro

@macro dktag{text}
@samp{\text\}
@end macro

@titlepage
@title Ledger Recurring Transactions 1.00
@author David Keegan
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents

@ifnottex
@node Top
@top Ledger Recurring Transactions
@end ifnottex

@menu
* Introduction::
* Configuration File::
* Operations::
* Index::
@end menu

@node Introduction
@chapter Introduction

An add-on to emacs ledger-mode which appends recurring
transactions to the current ledger file, usually on entry to
ledger-mode. Recurring transactions are configured in a
separate file which conforms to ledger file format and
resides in the same directory as the ledger file.

@menu
* Overview::
* Getting Started::
* Known Issues::
* Changes::
@end menu

@node Overview
@section Overview

@cindex recurring transactions
@cindex transactions, recurring
@pindex ledger
Recurring transactions are accounting transactions that
repeat at regular intervals such as paychecks, standing
orders, and pension contributions. This emacs package
facilitates entry of recurring transactions to a ledger
file, the input file for John Wiegley's ledger program.
@xref{Top,, Overview, ledger3, Ledger: Command-Line
Accounting}.

@findex @code{ledger-mode}
Operating as an add-on to emacs ledger-mode, the package
appends recurring transactions to the current ledger file,
usually on entry to @code{ledger-mode}. @xref{Top,,Overview,
ledger-mode, Ledger Mode}.

@cindex configuration file
Recurring transactions are configured in a separate file
which conforms to ledger file format, and resides in the
same directory as the ledger file. @xref{Configuration File}.

@node Getting Started
@section Getting Started

To append recurring transactions automatically on entry to
@code{ledger-mode}, add this line to your emacs profile:

@lisp
 (add-hook 'ledger-mode-hook 'dklrt-AppendRecurringMaybe)
@end lisp

To bind @kbd{\C-cr} to @code{dklrt-AppendRecurringMaybe} while in
@code{ledger-mode} only, add this line to your emacs profile
(optional):

@findex @code{dklrt-SetCcKeys}
@lisp
(add-hook 'ledger-mode-hook 'dklrt-SetCcKeys)
@end lisp

@vindex @code{dklrt-SortAfterAppend}
If you want to have recurring transactions positioned by date in
the ledger file, add this line to your emacs profile (optional):

@lisp
(setq dklrt-SortAfterAppend t)
@end lisp

Note that as this causes the whole ledger buffer to be
sorted after transactions are appended, it potentially
affects the positions of all transactions.

Finally as the recurring transactions configuration file is
a valid ledger file you may wish to edit it in
@code{ledger-mode}. If so add this to your emacs profile
(optional):

@lisp

(add-to-list 'auto-mode-alist '("\\.rec$" . ledger-mode))

@end lisp


@node Known Issues
@section Known Issues

@cindex issues
@cindex limitations
@enumerate
@item
In the recurring transactions configuration file, a
transaction date must be expressed in ISO format, eg
``YYYY-MM-DD'' or ``YYYY/MM/DD''. This format is preserved
when the transaction is appended to the ledger file. It is
compatible with ledger's default date format, and should
work with @code{ledger-mode}.

Problems can be expected if --input-date-format has been
configured with a non-ISO format in the ledger init file
(.ledgerrc) or on the ledger command line.

@item
The handling if repetition intervals specified in the
configuration file with unit @code{m} (month) or @code{y}
(year) is not ideal when their application results in an
invalid calendar day or a potentially invalid day. In these
situations, the configured day is adjusted back to @code{28}
to ensure validity, and remains at @code{28} for all future
recurrences.

For example, a monthly recurring transaction initially
configured as @emph{Jan 31} in the configuration file
produces recurrences in the ledger file of @emph{Jan 31},
@emph{Feb 28}, @emph{Mar 28}, @emph{Apr 28}, and so on.

Ideally day 31 should be preserved in the configuration file
(perhaps in a comment), and the days emitted to the ledger
file should be as close as possible to 31 as the calendar
permits.

Note that the current implementation does ensure that only
valid calendar dates occur in both the configuration and
ledger files.

@vindex @code{dklrt-PythonProgram}
@item
The emacs code depends on some python code which is included
in the package (and requires that python is installed on the
system). The python executable is customisable via variable
@code{dklrt-PythonProgram}.
@end enumerate

@node Changes
@section Changes

Package dklrt was developed mostly between 2011-06-08 and
2011-08-17.

@table @asis
@item Version 1.00 20131104:
Initial release as package.
@end table

@node Configuration File
@chapter Configuration File

@cindex configuration file
@cindex file, configuration
@vindex @code{dklrt-RecurringConfigFileSuffix}
Recurring transactions for a particular ledger file are
configured in a separate file. The configuration file is in
the same directory as the ledger file, and its filename is
the same as that of the ledger file except that the ledger
file suffix is replaced by @file{.rec}. The suffix is
customisable via variable
@code{dklrt-RecurringConfigFileSuffix}.

@menu
* Format::
* Date and Period::
* Restrictions::
@end menu

@node Format
@section Format

The configuration file contains one or more transactions in
ledger file format. For example:

@smallformat
@verbatim

2013-11-10 (1m) Payee Details
    ; Transaction Note.
    Asset:Bank:Current                       €-10.00  ; [=2013-11-08]
    Expense:Phone                             €10.00  ; Payee: Eircom.
    (Asset:OwedBy:Partner)                    €10.00
    ; Posting Note2.

2013-12-01 (1w) Payee8
    Asset:Bank:Savings                       €200.00
    Expense:SavingPlan

@end verbatim
@end smallformat

Each transaction date is followed by a repetition period
in the position normally occupied by a ledger transaction
code.

A transaction is considered to begin with a transaction date
at the beginning of a line, and includes the remainder of
the line and all subsequent lines up to but excluding the
next transaction date. The transaction date in the
configuration file controls when the transaction becomes due
for appending to the ledger file, and becomes the actual
date of the appended transaction.

@node Date and Period
@section Date and Period

@cindex transaction date
@cindex date, transaction
The transaction date must be in ISO format: ``YYYY-MM-DD''
or ``YYYY/MM/DD''.

@cindex repetition period
@cindex repetition interval
@cindex period, repetition
@cindex interval, repetition
A parenthesised transaction repetition period must follow
the date in the position where a ledger transaction ``code''
would normally occur. It is surrounded by whitespace and is
in the following format:

@verbatim
(<Count><Unit>)

Where:
@end verbatim

@table @code
@item Count
An unsigned decimal integer.

@item Unit
A single character specifying a unit and following
immediately after @code{Count} without intervening space.
The following values are accepted for @code{Unit}:

@table @code

@item d
A fixed interval of @code{Count} days.

@item w
A fixed interval @code{Count} weeks.

@item m
The interval to the same day @code{Count} months later, but
if this results in an invalid calendar day (eg Feb 31), the
day is shifted back until valid (eg to Feb 28).

@item y
The interval to the same day and month @code{Count} years
later, but if this results in an invalid calendar day (eg
Feb29), the day is shifted back until valid (eg to Feb 28).
@end table
@end table

@node Restrictions
@section Restrictions

@cindex restrictions, configuration file
The recurring transactions configuration file must not
contain any of the following ledger constructs:

@enumerate
@item
Stand-alone comment (ie not part of a transaction).

@item
Historical commodity price (starts with ``P'').

@item
Automated transaction (starts with ``='').

@item
Period transaction (starts with ``~'').

@item
Command directive.
@end enumerate

@cindex restrictions, transaction date/payee line
In addition the following restrictions apply to the the
initial (date/payee) line of each transaction:

@enumerate
@item
The transaction date must @emph{not} have an effective/auxiliary
date suffix (of the form ``=YYYY-MM-DD'').

@item
A transaction state/clear flag (immediately after the date)
is @emph{not} permitted.
@end enumerate

@node Operations
@chapter Operations

@findex @code{dklrt-AppendRecurringMaybe}
The main entry point is function
@code{dklrt-AppendRecurringMaybe}. This is normally
configured to run automatically on entry to
@code{ledger-mode}. It can also be bound to a key
(@kbd{\C-cr} is suggested).

@cindex append pre-conditions
@cindex pre-conditions, append
Function @code{dklrt-AppendRecurringMaybe} does nothing
unless all the following conditions are met:

@enumerate

@item
The current buffer is in @code{ledger-mode}.

@item
The current buffer is unmodified.

@item
The ledger file associated with the current buffer exists.

@item
The current file is @emph{not} a recurring transaction
configuration file (ie does not have suffix @file{.rec}).

@item
A recurring transaction configuration file exists for the
current ledger file (same directory and basename, but with
suffix @file{.rec}).

@end enumerate

If all the conditions are met, recurring transactions are
read from the configuration file and their dates are
compared with the current date to determine if they are
``due''.

@cindex append due time
@cindex due time, append
@vindex @code{dklrt-AppendBefore}
By default, a recurring transaction becomes due up to one
day before its transaction date. This is customisable via
variable @code{dklrt-AppendBefore}.

@cindex appended transaction
@cindex transaction, appended
If a transaction is considered ``due'', it is appended to
the ledger file. The append includes the full transaction
text as it appears in the configuration file, except that
the repetition period (including enclosing parentheses) is
removed. The configuration file transaction date is then
shifted forward by the repetition period and again compared
with the current date. If the recurring transaction is still
``due'', it is appended again to the ledger file. The
process repeats until the recurring transaction is no longer
``due''.

Finally the recurring transaction is written back to the
configuration file with its new transaction date.

@cindex sort transactions
@vindex @code{dklrt-SortAfterAppend}
After recurring transactions have been appended, the ledger
file can optionally be sorted to keep transactions ordered
by date. This behaviour is customisable via variable
@code{dklrt-SortAfterAppend}.

@node Index
@chapter Index
@printindex cp

@bye