sfos/ledger
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

updated docs

Browse source
This commit is contained in:
John Wiegley 2004-09-23 01:52:31 -04:00
parent 996c2abc0f
commit 61b007e58d
1 changed files with 130 additions and 97 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

227
ledger.texi
View file

@ -16,9 +16,6 @@
@node Top, Introduction, (dir), (dir) @node Top, Introduction, (dir), (dir)
@top Overview @top Overview
@c Page published by Emacs Muse begins here
@menu @menu
* Introduction:: * Introduction::
@ -776,7 +773,36 @@ involved. Some examples are:
Value expressions support most simple math and logic operators, in Value expressions support most simple math and logic operators, in
addition to a set of one letter functions and variables. A function's addition to a set of one letter functions and variables. A function's
argument is whatever follows it. argument is whatever follows it. The following is a display predicate
that I use with the @command{balance} command:
@example
ledger -d /^Liabilities/?T<0:AT>100 balance
@end example
The effect is that account totals are displayed only if: 1) A
Liabitilies account has a total less than zero; or 2) the absolute
value of the account's total exceeds 100 units of whatever commodity
contains. If it contains multiple commodities, only one of them must
exceed 100 units.
Display predicates are also very handy with register reports, to
constrain which entries are printed. For example, the following
command shows only entries from the beginning of the current month,
while still calculating the running balance based on all entries:
@example
ledger -d "d>[$(date +%Y/%m/01)]" register checking
@end example
This advantage to this command's complexity is that it prints the
running total in terms of all entries in the register. The following,
simpler command is similar, but totals only the transactions
displayed:
@example
ledger -b "this month" register checking
@end example
@subsection Variables @subsection Variables
@ -1005,100 +1031,106 @@ ledger balance -- -equity
@node File format, , Typical queries, Running Ledger @node File format, , Typical queries, Running Ledger
@section File format @section File format
The ledger file format is quite simple, but supports many options. The ledger file format is quite simple, but also very flexible. It
These are summarized here. supports many options, though typically the user can ignore most of
them. They are summarized below.
The initial character of each line determines what that line means, The initial character of each line determines what the line means, and
and how it should be parsed. The possibilities are: how it should be interpreted. Allowable initial characters are:
@table @code @table @code
@item NUMBER @item NUMBER
A line starting with a number denotes a regular ledger entry. It A line beginning with a number denotes an entry. It may be followed
may be followed by any number of lines that beginning whitespace, to by any number of lines, each beginning with whitespace, to denote the
denote account transactions. The format of the header line is: entry's account transactions. The format of the first line is:
@example @example
DATE [*] [(CODE)] DESC DATE [*] [(CODE)] DESC
@end example @end example
@item + If @samp{*} appears after the date, it indicates that entry is
If a line begins with plus, it denotes an inclusion regexp that ``cleared'', meaning it has been seen a bank statement, or otherwise
will always be considered, as if it had been specified by the user verified. If a @samp{CODE} appears in parentheses, it can be used to
at the end of their command-line. indicate a check number, or the type of the transaction. Following
these is the payee, or a description of the transaction.
@item -
If a line begins with minus, it denotes an exclusion regexp that
will always be considered, as if it had been specified by the user
at the end of their command-line.
@item = @item =
If a line begins with equals, it denotes an automated transaction. An automated transaction. A value expression must appear after the
The next item on the line must be a regular expression. Any number equal sign.
of such lines may appear, with no intervening whitespace.
Following this block of lines can be a list of account transactions
preceded by whitespace.
@item !WORD After this initial line there should be a set of one or more
A line beginning with an exclamation mark denotes a command transactions, just as if it were normal entry. If the amounts of the
directive. It must be immediately followed by a word specifying transactions have no commodity, they will be applied as modifiers to
which directories. At the moment, only @samp{!include} is supported, for whichever real transaction is matched by the value expression.
including the content of other ledger files into the current one.
@item whitespace @item !
A line beginning with whitespace, which is not part of a regular or A line beginning with an exclamation mark denotes a command directive.
automated transaction, is ignored. It must be immediately followed by the command word. The supported
commands are:
@table @strong
@item include
Include the stated ledger file.
@item account
The account name is given is taken to be the parent of all
transactions that follow, until @samp{!end} is seen.
@item end
Ends an account block.
@item python
If Python support is available, all of the lines following
@samp{!python} will be passed to the Python interpretor. Any
functions defined will be available to later Python blocks, and can be
called from a value expression. The Python code block must be ended
with @samp{!end}.
@end table @end table
@quotation @item ;
If a line begins with semicolon it is ignored. This is the A line beginning with a colon indicates a comment, and is ignored.
preferred method of entering comments.
@end quotation
@table @code @item (whitespace)
@item Y NUM A line beginning with whitespace, which is not part of a regular or
If a line begins with a capital Y, it denotes the year to be used automated transaction, is also ignored.
for all subsequent entries that specify a date, whatever their type.
This sets the ``default year'', which ordinarily is the current year
at the time the program is run. Useful at the beginning of a file
to specify the file's year.
@item P DATE SYMBOL PRICE @item Y
Capital P specifies a historical price for a commodity. Any such If a line begins with a capital Y, it denotes the year used for all
number of entries are allowed. These are usually found in a pricing subsequent entries that give a date without a year. The year should
history file (see the @option{-Q} option). appear immediately after the Y, for example: @samp{Y2004}. This is
useful at the beginning of a file, to specify the year for that file.
If all entries specify a year, however, this command has no effect.
@item C SYMBOL PRICE @item P
Capital C specifies a conversion price for a commodity. This has Specifies a historical price for a commodity. These are usually found
no reference to time, and always takes precedence over any in a pricing history file (see the @option{-Q} option). The syntax
historical price (even very current prices). is:
@example
P DATE SYMBOL PRICE
@end example
@item C
Specifies a conversion price for a commodity. This has no reference
to time, and takes precedence over all historical prices (even the
current prices). Syntax is:
@example
C SYMBOL PRICE
@end example
@item N SYMBOL @item N SYMBOL
Capital N indicates that no implicit price conversions should be Indicates that pricing information is to be ignored for a given
obtained for the given symbol. This means that no quotes will ever symbol, nor will quotes ever be downloaded for that symbol. Useful
be downloaded for that symbol. Useful for a home currency, such as with a home currency, such as the dollar ($). It is recommended that
the dollar ($). Be aware that these pricing options will set the these pricing options be set in the price database file, which
default reporting characteristics for a commodity. Thus it is defaults to @filename{~/.pricedb}. The syntax for this command is:
recommended that pricing options occur only after all regular ledger @example
entries have been parsed. N SYMBOL
@end example
@item i DATE TIME ACCOUNT [DESC]
Lowercase (and capital) i indicate an time-in event. This will
start accumulating hours in the account specified. Usually these
entries are created in a timelog file by the timeclock program,
which is distributed with ledger. There must be two spaces between
the account name, and the optional description, if one is used.
@item o DATE TIME ACCOUNT [DESC]
Lowercase (and capital) o indicate an time-out event. This will
accumulate hours in the account specified. Usually these entries
are created in a timelog file by the timeclock program, which is
distributed with ledger. There must be two spaces between the
account name, and the optional description, if one is used.
@item b, h
Entries beginning with lowercase b and h are ignored. These are
special entries used by timeclock, but ignored by ledger.
@item i, o, b, h
These four options relate to timeclock support, which permits ledger
to read timelog files. See the timeclock's documentation for more
info on the syntax of its timelog files.
@end table @end table
@node Keeping a ledger, Extending with Python, Running Ledger, Top @node Keeping a ledger, Extending with Python, Running Ledger, Top
@ -1165,7 +1197,7 @@ For this entry, Ledger will figure out that $-23.00 must come from
* Archiving previous years:: * Archiving previous years::
* Virtual transactions:: * Virtual transactions::
* Automated transactions:: * Automated transactions::
* Differences to Accounting Conventions:: * Differences with accounting conventions::
* Using Emacs to Keep Your Ledger:: * Using Emacs to Keep Your Ledger::
* Using GnuCash to Keep Your Ledger:: * Using GnuCash to Keep Your Ledger::
* Using timeclock to record billable time:: * Using timeclock to record billable time::
@ -1177,8 +1209,8 @@ For this entry, Ledger will figure out that $-23.00 must come from
Accountants will talk of `credits' and `debits', but their meaning is Accountants will talk of `credits' and `debits', but their meaning is
often different from the layman's definitions. To avoid this semantic often different from the layman's definitions. To avoid this semantic
overloading, we will refer to subtractions and additions. See overloading, we will refer to subtractions and additions. See
@uref{README.texi#DtAC, ``Differences to Accounting Conventions''} for how to @ref{Differences with accounting conventions} on how to reconcile the
reconcile the two systems. two systems.
Recall that every transaction will involve two or more accounts. Recall that every transaction will involve two or more accounts.
Money is transferred from one group of accounts to another group. To Money is transferred from one group of accounts to another group. To
@ -1847,16 +1879,17 @@ To view balances without any virtual balances factored in, using the
Write about: Saving for a Special Occasion; Keeping a Budget; Tracking Write about: Saving for a Special Occasion; Keeping a Budget; Tracking
Allocated Funds. Allocated Funds.
@node Automated transactions, Differences to Accounting Conventions, Virtual transactions, Keeping a ledger @node Automated transactions, Differences with accounting conventions, Virtual transactions, Keeping a ledger
@section Automated transactions @section Automated transactions
As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets. As a Bahá'í, I need to compute Huqúqu'lláh as I acquire assets. It is
The exact details of this are a bit complex, so if you have further similar to tithing for Jews and Christians, and to Zakát for Muslims.
interest, please consult the Web. The exact details of computing Huqúqu'lláh are a bit complex, but if
you have further interest, please consult the Web.
For any fellow Bahá'ís out there who want to track Huqúqu'lláh, the Ledger makes this otherwise difficult calculation quite easy. Just
Ledger tool makes this extremely easy. Just set up the following set up the following automated transaction at the top of your ledger
automated transaction at the top of your ledger file: file:
@example @example
; These entries will compute Huqúqu'lláh based on the ; These entries will compute Huqúqu'lláh based on the
@ -1874,12 +1907,13 @@ automated transaction at the top of your ledger file:
This automated transaction works by looking at each transaction This automated transaction works by looking at each transaction
appearing afterward in the ledger file. If any match the account appearing afterward in the ledger file. If any match the account
regexps, occurring after the equal signs above, 19% of the value of regexps, occurring after the equal signs above, 19% of the value of
that transaction is applied to the ``Liabilities:Huqúqu'lláh'' account. that transaction is applied to the ``Liabilities:Huqúqu'lláh''
So if $1000 is earned through Income:Salary, which is seen as a debit account. So if $1000 is earned through Income:Salary, which is seen
from Income, a debit of $190 is applied to ``Liabilities:Huqúqu'lláh''; as a debit from Income, a debit of $190 is applied to
if $1000 is spent on Rent---seen as a credit to the Expense account---a credit of $190 is applied to Huqúqu'lláh. The ultimate balance ``Liabilities:Huqúqu'lláh''; if $1000 is spent on Rent---seen as a
of Huqúqu'lláh reflects how much must be paid to that account in order credit to the Expense account---a credit of $190 is applied to
to balance it to zero. Huqúqu'lláh. The ultimate balance of Huqúqu'lláh reflects how much
must be paid to that account in order to balance it to zero.
When you're ready to pay, just write a check directly to the account When you're ready to pay, just write a check directly to the account
``Liabilities:Huqúqu'lláh'': ``Liabilities:Huqúqu'lláh'':
@ -1898,8 +1932,8 @@ ledger balance Liabilities:Huq
@end example @end example
@node Differences to Accounting Conventions, Using Emacs to Keep Your Ledger, Automated transactions, Keeping a ledger @node Differences with accounting conventions, Using Emacs to Keep Your Ledger, Automated transactions, Keeping a ledger
@section Differences to Accounting Conventions @section Differences with accounting conventions
If you are an accountant, or you are familiar with accounting If you are an accountant, or you are familiar with accounting
terminology, then you might be tearing your hair out after reading the terminology, then you might be tearing your hair out after reading the
above. Please don't! above. Please don't!
@ -1957,7 +1991,7 @@ However, from the bank's perspective it is a credit: the accountant's
cash is a liability for the bank. Consequently, payments to the cash is a liability for the bank. Consequently, payments to the
account will show up as credits on his bank statement. account will show up as credits on his bank statement.
@node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Differences to Accounting Conventions, Keeping a ledger @node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Differences with accounting conventions, Keeping a ledger
@section Using Emacs to Keep Your Ledger @section Using Emacs to Keep Your Ledger
In the Ledger tarball is an Emacs module, @file{ledger.el}. This module In the Ledger tarball is an Emacs module, @file{ledger.el}. This module
@ -2135,6 +2169,5 @@ def foo(d, val):
--amount-expr 'foo'@{$100@} --amount-expr 'foo'@{$100@}
@end example @end example
@c Page published by Emacs Muse ends here
@contents @contents
@bye @bye