dklrt/dklrt.texi

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

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

@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky 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.0.

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.0
@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

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

@node Overview
@section Overview

An add-on to ledger-mode, this package appends recurring
transactions to the current ledger file, usually on entry
to @code{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.

@node Getting Started
@section Getting Started

To append recurring transactions on entry to 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 dklrt-AppendRecurring while in ledger-mode
only, add this line to your emacs profile (optional):

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

If you want to have recurring transactions positioned by date in
the ledger file, add this line to your emacs profile (optional):

(setq dklrt-SortAfterAppend t)

Note that as this causes the ledger buffer to be sorted, it
may, as a side-effect, change the positions of non-recurring
transactions.

@node Known Issues
@section Known Issues

@enumerate
@item
In the configuration file, transaction dates must be
expressed in ISO format, eg ``YYYY-MM-DD'' or
``YYYY/MM/DD'', and this format is preserved when the
transaction is appended to the ledger file. This is
compatible with ledger's default date format, and should
work with 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
Depends on some python code which is included in the package
(and requires that python is installed on the system). The
python program is customisable via variable
@code{dklrt-PythonProgram}.
@end enumerate

@node History
@section History

This package was written between 2011-06-08 and 2011-08-17.

@node Configuration File
@chapter Configuration File

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 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 date is followed by a repetition interval in the
position normally occupied by a ledger transaction code.

The transaction date in the configuration file controls when
the transaction becomes due for appending to the ledger file,
and is the actual transaction date once appended.

@node Date and Period
@section Date and Period

The transaction date must be in ISO format: ``YYYY-MM-DD''
or ``YYYY/MM/DD''. It occurs at the beginning of a line and
marks the start of a transaction (and the end of the
previous transaction, if any).

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:

@cindex time interval
@verbatim
(<Digits><Unit>)
@end verbatim

Where:

@table @code
@item Digits
An unsigned decimal integer period count.

@item Unit
A single character from the following: y (year), m (month) w
(week), d (day), specifying the period unit and following
immediately after the integer without intervening space.
@end table

@node Restrictions
@section Restrictions

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

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

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).

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 file associated with the current buffer exists.

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

@item
A recurring transaction config 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 config file and their dates are compared with
the current date. 

If the transaction is considered
``due'', the transaction is appended to the ledger file. The
append includes the full transaction text as it appears in
the configuration file, except that the repetition interval
(including enclosing parentheses) is removed.

Once a recurring transaction has been appended to the ledger
file its transaction date in the configuration file is
shifted forward by the repetition interval to date of the
next append.

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

The ledger file can optionally be sorted after recurring
transactions are appended so transactions remain ordered by
date. This behaviour is customisable via variable
@code{dklrt-SortAfterAppend}

@node Index
@chapter Index
@printindex cp

@bye