From cce00a33decfd5ceef48f6c9d65ffbe7680a8639 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 28 Sep 2011 09:00:44 -0700 Subject: [PATCH 01/28] Initial commit of new documentation structure --- doc/L3-Introduction.texi | 161 +++ doc/L3-Journal.texi | 323 ++++++ doc/{ledger3.texi => L3-JournalFormat.texi} | 91 +- doc/L3-Main.texi | 96 ++ doc/L3-Principles.texi | 2 + doc/L3-Syntax.texi | 1044 +++++++++++++++++++ 6 files changed, 1630 insertions(+), 87 deletions(-) create mode 100644 doc/L3-Introduction.texi create mode 100644 doc/L3-Journal.texi rename doc/{ledger3.texi => L3-JournalFormat.texi} (80%) create mode 100644 doc/L3-Main.texi create mode 100644 doc/L3-Principles.texi create mode 100644 doc/L3-Syntax.texi diff --git a/doc/L3-Introduction.texi b/doc/L3-Introduction.texi new file mode 100644 index 00000000..d05f36c2 --- /dev/null +++ b/doc/L3-Introduction.texi @@ -0,0 +1,161 @@ +@c -*-texinfo-*- + +@ledgerprog@ is an accounting tool with the moxie to exist. It provides no +bells or whistles, and returns the user to the days before user +interfaces were even a twinkling in their father's CRT. + +What it does offer is a double-entry accounting journal with all the +flexibility and muscle of its modern day cousins, without any of the +fat. Think of it as the Bran Muffin of accounting tools. + +To use it, you need to start keeping a journal. This is the basis of +all accounting, and if you haven't started yet, now is the time to +learn. The little booklet that comes with your checkbook is a journal, +so we'll describe double-entry accounting in terms of that. + +A checkbook journal records debits (subtractions, or withdrawals) and +credits (additions, or deposits) with reference to a single account: +the checking account. Where the money comes from, and where it goes +to, are described in the payee field, where you write the person or +company's name. The ultimate aim of keeping a checkbook journal is to +know how much money is available to spend. That's really the aim of +all journals. + +What computers add is the ability to walk through these postings, +and tell you things about your spending habits; to let you devise +budgets and get control over your spending; to squirrel away money +into virtual savings account without having to physically move money +around; etc. As you keep your journal, you are recording information +about your life and habits, and sometimes that information can start +telling you things you aren't aware of. Such is the aim of all good +accounting tools. + +The next step up from a checkbook journal, is a journal that keeps track +of all your accounts, not just checking. In such a journal, you record +not only who gets paid---in the case of a debit---but where the money +came from. In a checkbook journal, its assumed that all the money +comes from your checking account. But in a general journal, you write +posting two-lines: the source account and target account. +@emph{There must always be a debit from at least one account for every +credit made to another account}. This is what is meant by +``double-entry'' accounting: the journal must always balance to zero, +with an equal number of debits and credits. + + +For example, let's say you have a checking account and a brokerage +account, and you can write checks from both of them. Rather than keep +two checkbooks, you decide to use one journal for both. In this general +journal you need to record a payment to Pacific Bell for your monthly +phone bill, and a transfer (via check) from your brokerage account to +your checking account. The Pacific Bell bill is $23.00, let's say, and +you want to pay it from your checking account. In the general journal +you need to say where the money came from, in addition to where it's +going to. These transactions might look like this: + +@smallexample +9/29 Pacific Bell $23.00 $23.00 + Checking $-23.00 0 +9/30 Checking $100.00 $100.00 + (123) Brokerage $-100.00 0 +@end smallexample + +The posting must balance to $0: $23 went to Pacific Bell, $23 came from +Checking. The next entry shows check number 123 written against your +brokerage account, transfering money to your checking account. There is +nothing left over to be accounted for, since the money has simply moved +from one account to another in both cases. This is the basis of +double-entry accounting: money never pops in or out of existence; it is +always a posting from one account to another. + +Keeping a general journal is the same as keeping two separate journals: +One for Pacific Bell and one for Checking. In that case, each time a +payment is written into one, you write a corresponding withdrawal into +the other. This makes it easier to write in a ``running balance'', +since you don't have to look back at the last time the account was +referenced---but it also means having a lot of journal books, if you +deal with multiple accounts. + +Here is a good place for an aside on the use of the word `account'. +Most private people consider an account to be something that holds money +at an institution for them. @ledgerprog@ uses a more general definition +of the word. An account is anywhere money can go. Other finance +programs use ``categories'', @ledgerprog@ uses accounts. So, for +example, if you buy some groceries at Trader Joe's then more groceries +at Whole Foods Markets you might assign the transactions like this +@smallexample +2011/03/15 Trader Joe's + Expenses:Groceries $100.00 + Assets:Checking +2011/03/15 Whole Food Market + Expenses:Groceries $75.00 + Assets:Checking +@end smallexample +In both cases the money goes to the ``Groceries'' account, even though +the payees were different. You can set up your accounts in any way you +choose. + +Enter the beauty of computerized accounting. The purpose of the +@ledgerprog@ program is to make general journal accounting simple, by keeping +track of the balances for you. Your only job is to enter the +postings. If a posting does not balance, @ledgerprog@ displays an +error and indicates the incorrect posting.@footnote{In some +special cases, it automatically balances this transaction for you.} + +In summary, there are two aspects of @ledgerprog@ use: updating the journal +data file, and using the @ledgerprog@ tool to view the summarized result of +your transactions. + +And just for the sake of example---as a starting point for those who +want to dive in head-first---here are the journal transactions from above, +formatted as the @ledgerprog program wishes to see them: + +@smallexample +2004/09/29 Pacific Bell + Expenses:Pacific Bell $23.00 + Assets:Checking +@end smallexample + +The account balances and registers in this file, if saved as +@file{ledger.dat}, could be reported using: + +@example +$ ledger -f ledger.dat balance +$ ledger -f ledger.dat register checking +$ ledger -f ledger.dat register bell +@end example + +An important difference between @ledgerprog@ and other finance packages is +that journal will never alter your input file. You can create and edit +that file in any way you prefer, but journal is only for analyzing the +data, not for altering it. + +@section More introduction + + +@section Building the program + +@ledgerprog@ is written in ANSI C++, and should compile on any platform. It +depends on the GNU multiprecision integer library (libgmp), and the +Perl regular expression library (libpcre). It was developed using GNU +make and gcc 3.3, on a PowerBook running OS/X. + +To build and install once you have these libraries on your system, +enter these commands: + +@example +./configure && make install +@end example + +@section Getting help + +If you need help on how to use @ledgerprog, or run into problems, you can +join the @ledgerprog@ mailing list at the following Web address: + +@example +http://groups.google.com/group/ledger-cli +@end example + +You can also find help at the @samp{#ledger} channel on the IRC server +@samp{irc.freenode.net}. + +@node Quick Reference, Ledger Tutorial, Introduction, Top diff --git a/doc/L3-Journal.texi b/doc/L3-Journal.texi new file mode 100644 index 00000000..d2dd565c --- /dev/null +++ b/doc/L3-Journal.texi @@ -0,0 +1,323 @@ +@c -*-texinfo-*- +The most important part of accounting is keeping a good journal. If you +have a good journal, tools can be written to work whatever mathematical +tricks you need to better understand your spending patterns. Without a +good journal, no tool, however smart, can help you. + +The @ledgerprog@ program aims at making journal transactions as simple as +possible. Since it is a command-line tool, it does not provide a user +interface for keeping a journal. If you like, you may use GnuCash to +maintain your journal, in which case @ledgerprog@ will read +GnuCash's data files directly. In that case, read the GnuCash manual +now, and skip to the next chapter. + +If you are not using GnuCash, but a text editor to maintain your +journal, read on. @ledgerprog@ has been designed to make data transactions as +simple as possible, by keeping the journal format easy, and also by +automagically determining as much information as possible based on the +nature of your transactions. + +For example, you do not need to tell @ledgerprog@ about the accounts you +use. Any time @ledgerprog@ sees a posting involving an account it knows +nothing about, it will create it@footnote{This also means if you +misspell an account it will end up getting counted separately from what +you intended. The provided Emacs major mode provides for automatically +filling in account names.}. If you use a commodity that is new to +@ledgerprog@, it will create that commodity, and determine its display +characteristics (placement of the symbol before or after the amount, +display precision, etc) based on how you used the commodity in the +posting. + +@section The Most Basic Entry + +Here is the Pacific Bell example from above, given as a @ledgerprog@ +posting, with the additional of a check number: + +@smallexample +9/29 (1023) Pacific Bell + Expenses:Utilities:Phone $23.00 + Assets:Checking $-23.00 +@end smallexample + +As you can see, it is very similar to what would be written on paper, +minus the computed balance totals, and adding in account names that work +better with @ledgerprog@'s scheme of things. In fact, since +@ledgerprog@ is smart about many things, you don't need to specify the +balanced amount, if it is the same as the first line: + +@smallexample +9/29 (1023) Pacific Bell + Expenses:Utilities:Phone $23.00 + Assets:Checking +@end smallexample + +For this transaction, @ledgerprog@ will figure out that $-23.00 must come from +@samp{Assets:Checking} in order to balance the transaction. + +Also note the structure of the account entries. There is an implied +hierarchy established by separating with colons. See +(@pxref{Structuring Your Accounts}) for details and suggestions regarding +your accounts. + + + +@strong{The format is very flexible and it isn't necessary that you +indent and space out things exactly as shown. The only requirements are +that the start of the transaction (the date typically) is at the +beginning of the first line of the transaction, and the accounts are +indented by at least one space. If you omit the leading spaces in the +account lines @ledgerprog@ will not count the transaction and will not +give an error. There must be at least two spaces, or a tab, between the +amount and the account. If you do not have adequate separation between +the amount and the account @ledgerprog@ will give an error and stop +calculating} + +@section Commodities + +@ledgerprog@ is agnostic when it comes to how you value your accounts. +Dollars, Euros, Pounds, Francs, etc. are just ``commodities''. Holdings +in stocks, bonds, mutual funds and other financial instrument can be +label using whatever is convenient for you (stock ticker symbols are +suggested for publicly traded assets).@footnote{you can track ANYTHING, +even time. As long as it cannot be created or destroyed inside your +accounting system.} + +This is fundamentally different than many common accounting packages, +which assume the same currency throughout all of your accounts. This +means if you typically operate in Euros, but travel to the US and has +some expenses, you would have to do the currency conversion BEFORE you +made the entry into your financial system. With ledger this is not +required. In the same journal you can have entries in any or all +commodities you actually hold. You can use the reporting capabilities +to convert all commodities to a single commodity for reporting purposes +without ever changing the underlying entry. + +For example, the following entries reflect transaction made for a +business trip to Europe from the US: + +@smallexample +2011/09/23 Cash in Munich + Assets:Cash 50.00 Euros + Assets:Checking $-66.00 + +2011/09/24 Dinner in Munich + Expenses:Business:Travel 35.00 Euro + Assets:Cash +@end smallexample + +This says that $66.00 came out of checking and turned into 50 Euros. The +implied exchange rate was $1.32. Then 35 Euros was spent on Dinner in Munich. + + + +@section Structuring your Accounts + +There really are no requirements for how you do this, but to preserve +your sanity we suggest some very basic structure to your accounting +system. + +At the highest level you have five sorts of accounts: Expenses, Assets, +Income, Liabilities and Equity. Briefly, you can think of these as places money goes, +places money sits, places money comes from and money you owe. + +Starting the structure off this way will make it simpler for you to get +answers to the questions you really need to ask about your finances. + +@section Transaction Notes and Tags +@ledgerprog@ 3.0 supports entry and transaction ``notes'', which may +contain new metadata and tag markers. Here's an example: + +@smallexample + 2004/05/27 (100) Credit card company + ; This is an entry note! + ; Sample: Value + Liabilities:MasterCard $20.00 + ; This is a transaction note! + ; Sample: Another Value + ; :MyTag: + Assets:Bank:Checking + ; :AnotherTag: +@end smallexample + +An indented paragraph starting with `;' is parsed as a persistent note +for its preceding category. These notes will get printed back to you +with the ``print'' command. They are accessible to value expressions +using the ``note'' variable. + +Further, any occurrence of ``:foo:'' in a note will cause a metadata tag +for "foo" to be registered for that entry. You can then search for +such transactions using: + +@smallexample + ledger reg %foo + ldeger reg tag foo +@end smallexample + +Also, if any word in the note ends (but does not start) with a colon, +the remainder of that line will be taken to be the metadata value for +that tag. That is: + +@smallexample + ; :foo:bar:baz: <-- These are three tags + ; name: value <-- this is a tag with a value +@end smallexample + +Tags with value can be searched for just like tags. In addition, you +can further limit your tag search by looking for only those tags that +have specific values: + +@smallexample + ledger reg %name=value + ledger reg tag name=value +@end smallexample + +The group-by and sort functions also support tags: +@smallexample +ledger --group-by "tag('foo')" bal +@end smallexample +Will produce a balalnce summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'. + +@smallexample +ledger reg --sort "tag('foo')" %foo +@end smallexample +Produces a register view with the transaction have tag `foo' sorted by the tags value. + +Comments that occur before an entry, or which starts at column +zero, are always ignored and are neither searched nor printed back. + + + +@node File format, , Value expressions, Quick Reference +@section File format + +The ledger file format is quite simple, but also very flexible. It +supports many options, though typically the user can ignore most of +them. They are summarized below. + +The initial character of each line determines what the line means, and +how it should be interpreted. Allowable initial characters are: + +@table @code +@item NUMBER +A line beginning with a number denotes a transaction. It may be followed +by any number of lines, each beginning with whitespace, to denote the +transaction's account postings. The format of the first line is: + +@example +DATE[=EDATE] [*|!] [(CODE)] DESC +@end example + +If @samp{*} appears after the date (with optional effective date), it +indicates the transaction is ``cleared'', which can mean whatever the user +wants it to mean. If @samp{!} appears after the date, it indicates d +the transaction is ``pending''; i.e., tentatively cleared from the user's +point of view, but not yet actually cleared. If a @samp{CODE} appears +in parentheses, it may be used to indicate a check number, or the type +of the posting. Following these is the payee, or a description of +the posting. + +The format of each following posting is: + +@example + ACCOUNT AMOUNT [; NOTE] +@end example + +The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual +postings, or square brackets if it is a virtual postings that +must balance. The @samp{AMOUNT} can be followed by a per-unit +posting cost, by specifying @samp{@@ AMOUNT}, or a complete +posting cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may +specify an actual and/or effective date for the posting by using +the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or +@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}. + +@item = +An automated transaction. A value expression must appear after the equal +sign. + +After this initial line there should be a set of one or more +postings, just as if it were normal transaction. If the amounts of the +postings have no commodity, they will be applied as modifiers to +whichever real posting is matched by the value expression. + +@item ~ +A period transaction. A period expression must appear after the tilde. + +After this initial line there should be a set of one or more +postings, just as if it were normal transaction. + +@item ! +A line beginning with an exclamation mark denotes a command directive. +It must be immediately followed by the command word. The supported +commands are: + +@table @samp +@item !include +Include the stated journal file. + +@item !account +The account name is given is taken to be the parent of all +postings that follow, until @samp{!end} is seen. + +@item !end +Ends an account block. +@end table + +@item ; +A line beginning with a colon indicates a comment, and is +ignored. Comments will not be returned in a ``print'' response. +@item indented ; +If the semi colon is indented and occurs inside a transaction, it is +parsed as a persistent note for its preceding category. These notes or +tags can be used to augment to reporting and filtering capabilities of +@ledgerprog. +@item Y +If a line begins with a capital Y, it denotes the year used for all +subsequent transactions that give a date without a year. The year should +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 transactions specify a year, however, this command has no effect. + +@item P +Specifies a historical price for a commodity. These are usually found +in a pricing history file (see the @option{-Q} option). The syntax +is: +@example +P DATE SYMBOL PRICE +@end example + +@item N SYMBOL +Indicates that pricing information is to be ignored for a given +symbol, nor will quotes ever be downloaded for that symbol. Useful +with a home currency, such as the dollar ($). It is recommended that +these pricing options be set in the price database file, which +defaults to @file{~/.pricedb}. The syntax for this command is: +@example +N SYMBOL +@end example + +@item D AMOUNT +Specifies the default commodity to use, by specifying an amount in the +expected format. The @command{transaction} command will use this commodity +as the default when none other can be determined. This command may be +used multiple times, to set the default flags for different +commodities; whichever is seen last is used as the default commodity. +For example, to set US dollars as the default commodity, while also +setting the thousands flag and decimal flag for that commodity, use: +@example +D $1,000.00 +@end example + +@item C AMOUNT1 = AMOUNT2 +Specifies a commodity conversion, where the first amount is given to +be equivalent to the second amount. The first amount should use the +decimal precision desired during reporting: +@example +C 1.00 Kb = 1024 bytes +@end example + +@item i, o, b, h +These four relate to timeclock support, which permits @ledgerprog@ to read +timelog files. See the timeclock's documentation for more info on the +syntax of its timelog files. +@end table diff --git a/doc/ledger3.texi b/doc/L3-JournalFormat.texi similarity index 80% rename from doc/ledger3.texi rename to doc/L3-JournalFormat.texi index 1f875764..cb14d3c5 100644 --- a/doc/ledger3.texi +++ b/doc/L3-JournalFormat.texi @@ -1,80 +1,3 @@ -\input texinfo @c -*-texinfo-*- - -@setfilename ledger.info -@settitle Ledger: Command-Line Accounting - -@dircategory User Applications -@copying -Copyright (c) 2003-2010, John Wiegley. All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -- Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -- Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -- Neither the name of New Artisans LLC nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -@end copying - -@documentencoding UTF-8 - -@iftex -@finalout -@end iftex - -@titlepage -@title Ledger: Command-Line Accounting -@author John Wiegley -@end titlepage - -@direntry -* Ledger: (ledger). Command-Line Accounting -@end direntry - -@contents - -@ifnottex -@node Top, , (dir), (dir) -@top Overview - -@insertcopying -@end ifnottex - -@ifnottex -@section Copyright -@insertcopying -@end ifnottex - -@chapter Introduction - -@chapter Principles of accounting - -@chapter Keeping a journal - -@chapter Basic reporting commands - -@chapter Command-line syntax - -@chapter Journal data format This chapter offers a complete description of the journal data format, suitable for implementors in other languages to follow. For users, @@ -121,6 +44,10 @@ amount of the first posting is typically positive. Consider: Assets:Checking @end example +@emph{Note:} It is important to note that there must be at least two spaces between +the end of the post and the beginning of the amount (including and +commdity designator). + @section Specifying amounts The heart of a journal is the amounts it records, and this fact is @@ -310,13 +237,3 @@ If a transaction uses only one commodity, this commodity is also considered a primary. In fact, when Ledger goes about ensures that all transactions balance to zero, it only ever asks this of primary commodities. - -@chapter Report queries - -@chapter Value expressions - -@chapter Format strings - -@chapter Extending with Python - -@bye diff --git a/doc/L3-Main.texi b/doc/L3-Main.texi new file mode 100644 index 00000000..03fd268b --- /dev/null +++ b/doc/L3-Main.texi @@ -0,0 +1,96 @@ +\input texinfo @c -*-texinfo-*- + +@setfilename ledger.info +@settitle Ledger: Command-Line Accounting + +@dircategory User Applications +@copying +Copyright (c) 2003-2010, John Wiegley. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +- Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +- Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +- Neither the name of New Artisans LLC nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +@end copying + +@documentencoding UTF-8 + +@iftex +@finalout +@end iftex + +@macro ledgerprog + @sc{ledger} +@end macro + + +@titlepage +@title @ledgerprog: Command-Line Accounting +@author John Wiegley +@end titlepage + +@direntry +* Ledger: (ledger). Command-Line Accounting +@end direntry + +@contents + +@ifnottex +@node Top, , (dir), (dir) +@top Overview + +@insertcopying +@end ifnottex + +@ifnottex +@section Copyright +@insertcopying +@end ifnottex + + +@chapter Introduction + +@include Introduction3.texi + +@chapter Principles of accounting +@include Principles3.texi +@chapter Keeping a journal +@include Journal3.texi +@chapter Basic reporting commands + +@chapter Command-line syntax +@include Syntax3.texi +@chapter Journal data format +@include JournalFormat3.texi + +@chapter Report queries + +@chapter Value expressions + +@chapter Format strings + +@chapter Extending with Python + +@bye diff --git a/doc/L3-Principles.texi b/doc/L3-Principles.texi new file mode 100644 index 00000000..8b7ebf84 --- /dev/null +++ b/doc/L3-Principles.texi @@ -0,0 +1,2 @@ +@c -*-texinfo-*- + diff --git a/doc/L3-Syntax.texi b/doc/L3-Syntax.texi new file mode 100644 index 00000000..afe4520d --- /dev/null +++ b/doc/L3-Syntax.texi @@ -0,0 +1,1044 @@ +@c -*-texinfo-*- + +@section Cookbook + +@subsection Invoking Ledger + +@example +ledger --group-by "tag('trip')" bal +legder reg --sort "tag('foo')" %foo +ledger cleared VWCU NFCU Tithe Misentry +ledger register Joint --uncleared +ledger register NFCUChecking --sort d -d 'd>[2011/04/01]' until 2011/05/25 +@end example +@subsection Ledger Files + +@example += /^Income:Taxable/ + (Liabilities:Tithe Owed) -0.1 += /Noah/ + (Liabilities:Tithe Owed) -0.1 += /Jonah/ + (Liabilities:Tithe Owed) -0.1 += /Tithe/ + (Liabilities:Tithe Owed) -1.0 +@end example + + +@section Quick Reference + +This chapter describes @ledgerprog's features and serves as a quick +reference. You may wish to survey this to get an overview before diving +in to the @ref{Ledger Tutorial} and more detailed examples that follow. + +@ledgerprog@ has a very simple command-line interface, named---enticingly +enough---@command{ledger}. It supports a few reporting commands, and +a large number of options for refining the output from those commands. +The basic syntax of any ledger command is: + +@example +ledger [OPTIONS...] COMMAND [ARGS...] +@end example + +Command options must always precede the command word. After the +command word there may appear any number of arguments. For most +commands, these arguments are regular expressions that cause the +output to relate only to postings matching those regular +expressions. For the @command{transaction} command, the arguments have a +special meaning, described below. + +The regular expressions arguments always match the account name that a +posting refers to. To match on the payee of the transaction instead, +precede the regular expression with @samp{--}. For example, the +following balance command reports account totals for rent, food and +movies, but only those whose payee matches Freddie: + +@example +ledger bal rent food movies -- freddie +@end example + +There are many, many command options available with the +@command{ledger} command, and it takes a while to master them. +However, none of them are required to use the basic reporting +commands. + +@menu +* Commands:: +* Options:: +* Period expressions:: +* Format strings:: +* Value expressions:: +* File format:: +@end menu + +@node Commands, Options, Quick Reference, Quick Reference +@section Commands + +@subsection balance + +The @command{balance} command reports the current balance of all +accounts. It accepts a list of optional regexps, which confine the +balance report to the matching accounts. If an account contains +multiple types of commodities, each commodity's total is reported +separately. + +@subsection register + +The @command{register} command displays all the postings occurring +in a single account, line by line. The account regexp must be +specified as the only argument to this command. If any regexps occur +after the required account name, the register will contain only those +postings that match. Very useful for hunting down a particular +posting. + +The output from @command{register} is very close to what a typical +checkbook, or single-account ledger, would look like. It also shows a +running balance. The final running balance of any register should +always be the same as the current balance of that account. + +If you have Gnuplot installed, you may plot the amount or running +total of any register by using the script @file{report}, which is +included in the @ledgerprog@ distribution. The only requirement is that you +add either @option{-j} or @option{-J} to your register command, in +order to plot either the amount or total column, respectively. + +@subsection print + +The @command{print} command prints out ledger transactions in a textual +format that can be parsed by @ledgerprog@. They will be properly formatted, +and output in the most economic form possible. The ``print'' command +also takes a list of optional regexps, which will cause only those +postings which match in some way to be printed. + +The @command{print} command can be a handy way to clean up a ledger +file whose formatting has gotten out of hand. + +@subsection output + +The @command{output} command is very similar to the @command{print} +command, except that it attempts to replicate the specified ledger +file exactly. The format of the command is: + +@example +ledger -f FILENAME output FILENAME +@end example + +Where @file{FILENAME} is the name of the ledger file to output. The +reason for specifying this command is that only transactions contained +within that file will be output, and not an included transactions (as can +happen with the @command{print} command). + +@subsection xml + +The @command{xml} command outputs results similar to what +@command{print} and @command{register} display, but as an XML form. +This data can then be read in and processed. Use the +@option{--totals} option to include the running total with each +posting. + +@subsection emacs + +The @command{emacs} command outputs results in a form that can be read +directly by Emacs Lisp. The format of the sexp is: + +@example +((BEG-POS CLEARED DATE CODE PAYEE + (ACCOUNT AMOUNT)...) ; list of postings + ...) ; list of transactions +@end example + +@subsection equity + +The @command{equity} command prints out accounts balances as if they +were transactions. This makes it easy to establish the starting balances +for an account, such as when @ref{Archiving previous years}. + +@subsection prices + +The @command{prices} command displays the price history for matching +commodities. The @option{-A} flag is useful with this report, to +display the running average price, or @option{-D} to show each price's +deviation from that average. + +There is also a @command{pricesdb} command which outputs the same +information as @command{prices}, but does in a format that can be +parsed by @ledgerprog@. + +@subsection xact + +The @command{xact} commands simplifies the creation of new transactions. +It works on the principle that 80% of all postings are variants of +earlier postings. Here's how it works: + +Say you currently have this posting in your ledger file: + +@smallexample +2004/03/15 * Viva Italiano + Expenses:Food $12.45 + Expenses:Tips $2.55 + Liabilities:MasterCard $-15.00 +@end smallexample + +Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva +Italiano} again. The exact amounts are different, but the overall +form is the same. With the @command{xact} command you can type: + +@example +ledger xact 2004/4/9 viva food 11 tips 2.50 +@end example + +This produces the following output: + +@smallexample +2004/04/09 Viva Italiano + Expenses:Food $11.00 + Expenses:Tips $2.50 + Liabilities:MasterCard $-13.50 +@end smallexample + +It works by finding a past posting matching the regular expression +@samp{viva}, and assuming that any accounts or amounts specified will +be similar to that earlier posting. If @ledgerprog@ does not succeed in +generating a new transaction, an error is printed and the exit code is set +to @samp{1}. + +There is a shell script in the distribution's @file{scripts} directory +called @file{xact}, which simplifies the task of adding a new transaction +to your ledger. It launches @command{vi} to confirm that the transaction +looks appropriate. + +Here are a few more examples of the @command{xact} command, assuming +the above journal transaction: + +@example +ledger xact 4/9 viva 11.50 +ledger xact 4/9 viva 11.50 checking # (from `checking') +ledger xact 4/9 viva food 11.50 tips 8 +ledger xact 4/9 viva food 11.50 tips 8 cash +ledger xact 4/9 viva food $11.50 tips $8 cash +ledger xact 4/9 viva dining "DM 11.50" +@end example + +@node Options, Period expressions, Commands, Quick Reference +@section Options + +With all of the reports, command-line options are useful to modify the +output generated. These command-line options always occur before the +command word. This is done to distinguish options from exclusive +regular expressions, which also begin with a dash. The basic form for +most commands is: + +@example +ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] +@end example + +The @var{OPTIONS} and @var{REGEXPS} expressions are both optional. +You could just use @samp{ledger balance}, without any options---which +prints a summary of all accounts. But for more specific reporting, or +to change the appearance of the output, options are needed. + +@subsection Basic options + +These are the most basic command options. Most likely, the user will +want to set them using environment variables (see @ref{Options}), +instead of using actual command-line options: + +@option{--help} (@option{-h}) prints a summary of all the options, and +what they are used for. This can be a handy way to remember which +options do what. This help screen is also printed if ledger is run +without a command. + +@option{--version} (@option{-v}) prints the current version of ledger +and exits. This is useful for sending bug reports, to let the author +know which version of ledger you are using. + +@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. +This command may be used multiple times. +Typically, the environment variable +@env{LEDGER_FILE} is set, rather than using this command-line option. + +@option{--output FILE} (@option{-o FILE}) redirects output from any +command to @var{FILE}. By default, all output goes to standard +output. + +@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by +ledger before any other ledger file. This file may not contain any +postings, but it may contain option settings. To specify options +in the init file, use the same syntax as the command-line, but put each +option on it's own line. Here's an example init file: + +@smallexample +--price-db ~/finance/.pricedb +--cache /tmp/ledger-cache + +; ~/.ledgerrc ends here +@end smallexample + +Option settings on the command-line or in the environment always take +precedence over settings in the init file. + +@option{--cache FILE} identifies FILE as the default binary cache +file. That is, if the ledger files to be read are specified using the +environment variable @env{LEDGER_FILE}, then whenever a command is +finished a binary copy will be written to the specified cache, to +speed up the loading time of subsequent queries. This filename can +also be given using the environment variable @env{LEDGER_CACHE}, or by +putting the option into your init file. The @option{--no-cache} +option causes @ledgerprog@ to always ignore the binary cache. + +@option{--account NAME} (@option{-a NAME}) specifies the default +account which QIF file postings are assumed to relate to. + +@subsection Report filtering + +These options change which postings affect the outcome of a +report, in ways other than just using regular expressions: + +@option{--current}(@option{-c}) displays only transactions occurring on or +before the current date. + +@option{--begin DATE} (@option{-b DATE}) constrains the report to +transactions on or after @var{DATE}. Only transactions after that date will be +calculated, which means that the running total in the balance report +will always start at zero with the first matching transaction. (Note: This +is different from using @option{--display} to constrain what is +displayed). + +@option{--end DATE} (@option{-e DATE}) constrains the report so that +transactions on or after @var{DATE} are not considered. The ending date +is inclusive. + +@option{--period STR} (@option{-p STR}) sets the reporting period +to @var{STR}. This will subtotal all matching transactions within each +period separately, making it easy to see weekly, monthly, quarterly, +etc., posting totals. A period string can even specify the +beginning and end of the report range, using simple terms like ``last +june'' or ``next month''. For more using period expressions, see +@ref{Period expressions}. + +@option{--period-sort EXPR} sorts the postings within each +reporting period using the value expression @var{EXPR}. This is most +often useful when reporting monthly expenses, in order to view the +highest expense categories at the top of each month: + +@example +ledger -M --period-sort -At reg ^Expenses +@end example + +@option{--cleared} (@option{-C}) displays only postings whose transaction +has been marked ``cleared'' (by placing an asterix to the right of the +date). + +@option{--uncleared} (@option{-U}) displays only postings whose +transaction has not been marked ``cleared'' (i.e., if there is no asterix to +the right of the date). + +@option{--real} (@option{-R}) displays only real postings, not +virtual. (A virtual posting is indicated by surrounding the +account name with parentheses or brackets; see the section on using +virtual postings for more information). + +@option{--actual} (@option{-L}) displays only actual postings, and +not those created due to automated postings. + +@option{--related} (@option{-r}) displays postings that are +related to whichever postings would otherwise have matched the +filtering criteria. In the register report, this shows where money +went to, or the account it came from. In the balance report, it shows +all the accounts affected by transactions having a related posting. +For example, if a file had this transaction: + +@smallexample +2004/03/20 Safeway + Expenses:Food $65.00 + Expenses:Cash $20.00 + Assets:Checking $-85.00 +@end smallexample + +And the register command was: + +@example +ledger -r register food +@end example + +The following would be output, showing the postings related to the +posting that matched: + +@smallexample +2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 + Assets:Checking $85.00 $65.00 +@end smallexample + +@option{--budget} is useful for displaying how close your postings +meet your budget. @option{--add-budget} also shows unbudgeted +postings, while @option{--unbudgeted} shows only those. +@option{--forecast} is a related option that projects your budget into +the future, showing how it will affect future balances. +@xref{Budgeting and forecasting}. + +@option{--limit EXPR} (@option{-l EXPR}) limits which postings +take part in the calculations of a report. + +@option{--amount EXPR} (@option{-t EXPR}) changes the value expression +used to calculate the ``value'' column in the @command{register} +report, the amount used to calculate account totals in the +@command{balance} report, and the values printed in the +@command{equity} report. @xref{Value expressions}. + +@option{--total EXPR} (@option{-T EXPR}) sets the value expression +used for the ``totals'' column in the @command{register} and +@command{balance} reports. + +@subsection Output customization + +These options affect only the output, but not which postings are +used to create it: + +@option{--collapse} (@option{-n}) causes transactions in a +@command{register} report with multiple postings to be collapsed +into a single, subtotaled transaction. + +@option{--subtotal} (@option{-s}) causes all transactions in a +@command{register} report to be collapsed into a single, subtotaled +transaction. + +@option{--by-payee} (@option{-P}) reports subtotals by payee. + +@option{--comm-as-payee} (@option{-x}) changes the payee of every +posting to be the commodity used in that posting. This can be +useful when combined with other options, such as @option{-s}. + +@option{--empty} (@option{-E}) includes even empty accounts in the +@command{balance} report. + +@option{--weekly} (@option{-W}) reports posting totals by the +week. The week begins on whichever day of the week begins the month +containing that posting. To set a specific begin date, use a +period string, such as @samp{weekly from DATE}. @option{--monthly} +(@option{-M}) reports posting totals by month; @option{--yearly} +(@option{-Y}) reports posting totals by year. For more complex +period, using the @option{--period} option described above. + +@option{--dow} reports postings totals for each day of the week. +This is an easy way to see if weekend spending is more than on +weekdays. + +@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing +the values determined using the value expression @var{EXPR}. For +example, using @option{-S -UT} in the balance report will sort account +balances from greatest to least, using the absolute value of the +total. For more on how to use value expressions, see @ref{Value +expressions}. + +@option{--wide} (@option{-w}) causes the default @command{register} +report to assume 132 columns instead of 80. + +@option{--head} causes only the first N transactions to be printed. This +is different from using the command-line utility @command{head}, which +would limit to the first N postings. @option{--tail} outputs only +the last N transactions. Both options may be used simultaneously. If a +negative amount is given, it will invert the meaning of the flag +(instead of the first five transactions being printed, for example, it +would print all but the first five). + +@option{--pager} tells @ledgerprog@ to pass its output to the given pager +program---very useful when the output is especially long. This +behavior can be made the default by setting the @env{LEDGER_PAGER} +environment variable. + +@option{--average} (@option{-A}) reports the average posting +value. + +@option{--deviation} (@option{-D}) reports each posting's +deviation from the average. It is only meaningful in the +@command{register} and @command{prices} reports. + +@option{--percentage} (@option{-%}) shows account subtotals in the +@command{balance} report as percentages of the parent account. + +@option{--totals} include running total information in the +@command{xml} report. + +@option{--amount-data} (@option{-j}) changes the @command{register} +report so that it outputs nothing but the date and the value column, +and the latter without commodities. This is only meaningful if the +report uses a single commodity. This data can then be fed to other +programs, which could plot the date, analyze it, etc. + +@option{--total-data} (@option{-J}) changes the @command{register} +report so that it outputs nothing but the date and totals column, +without commodities. + +@option{--display EXPR} (@option{-d EXPR}) limits which postings +or accounts or actually displayed in a report. They might still be +calculated, and be part of the running total of a register report, for +example, but they will not be displayed. This is useful for seeing +last month's checking postings, against a running balance which +includes all posting values: + +@example +ledger -d "d>=[last month]" reg checking +@end example + +The output from this command is very different from the following, +whose running total includes only postings from the last month +onward: + +@example +ledger -p "last month" reg checking +@end example + +Which is more useful depends on what you're looking to know: the total +amount for the reporting range (@option{-p}), or simply a display +restricted to the reporting range (using @option{-d}). + +@option{--date-format STR} (@option{-y STR}) changes the basic date +format used by reports. The default uses a date like 2004/08/01, +which represents the default date format of @samp{%Y/%m/%d}. To +change the way dates are printed in general, the easiest way is to put +@option{--date-format FORMAT} in the @ledgerprog@ initialization file +@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). + +@option{--format STR} (@option{-F STR}) sets the reporting format for +whatever report ledger is about to make. @xref{Format strings}. +There are also specific format commands for each report type: + +@itemize +@item @option{--balance-format STR} +@item @option{--register-format STR} +@item @option{--print-format STR} +@item @option{--plot-amount-format STR} (-j @command{register}) +@item @option{--plot-total-format STR} (-J @command{register}) +@item @option{--equity-format STR} +@item @option{--prices-format STR} +@item @option{--wide-register-format STR} (-w @command{register}) +@end itemize + +@subsection Commodity reporting + +These options affect how commodity values are displayed: + +@option{--price-db FILE} sets the file that is used for recording +downloaded commodity prices. It is always read on startup, to +determine historical prices. Other settings can be placed in this +file manually, to prevent downloading quotes for a specific, for +example. This is done by adding a line like the following: + +@example +; Don't download quotes for the dollar, or timelog values +N $ +N h +@end example + +@option{--price-exp MINS} (@option{-L MINS}) sets the expected +freshness of price quotes, in minutes. That is, if the last known +quote for any commodity is older than this value---and if +@option{--download} is being used---then the Internet will be +consulted again for a newer price. Otherwise, the old price is still +considered to be fresh enough. + +@option{--download} (@option{-Q}) causes quotes to be automagically +downloaded, as needed, by running a script named @command{getquote} +and expecting that script to return a value understood by ledger. A +sample implementation of a @command{getquote} script, implemented in +Perl, is provided in the distribution. Downloaded quote price are +then appended to the price database, usually specified using the +environment variable @env{LEDGER_PRICE_DB}. + +There are several different ways that ledger can report the totals it +displays. The most flexible way to adjust them is by using value +expressions, and the @option{-t} and @option{-T} options. However, +there are also several ``default'' reports, which will satisfy most +users basic reporting needs: + +@table @code +@item -O, --quantity +Reports commodity totals (this is the default) + +@item -B, --basis +Reports the cost basis for all postings. + +@item -V, --market +Reports the last known market value for all commodities. + +@item -G --gain +Reports the net gain/loss for all commodities in the report that have +a price history. +@end table + +@subsection Environment variables + +Every option to ledger may be set using an environment variable. If +an option has a long name such @option{--this-option}, setting the +environment variable @env{LEDGER_THIS_OPTION} will have the same +affect as specifying that option on the command-line. Options on the +command-line always take precedence over environment variable +settings, however. + +Note that you may also permanently specify option values by placing +option settings in the file @file{~/.ledgerrc}, for example: + +@example +--cache /tmp/.mycache +--pager /bin/cat + +@end example + +@node Period expressions, Format strings, Options, Quick Reference +@section Period expressions + +A period expression indicates a span of time, or a reporting interval, +or both. The full syntax is: + +@example +[INTERVAL] [BEGIN] [END] +@end example + +The optional @var{INTERVAL} part may be any one of: + +@example +every day +every week +every monthly +every quarter +every year +every N days # N is any integer +every N weeks +every N months +every N quarters +every N years +daily +weekly +biweekly +monthly +bimonthly +quarterly +yearly +@end example + +After the interval, a begin time, end time, both or neither may be +specified. As for the begin time, it can be either of: + +@example +from +since +@end example + +The end time can be either of: + +@example +to +until +@end example + +Where @var{SPEC} can be any of: + +@example +2004 +2004/10 +2004/10/1 +10/1 +october +oct +this week # or day, month, quarter, year +next week +last week +@end example + +The beginning and ending can be given at the same time, if it spans a +single period. In that case, just use @var{SPEC} by itself. In that +case, the period @samp{oct}, for example, will cover all the days in +october. The possible forms are: + +@example + +in +@end example + +Here are a few examples of period expressions: + +@example +monthly +monthly in 2004 +weekly from oct +weekly from last month +from sep to oct +from 10/1 to 10/5 +monthly until 2005 +from apr +until nov +last oct +weekly last august +@end example + +@node Format strings, Value expressions, Period expressions, Quick Reference +@section Format strings + +Format strings may be used to change the output format of reports. +They are specified by passing a formatting string to the +@option{--format} (@option{-F}) option. Within that string, +constructs are allowed which make it possible to display the various +parts of an account or posting in custom ways. + +Within a format strings, a substitution is specified using a percent +character (@samp{%}). The basic format of all substitutions is: + +@example +%[-][MIN WIDTH][.MAX WIDTH]EXPR +@end example + +If the optional minus sign (@samp{-}) follows the percent character, +whatever is substituted will be left justified. The default is right +justified. If a minimum width is given next, the substituted text +will be at least that wide, perhaps wider. If a period and a maximum +width is given, the substituted text will never be wider than this, +and will be truncated to fit. Here are some examples: + +@example +%-P a transaction's payee, left justified +%20P The same, right justified, at least 20 chars wide +%.20P The same, no more than 20 chars wide +%-.20P Left justified, maximum twenty chars wide +@end example + +The expression following the format constraints can be a single +letter, or an expression enclosed in parentheses or brackets. The +allowable expressions are: + +@table @code +@item % +Inserts a percent sign. + +@item t +Inserts the results of the value expression specified by @option{-t}. +If @option{-t} was not specified, the current report style's value +expression is used. + +@item T +Inserts the results of the value expression specified by @option{-T}. +If @option{-T} was not specified, the current report style's value +expression is used. + +@item | +Inserts a single space. This is useful if a width is specified, for +inserting a certain number of spaces. + +@item _ +Inserts a space for each level of an account's depth. That is, if an +account has two parents, this construct will insert two spaces. If a +minimum width is specified, that much space is inserted for each level +of depth. Thus @samp{%5_}, for an account with four parents, will +insert twenty spaces. + +@item (EXPR) +Inserts the amount resulting from the value expression given in +parentheses. To insert five times the total value of an account, for +example, one could say @samp{%12(5*O)}. Note: It's important to put +the five first in that expression, so that the commodity doesn't get +stripped from the total. + +@item [DATEFMT] +Inserts the result of formatting a posting's date with a date +format string, exactly like those supported by @code{strftime}. For +example: @samp{%[%Y/%m/%d %H:%M:%S]}. + +@item S +Insert the pathname of the file from which the transaction's data was read. + +@item B +Inserts the beginning character position of that transaction within the file. + +@item b +Inserts the beginning line of that transaction within the file. + +@item E +Inserts the ending character position of that transaction within the file. + +@item e +Inserts the ending line of that transaction within the file. + +@item D +By default, this is the same as @samp{%[%Y/%m%/d]}. The date format +used can be changed at any time with the @option{-y} flag, however. +Using @samp{%D} gives the user more control over the way dates are +output. + +@item d +This is the same as the @samp{%D} option, unless the transaction has an +effective date, in which case it prints +@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}. + +@item X +If a posting has been cleared, this inserts @samp{*} followed by a +space; otherwise nothing is inserted. + +@item Y +This is the same as @samp{%X}, except that it only displays a state +character if all of the member postings have the same state. + +@item C +Inserts the checking number for a transaction, in parentheses, followed by +a space; if none was specified, nothing is inserted. + +@item P +Inserts the payee related to a posting. + +@item a +Inserts the optimal short name for an account. This is normally used +in balance reports. It prints a parent account's name if that name +has not been printed yet, otherwise it just prints the account's name. + +@item A +Inserts the full name of an account. + +@item W +This is the same as @samp{%A}, except that it first displays the +posting's state @emph{if the transaction's posting states are not +all the same}, followed by the full account name. This is offered as +a printing optimization, so that combined with @samp{%Y}, only the +minimum amount of state detail is printed. + +@item o +Inserts the ``optimized'' form of a posting's amount. This is +used by the print report. In some cases, this inserts nothing; in +others, it inserts the posting amount and its cost. It's use is +not recommend unless you are modifying the print report. + +@item n +Inserts the note associated with a posting, preceded by two spaces +and a semi-colon, if it exists. Thus, no none becomes an empty +string, while the note @samp{foo} is substituted as @samp{ ; foo}. + +@item N +Inserts the note associated with a posting, if one exists. + +@item / +The @samp{%/} construct is special. It separates a format string +between what is printed for the first posting of a transaction, and +what is printed for all subsequent postings. If not used, the +same format string is used for all postings. +@end table + +@node Value expressions, File format, Format strings, Quick Reference +@section Value expressions + +Value expressions are an expression language used by @ledgerprog@ to +calculate values used by the program for many different purposes: + +@enumerate +@item +The values displayed in reports +@item +For predicates (where truth is anything non-zero), to determine which +postings are calculated (@option{-l}) or displayed (@option{-d}). +@item +For sorting criteria, to yield the sort key. +@item +In the matching criteria used by automated postings. +@end enumerate + +Value expressions support most simple math and logic operators, in +addition to a set of one letter functions and variables. A function's +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:UT>100 balance +@end example + +The effect is that account totals are displayed only if: 1) A +Liabilities 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 transactions are printed. For example, the following +command shows only transactions from the beginning of the current month, +while still calculating the running balance based on all transactions: + +@example +ledger -d "d>[this month]" register checking +@end example + +This advantage to this command's complexity is that it prints the +running total in terms of all transactions in the register. The following, +simpler command is similar, but totals only the displayed +postings: + +@example +ledger -b "this month" register checking +@end example + +@subsection Variables + +Below are the one letter variables available in any value expression. +For the register and print commands, these variables relate to +individual postings, and sometimes the account affected by a +posting. For the balance command, these variables relate to +accounts---often with a subtle difference in meaning. The use of each +variable for both is specified. + +@table @code +@item t +This maps to whatever the user specified with @option{-t}. In a +register report, @option{-t} changes the value column; in a balance +report, it has no meaning by default. If @option{-t} was not +specified, the current report style's value expression is used. + +@item T +This maps to whatever the user specified with @option{-T}. In a +register report, @option{-T} changes the totals column; in a balance +report, this is the value given for each account. If @option{-T} was +not specified, the current report style's value expression is used. + +@item m +This is always the present moment/date. +@end table + +@subsubsection Posting/account details + +@table @code +@item d +A posting's date, as the number of seconds past the epoch. This +is always ``today'' for an account. + +@item a +The posting's amount; the balance of an account, without +considering children. + +@item b +The cost of a posting; the cost of an account, without its +children. + +@item v +The market value of a posting, or an account without its children. + +@item g +The net gain (market value minus cost basis), for a posting or an +account without its children. It is the same as @samp{v-b}. + +@item l +The depth (``level'') of an account. If an account has one parent, +it's depth is one. + +@item n +The index of a posting, or the count of postings affecting an +account. + +@item X +1 if a posting's transaction has been cleared, 0 otherwise. + +@item R +1 if a posting is not virtual, 0 otherwise. + +@item Z +1 if a posting is not automated, 0 otherwise. +@end table + +@subsubsection Calculated totals + +@table @code +@item O +The total of all postings seen so far, or the total of an account +and all its children. + +@item N +The total count of postings affecting an account and all its +children. + +@item B +The total cost of all postings seen so far; the total cost of an +account and all its children. + +@item V +The market value of all postings seen so far, or of an account and +all its children. + +@item G +The total net gain (market value minus cost basis), for a series of +postings, or an account and its children. It is the same as +@samp{V-B}. +@end table + +@subsection Functions + +The available one letter functions are: + +@table @code +@item - +Negates the argument. + +@item U +The absolute (unsigned) value of the argument. + +@item S +Strips the commodity from the argument. + +@item A +The arithmetic mean of the argument; @samp{Ax} is the same as +@samp{x/n}. + +@item P +The present market value of the argument. The syntax @samp{P(x,d)} is +supported, which yields the market value at time @samp{d}. If no date +is given, then the current moment is used. +@end table + +@subsection Operators + +The binary and ternary operators, in order of precedence, are: + +@enumerate +@item @samp{* /} +@item @samp{+ -} +@item @samp{! < > =} +@item @samp{& | ?:} +@end enumerate + +@subsection Complex expressions + +More complicated expressions are possible using: + +@table @code +@item NUM +A plain integer represents a commodity-less amount. + +@item @{AMOUNT@} +An amount in braces can be any kind of amount supported by ledger, +with or without a commodity. Use this for decimal values. + +@item /REGEXP/ +@item W/REGEXP/ +A regular expression that matches against an account's full name. If +a posting, this will match against the account affected by the +posting. + +@item //REGEXP/ +@item p/REGEXP/ +A regular expression that matches against a transaction's payee name. + +@item ///REGEXP/ +@item w/REGEXP/ +A regular expression that matches against an account's base name. If +a posting, this will match against the account affected by the +posting. + +@item c/REGEXP/ +A regular expression that matches against the transaction code (the text +that occurs between parentheses before the payee name). + +@item e/REGEXP/ +A regular expression that matches against a posting's note, or +comment field. + +@item (EXPR) +A sub-expression is nested in parenthesis. This can be useful passing +more complicated arguments to functions, or for overriding the natural +precedence order of operators. + +@item [DATE] +Useful specifying a date in plain terms. For example, you could say +@samp{[2004/06/01]}. +@end table + From c866dbd82124392f965779b74125308c1aa96e12 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 28 Sep 2011 09:22:59 -0700 Subject: [PATCH 02/28] added chapter files for Queries, Reporting, Format Strings, Python Extensions, and Value Expressions --- doc/L3-FormatStrings.texi | 3 +++ doc/L3-Python.texi | 3 +++ doc/L3-Queries.texi | 3 +++ doc/L3-Reporting.texi | 3 +++ doc/L3-ValueExpressions.texi | 3 +++ 5 files changed, 15 insertions(+) create mode 100644 doc/L3-FormatStrings.texi create mode 100644 doc/L3-Python.texi create mode 100644 doc/L3-Queries.texi create mode 100644 doc/L3-Reporting.texi create mode 100644 doc/L3-ValueExpressions.texi diff --git a/doc/L3-FormatStrings.texi b/doc/L3-FormatStrings.texi new file mode 100644 index 00000000..c7fff08c --- /dev/null +++ b/doc/L3-FormatStrings.texi @@ -0,0 +1,3 @@ +@c -*-texinfo-*- + +@chapter Format Strings diff --git a/doc/L3-Python.texi b/doc/L3-Python.texi new file mode 100644 index 00000000..ebb4d530 --- /dev/null +++ b/doc/L3-Python.texi @@ -0,0 +1,3 @@ +@c -*-texinfo-*- + +@chapter Extending with Python diff --git a/doc/L3-Queries.texi b/doc/L3-Queries.texi new file mode 100644 index 00000000..ef45d948 --- /dev/null +++ b/doc/L3-Queries.texi @@ -0,0 +1,3 @@ +@c -*-texinfo-*- + +@chapter Report Queries diff --git a/doc/L3-Reporting.texi b/doc/L3-Reporting.texi new file mode 100644 index 00000000..7fea2fef --- /dev/null +++ b/doc/L3-Reporting.texi @@ -0,0 +1,3 @@ +@c -*-texinfo-*- + +@chapter Basic Reporting Commands diff --git a/doc/L3-ValueExpressions.texi b/doc/L3-ValueExpressions.texi new file mode 100644 index 00000000..02d00e6a --- /dev/null +++ b/doc/L3-ValueExpressions.texi @@ -0,0 +1,3 @@ +@c -*-texinfo-*- + +@chapter Value Expression From 64a01eac286886e484b800e1b3b5e652661aeaa3 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 28 Sep 2011 09:24:27 -0700 Subject: [PATCH 03/28] added chapter files for Queries, Reporting, Format Strings, Python Extensions, and Value Expressions --- doc/L3-Introduction.texi | 1 + doc/L3-Journal.texi | 3 +++ doc/L3-JournalFormat.texi | 3 +++ doc/L3-Main.texi | 34 +++++++++++----------------------- doc/L3-Principles.texi | 1 + doc/L3-Syntax.texi | 1 + 6 files changed, 20 insertions(+), 23 deletions(-) diff --git a/doc/L3-Introduction.texi b/doc/L3-Introduction.texi index d05f36c2..6b0167d8 100644 --- a/doc/L3-Introduction.texi +++ b/doc/L3-Introduction.texi @@ -1,4 +1,5 @@ @c -*-texinfo-*- +@chapter Introduction @ledgerprog@ is an accounting tool with the moxie to exist. It provides no bells or whistles, and returns the user to the days before user diff --git a/doc/L3-Journal.texi b/doc/L3-Journal.texi index d2dd565c..1eb9afa6 100644 --- a/doc/L3-Journal.texi +++ b/doc/L3-Journal.texi @@ -1,4 +1,7 @@ @c -*-texinfo-*- + +@chapter Keeping a Journal + The most important part of accounting is keeping a good journal. If you have a good journal, tools can be written to work whatever mathematical tricks you need to better understand your spending patterns. Without a diff --git a/doc/L3-JournalFormat.texi b/doc/L3-JournalFormat.texi index cb14d3c5..f06e5a62 100644 --- a/doc/L3-JournalFormat.texi +++ b/doc/L3-JournalFormat.texi @@ -1,3 +1,6 @@ +@c -*-texinfo-*- + +@chapter @ledgerprog@ Journal File Format This chapter offers a complete description of the journal data format, suitable for implementors in other languages to follow. For users, diff --git a/doc/L3-Main.texi b/doc/L3-Main.texi index 03fd268b..7f1c91f7 100644 --- a/doc/L3-Main.texi +++ b/doc/L3-Main.texi @@ -69,28 +69,16 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @insertcopying @end ifnottex - -@chapter Introduction - -@include Introduction3.texi - -@chapter Principles of accounting -@include Principles3.texi -@chapter Keeping a journal -@include Journal3.texi -@chapter Basic reporting commands - -@chapter Command-line syntax -@include Syntax3.texi -@chapter Journal data format -@include JournalFormat3.texi - -@chapter Report queries - -@chapter Value expressions - -@chapter Format strings - -@chapter Extending with Python +@c each chapter is in an idividual texi file included here +@include L3-Introduction.texi +@include L3-Principles.texi +@include L3-Journal.texi +@include L3-Reporting.texi +@include L3-Syntax.texi +@include L3-JournalFormat.texi +@include L3-Reporting.texi +@include L3-ValueExpressions.texi +@include L3-FormatStrings.texi +@include L3-Python.texi @bye diff --git a/doc/L3-Principles.texi b/doc/L3-Principles.texi index 8b7ebf84..778cc52d 100644 --- a/doc/L3-Principles.texi +++ b/doc/L3-Principles.texi @@ -1,2 +1,3 @@ @c -*-texinfo-*- +@chapter Principles of Accounting diff --git a/doc/L3-Syntax.texi b/doc/L3-Syntax.texi index afe4520d..15e6e8f8 100644 --- a/doc/L3-Syntax.texi +++ b/doc/L3-Syntax.texi @@ -1,5 +1,6 @@ @c -*-texinfo-*- +@chapter Command-line Syntax @section Cookbook @subsection Invoking Ledger From a45ae5d8def88f7e37eae622d179a7b0b58adb84 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 28 Sep 2011 11:08:54 -0700 Subject: [PATCH 04/28] Corrected bracket quotation problem --- doc/L3-JournalFormat.texi | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/L3-JournalFormat.texi b/doc/L3-JournalFormat.texi index f06e5a62..ac7059ca 100644 --- a/doc/L3-JournalFormat.texi +++ b/doc/L3-JournalFormat.texi @@ -1,11 +1,11 @@ @c -*-texinfo-*- - -@chapter @ledgerprog@ Journal File Format +@node Journal File Format,Extending with Python, Format Strings, Top +@chapter LEDGER Journal File Format This chapter offers a complete description of the journal data format, suitable for implementors in other languages to follow. For users, the chapter on keeping a journal is less extensive, but more typical -of common usage (@pxref{Keeping a journal}). +of common usage (@pxref{Keeping a Journal}). Data is collected in the form of @dfn{transactions} which occur in one or more @dfn{journal files}. Each transaction, in turn, is made up of @@ -25,7 +25,7 @@ one hundred dollars from an account within the Income hierarchy, to the specified expense account. The name and meaning of these accounts in arbitrary, with no preferences implied, although you will find it useful to follow standard accounting practice (@pxref{Principles of -accounting}). +Accounting}). Since an amount is missing from the second posting, it is assumed to be the inverse of the first. This guarantee the cardinal rule of @@ -123,7 +123,7 @@ characters are allowed in a commodity name, except for the following: @item Numerical digits @item Punctuation: @samp{.,;:?!} @item Mathematical and logical operators: @samp{-+*/^&|=} -@item Bracketing characters: @samp{<>[](){}} +@item Bracketing characters: @samp{<>[]()}@{@} @item The at symbol: @samp{@@} @end itemize From 49f9a28715b2813db47d6dc7302be6ca3cc482d3 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 28 Sep 2011 12:06:47 -0700 Subject: [PATCH 05/28] Established info node consistency --- doc/L3-FormatStrings.texi | 146 ++++++++++++ doc/L3-Introduction.texi | 28 +-- doc/L3-Journal.texi | 58 +++-- doc/L3-Main.texi | 18 +- doc/L3-Principles.texi | 1 + doc/L3-Python.texi | 2 +- doc/L3-Reporting.texi | 8 + doc/L3-Syntax.texi | 432 +++-------------------------------- doc/L3-ValueExpressions.texi | 229 ++++++++++++++++++- 9 files changed, 484 insertions(+), 438 deletions(-) diff --git a/doc/L3-FormatStrings.texi b/doc/L3-FormatStrings.texi index c7fff08c..ee56891f 100644 --- a/doc/L3-FormatStrings.texi +++ b/doc/L3-FormatStrings.texi @@ -1,3 +1,149 @@ @c -*-texinfo-*- +@node Format Strings, Journal File Format, Period Expressions, Top @chapter Format Strings + +Format strings may be used to change the output format of reports. +They are specified by passing a formatting string to the +@option{--format} (@option{-F}) option. Within that string, +constructs are allowed which make it possible to display the various +parts of an account or posting in custom ways. + +Within a format strings, a substitution is specified using a percent +character (@samp{%}). The basic format of all substitutions is: + +@example +%[-][MIN WIDTH][.MAX WIDTH]EXPR +@end example + +If the optional minus sign (@samp{-}) follows the percent character, +whatever is substituted will be left justified. The default is right +justified. If a minimum width is given next, the substituted text +will be at least that wide, perhaps wider. If a period and a maximum +width is given, the substituted text will never be wider than this, +and will be truncated to fit. Here are some examples: + +@example +%-P a transaction's payee, left justified +%20P The same, right justified, at least 20 chars wide +%.20P The same, no more than 20 chars wide +%-.20P Left justified, maximum twenty chars wide +@end example + +The expression following the format constraints can be a single +letter, or an expression enclosed in parentheses or brackets. The +allowable expressions are: + +@table @code +@item % +Inserts a percent sign. + +@item t +Inserts the results of the value expression specified by @option{-t}. +If @option{-t} was not specified, the current report style's value +expression is used. + +@item T +Inserts the results of the value expression specified by @option{-T}. +If @option{-T} was not specified, the current report style's value +expression is used. + +@item | +Inserts a single space. This is useful if a width is specified, for +inserting a certain number of spaces. + +@item _ +Inserts a space for each level of an account's depth. That is, if an +account has two parents, this construct will insert two spaces. If a +minimum width is specified, that much space is inserted for each level +of depth. Thus @samp{%5_}, for an account with four parents, will +insert twenty spaces. + +@item (EXPR) +Inserts the amount resulting from the value expression given in +parentheses. To insert five times the total value of an account, for +example, one could say @samp{%12(5*O)}. Note: It's important to put +the five first in that expression, so that the commodity doesn't get +stripped from the total. + +@item [DATEFMT] +Inserts the result of formatting a posting's date with a date +format string, exactly like those supported by @code{strftime}. For +example: @samp{%[%Y/%m/%d %H:%M:%S]}. + +@item S +Insert the pathname of the file from which the transaction's data was read. + +@item B +Inserts the beginning character position of that transaction within the file. + +@item b +Inserts the beginning line of that transaction within the file. + +@item E +Inserts the ending character position of that transaction within the file. + +@item e +Inserts the ending line of that transaction within the file. + +@item D +By default, this is the same as @samp{%[%Y/%m%/d]}. The date format +used can be changed at any time with the @option{-y} flag, however. +Using @samp{%D} gives the user more control over the way dates are +output. + +@item d +This is the same as the @samp{%D} option, unless the transaction has an +effective date, in which case it prints +@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}. + +@item X +If a posting has been cleared, this inserts @samp{*} followed by a +space; otherwise nothing is inserted. + +@item Y +This is the same as @samp{%X}, except that it only displays a state +character if all of the member postings have the same state. + +@item C +Inserts the checking number for a transaction, in parentheses, followed by +a space; if none was specified, nothing is inserted. + +@item P +Inserts the payee related to a posting. + +@item a +Inserts the optimal short name for an account. This is normally used +in balance reports. It prints a parent account's name if that name +has not been printed yet, otherwise it just prints the account's name. + +@item A +Inserts the full name of an account. + +@item W +This is the same as @samp{%A}, except that it first displays the +posting's state @emph{if the transaction's posting states are not +all the same}, followed by the full account name. This is offered as +a printing optimization, so that combined with @samp{%Y}, only the +minimum amount of state detail is printed. + +@item o +Inserts the ``optimized'' form of a posting's amount. This is +used by the print report. In some cases, this inserts nothing; in +others, it inserts the posting amount and its cost. It's use is +not recommend unless you are modifying the print report. + +@item n +Inserts the note associated with a posting, preceded by two spaces +and a semi-colon, if it exists. Thus, no none becomes an empty +string, while the note @samp{foo} is substituted as @samp{ ; foo}. + +@item N +Inserts the note associated with a posting, if one exists. + +@item / +The @samp{%/} construct is special. It separates a format string +between what is printed for the first posting of a transaction, and +what is printed for all subsequent postings. If not used, the +same format string is used for all postings. +@end table diff --git a/doc/L3-Introduction.texi b/doc/L3-Introduction.texi index 6b0167d8..b393ce06 100644 --- a/doc/L3-Introduction.texi +++ b/doc/L3-Introduction.texi @@ -1,7 +1,8 @@ @c -*-texinfo-*- -@chapter Introduction +@node Introduction to Ledger, Principles of Accounting, ,Top +@chapter Introduction to Ledger -@ledgerprog@ is an accounting tool with the moxie to exist. It provides no +LEDGER is an accounting tool with the moxie to exist. It provides no bells or whistles, and returns the user to the days before user interfaces were even a twinkling in their father's CRT. @@ -78,9 +79,9 @@ deal with multiple accounts. Here is a good place for an aside on the use of the word `account'. Most private people consider an account to be something that holds money -at an institution for them. @ledgerprog@ uses a more general definition +at an institution for them. LEDGER uses a more general definition of the word. An account is anywhere money can go. Other finance -programs use ``categories'', @ledgerprog@ uses accounts. So, for +programs use ``categories'', LEDGER uses accounts. So, for example, if you buy some groceries at Trader Joe's then more groceries at Whole Foods Markets you might assign the transactions like this @smallexample @@ -96,19 +97,19 @@ the payees were different. You can set up your accounts in any way you choose. Enter the beauty of computerized accounting. The purpose of the -@ledgerprog@ program is to make general journal accounting simple, by keeping +LEDGER program is to make general journal accounting simple, by keeping track of the balances for you. Your only job is to enter the -postings. If a posting does not balance, @ledgerprog@ displays an +postings. If a posting does not balance, LEDGER displays an error and indicates the incorrect posting.@footnote{In some special cases, it automatically balances this transaction for you.} -In summary, there are two aspects of @ledgerprog@ use: updating the journal -data file, and using the @ledgerprog@ tool to view the summarized result of +In summary, there are two aspects of LEDGER use: updating the journal +data file, and using the LEDGER tool to view the summarized result of your transactions. And just for the sake of example---as a starting point for those who want to dive in head-first---here are the journal transactions from above, -formatted as the @ledgerprog program wishes to see them: +formatted as the LEDGER program wishes to see them: @smallexample 2004/09/29 Pacific Bell @@ -125,7 +126,7 @@ $ ledger -f ledger.dat register checking $ ledger -f ledger.dat register bell @end example -An important difference between @ledgerprog@ and other finance packages is +An important difference between LEDGER and other finance packages is that journal will never alter your input file. You can create and edit that file in any way you prefer, but journal is only for analyzing the data, not for altering it. @@ -135,7 +136,7 @@ data, not for altering it. @section Building the program -@ledgerprog@ is written in ANSI C++, and should compile on any platform. It +LEDGER is written in ANSI C++, and should compile on any platform. It depends on the GNU multiprecision integer library (libgmp), and the Perl regular expression library (libpcre). It was developed using GNU make and gcc 3.3, on a PowerBook running OS/X. @@ -149,8 +150,8 @@ enter these commands: @section Getting help -If you need help on how to use @ledgerprog, or run into problems, you can -join the @ledgerprog@ mailing list at the following Web address: +If you need help on how to use LEDGER, or run into problems, you can +join the LEDGER mailing list at the following Web address: @example http://groups.google.com/group/ledger-cli @@ -159,4 +160,3 @@ http://groups.google.com/group/ledger-cli You can also find help at the @samp{#ledger} channel on the IRC server @samp{irc.freenode.net}. -@node Quick Reference, Ledger Tutorial, Introduction, Top diff --git a/doc/L3-Journal.texi b/doc/L3-Journal.texi index 1eb9afa6..419d1445 100644 --- a/doc/L3-Journal.texi +++ b/doc/L3-Journal.texi @@ -1,5 +1,6 @@ @c -*-texinfo-*- +@node Keeping a Journal, Most Basic Entry, Principles of Accounting, Top @chapter Keeping a Journal The most important part of accounting is keeping a good journal. If you @@ -7,33 +8,44 @@ have a good journal, tools can be written to work whatever mathematical tricks you need to better understand your spending patterns. Without a good journal, no tool, however smart, can help you. -The @ledgerprog@ program aims at making journal transactions as simple as +The LEDGER program aims at making journal transactions as simple as possible. Since it is a command-line tool, it does not provide a user interface for keeping a journal. If you like, you may use GnuCash to -maintain your journal, in which case @ledgerprog@ will read +maintain your journal, in which case LEDGER will read GnuCash's data files directly. In that case, read the GnuCash manual now, and skip to the next chapter. If you are not using GnuCash, but a text editor to maintain your -journal, read on. @ledgerprog@ has been designed to make data transactions as +journal, read on. LEDGER has been designed to make data transactions as simple as possible, by keeping the journal format easy, and also by automagically determining as much information as possible based on the nature of your transactions. -For example, you do not need to tell @ledgerprog@ about the accounts you -use. Any time @ledgerprog@ sees a posting involving an account it knows +For example, you do not need to tell LEDGER about the accounts you +use. Any time LEDGER sees a posting involving an account it knows nothing about, it will create it@footnote{This also means if you misspell an account it will end up getting counted separately from what you intended. The provided Emacs major mode provides for automatically filling in account names.}. If you use a commodity that is new to -@ledgerprog@, it will create that commodity, and determine its display +LEDGER, it will create that commodity, and determine its display characteristics (placement of the symbol before or after the amount, display precision, etc) based on how you used the commodity in the posting. +@menu +* Most Basic Entry:: +* Commodities:: +* Structuring Your Accounts:: +* Transaction Notes and Tags:: +* File Format:: +* Archiving Previous Years :: +* Ledger Tutorial :: +@end menu + +@node Most Basic Entry, Commodities, Keeping a Journal, Keeping a Journal @section The Most Basic Entry -Here is the Pacific Bell example from above, given as a @ledgerprog@ +Here is the Pacific Bell example from above, given as a LEDGER posting, with the additional of a check number: @smallexample @@ -44,8 +56,8 @@ posting, with the additional of a check number: As you can see, it is very similar to what would be written on paper, minus the computed balance totals, and adding in account names that work -better with @ledgerprog@'s scheme of things. In fact, since -@ledgerprog@ is smart about many things, you don't need to specify the +better with LEDGER's scheme of things. In fact, since +LEDGER is smart about many things, you don't need to specify the balanced amount, if it is the same as the first line: @smallexample @@ -54,7 +66,7 @@ balanced amount, if it is the same as the first line: Assets:Checking @end smallexample -For this transaction, @ledgerprog@ will figure out that $-23.00 must come from +For this transaction, LEDGER will figure out that $-23.00 must come from @samp{Assets:Checking} in order to balance the transaction. Also note the structure of the account entries. There is an implied @@ -69,15 +81,16 @@ indent and space out things exactly as shown. The only requirements are that the start of the transaction (the date typically) is at the beginning of the first line of the transaction, and the accounts are indented by at least one space. If you omit the leading spaces in the -account lines @ledgerprog@ will not count the transaction and will not +account lines LEDGER will not count the transaction and will not give an error. There must be at least two spaces, or a tab, between the amount and the account. If you do not have adequate separation between -the amount and the account @ledgerprog@ will give an error and stop +the amount and the account LEDGER will give an error and stop calculating} +@node Commodities, Structuring Your Accounts, Most Basic Entry, Keeping a Journal @section Commodities -@ledgerprog@ is agnostic when it comes to how you value your accounts. +LEDGER is agnostic when it comes to how you value your accounts. Dollars, Euros, Pounds, Francs, etc. are just ``commodities''. Holdings in stocks, bonds, mutual funds and other financial instrument can be label using whatever is convenient for you (stock ticker symbols are @@ -112,7 +125,7 @@ This says that $66.00 came out of checking and turned into 50 Euros. The implied exchange rate was $1.32. Then 35 Euros was spent on Dinner in Munich. - +@node Structuring Your Accounts, Transaction Notes and Tags , Commodities ,Keeping a Journal @section Structuring your Accounts There really are no requirements for how you do this, but to preserve @@ -126,8 +139,9 @@ places money sits, places money comes from and money you owe. Starting the structure off this way will make it simpler for you to get answers to the questions you really need to ask about your finances. +@node Transaction Notes and Tags, File Format, Structuring Your Accounts, Keeping a Journal @section Transaction Notes and Tags -@ledgerprog@ 3.0 supports entry and transaction ``notes'', which may +LEDGER 3.0 supports entry and transaction ``notes'', which may contain new metadata and tag markers. Here's an example: @smallexample @@ -178,7 +192,7 @@ The group-by and sort functions also support tags: @smallexample ledger --group-by "tag('foo')" bal @end smallexample -Will produce a balalnce summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'. +Will produce a balance summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'. @smallexample ledger reg --sort "tag('foo')" %foo @@ -190,7 +204,7 @@ zero, are always ignored and are neither searched nor printed back. -@node File format, , Value expressions, Quick Reference +@node File Format, Command-line Syntax ,Transaction Notes and Tags, Keeping a Journal @section File format The ledger file format is quite simple, but also very flexible. It @@ -273,7 +287,7 @@ ignored. Comments will not be returned in a ``print'' response. If the semi colon is indented and occurs inside a transaction, it is parsed as a persistent note for its preceding category. These notes or tags can be used to augment to reporting and filtering capabilities of -@ledgerprog. +LEDGER. @item Y If a line begins with a capital Y, it denotes the year used for all subsequent transactions that give a date without a year. The year should @@ -320,7 +334,13 @@ C 1.00 Kb = 1024 bytes @end example @item i, o, b, h -These four relate to timeclock support, which permits @ledgerprog@ to read +These four 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 + +@node Archiving Previous Years , , ,Keeping a Journal +@section Archiving Previous Years + +@node Ledger Tutorial , , ,Keeping a Journal +@section Ledger Tutorial diff --git a/doc/L3-Main.texi b/doc/L3-Main.texi index 7f1c91f7..aabc0f34 100644 --- a/doc/L3-Main.texi +++ b/doc/L3-Main.texi @@ -47,7 +47,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @titlepage -@title @ledgerprog: Command-Line Accounting +@title LEDGER: Command-Line Accounting @author John Wiegley @end titlepage @@ -69,16 +69,28 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @insertcopying @end ifnottex +@menu +* Introduction to Ledger:: +* Principles of Accounting:: +* Keeping a Journal:: +* Command-line Syntax:: +* Basic Reporting Commands:: +* Value Expressions:: +* Format Strings:: +* Journal File Format:: +* Extending with Python:: +@end menu + + @c each chapter is in an idividual texi file included here @include L3-Introduction.texi @include L3-Principles.texi @include L3-Journal.texi -@include L3-Reporting.texi @include L3-Syntax.texi -@include L3-JournalFormat.texi @include L3-Reporting.texi @include L3-ValueExpressions.texi @include L3-FormatStrings.texi +@include L3-JournalFormat.texi @include L3-Python.texi @bye diff --git a/doc/L3-Principles.texi b/doc/L3-Principles.texi index 778cc52d..1de75967 100644 --- a/doc/L3-Principles.texi +++ b/doc/L3-Principles.texi @@ -1,3 +1,4 @@ @c -*-texinfo-*- +@node Principles of Accounting, Keeping a Journal, Introduction to Ledger, Top @chapter Principles of Accounting diff --git a/doc/L3-Python.texi b/doc/L3-Python.texi index ebb4d530..3f985237 100644 --- a/doc/L3-Python.texi +++ b/doc/L3-Python.texi @@ -1,3 +1,3 @@ @c -*-texinfo-*- - +@node Extending with Python, , Journal File Format, Top @chapter Extending with Python diff --git a/doc/L3-Reporting.texi b/doc/L3-Reporting.texi index 7fea2fef..cb675aba 100644 --- a/doc/L3-Reporting.texi +++ b/doc/L3-Reporting.texi @@ -1,3 +1,11 @@ @c -*-texinfo-*- +@node Basic Reporting Commands, Value Expressions, Command-line Syntax, Top @chapter Basic Reporting Commands + +@menu +* Budgeting and Forecasting:: +@end menu + +@node Budgeting and Forecasting, , ,Basic Reporting Commands +@section Budgeting and Forecasting diff --git a/doc/L3-Syntax.texi b/doc/L3-Syntax.texi index 15e6e8f8..83bd1320 100644 --- a/doc/L3-Syntax.texi +++ b/doc/L3-Syntax.texi @@ -1,6 +1,17 @@ @c -*-texinfo-*- - +@node Command-line Syntax, Basic Reporting Commands, File Format, Top @chapter Command-line Syntax + + +@menu +* Cookbook:: +* Quick Reference:: +* Commands:: +* Options:: +* Period Expressions:: +@end menu + +@node Cookbook, Quick Reference, Command-line Syntax, Command-line Syntax @section Cookbook @subsection Invoking Ledger @@ -25,14 +36,14 @@ ledger register NFCUChecking --sort d -d 'd>[2011/04/01]' until 2011/05/25 (Liabilities:Tithe Owed) -1.0 @end example - +@node Quick Reference, Commands, Cookbook, Command-line Syntax @section Quick Reference -This chapter describes @ledgerprog's features and serves as a quick +This chapter describes LEDGER's features and serves as a quick reference. You may wish to survey this to get an overview before diving in to the @ref{Ledger Tutorial} and more detailed examples that follow. -@ledgerprog@ has a very simple command-line interface, named---enticingly +LEDGER has a very simple command-line interface, named---enticingly enough---@command{ledger}. It supports a few reporting commands, and a large number of options for refining the output from those commands. The basic syntax of any ledger command is: @@ -63,16 +74,8 @@ There are many, many command options available with the However, none of them are required to use the basic reporting commands. -@menu -* Commands:: -* Options:: -* Period expressions:: -* Format strings:: -* Value expressions:: -* File format:: -@end menu -@node Commands, Options, Quick Reference, Quick Reference +@node Commands, Options, Quick Reference, Command-line Syntax @section Commands @subsection balance @@ -99,14 +102,14 @@ always be the same as the current balance of that account. If you have Gnuplot installed, you may plot the amount or running total of any register by using the script @file{report}, which is -included in the @ledgerprog@ distribution. The only requirement is that you +included in the LEDGER distribution. The only requirement is that you add either @option{-j} or @option{-J} to your register command, in order to plot either the amount or total column, respectively. @subsection print The @command{print} command prints out ledger transactions in a textual -format that can be parsed by @ledgerprog@. They will be properly formatted, +format that can be parsed by LEDGER. They will be properly formatted, and output in the most economic form possible. The ``print'' command also takes a list of optional regexps, which will cause only those postings which match in some way to be printed. @@ -152,7 +155,7 @@ directly by Emacs Lisp. The format of the sexp is: The @command{equity} command prints out accounts balances as if they were transactions. This makes it easy to establish the starting balances -for an account, such as when @ref{Archiving previous years}. +for an account, such as when @ref{Archiving Previous Years}. @subsection prices @@ -163,7 +166,7 @@ deviation from that average. There is also a @command{pricesdb} command which outputs the same information as @command{prices}, but does in a format that can be -parsed by @ledgerprog@. +parsed by LEDGER. @subsection xact @@ -199,7 +202,7 @@ This produces the following output: It works by finding a past posting matching the regular expression @samp{viva}, and assuming that any accounts or amounts specified will -be similar to that earlier posting. If @ledgerprog@ does not succeed in +be similar to that earlier posting. If LEDGER does not succeed in generating a new transaction, an error is printed and the exit code is set to @samp{1}. @@ -220,7 +223,7 @@ ledger xact 4/9 viva food $11.50 tips $8 cash ledger xact 4/9 viva dining "DM 11.50" @end example -@node Options, Period expressions, Commands, Quick Reference +@node Options, Period Expressions, Commands, Command-line Syntax @section Options With all of the reports, command-line options are useful to modify the @@ -285,7 +288,7 @@ finished a binary copy will be written to the specified cache, to speed up the loading time of subsequent queries. This filename can also be given using the environment variable @env{LEDGER_CACHE}, or by putting the option into your init file. The @option{--no-cache} -option causes @ledgerprog@ to always ignore the binary cache. +option causes LEDGER to always ignore the binary cache. @option{--account NAME} (@option{-a NAME}) specifies the default account which QIF file postings are assumed to relate to. @@ -315,7 +318,7 @@ period separately, making it easy to see weekly, monthly, quarterly, etc., posting totals. A period string can even specify the beginning and end of the report range, using simple terms like ``last june'' or ``next month''. For more using period expressions, see -@ref{Period expressions}. +@ref{Period Expressions}. @option{--period-sort EXPR} sorts the postings within each reporting period using the value expression @var{EXPR}. This is most @@ -375,7 +378,7 @@ meet your budget. @option{--add-budget} also shows unbudgeted postings, while @option{--unbudgeted} shows only those. @option{--forecast} is a related option that projects your budget into the future, showing how it will affect future balances. -@xref{Budgeting and forecasting}. +@xref{Budgeting and Forecasting}. @option{--limit EXPR} (@option{-l EXPR}) limits which postings take part in the calculations of a report. @@ -384,7 +387,7 @@ take part in the calculations of a report. used to calculate the ``value'' column in the @command{register} report, the amount used to calculate account totals in the @command{balance} report, and the values printed in the -@command{equity} report. @xref{Value expressions}. +@command{equity} report. @xref{Value Expressions}. @option{--total EXPR} (@option{-T EXPR}) sets the value expression used for the ``totals'' column in the @command{register} and @@ -429,7 +432,7 @@ the values determined using the value expression @var{EXPR}. For example, using @option{-S -UT} in the balance report will sort account balances from greatest to least, using the absolute value of the total. For more on how to use value expressions, see @ref{Value -expressions}. +Expressions}. @option{--wide} (@option{-w}) causes the default @command{register} report to assume 132 columns instead of 80. @@ -442,7 +445,7 @@ negative amount is given, it will invert the meaning of the flag (instead of the first five transactions being printed, for example, it would print all but the first five). -@option{--pager} tells @ledgerprog@ to pass its output to the given pager +@option{--pager} tells LEDGER to pass its output to the given pager program---very useful when the output is especially long. This behavior can be made the default by setting the @env{LEDGER_PAGER} environment variable. @@ -497,11 +500,11 @@ restricted to the reporting range (using @option{-d}). format used by reports. The default uses a date like 2004/08/01, which represents the default date format of @samp{%Y/%m/%d}. To change the way dates are printed in general, the easiest way is to put -@option{--date-format FORMAT} in the @ledgerprog@ initialization file +@option{--date-format FORMAT} in the LEDGER initialization file @file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). @option{--format STR} (@option{-F STR}) sets the reporting format for -whatever report ledger is about to make. @xref{Format strings}. +whatever report ledger is about to make. @xref{Format Strings}. There are also specific format commands for each report type: @itemize @@ -585,8 +588,8 @@ option settings in the file @file{~/.ledgerrc}, for example: @end example -@node Period expressions, Format strings, Options, Quick Reference -@section Period expressions +@node Period Expressions, Format Strings, Options, Command-line Syntax +@section Period Expressions A period expression indicates a span of time, or a reporting interval, or both. The full syntax is: @@ -672,374 +675,3 @@ last oct weekly last august @end example -@node Format strings, Value expressions, Period expressions, Quick Reference -@section Format strings - -Format strings may be used to change the output format of reports. -They are specified by passing a formatting string to the -@option{--format} (@option{-F}) option. Within that string, -constructs are allowed which make it possible to display the various -parts of an account or posting in custom ways. - -Within a format strings, a substitution is specified using a percent -character (@samp{%}). The basic format of all substitutions is: - -@example -%[-][MIN WIDTH][.MAX WIDTH]EXPR -@end example - -If the optional minus sign (@samp{-}) follows the percent character, -whatever is substituted will be left justified. The default is right -justified. If a minimum width is given next, the substituted text -will be at least that wide, perhaps wider. If a period and a maximum -width is given, the substituted text will never be wider than this, -and will be truncated to fit. Here are some examples: - -@example -%-P a transaction's payee, left justified -%20P The same, right justified, at least 20 chars wide -%.20P The same, no more than 20 chars wide -%-.20P Left justified, maximum twenty chars wide -@end example - -The expression following the format constraints can be a single -letter, or an expression enclosed in parentheses or brackets. The -allowable expressions are: - -@table @code -@item % -Inserts a percent sign. - -@item t -Inserts the results of the value expression specified by @option{-t}. -If @option{-t} was not specified, the current report style's value -expression is used. - -@item T -Inserts the results of the value expression specified by @option{-T}. -If @option{-T} was not specified, the current report style's value -expression is used. - -@item | -Inserts a single space. This is useful if a width is specified, for -inserting a certain number of spaces. - -@item _ -Inserts a space for each level of an account's depth. That is, if an -account has two parents, this construct will insert two spaces. If a -minimum width is specified, that much space is inserted for each level -of depth. Thus @samp{%5_}, for an account with four parents, will -insert twenty spaces. - -@item (EXPR) -Inserts the amount resulting from the value expression given in -parentheses. To insert five times the total value of an account, for -example, one could say @samp{%12(5*O)}. Note: It's important to put -the five first in that expression, so that the commodity doesn't get -stripped from the total. - -@item [DATEFMT] -Inserts the result of formatting a posting's date with a date -format string, exactly like those supported by @code{strftime}. For -example: @samp{%[%Y/%m/%d %H:%M:%S]}. - -@item S -Insert the pathname of the file from which the transaction's data was read. - -@item B -Inserts the beginning character position of that transaction within the file. - -@item b -Inserts the beginning line of that transaction within the file. - -@item E -Inserts the ending character position of that transaction within the file. - -@item e -Inserts the ending line of that transaction within the file. - -@item D -By default, this is the same as @samp{%[%Y/%m%/d]}. The date format -used can be changed at any time with the @option{-y} flag, however. -Using @samp{%D} gives the user more control over the way dates are -output. - -@item d -This is the same as the @samp{%D} option, unless the transaction has an -effective date, in which case it prints -@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}. - -@item X -If a posting has been cleared, this inserts @samp{*} followed by a -space; otherwise nothing is inserted. - -@item Y -This is the same as @samp{%X}, except that it only displays a state -character if all of the member postings have the same state. - -@item C -Inserts the checking number for a transaction, in parentheses, followed by -a space; if none was specified, nothing is inserted. - -@item P -Inserts the payee related to a posting. - -@item a -Inserts the optimal short name for an account. This is normally used -in balance reports. It prints a parent account's name if that name -has not been printed yet, otherwise it just prints the account's name. - -@item A -Inserts the full name of an account. - -@item W -This is the same as @samp{%A}, except that it first displays the -posting's state @emph{if the transaction's posting states are not -all the same}, followed by the full account name. This is offered as -a printing optimization, so that combined with @samp{%Y}, only the -minimum amount of state detail is printed. - -@item o -Inserts the ``optimized'' form of a posting's amount. This is -used by the print report. In some cases, this inserts nothing; in -others, it inserts the posting amount and its cost. It's use is -not recommend unless you are modifying the print report. - -@item n -Inserts the note associated with a posting, preceded by two spaces -and a semi-colon, if it exists. Thus, no none becomes an empty -string, while the note @samp{foo} is substituted as @samp{ ; foo}. - -@item N -Inserts the note associated with a posting, if one exists. - -@item / -The @samp{%/} construct is special. It separates a format string -between what is printed for the first posting of a transaction, and -what is printed for all subsequent postings. If not used, the -same format string is used for all postings. -@end table - -@node Value expressions, File format, Format strings, Quick Reference -@section Value expressions - -Value expressions are an expression language used by @ledgerprog@ to -calculate values used by the program for many different purposes: - -@enumerate -@item -The values displayed in reports -@item -For predicates (where truth is anything non-zero), to determine which -postings are calculated (@option{-l}) or displayed (@option{-d}). -@item -For sorting criteria, to yield the sort key. -@item -In the matching criteria used by automated postings. -@end enumerate - -Value expressions support most simple math and logic operators, in -addition to a set of one letter functions and variables. A function's -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:UT>100 balance -@end example - -The effect is that account totals are displayed only if: 1) A -Liabilities 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 transactions are printed. For example, the following -command shows only transactions from the beginning of the current month, -while still calculating the running balance based on all transactions: - -@example -ledger -d "d>[this month]" register checking -@end example - -This advantage to this command's complexity is that it prints the -running total in terms of all transactions in the register. The following, -simpler command is similar, but totals only the displayed -postings: - -@example -ledger -b "this month" register checking -@end example - -@subsection Variables - -Below are the one letter variables available in any value expression. -For the register and print commands, these variables relate to -individual postings, and sometimes the account affected by a -posting. For the balance command, these variables relate to -accounts---often with a subtle difference in meaning. The use of each -variable for both is specified. - -@table @code -@item t -This maps to whatever the user specified with @option{-t}. In a -register report, @option{-t} changes the value column; in a balance -report, it has no meaning by default. If @option{-t} was not -specified, the current report style's value expression is used. - -@item T -This maps to whatever the user specified with @option{-T}. In a -register report, @option{-T} changes the totals column; in a balance -report, this is the value given for each account. If @option{-T} was -not specified, the current report style's value expression is used. - -@item m -This is always the present moment/date. -@end table - -@subsubsection Posting/account details - -@table @code -@item d -A posting's date, as the number of seconds past the epoch. This -is always ``today'' for an account. - -@item a -The posting's amount; the balance of an account, without -considering children. - -@item b -The cost of a posting; the cost of an account, without its -children. - -@item v -The market value of a posting, or an account without its children. - -@item g -The net gain (market value minus cost basis), for a posting or an -account without its children. It is the same as @samp{v-b}. - -@item l -The depth (``level'') of an account. If an account has one parent, -it's depth is one. - -@item n -The index of a posting, or the count of postings affecting an -account. - -@item X -1 if a posting's transaction has been cleared, 0 otherwise. - -@item R -1 if a posting is not virtual, 0 otherwise. - -@item Z -1 if a posting is not automated, 0 otherwise. -@end table - -@subsubsection Calculated totals - -@table @code -@item O -The total of all postings seen so far, or the total of an account -and all its children. - -@item N -The total count of postings affecting an account and all its -children. - -@item B -The total cost of all postings seen so far; the total cost of an -account and all its children. - -@item V -The market value of all postings seen so far, or of an account and -all its children. - -@item G -The total net gain (market value minus cost basis), for a series of -postings, or an account and its children. It is the same as -@samp{V-B}. -@end table - -@subsection Functions - -The available one letter functions are: - -@table @code -@item - -Negates the argument. - -@item U -The absolute (unsigned) value of the argument. - -@item S -Strips the commodity from the argument. - -@item A -The arithmetic mean of the argument; @samp{Ax} is the same as -@samp{x/n}. - -@item P -The present market value of the argument. The syntax @samp{P(x,d)} is -supported, which yields the market value at time @samp{d}. If no date -is given, then the current moment is used. -@end table - -@subsection Operators - -The binary and ternary operators, in order of precedence, are: - -@enumerate -@item @samp{* /} -@item @samp{+ -} -@item @samp{! < > =} -@item @samp{& | ?:} -@end enumerate - -@subsection Complex expressions - -More complicated expressions are possible using: - -@table @code -@item NUM -A plain integer represents a commodity-less amount. - -@item @{AMOUNT@} -An amount in braces can be any kind of amount supported by ledger, -with or without a commodity. Use this for decimal values. - -@item /REGEXP/ -@item W/REGEXP/ -A regular expression that matches against an account's full name. If -a posting, this will match against the account affected by the -posting. - -@item //REGEXP/ -@item p/REGEXP/ -A regular expression that matches against a transaction's payee name. - -@item ///REGEXP/ -@item w/REGEXP/ -A regular expression that matches against an account's base name. If -a posting, this will match against the account affected by the -posting. - -@item c/REGEXP/ -A regular expression that matches against the transaction code (the text -that occurs between parentheses before the payee name). - -@item e/REGEXP/ -A regular expression that matches against a posting's note, or -comment field. - -@item (EXPR) -A sub-expression is nested in parenthesis. This can be useful passing -more complicated arguments to functions, or for overriding the natural -precedence order of operators. - -@item [DATE] -Useful specifying a date in plain terms. For example, you could say -@samp{[2004/06/01]}. -@end table - diff --git a/doc/L3-ValueExpressions.texi b/doc/L3-ValueExpressions.texi index 02d00e6a..f893229f 100644 --- a/doc/L3-ValueExpressions.texi +++ b/doc/L3-ValueExpressions.texi @@ -1,3 +1,230 @@ @c -*-texinfo-*- -@chapter Value Expression +@node Value Expressions, Variables, Basic Reporting Commands, Top +@chapter Value Expressions + +Value expressions are an expression language used by LEDGER to +calculate values used by the program for many different purposes: + +@enumerate +@item +The values displayed in reports +@item +For predicates (where truth is anything non-zero), to determine which +postings are calculated (@option{-l}) or displayed (@option{-d}). +@item +For sorting criteria, to yield the sort key. +@item +In the matching criteria used by automated postings. +@end enumerate + +Value expressions support most simple math and logic operators, in +addition to a set of one letter functions and variables. A function's +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:UT>100 balance +@end example + +The effect is that account totals are displayed only if: 1) A +Liabilities 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 transactions are printed. For example, the following +command shows only transactions from the beginning of the current month, +while still calculating the running balance based on all transactions: + +@example +ledger -d "d>[this month]" register checking +@end example + +This advantage to this command's complexity is that it prints the +running total in terms of all transactions in the register. The following, +simpler command is similar, but totals only the displayed +postings: + +@example +ledger -b "this month" register checking +@end example + +@menu +* Variables:: +@end menu + +@node Variables, , Value Expressions, Value Expressions +@section Variables + +Below are the one letter variables available in any value expression. +For the register and print commands, these variables relate to +individual postings, and sometimes the account affected by a +posting. For the balance command, these variables relate to +accounts---often with a subtle difference in meaning. The use of each +variable for both is specified. + +@table @code +@item t +This maps to whatever the user specified with @option{-t}. In a +register report, @option{-t} changes the value column; in a balance +report, it has no meaning by default. If @option{-t} was not +specified, the current report style's value expression is used. + +@item T +This maps to whatever the user specified with @option{-T}. In a +register report, @option{-T} changes the totals column; in a balance +report, this is the value given for each account. If @option{-T} was +not specified, the current report style's value expression is used. + +@item m +This is always the present moment/date. +@end table + +@subsection Posting/account details + +@table @code +@item d +A posting's date, as the number of seconds past the epoch. This +is always ``today'' for an account. + +@item a +The posting's amount; the balance of an account, without +considering children. + +@item b +The cost of a posting; the cost of an account, without its +children. + +@item v +The market value of a posting, or an account without its children. + +@item g +The net gain (market value minus cost basis), for a posting or an +account without its children. It is the same as @samp{v-b}. + +@item l +The depth (``level'') of an account. If an account has one parent, +it's depth is one. + +@item n +The index of a posting, or the count of postings affecting an +account. + +@item X +1 if a posting's transaction has been cleared, 0 otherwise. + +@item R +1 if a posting is not virtual, 0 otherwise. + +@item Z +1 if a posting is not automated, 0 otherwise. +@end table + +@subsection Calculated totals + +@table @code +@item O +The total of all postings seen so far, or the total of an account +and all its children. + +@item N +The total count of postings affecting an account and all its +children. + +@item B +The total cost of all postings seen so far; the total cost of an +account and all its children. + +@item V +The market value of all postings seen so far, or of an account and +all its children. + +@item G +The total net gain (market value minus cost basis), for a series of +postings, or an account and its children. It is the same as +@samp{V-B}. +@end table + +@section Functions + +The available one letter functions are: + +@table @code +@item - +Negates the argument. + +@item U +The absolute (unsigned) value of the argument. + +@item S +Strips the commodity from the argument. + +@item A +The arithmetic mean of the argument; @samp{Ax} is the same as +@samp{x/n}. + +@item P +The present market value of the argument. The syntax @samp{P(x,d)} is +supported, which yields the market value at time @samp{d}. If no date +is given, then the current moment is used. +@end table + +@section Operators + +The binary and ternary operators, in order of precedence, are: + +@enumerate +@item @samp{* /} +@item @samp{+ -} +@item @samp{! < > =} +@item @samp{& | ?:} +@end enumerate + +@section Complex expressions + +More complicated expressions are possible using: + +@table @code +@item NUM +A plain integer represents a commodity-less amount. + +@item @{AMOUNT@} +An amount in braces can be any kind of amount supported by ledger, +with or without a commodity. Use this for decimal values. + +@item /REGEXP/ +@item W/REGEXP/ +A regular expression that matches against an account's full name. If +a posting, this will match against the account affected by the +posting. + +@item //REGEXP/ +@item p/REGEXP/ +A regular expression that matches against a transaction's payee name. + +@item ///REGEXP/ +@item w/REGEXP/ +A regular expression that matches against an account's base name. If +a posting, this will match against the account affected by the +posting. + +@item c/REGEXP/ +A regular expression that matches against the transaction code (the text +that occurs between parentheses before the payee name). + +@item e/REGEXP/ +A regular expression that matches against a posting's note, or +comment field. + +@item (EXPR) +A sub-expression is nested in parenthesis. This can be useful passing +more complicated arguments to functions, or for overriding the natural +precedence order of operators. + +@item [DATE] +Useful specifying a date in plain terms. For example, you could say +@samp{[2004/06/01]}. +@end table + From 471ced9efca2974e8c2a2161b6aaf5a313a3dabb Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 28 Sep 2011 12:50:06 -0700 Subject: [PATCH 06/28] reverted to single file for ease of use with emacs texinfo mode --- doc/L3-FormatStrings.texi | 149 --- doc/L3-Introduction.texi | 162 --- doc/L3-Journal.texi | 346 ------ doc/L3-JournalFormat.texi | 242 ----- doc/L3-Main.texi | 96 -- doc/L3-Principles.texi | 4 - doc/L3-Python.texi | 3 - doc/L3-Queries.texi | 3 - doc/L3-Reporting.texi | 11 - doc/L3-Syntax.texi | 677 ------------ doc/L3-ValueExpressions.texi | 230 ---- doc/Ledger3.texi | 1914 ++++++++++++++++++++++++++++++++++ 12 files changed, 1914 insertions(+), 1923 deletions(-) delete mode 100644 doc/L3-FormatStrings.texi delete mode 100644 doc/L3-Introduction.texi delete mode 100644 doc/L3-Journal.texi delete mode 100644 doc/L3-JournalFormat.texi delete mode 100644 doc/L3-Main.texi delete mode 100644 doc/L3-Principles.texi delete mode 100644 doc/L3-Python.texi delete mode 100644 doc/L3-Queries.texi delete mode 100644 doc/L3-Reporting.texi delete mode 100644 doc/L3-Syntax.texi delete mode 100644 doc/L3-ValueExpressions.texi create mode 100644 doc/Ledger3.texi diff --git a/doc/L3-FormatStrings.texi b/doc/L3-FormatStrings.texi deleted file mode 100644 index ee56891f..00000000 --- a/doc/L3-FormatStrings.texi +++ /dev/null @@ -1,149 +0,0 @@ -@c -*-texinfo-*- - -@node Format Strings, Journal File Format, Period Expressions, Top -@chapter Format Strings - -Format strings may be used to change the output format of reports. -They are specified by passing a formatting string to the -@option{--format} (@option{-F}) option. Within that string, -constructs are allowed which make it possible to display the various -parts of an account or posting in custom ways. - -Within a format strings, a substitution is specified using a percent -character (@samp{%}). The basic format of all substitutions is: - -@example -%[-][MIN WIDTH][.MAX WIDTH]EXPR -@end example - -If the optional minus sign (@samp{-}) follows the percent character, -whatever is substituted will be left justified. The default is right -justified. If a minimum width is given next, the substituted text -will be at least that wide, perhaps wider. If a period and a maximum -width is given, the substituted text will never be wider than this, -and will be truncated to fit. Here are some examples: - -@example -%-P a transaction's payee, left justified -%20P The same, right justified, at least 20 chars wide -%.20P The same, no more than 20 chars wide -%-.20P Left justified, maximum twenty chars wide -@end example - -The expression following the format constraints can be a single -letter, or an expression enclosed in parentheses or brackets. The -allowable expressions are: - -@table @code -@item % -Inserts a percent sign. - -@item t -Inserts the results of the value expression specified by @option{-t}. -If @option{-t} was not specified, the current report style's value -expression is used. - -@item T -Inserts the results of the value expression specified by @option{-T}. -If @option{-T} was not specified, the current report style's value -expression is used. - -@item | -Inserts a single space. This is useful if a width is specified, for -inserting a certain number of spaces. - -@item _ -Inserts a space for each level of an account's depth. That is, if an -account has two parents, this construct will insert two spaces. If a -minimum width is specified, that much space is inserted for each level -of depth. Thus @samp{%5_}, for an account with four parents, will -insert twenty spaces. - -@item (EXPR) -Inserts the amount resulting from the value expression given in -parentheses. To insert five times the total value of an account, for -example, one could say @samp{%12(5*O)}. Note: It's important to put -the five first in that expression, so that the commodity doesn't get -stripped from the total. - -@item [DATEFMT] -Inserts the result of formatting a posting's date with a date -format string, exactly like those supported by @code{strftime}. For -example: @samp{%[%Y/%m/%d %H:%M:%S]}. - -@item S -Insert the pathname of the file from which the transaction's data was read. - -@item B -Inserts the beginning character position of that transaction within the file. - -@item b -Inserts the beginning line of that transaction within the file. - -@item E -Inserts the ending character position of that transaction within the file. - -@item e -Inserts the ending line of that transaction within the file. - -@item D -By default, this is the same as @samp{%[%Y/%m%/d]}. The date format -used can be changed at any time with the @option{-y} flag, however. -Using @samp{%D} gives the user more control over the way dates are -output. - -@item d -This is the same as the @samp{%D} option, unless the transaction has an -effective date, in which case it prints -@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}. - -@item X -If a posting has been cleared, this inserts @samp{*} followed by a -space; otherwise nothing is inserted. - -@item Y -This is the same as @samp{%X}, except that it only displays a state -character if all of the member postings have the same state. - -@item C -Inserts the checking number for a transaction, in parentheses, followed by -a space; if none was specified, nothing is inserted. - -@item P -Inserts the payee related to a posting. - -@item a -Inserts the optimal short name for an account. This is normally used -in balance reports. It prints a parent account's name if that name -has not been printed yet, otherwise it just prints the account's name. - -@item A -Inserts the full name of an account. - -@item W -This is the same as @samp{%A}, except that it first displays the -posting's state @emph{if the transaction's posting states are not -all the same}, followed by the full account name. This is offered as -a printing optimization, so that combined with @samp{%Y}, only the -minimum amount of state detail is printed. - -@item o -Inserts the ``optimized'' form of a posting's amount. This is -used by the print report. In some cases, this inserts nothing; in -others, it inserts the posting amount and its cost. It's use is -not recommend unless you are modifying the print report. - -@item n -Inserts the note associated with a posting, preceded by two spaces -and a semi-colon, if it exists. Thus, no none becomes an empty -string, while the note @samp{foo} is substituted as @samp{ ; foo}. - -@item N -Inserts the note associated with a posting, if one exists. - -@item / -The @samp{%/} construct is special. It separates a format string -between what is printed for the first posting of a transaction, and -what is printed for all subsequent postings. If not used, the -same format string is used for all postings. -@end table diff --git a/doc/L3-Introduction.texi b/doc/L3-Introduction.texi deleted file mode 100644 index b393ce06..00000000 --- a/doc/L3-Introduction.texi +++ /dev/null @@ -1,162 +0,0 @@ -@c -*-texinfo-*- -@node Introduction to Ledger, Principles of Accounting, ,Top -@chapter Introduction to Ledger - -LEDGER is an accounting tool with the moxie to exist. It provides no -bells or whistles, and returns the user to the days before user -interfaces were even a twinkling in their father's CRT. - -What it does offer is a double-entry accounting journal with all the -flexibility and muscle of its modern day cousins, without any of the -fat. Think of it as the Bran Muffin of accounting tools. - -To use it, you need to start keeping a journal. This is the basis of -all accounting, and if you haven't started yet, now is the time to -learn. The little booklet that comes with your checkbook is a journal, -so we'll describe double-entry accounting in terms of that. - -A checkbook journal records debits (subtractions, or withdrawals) and -credits (additions, or deposits) with reference to a single account: -the checking account. Where the money comes from, and where it goes -to, are described in the payee field, where you write the person or -company's name. The ultimate aim of keeping a checkbook journal is to -know how much money is available to spend. That's really the aim of -all journals. - -What computers add is the ability to walk through these postings, -and tell you things about your spending habits; to let you devise -budgets and get control over your spending; to squirrel away money -into virtual savings account without having to physically move money -around; etc. As you keep your journal, you are recording information -about your life and habits, and sometimes that information can start -telling you things you aren't aware of. Such is the aim of all good -accounting tools. - -The next step up from a checkbook journal, is a journal that keeps track -of all your accounts, not just checking. In such a journal, you record -not only who gets paid---in the case of a debit---but where the money -came from. In a checkbook journal, its assumed that all the money -comes from your checking account. But in a general journal, you write -posting two-lines: the source account and target account. -@emph{There must always be a debit from at least one account for every -credit made to another account}. This is what is meant by -``double-entry'' accounting: the journal must always balance to zero, -with an equal number of debits and credits. - - -For example, let's say you have a checking account and a brokerage -account, and you can write checks from both of them. Rather than keep -two checkbooks, you decide to use one journal for both. In this general -journal you need to record a payment to Pacific Bell for your monthly -phone bill, and a transfer (via check) from your brokerage account to -your checking account. The Pacific Bell bill is $23.00, let's say, and -you want to pay it from your checking account. In the general journal -you need to say where the money came from, in addition to where it's -going to. These transactions might look like this: - -@smallexample -9/29 Pacific Bell $23.00 $23.00 - Checking $-23.00 0 -9/30 Checking $100.00 $100.00 - (123) Brokerage $-100.00 0 -@end smallexample - -The posting must balance to $0: $23 went to Pacific Bell, $23 came from -Checking. The next entry shows check number 123 written against your -brokerage account, transfering money to your checking account. There is -nothing left over to be accounted for, since the money has simply moved -from one account to another in both cases. This is the basis of -double-entry accounting: money never pops in or out of existence; it is -always a posting from one account to another. - -Keeping a general journal is the same as keeping two separate journals: -One for Pacific Bell and one for Checking. In that case, each time a -payment is written into one, you write a corresponding withdrawal into -the other. This makes it easier to write in a ``running balance'', -since you don't have to look back at the last time the account was -referenced---but it also means having a lot of journal books, if you -deal with multiple accounts. - -Here is a good place for an aside on the use of the word `account'. -Most private people consider an account to be something that holds money -at an institution for them. LEDGER uses a more general definition -of the word. An account is anywhere money can go. Other finance -programs use ``categories'', LEDGER uses accounts. So, for -example, if you buy some groceries at Trader Joe's then more groceries -at Whole Foods Markets you might assign the transactions like this -@smallexample -2011/03/15 Trader Joe's - Expenses:Groceries $100.00 - Assets:Checking -2011/03/15 Whole Food Market - Expenses:Groceries $75.00 - Assets:Checking -@end smallexample -In both cases the money goes to the ``Groceries'' account, even though -the payees were different. You can set up your accounts in any way you -choose. - -Enter the beauty of computerized accounting. The purpose of the -LEDGER program is to make general journal accounting simple, by keeping -track of the balances for you. Your only job is to enter the -postings. If a posting does not balance, LEDGER displays an -error and indicates the incorrect posting.@footnote{In some -special cases, it automatically balances this transaction for you.} - -In summary, there are two aspects of LEDGER use: updating the journal -data file, and using the LEDGER tool to view the summarized result of -your transactions. - -And just for the sake of example---as a starting point for those who -want to dive in head-first---here are the journal transactions from above, -formatted as the LEDGER program wishes to see them: - -@smallexample -2004/09/29 Pacific Bell - Expenses:Pacific Bell $23.00 - Assets:Checking -@end smallexample - -The account balances and registers in this file, if saved as -@file{ledger.dat}, could be reported using: - -@example -$ ledger -f ledger.dat balance -$ ledger -f ledger.dat register checking -$ ledger -f ledger.dat register bell -@end example - -An important difference between LEDGER and other finance packages is -that journal will never alter your input file. You can create and edit -that file in any way you prefer, but journal is only for analyzing the -data, not for altering it. - -@section More introduction - - -@section Building the program - -LEDGER is written in ANSI C++, and should compile on any platform. It -depends on the GNU multiprecision integer library (libgmp), and the -Perl regular expression library (libpcre). It was developed using GNU -make and gcc 3.3, on a PowerBook running OS/X. - -To build and install once you have these libraries on your system, -enter these commands: - -@example -./configure && make install -@end example - -@section Getting help - -If you need help on how to use LEDGER, or run into problems, you can -join the LEDGER mailing list at the following Web address: - -@example -http://groups.google.com/group/ledger-cli -@end example - -You can also find help at the @samp{#ledger} channel on the IRC server -@samp{irc.freenode.net}. - diff --git a/doc/L3-Journal.texi b/doc/L3-Journal.texi deleted file mode 100644 index 419d1445..00000000 --- a/doc/L3-Journal.texi +++ /dev/null @@ -1,346 +0,0 @@ -@c -*-texinfo-*- - -@node Keeping a Journal, Most Basic Entry, Principles of Accounting, Top -@chapter Keeping a Journal - -The most important part of accounting is keeping a good journal. If you -have a good journal, tools can be written to work whatever mathematical -tricks you need to better understand your spending patterns. Without a -good journal, no tool, however smart, can help you. - -The LEDGER program aims at making journal transactions as simple as -possible. Since it is a command-line tool, it does not provide a user -interface for keeping a journal. If you like, you may use GnuCash to -maintain your journal, in which case LEDGER will read -GnuCash's data files directly. In that case, read the GnuCash manual -now, and skip to the next chapter. - -If you are not using GnuCash, but a text editor to maintain your -journal, read on. LEDGER has been designed to make data transactions as -simple as possible, by keeping the journal format easy, and also by -automagically determining as much information as possible based on the -nature of your transactions. - -For example, you do not need to tell LEDGER about the accounts you -use. Any time LEDGER sees a posting involving an account it knows -nothing about, it will create it@footnote{This also means if you -misspell an account it will end up getting counted separately from what -you intended. The provided Emacs major mode provides for automatically -filling in account names.}. If you use a commodity that is new to -LEDGER, it will create that commodity, and determine its display -characteristics (placement of the symbol before or after the amount, -display precision, etc) based on how you used the commodity in the -posting. - -@menu -* Most Basic Entry:: -* Commodities:: -* Structuring Your Accounts:: -* Transaction Notes and Tags:: -* File Format:: -* Archiving Previous Years :: -* Ledger Tutorial :: -@end menu - -@node Most Basic Entry, Commodities, Keeping a Journal, Keeping a Journal -@section The Most Basic Entry - -Here is the Pacific Bell example from above, given as a LEDGER -posting, with the additional of a check number: - -@smallexample -9/29 (1023) Pacific Bell - Expenses:Utilities:Phone $23.00 - Assets:Checking $-23.00 -@end smallexample - -As you can see, it is very similar to what would be written on paper, -minus the computed balance totals, and adding in account names that work -better with LEDGER's scheme of things. In fact, since -LEDGER is smart about many things, you don't need to specify the -balanced amount, if it is the same as the first line: - -@smallexample -9/29 (1023) Pacific Bell - Expenses:Utilities:Phone $23.00 - Assets:Checking -@end smallexample - -For this transaction, LEDGER will figure out that $-23.00 must come from -@samp{Assets:Checking} in order to balance the transaction. - -Also note the structure of the account entries. There is an implied -hierarchy established by separating with colons. See -(@pxref{Structuring Your Accounts}) for details and suggestions regarding -your accounts. - - - -@strong{The format is very flexible and it isn't necessary that you -indent and space out things exactly as shown. The only requirements are -that the start of the transaction (the date typically) is at the -beginning of the first line of the transaction, and the accounts are -indented by at least one space. If you omit the leading spaces in the -account lines LEDGER will not count the transaction and will not -give an error. There must be at least two spaces, or a tab, between the -amount and the account. If you do not have adequate separation between -the amount and the account LEDGER will give an error and stop -calculating} - -@node Commodities, Structuring Your Accounts, Most Basic Entry, Keeping a Journal -@section Commodities - -LEDGER is agnostic when it comes to how you value your accounts. -Dollars, Euros, Pounds, Francs, etc. are just ``commodities''. Holdings -in stocks, bonds, mutual funds and other financial instrument can be -label using whatever is convenient for you (stock ticker symbols are -suggested for publicly traded assets).@footnote{you can track ANYTHING, -even time. As long as it cannot be created or destroyed inside your -accounting system.} - -This is fundamentally different than many common accounting packages, -which assume the same currency throughout all of your accounts. This -means if you typically operate in Euros, but travel to the US and has -some expenses, you would have to do the currency conversion BEFORE you -made the entry into your financial system. With ledger this is not -required. In the same journal you can have entries in any or all -commodities you actually hold. You can use the reporting capabilities -to convert all commodities to a single commodity for reporting purposes -without ever changing the underlying entry. - -For example, the following entries reflect transaction made for a -business trip to Europe from the US: - -@smallexample -2011/09/23 Cash in Munich - Assets:Cash 50.00 Euros - Assets:Checking $-66.00 - -2011/09/24 Dinner in Munich - Expenses:Business:Travel 35.00 Euro - Assets:Cash -@end smallexample - -This says that $66.00 came out of checking and turned into 50 Euros. The -implied exchange rate was $1.32. Then 35 Euros was spent on Dinner in Munich. - - -@node Structuring Your Accounts, Transaction Notes and Tags , Commodities ,Keeping a Journal -@section Structuring your Accounts - -There really are no requirements for how you do this, but to preserve -your sanity we suggest some very basic structure to your accounting -system. - -At the highest level you have five sorts of accounts: Expenses, Assets, -Income, Liabilities and Equity. Briefly, you can think of these as places money goes, -places money sits, places money comes from and money you owe. - -Starting the structure off this way will make it simpler for you to get -answers to the questions you really need to ask about your finances. - -@node Transaction Notes and Tags, File Format, Structuring Your Accounts, Keeping a Journal -@section Transaction Notes and Tags -LEDGER 3.0 supports entry and transaction ``notes'', which may -contain new metadata and tag markers. Here's an example: - -@smallexample - 2004/05/27 (100) Credit card company - ; This is an entry note! - ; Sample: Value - Liabilities:MasterCard $20.00 - ; This is a transaction note! - ; Sample: Another Value - ; :MyTag: - Assets:Bank:Checking - ; :AnotherTag: -@end smallexample - -An indented paragraph starting with `;' is parsed as a persistent note -for its preceding category. These notes will get printed back to you -with the ``print'' command. They are accessible to value expressions -using the ``note'' variable. - -Further, any occurrence of ``:foo:'' in a note will cause a metadata tag -for "foo" to be registered for that entry. You can then search for -such transactions using: - -@smallexample - ledger reg %foo - ldeger reg tag foo -@end smallexample - -Also, if any word in the note ends (but does not start) with a colon, -the remainder of that line will be taken to be the metadata value for -that tag. That is: - -@smallexample - ; :foo:bar:baz: <-- These are three tags - ; name: value <-- this is a tag with a value -@end smallexample - -Tags with value can be searched for just like tags. In addition, you -can further limit your tag search by looking for only those tags that -have specific values: - -@smallexample - ledger reg %name=value - ledger reg tag name=value -@end smallexample - -The group-by and sort functions also support tags: -@smallexample -ledger --group-by "tag('foo')" bal -@end smallexample -Will produce a balance summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'. - -@smallexample -ledger reg --sort "tag('foo')" %foo -@end smallexample -Produces a register view with the transaction have tag `foo' sorted by the tags value. - -Comments that occur before an entry, or which starts at column -zero, are always ignored and are neither searched nor printed back. - - - -@node File Format, Command-line Syntax ,Transaction Notes and Tags, Keeping a Journal -@section File format - -The ledger file format is quite simple, but also very flexible. It -supports many options, though typically the user can ignore most of -them. They are summarized below. - -The initial character of each line determines what the line means, and -how it should be interpreted. Allowable initial characters are: - -@table @code -@item NUMBER -A line beginning with a number denotes a transaction. It may be followed -by any number of lines, each beginning with whitespace, to denote the -transaction's account postings. The format of the first line is: - -@example -DATE[=EDATE] [*|!] [(CODE)] DESC -@end example - -If @samp{*} appears after the date (with optional effective date), it -indicates the transaction is ``cleared'', which can mean whatever the user -wants it to mean. If @samp{!} appears after the date, it indicates d -the transaction is ``pending''; i.e., tentatively cleared from the user's -point of view, but not yet actually cleared. If a @samp{CODE} appears -in parentheses, it may be used to indicate a check number, or the type -of the posting. Following these is the payee, or a description of -the posting. - -The format of each following posting is: - -@example - ACCOUNT AMOUNT [; NOTE] -@end example - -The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual -postings, or square brackets if it is a virtual postings that -must balance. The @samp{AMOUNT} can be followed by a per-unit -posting cost, by specifying @samp{@@ AMOUNT}, or a complete -posting cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may -specify an actual and/or effective date for the posting by using -the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or -@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}. - -@item = -An automated transaction. A value expression must appear after the equal -sign. - -After this initial line there should be a set of one or more -postings, just as if it were normal transaction. If the amounts of the -postings have no commodity, they will be applied as modifiers to -whichever real posting is matched by the value expression. - -@item ~ -A period transaction. A period expression must appear after the tilde. - -After this initial line there should be a set of one or more -postings, just as if it were normal transaction. - -@item ! -A line beginning with an exclamation mark denotes a command directive. -It must be immediately followed by the command word. The supported -commands are: - -@table @samp -@item !include -Include the stated journal file. - -@item !account -The account name is given is taken to be the parent of all -postings that follow, until @samp{!end} is seen. - -@item !end -Ends an account block. -@end table - -@item ; -A line beginning with a colon indicates a comment, and is -ignored. Comments will not be returned in a ``print'' response. -@item indented ; -If the semi colon is indented and occurs inside a transaction, it is -parsed as a persistent note for its preceding category. These notes or -tags can be used to augment to reporting and filtering capabilities of -LEDGER. -@item Y -If a line begins with a capital Y, it denotes the year used for all -subsequent transactions that give a date without a year. The year should -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 transactions specify a year, however, this command has no effect. - -@item P -Specifies a historical price for a commodity. These are usually found -in a pricing history file (see the @option{-Q} option). The syntax -is: -@example -P DATE SYMBOL PRICE -@end example - -@item N SYMBOL -Indicates that pricing information is to be ignored for a given -symbol, nor will quotes ever be downloaded for that symbol. Useful -with a home currency, such as the dollar ($). It is recommended that -these pricing options be set in the price database file, which -defaults to @file{~/.pricedb}. The syntax for this command is: -@example -N SYMBOL -@end example - -@item D AMOUNT -Specifies the default commodity to use, by specifying an amount in the -expected format. The @command{transaction} command will use this commodity -as the default when none other can be determined. This command may be -used multiple times, to set the default flags for different -commodities; whichever is seen last is used as the default commodity. -For example, to set US dollars as the default commodity, while also -setting the thousands flag and decimal flag for that commodity, use: -@example -D $1,000.00 -@end example - -@item C AMOUNT1 = AMOUNT2 -Specifies a commodity conversion, where the first amount is given to -be equivalent to the second amount. The first amount should use the -decimal precision desired during reporting: -@example -C 1.00 Kb = 1024 bytes -@end example - -@item i, o, b, h -These four 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 - -@node Archiving Previous Years , , ,Keeping a Journal -@section Archiving Previous Years - -@node Ledger Tutorial , , ,Keeping a Journal -@section Ledger Tutorial diff --git a/doc/L3-JournalFormat.texi b/doc/L3-JournalFormat.texi deleted file mode 100644 index ac7059ca..00000000 --- a/doc/L3-JournalFormat.texi +++ /dev/null @@ -1,242 +0,0 @@ -@c -*-texinfo-*- -@node Journal File Format,Extending with Python, Format Strings, Top -@chapter LEDGER Journal File Format - -This chapter offers a complete description of the journal data format, -suitable for implementors in other languages to follow. For users, -the chapter on keeping a journal is less extensive, but more typical -of common usage (@pxref{Keeping a Journal}). - -Data is collected in the form of @dfn{transactions} which occur in one -or more @dfn{journal files}. Each transaction, in turn, is made up of -one or more @dfn{postings}, which describe how @dfn{amounts} flow from -one @dfn{account} to another. Here is an example of the simplest of -journal files: - -@example -2010/05/31 Just an example - Expenses:Some:Account $100.00 - Income:Another:Account -@end example - -In this example, there is a transaction date, a payee, or description -of the transaction, and two postings. The postings show movement of -one hundred dollars from an account within the Income hierarchy, to -the specified expense account. The name and meaning of these accounts -in arbitrary, with no preferences implied, although you will find it -useful to follow standard accounting practice (@pxref{Principles of -Accounting}). - -Since an amount is missing from the second posting, it is assumed to -be the inverse of the first. This guarantee the cardinal rule of -double-entry accounting: the sum of every transaction must balance to -zero, or it is in error. Whenever Ledger encounters a @dfn{null -posting} in a transaction, it uses it to balance the remainder. - -It is also typical---though not enforced---to think of the first -posting as the destination, and the final as the source. Thus, the -amount of the first posting is typically positive. Consider: - -@example -2010/05/31 An income transaction - Assets:Checking $1,000.00 - Income:Salary - -2010/05/31 An expense transaction - Expenses:Dining $100.00 - Assets:Checking -@end example - -@emph{Note:} It is important to note that there must be at least two spaces between -the end of the post and the beginning of the amount (including and -commdity designator). - -@section Specifying amounts - -The heart of a journal is the amounts it records, and this fact is -reflected in the diversity of amount expressions allowed. All of them -are covered here, though it must be said that sometimes, there are -multiple ways to achieve a desired result. - -@subsection Integer amounts - -In the simplest form, bare decimal numbers are accepted: - -@example -2010/05/31 An income transaction - Assets:Checking 1000.00 - Income:Salary -@end example - -Such amounts may only use an optional period for a decimal point. -These are referred to as @dfn{integer amounts} or @dfn{uncommoditized -amounts}. In most ways they are similar to @dfn{commoditized -amounts}, but for one signficant difference: They always display in -reports with @dfn{full precision}. More on this in a moment. For -now, a word must be said about how Ledger stores numbers. - -Every number parsed by Ledger is stored internally as an -infinite-precision rational value. Floating-point math is never used, -as it cannot be trusted to maintain precision of values. So, in the -case of @samp{1000.00} above, the internal value is @samp{100000/100}. - -While rational numbers are great at not losing precision, the question -arises: How should they be displayed? A number like @samp{100000/100} -is no problem, since it represents a clean decimal fraction. But what -about when the number @samp{1/1} is divided by three? How should one -print @samp{1/3}, an infinitely repeating decimal? - -Ledger gets around this problem by rendering rationals into decimal at -the last possible moment, and only for display. As such, some -rounding must, at times, occur. If this rounding would affect the -calculation of a running total, special accommodation postings are -generated to make you aware it has happened. In practice, it happens -rarely, but even then it does not reflect adjustment of the -@emph{internal amount}, only the displayed amount. - -What has still not been answered is how Ledger rounds values. Should -@samp{1/3} be printed as @samp{0.33} or @samp{0.33333}? For -commoditized amounts, the number of decimal places is decided by -observing how each commodity is used; but in the case of integer -amounts, an arbitrary factor must be chosen. Initially, this factor -is six. Thus, @samp{1/3} is printed back as @samp{0.333333}. -Further, this rounding factor becomes associated with each particular -value, and is carried through mathematical operations. For example, -if that particular number were multiplied by itself, the decimal -precision of the result would be twelve. Addition and subtraction do -not affect precision. - -Since each integer amount retains its own display precision, this is -called @dfn{full precision}, as opposed to commoditized amounts, which -always look to their commodity to know what precision they should -round to, and so use @dfn{commodity precision}. - -@subsection Commoditized amounts - -A @dfn{commoditized amount} is an integer amount which has an -associated commodity. This commodity can appear before or after the -amount, and may or may not be separated from it by a space. Most -characters are allowed in a commodity name, except for the following: - -@itemize -@item Any kind of whitespace -@item Numerical digits -@item Punctuation: @samp{.,;:?!} -@item Mathematical and logical operators: @samp{-+*/^&|=} -@item Bracketing characters: @samp{<>[]()}@{@} -@item The at symbol: @samp{@@} -@end itemize - -And yet, any of these may appear in a commodity name if it is -surrounded by double quotes, for example: - -@example -100 "EUN+133" -@end example - -If a @dfn{quoted commodity} is found, it is displayed in quotes as -well, to avoid any confusion as to which part is the amount, and which -part is the commodity. - -Another feature of commoditized amounts is that they are reported back -in the same form as parsed. If you specify dollar amounts using -@samp{$100}, they will print the same; likewise with @samp{100 $} or -@samp{$100.000}. You may even use decimal commas, such as -@samp{$100,00}, or thousand-marks, as in @samp{$10,000.00}. - -These display characteristics become associated with the commodity, -with the result being that all amounts of the same commodity are -reported consistently. Where this is most noticeable is the -@dfn{display precision}, which is determined by the most precise value -seen for a given commodity. In most cases. - -Ledger makes a distinction by @dfn{observed amounts} and unobserved -amounts. An observed amount is critiqued by Ledger to determine how -amounts using that commodity should be displayed; unobserved amounts -are significant in their value only---no matter how they are -specified, it does not change how other amounts in that commodity will -be displayed. - -An example of this is found in cost expressions, covered next. - -@section Posting costs - -You have seen how to specify either a commoditized or an integer -amount for a posting. But what if the amount you paid for something -was in one commodity, and the amount received was another? There are -two main ways to express this: - -@example -2010/05/31 Farmer's Market - Assets:My Larder 100 apples - Assets:Checking $20.00 -@end example - -In this example, you have paid twenty dollars for one hundred apples. -The cost to you is twenty cents per apple, and Ledger calculates this -implied cost for you. You can also make the cost explicit using a -@dfn{cost amount}: - -@example -2010/05/31 Farmer's Market - Assets:My Larder 100 apples @@ $0.200000 - Assets:Checking -@end example - -Here the @dfn{per-unit cost} is given explicitly in the form of a cost -amount; and since cost amount are @emph{unobserved}, the use of six -decimal places has no effect on how dollar amounts are displayed in -the final report. You can also specify the @dfn{total cost}: - -@example -2010/05/31 Farmer's Market - Assets:My Larder 100 apples @@@@ $20 - Assets:Checking -@end example - -These three forms have identical meaning. In most cases the first is -preferred, but the second two are necessary when more than two -postings are involved: - -@example -2010/05/31 Farmer's Market - Assets:My Larder 100 apples @@ $0.200000 - Assets:My Larder 100 pineapples @@ $0.33 - Assets:My Larder 100 "crab apples" @@ $0.04 - Assets:Checking -@end example - -Here the implied cost is @samp{$57.00}, which is entered into the null -posting automatically so that the transaction balances. - -@subsection Primary commodities - -In every transaction involving more than one commodity, there is -always one which is the @dfn{primary commodity}. This commodity -should be thought of as the exchange commodity, or the commodity used -to buy and sells units of the other commodity. In the fruit examples -above, dollars are the primary commodity. This is decided by Ledger -on the placement of the commodity in the transaction: - -@example -2010/05/31 Sample Transaction - Expenses 100 secondary - Assets 50 primary - -2010/05/31 Sample Transaction - Expenses 100 secondary @@ 0.5 primary - Assets - -2010/05/31 Sample Transaction - Expenses 100 secondary @@@@ 50 primary - Assets -@end example - -The only case where knowledge of primary versus secondary comes into -play is in reports that use the @option{-V} or @option{-B} options. -With these, only primary commodities are shown. - -If a transaction uses only one commodity, this commodity is also -considered a primary. In fact, when Ledger goes about ensures that -all transactions balance to zero, it only ever asks this of primary -commodities. diff --git a/doc/L3-Main.texi b/doc/L3-Main.texi deleted file mode 100644 index aabc0f34..00000000 --- a/doc/L3-Main.texi +++ /dev/null @@ -1,96 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@setfilename ledger.info -@settitle Ledger: Command-Line Accounting - -@dircategory User Applications -@copying -Copyright (c) 2003-2010, John Wiegley. All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -- Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -- Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -- Neither the name of New Artisans LLC nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -@end copying - -@documentencoding UTF-8 - -@iftex -@finalout -@end iftex - -@macro ledgerprog - @sc{ledger} -@end macro - - -@titlepage -@title LEDGER: Command-Line Accounting -@author John Wiegley -@end titlepage - -@direntry -* Ledger: (ledger). Command-Line Accounting -@end direntry - -@contents - -@ifnottex -@node Top, , (dir), (dir) -@top Overview - -@insertcopying -@end ifnottex - -@ifnottex -@section Copyright -@insertcopying -@end ifnottex - -@menu -* Introduction to Ledger:: -* Principles of Accounting:: -* Keeping a Journal:: -* Command-line Syntax:: -* Basic Reporting Commands:: -* Value Expressions:: -* Format Strings:: -* Journal File Format:: -* Extending with Python:: -@end menu - - -@c each chapter is in an idividual texi file included here -@include L3-Introduction.texi -@include L3-Principles.texi -@include L3-Journal.texi -@include L3-Syntax.texi -@include L3-Reporting.texi -@include L3-ValueExpressions.texi -@include L3-FormatStrings.texi -@include L3-JournalFormat.texi -@include L3-Python.texi - -@bye diff --git a/doc/L3-Principles.texi b/doc/L3-Principles.texi deleted file mode 100644 index 1de75967..00000000 --- a/doc/L3-Principles.texi +++ /dev/null @@ -1,4 +0,0 @@ -@c -*-texinfo-*- - -@node Principles of Accounting, Keeping a Journal, Introduction to Ledger, Top -@chapter Principles of Accounting diff --git a/doc/L3-Python.texi b/doc/L3-Python.texi deleted file mode 100644 index 3f985237..00000000 --- a/doc/L3-Python.texi +++ /dev/null @@ -1,3 +0,0 @@ -@c -*-texinfo-*- -@node Extending with Python, , Journal File Format, Top -@chapter Extending with Python diff --git a/doc/L3-Queries.texi b/doc/L3-Queries.texi deleted file mode 100644 index ef45d948..00000000 --- a/doc/L3-Queries.texi +++ /dev/null @@ -1,3 +0,0 @@ -@c -*-texinfo-*- - -@chapter Report Queries diff --git a/doc/L3-Reporting.texi b/doc/L3-Reporting.texi deleted file mode 100644 index cb675aba..00000000 --- a/doc/L3-Reporting.texi +++ /dev/null @@ -1,11 +0,0 @@ -@c -*-texinfo-*- - -@node Basic Reporting Commands, Value Expressions, Command-line Syntax, Top -@chapter Basic Reporting Commands - -@menu -* Budgeting and Forecasting:: -@end menu - -@node Budgeting and Forecasting, , ,Basic Reporting Commands -@section Budgeting and Forecasting diff --git a/doc/L3-Syntax.texi b/doc/L3-Syntax.texi deleted file mode 100644 index 83bd1320..00000000 --- a/doc/L3-Syntax.texi +++ /dev/null @@ -1,677 +0,0 @@ -@c -*-texinfo-*- -@node Command-line Syntax, Basic Reporting Commands, File Format, Top -@chapter Command-line Syntax - - -@menu -* Cookbook:: -* Quick Reference:: -* Commands:: -* Options:: -* Period Expressions:: -@end menu - -@node Cookbook, Quick Reference, Command-line Syntax, Command-line Syntax -@section Cookbook - -@subsection Invoking Ledger - -@example -ledger --group-by "tag('trip')" bal -legder reg --sort "tag('foo')" %foo -ledger cleared VWCU NFCU Tithe Misentry -ledger register Joint --uncleared -ledger register NFCUChecking --sort d -d 'd>[2011/04/01]' until 2011/05/25 -@end example -@subsection Ledger Files - -@example -= /^Income:Taxable/ - (Liabilities:Tithe Owed) -0.1 -= /Noah/ - (Liabilities:Tithe Owed) -0.1 -= /Jonah/ - (Liabilities:Tithe Owed) -0.1 -= /Tithe/ - (Liabilities:Tithe Owed) -1.0 -@end example - -@node Quick Reference, Commands, Cookbook, Command-line Syntax -@section Quick Reference - -This chapter describes LEDGER's features and serves as a quick -reference. You may wish to survey this to get an overview before diving -in to the @ref{Ledger Tutorial} and more detailed examples that follow. - -LEDGER has a very simple command-line interface, named---enticingly -enough---@command{ledger}. It supports a few reporting commands, and -a large number of options for refining the output from those commands. -The basic syntax of any ledger command is: - -@example -ledger [OPTIONS...] COMMAND [ARGS...] -@end example - -Command options must always precede the command word. After the -command word there may appear any number of arguments. For most -commands, these arguments are regular expressions that cause the -output to relate only to postings matching those regular -expressions. For the @command{transaction} command, the arguments have a -special meaning, described below. - -The regular expressions arguments always match the account name that a -posting refers to. To match on the payee of the transaction instead, -precede the regular expression with @samp{--}. For example, the -following balance command reports account totals for rent, food and -movies, but only those whose payee matches Freddie: - -@example -ledger bal rent food movies -- freddie -@end example - -There are many, many command options available with the -@command{ledger} command, and it takes a while to master them. -However, none of them are required to use the basic reporting -commands. - - -@node Commands, Options, Quick Reference, Command-line Syntax -@section Commands - -@subsection balance - -The @command{balance} command reports the current balance of all -accounts. It accepts a list of optional regexps, which confine the -balance report to the matching accounts. If an account contains -multiple types of commodities, each commodity's total is reported -separately. - -@subsection register - -The @command{register} command displays all the postings occurring -in a single account, line by line. The account regexp must be -specified as the only argument to this command. If any regexps occur -after the required account name, the register will contain only those -postings that match. Very useful for hunting down a particular -posting. - -The output from @command{register} is very close to what a typical -checkbook, or single-account ledger, would look like. It also shows a -running balance. The final running balance of any register should -always be the same as the current balance of that account. - -If you have Gnuplot installed, you may plot the amount or running -total of any register by using the script @file{report}, which is -included in the LEDGER distribution. The only requirement is that you -add either @option{-j} or @option{-J} to your register command, in -order to plot either the amount or total column, respectively. - -@subsection print - -The @command{print} command prints out ledger transactions in a textual -format that can be parsed by LEDGER. They will be properly formatted, -and output in the most economic form possible. The ``print'' command -also takes a list of optional regexps, which will cause only those -postings which match in some way to be printed. - -The @command{print} command can be a handy way to clean up a ledger -file whose formatting has gotten out of hand. - -@subsection output - -The @command{output} command is very similar to the @command{print} -command, except that it attempts to replicate the specified ledger -file exactly. The format of the command is: - -@example -ledger -f FILENAME output FILENAME -@end example - -Where @file{FILENAME} is the name of the ledger file to output. The -reason for specifying this command is that only transactions contained -within that file will be output, and not an included transactions (as can -happen with the @command{print} command). - -@subsection xml - -The @command{xml} command outputs results similar to what -@command{print} and @command{register} display, but as an XML form. -This data can then be read in and processed. Use the -@option{--totals} option to include the running total with each -posting. - -@subsection emacs - -The @command{emacs} command outputs results in a form that can be read -directly by Emacs Lisp. The format of the sexp is: - -@example -((BEG-POS CLEARED DATE CODE PAYEE - (ACCOUNT AMOUNT)...) ; list of postings - ...) ; list of transactions -@end example - -@subsection equity - -The @command{equity} command prints out accounts balances as if they -were transactions. This makes it easy to establish the starting balances -for an account, such as when @ref{Archiving Previous Years}. - -@subsection prices - -The @command{prices} command displays the price history for matching -commodities. The @option{-A} flag is useful with this report, to -display the running average price, or @option{-D} to show each price's -deviation from that average. - -There is also a @command{pricesdb} command which outputs the same -information as @command{prices}, but does in a format that can be -parsed by LEDGER. - -@subsection xact - -The @command{xact} commands simplifies the creation of new transactions. -It works on the principle that 80% of all postings are variants of -earlier postings. Here's how it works: - -Say you currently have this posting in your ledger file: - -@smallexample -2004/03/15 * Viva Italiano - Expenses:Food $12.45 - Expenses:Tips $2.55 - Liabilities:MasterCard $-15.00 -@end smallexample - -Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva -Italiano} again. The exact amounts are different, but the overall -form is the same. With the @command{xact} command you can type: - -@example -ledger xact 2004/4/9 viva food 11 tips 2.50 -@end example - -This produces the following output: - -@smallexample -2004/04/09 Viva Italiano - Expenses:Food $11.00 - Expenses:Tips $2.50 - Liabilities:MasterCard $-13.50 -@end smallexample - -It works by finding a past posting matching the regular expression -@samp{viva}, and assuming that any accounts or amounts specified will -be similar to that earlier posting. If LEDGER does not succeed in -generating a new transaction, an error is printed and the exit code is set -to @samp{1}. - -There is a shell script in the distribution's @file{scripts} directory -called @file{xact}, which simplifies the task of adding a new transaction -to your ledger. It launches @command{vi} to confirm that the transaction -looks appropriate. - -Here are a few more examples of the @command{xact} command, assuming -the above journal transaction: - -@example -ledger xact 4/9 viva 11.50 -ledger xact 4/9 viva 11.50 checking # (from `checking') -ledger xact 4/9 viva food 11.50 tips 8 -ledger xact 4/9 viva food 11.50 tips 8 cash -ledger xact 4/9 viva food $11.50 tips $8 cash -ledger xact 4/9 viva dining "DM 11.50" -@end example - -@node Options, Period Expressions, Commands, Command-line Syntax -@section Options - -With all of the reports, command-line options are useful to modify the -output generated. These command-line options always occur before the -command word. This is done to distinguish options from exclusive -regular expressions, which also begin with a dash. The basic form for -most commands is: - -@example -ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] -@end example - -The @var{OPTIONS} and @var{REGEXPS} expressions are both optional. -You could just use @samp{ledger balance}, without any options---which -prints a summary of all accounts. But for more specific reporting, or -to change the appearance of the output, options are needed. - -@subsection Basic options - -These are the most basic command options. Most likely, the user will -want to set them using environment variables (see @ref{Options}), -instead of using actual command-line options: - -@option{--help} (@option{-h}) prints a summary of all the options, and -what they are used for. This can be a handy way to remember which -options do what. This help screen is also printed if ledger is run -without a command. - -@option{--version} (@option{-v}) prints the current version of ledger -and exits. This is useful for sending bug reports, to let the author -know which version of ledger you are using. - -@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. -This command may be used multiple times. -Typically, the environment variable -@env{LEDGER_FILE} is set, rather than using this command-line option. - -@option{--output FILE} (@option{-o FILE}) redirects output from any -command to @var{FILE}. By default, all output goes to standard -output. - -@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by -ledger before any other ledger file. This file may not contain any -postings, but it may contain option settings. To specify options -in the init file, use the same syntax as the command-line, but put each -option on it's own line. Here's an example init file: - -@smallexample ---price-db ~/finance/.pricedb ---cache /tmp/ledger-cache - -; ~/.ledgerrc ends here -@end smallexample - -Option settings on the command-line or in the environment always take -precedence over settings in the init file. - -@option{--cache FILE} identifies FILE as the default binary cache -file. That is, if the ledger files to be read are specified using the -environment variable @env{LEDGER_FILE}, then whenever a command is -finished a binary copy will be written to the specified cache, to -speed up the loading time of subsequent queries. This filename can -also be given using the environment variable @env{LEDGER_CACHE}, or by -putting the option into your init file. The @option{--no-cache} -option causes LEDGER to always ignore the binary cache. - -@option{--account NAME} (@option{-a NAME}) specifies the default -account which QIF file postings are assumed to relate to. - -@subsection Report filtering - -These options change which postings affect the outcome of a -report, in ways other than just using regular expressions: - -@option{--current}(@option{-c}) displays only transactions occurring on or -before the current date. - -@option{--begin DATE} (@option{-b DATE}) constrains the report to -transactions on or after @var{DATE}. Only transactions after that date will be -calculated, which means that the running total in the balance report -will always start at zero with the first matching transaction. (Note: This -is different from using @option{--display} to constrain what is -displayed). - -@option{--end DATE} (@option{-e DATE}) constrains the report so that -transactions on or after @var{DATE} are not considered. The ending date -is inclusive. - -@option{--period STR} (@option{-p STR}) sets the reporting period -to @var{STR}. This will subtotal all matching transactions within each -period separately, making it easy to see weekly, monthly, quarterly, -etc., posting totals. A period string can even specify the -beginning and end of the report range, using simple terms like ``last -june'' or ``next month''. For more using period expressions, see -@ref{Period Expressions}. - -@option{--period-sort EXPR} sorts the postings within each -reporting period using the value expression @var{EXPR}. This is most -often useful when reporting monthly expenses, in order to view the -highest expense categories at the top of each month: - -@example -ledger -M --period-sort -At reg ^Expenses -@end example - -@option{--cleared} (@option{-C}) displays only postings whose transaction -has been marked ``cleared'' (by placing an asterix to the right of the -date). - -@option{--uncleared} (@option{-U}) displays only postings whose -transaction has not been marked ``cleared'' (i.e., if there is no asterix to -the right of the date). - -@option{--real} (@option{-R}) displays only real postings, not -virtual. (A virtual posting is indicated by surrounding the -account name with parentheses or brackets; see the section on using -virtual postings for more information). - -@option{--actual} (@option{-L}) displays only actual postings, and -not those created due to automated postings. - -@option{--related} (@option{-r}) displays postings that are -related to whichever postings would otherwise have matched the -filtering criteria. In the register report, this shows where money -went to, or the account it came from. In the balance report, it shows -all the accounts affected by transactions having a related posting. -For example, if a file had this transaction: - -@smallexample -2004/03/20 Safeway - Expenses:Food $65.00 - Expenses:Cash $20.00 - Assets:Checking $-85.00 -@end smallexample - -And the register command was: - -@example -ledger -r register food -@end example - -The following would be output, showing the postings related to the -posting that matched: - -@smallexample -2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 - Assets:Checking $85.00 $65.00 -@end smallexample - -@option{--budget} is useful for displaying how close your postings -meet your budget. @option{--add-budget} also shows unbudgeted -postings, while @option{--unbudgeted} shows only those. -@option{--forecast} is a related option that projects your budget into -the future, showing how it will affect future balances. -@xref{Budgeting and Forecasting}. - -@option{--limit EXPR} (@option{-l EXPR}) limits which postings -take part in the calculations of a report. - -@option{--amount EXPR} (@option{-t EXPR}) changes the value expression -used to calculate the ``value'' column in the @command{register} -report, the amount used to calculate account totals in the -@command{balance} report, and the values printed in the -@command{equity} report. @xref{Value Expressions}. - -@option{--total EXPR} (@option{-T EXPR}) sets the value expression -used for the ``totals'' column in the @command{register} and -@command{balance} reports. - -@subsection Output customization - -These options affect only the output, but not which postings are -used to create it: - -@option{--collapse} (@option{-n}) causes transactions in a -@command{register} report with multiple postings to be collapsed -into a single, subtotaled transaction. - -@option{--subtotal} (@option{-s}) causes all transactions in a -@command{register} report to be collapsed into a single, subtotaled -transaction. - -@option{--by-payee} (@option{-P}) reports subtotals by payee. - -@option{--comm-as-payee} (@option{-x}) changes the payee of every -posting to be the commodity used in that posting. This can be -useful when combined with other options, such as @option{-s}. - -@option{--empty} (@option{-E}) includes even empty accounts in the -@command{balance} report. - -@option{--weekly} (@option{-W}) reports posting totals by the -week. The week begins on whichever day of the week begins the month -containing that posting. To set a specific begin date, use a -period string, such as @samp{weekly from DATE}. @option{--monthly} -(@option{-M}) reports posting totals by month; @option{--yearly} -(@option{-Y}) reports posting totals by year. For more complex -period, using the @option{--period} option described above. - -@option{--dow} reports postings totals for each day of the week. -This is an easy way to see if weekend spending is more than on -weekdays. - -@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing -the values determined using the value expression @var{EXPR}. For -example, using @option{-S -UT} in the balance report will sort account -balances from greatest to least, using the absolute value of the -total. For more on how to use value expressions, see @ref{Value -Expressions}. - -@option{--wide} (@option{-w}) causes the default @command{register} -report to assume 132 columns instead of 80. - -@option{--head} causes only the first N transactions to be printed. This -is different from using the command-line utility @command{head}, which -would limit to the first N postings. @option{--tail} outputs only -the last N transactions. Both options may be used simultaneously. If a -negative amount is given, it will invert the meaning of the flag -(instead of the first five transactions being printed, for example, it -would print all but the first five). - -@option{--pager} tells LEDGER to pass its output to the given pager -program---very useful when the output is especially long. This -behavior can be made the default by setting the @env{LEDGER_PAGER} -environment variable. - -@option{--average} (@option{-A}) reports the average posting -value. - -@option{--deviation} (@option{-D}) reports each posting's -deviation from the average. It is only meaningful in the -@command{register} and @command{prices} reports. - -@option{--percentage} (@option{-%}) shows account subtotals in the -@command{balance} report as percentages of the parent account. - -@option{--totals} include running total information in the -@command{xml} report. - -@option{--amount-data} (@option{-j}) changes the @command{register} -report so that it outputs nothing but the date and the value column, -and the latter without commodities. This is only meaningful if the -report uses a single commodity. This data can then be fed to other -programs, which could plot the date, analyze it, etc. - -@option{--total-data} (@option{-J}) changes the @command{register} -report so that it outputs nothing but the date and totals column, -without commodities. - -@option{--display EXPR} (@option{-d EXPR}) limits which postings -or accounts or actually displayed in a report. They might still be -calculated, and be part of the running total of a register report, for -example, but they will not be displayed. This is useful for seeing -last month's checking postings, against a running balance which -includes all posting values: - -@example -ledger -d "d>=[last month]" reg checking -@end example - -The output from this command is very different from the following, -whose running total includes only postings from the last month -onward: - -@example -ledger -p "last month" reg checking -@end example - -Which is more useful depends on what you're looking to know: the total -amount for the reporting range (@option{-p}), or simply a display -restricted to the reporting range (using @option{-d}). - -@option{--date-format STR} (@option{-y STR}) changes the basic date -format used by reports. The default uses a date like 2004/08/01, -which represents the default date format of @samp{%Y/%m/%d}. To -change the way dates are printed in general, the easiest way is to put -@option{--date-format FORMAT} in the LEDGER initialization file -@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). - -@option{--format STR} (@option{-F STR}) sets the reporting format for -whatever report ledger is about to make. @xref{Format Strings}. -There are also specific format commands for each report type: - -@itemize -@item @option{--balance-format STR} -@item @option{--register-format STR} -@item @option{--print-format STR} -@item @option{--plot-amount-format STR} (-j @command{register}) -@item @option{--plot-total-format STR} (-J @command{register}) -@item @option{--equity-format STR} -@item @option{--prices-format STR} -@item @option{--wide-register-format STR} (-w @command{register}) -@end itemize - -@subsection Commodity reporting - -These options affect how commodity values are displayed: - -@option{--price-db FILE} sets the file that is used for recording -downloaded commodity prices. It is always read on startup, to -determine historical prices. Other settings can be placed in this -file manually, to prevent downloading quotes for a specific, for -example. This is done by adding a line like the following: - -@example -; Don't download quotes for the dollar, or timelog values -N $ -N h -@end example - -@option{--price-exp MINS} (@option{-L MINS}) sets the expected -freshness of price quotes, in minutes. That is, if the last known -quote for any commodity is older than this value---and if -@option{--download} is being used---then the Internet will be -consulted again for a newer price. Otherwise, the old price is still -considered to be fresh enough. - -@option{--download} (@option{-Q}) causes quotes to be automagically -downloaded, as needed, by running a script named @command{getquote} -and expecting that script to return a value understood by ledger. A -sample implementation of a @command{getquote} script, implemented in -Perl, is provided in the distribution. Downloaded quote price are -then appended to the price database, usually specified using the -environment variable @env{LEDGER_PRICE_DB}. - -There are several different ways that ledger can report the totals it -displays. The most flexible way to adjust them is by using value -expressions, and the @option{-t} and @option{-T} options. However, -there are also several ``default'' reports, which will satisfy most -users basic reporting needs: - -@table @code -@item -O, --quantity -Reports commodity totals (this is the default) - -@item -B, --basis -Reports the cost basis for all postings. - -@item -V, --market -Reports the last known market value for all commodities. - -@item -G --gain -Reports the net gain/loss for all commodities in the report that have -a price history. -@end table - -@subsection Environment variables - -Every option to ledger may be set using an environment variable. If -an option has a long name such @option{--this-option}, setting the -environment variable @env{LEDGER_THIS_OPTION} will have the same -affect as specifying that option on the command-line. Options on the -command-line always take precedence over environment variable -settings, however. - -Note that you may also permanently specify option values by placing -option settings in the file @file{~/.ledgerrc}, for example: - -@example ---cache /tmp/.mycache ---pager /bin/cat - -@end example - -@node Period Expressions, Format Strings, Options, Command-line Syntax -@section Period Expressions - -A period expression indicates a span of time, or a reporting interval, -or both. The full syntax is: - -@example -[INTERVAL] [BEGIN] [END] -@end example - -The optional @var{INTERVAL} part may be any one of: - -@example -every day -every week -every monthly -every quarter -every year -every N days # N is any integer -every N weeks -every N months -every N quarters -every N years -daily -weekly -biweekly -monthly -bimonthly -quarterly -yearly -@end example - -After the interval, a begin time, end time, both or neither may be -specified. As for the begin time, it can be either of: - -@example -from -since -@end example - -The end time can be either of: - -@example -to -until -@end example - -Where @var{SPEC} can be any of: - -@example -2004 -2004/10 -2004/10/1 -10/1 -october -oct -this week # or day, month, quarter, year -next week -last week -@end example - -The beginning and ending can be given at the same time, if it spans a -single period. In that case, just use @var{SPEC} by itself. In that -case, the period @samp{oct}, for example, will cover all the days in -october. The possible forms are: - -@example - -in -@end example - -Here are a few examples of period expressions: - -@example -monthly -monthly in 2004 -weekly from oct -weekly from last month -from sep to oct -from 10/1 to 10/5 -monthly until 2005 -from apr -until nov -last oct -weekly last august -@end example - diff --git a/doc/L3-ValueExpressions.texi b/doc/L3-ValueExpressions.texi deleted file mode 100644 index f893229f..00000000 --- a/doc/L3-ValueExpressions.texi +++ /dev/null @@ -1,230 +0,0 @@ -@c -*-texinfo-*- - -@node Value Expressions, Variables, Basic Reporting Commands, Top -@chapter Value Expressions - -Value expressions are an expression language used by LEDGER to -calculate values used by the program for many different purposes: - -@enumerate -@item -The values displayed in reports -@item -For predicates (where truth is anything non-zero), to determine which -postings are calculated (@option{-l}) or displayed (@option{-d}). -@item -For sorting criteria, to yield the sort key. -@item -In the matching criteria used by automated postings. -@end enumerate - -Value expressions support most simple math and logic operators, in -addition to a set of one letter functions and variables. A function's -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:UT>100 balance -@end example - -The effect is that account totals are displayed only if: 1) A -Liabilities 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 transactions are printed. For example, the following -command shows only transactions from the beginning of the current month, -while still calculating the running balance based on all transactions: - -@example -ledger -d "d>[this month]" register checking -@end example - -This advantage to this command's complexity is that it prints the -running total in terms of all transactions in the register. The following, -simpler command is similar, but totals only the displayed -postings: - -@example -ledger -b "this month" register checking -@end example - -@menu -* Variables:: -@end menu - -@node Variables, , Value Expressions, Value Expressions -@section Variables - -Below are the one letter variables available in any value expression. -For the register and print commands, these variables relate to -individual postings, and sometimes the account affected by a -posting. For the balance command, these variables relate to -accounts---often with a subtle difference in meaning. The use of each -variable for both is specified. - -@table @code -@item t -This maps to whatever the user specified with @option{-t}. In a -register report, @option{-t} changes the value column; in a balance -report, it has no meaning by default. If @option{-t} was not -specified, the current report style's value expression is used. - -@item T -This maps to whatever the user specified with @option{-T}. In a -register report, @option{-T} changes the totals column; in a balance -report, this is the value given for each account. If @option{-T} was -not specified, the current report style's value expression is used. - -@item m -This is always the present moment/date. -@end table - -@subsection Posting/account details - -@table @code -@item d -A posting's date, as the number of seconds past the epoch. This -is always ``today'' for an account. - -@item a -The posting's amount; the balance of an account, without -considering children. - -@item b -The cost of a posting; the cost of an account, without its -children. - -@item v -The market value of a posting, or an account without its children. - -@item g -The net gain (market value minus cost basis), for a posting or an -account without its children. It is the same as @samp{v-b}. - -@item l -The depth (``level'') of an account. If an account has one parent, -it's depth is one. - -@item n -The index of a posting, or the count of postings affecting an -account. - -@item X -1 if a posting's transaction has been cleared, 0 otherwise. - -@item R -1 if a posting is not virtual, 0 otherwise. - -@item Z -1 if a posting is not automated, 0 otherwise. -@end table - -@subsection Calculated totals - -@table @code -@item O -The total of all postings seen so far, or the total of an account -and all its children. - -@item N -The total count of postings affecting an account and all its -children. - -@item B -The total cost of all postings seen so far; the total cost of an -account and all its children. - -@item V -The market value of all postings seen so far, or of an account and -all its children. - -@item G -The total net gain (market value minus cost basis), for a series of -postings, or an account and its children. It is the same as -@samp{V-B}. -@end table - -@section Functions - -The available one letter functions are: - -@table @code -@item - -Negates the argument. - -@item U -The absolute (unsigned) value of the argument. - -@item S -Strips the commodity from the argument. - -@item A -The arithmetic mean of the argument; @samp{Ax} is the same as -@samp{x/n}. - -@item P -The present market value of the argument. The syntax @samp{P(x,d)} is -supported, which yields the market value at time @samp{d}. If no date -is given, then the current moment is used. -@end table - -@section Operators - -The binary and ternary operators, in order of precedence, are: - -@enumerate -@item @samp{* /} -@item @samp{+ -} -@item @samp{! < > =} -@item @samp{& | ?:} -@end enumerate - -@section Complex expressions - -More complicated expressions are possible using: - -@table @code -@item NUM -A plain integer represents a commodity-less amount. - -@item @{AMOUNT@} -An amount in braces can be any kind of amount supported by ledger, -with or without a commodity. Use this for decimal values. - -@item /REGEXP/ -@item W/REGEXP/ -A regular expression that matches against an account's full name. If -a posting, this will match against the account affected by the -posting. - -@item //REGEXP/ -@item p/REGEXP/ -A regular expression that matches against a transaction's payee name. - -@item ///REGEXP/ -@item w/REGEXP/ -A regular expression that matches against an account's base name. If -a posting, this will match against the account affected by the -posting. - -@item c/REGEXP/ -A regular expression that matches against the transaction code (the text -that occurs between parentheses before the payee name). - -@item e/REGEXP/ -A regular expression that matches against a posting's note, or -comment field. - -@item (EXPR) -A sub-expression is nested in parenthesis. This can be useful passing -more complicated arguments to functions, or for overriding the natural -precedence order of operators. - -@item [DATE] -Useful specifying a date in plain terms. For example, you could say -@samp{[2004/06/01]}. -@end table - diff --git a/doc/Ledger3.texi b/doc/Ledger3.texi new file mode 100644 index 00000000..b804ee4c --- /dev/null +++ b/doc/Ledger3.texi @@ -0,0 +1,1914 @@ +\input texinfo @c -*-texinfo-*- + +@setfilename ledger3.info +@settitle Ledger: Command-Line Accounting + +@dircategory User Applications +@copying +Copyright (c) 2003-2010, John Wiegley. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +- Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +- Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +- Neither the name of New Artisans LLC nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +@end copying + +@documentencoding UTF-8 + +@iftex +@finalout +@end iftex + +@macro ledgerprog + @sc{ledger} +@end macro + + +@titlepage +@title LEDGER: Command-Line Accounting +@author John Wiegley +@end titlepage + +@direntry +* Ledger: (ledger). Command-Line Accounting +@end direntry + +@contents + +@ifnottex +@node Top, Copying, (dir), (dir) +@top Overview +LEDGER is an accounting tool with the moxie to exist. It provides no +bells or whistles, and returns the user to the days before user +interfaces were even a twinkling in their father's CRT. +@c @insertcopying +@end ifnottex + +@menu +* Copying:: +* Introduction to Ledger:: +* Principles of Accounting:: +* Keeping a Journal:: +* Command-line Syntax:: +* Basic Reporting Commands:: +* Value Expressions:: +* Format Strings:: +* Journal File Format:: +* Extending with Python:: +@end menu + +@node Copying, Introduction to Ledger, Top, Top +@chapter Copying +@insertcopying + +@node Introduction to Ledger, Principles of Accounting, Copying, Top +@chapter Introduction to Ledger + +LEDGER is an accounting tool with the moxie to exist. It provides no +bells or whistles, and returns the user to the days before user +interfaces were even a twinkling in their father's CRT. + +What it does offer is a double-entry accounting journal with all the +flexibility and muscle of its modern day cousins, without any of the +fat. Think of it as the Bran Muffin of accounting tools. + +To use it, you need to start keeping a journal. This is the basis of +all accounting, and if you haven't started yet, now is the time to +learn. The little booklet that comes with your checkbook is a journal, +so we'll describe double-entry accounting in terms of that. + +A checkbook journal records debits (subtractions, or withdrawals) and +credits (additions, or deposits) with reference to a single account: +the checking account. Where the money comes from, and where it goes +to, are described in the payee field, where you write the person or +company's name. The ultimate aim of keeping a checkbook journal is to +know how much money is available to spend. That's really the aim of +all journals. + +What computers add is the ability to walk through these postings, +and tell you things about your spending habits; to let you devise +budgets and get control over your spending; to squirrel away money +into virtual savings account without having to physically move money +around; etc. As you keep your journal, you are recording information +about your life and habits, and sometimes that information can start +telling you things you aren't aware of. Such is the aim of all good +accounting tools. + +The next step up from a checkbook journal, is a journal that keeps track +of all your accounts, not just checking. In such a journal, you record +not only who gets paid---in the case of a debit---but where the money +came from. In a checkbook journal, its assumed that all the money +comes from your checking account. But in a general journal, you write +posting two-lines: the source account and target account. +@emph{There must always be a debit from at least one account for every +credit made to another account}. This is what is meant by +``double-entry'' accounting: the journal must always balance to zero, +with an equal number of debits and credits. + + +For example, let's say you have a checking account and a brokerage +account, and you can write checks from both of them. Rather than keep +two checkbooks, you decide to use one journal for both. In this general +journal you need to record a payment to Pacific Bell for your monthly +phone bill, and a transfer (via check) from your brokerage account to +your checking account. The Pacific Bell bill is $23.00, let's say, and +you want to pay it from your checking account. In the general journal +you need to say where the money came from, in addition to where it's +going to. These transactions might look like this: + +@smallexample +9/29 Pacific Bell $23.00 $23.00 + Checking $-23.00 0 +9/30 Checking $100.00 $100.00 + (123) Brokerage $-100.00 0 +@end smallexample + +The posting must balance to $0: $23 went to Pacific Bell, $23 came from +Checking. The next entry shows check number 123 written against your +brokerage account, transfering money to your checking account. There is +nothing left over to be accounted for, since the money has simply moved +from one account to another in both cases. This is the basis of +double-entry accounting: money never pops in or out of existence; it is +always a posting from one account to another. + +Keeping a general journal is the same as keeping two separate journals: +One for Pacific Bell and one for Checking. In that case, each time a +payment is written into one, you write a corresponding withdrawal into +the other. This makes it easier to write in a ``running balance'', +since you don't have to look back at the last time the account was +referenced---but it also means having a lot of journal books, if you +deal with multiple accounts. + +Here is a good place for an aside on the use of the word `account'. +Most private people consider an account to be something that holds money +at an institution for them. LEDGER uses a more general definition +of the word. An account is anywhere money can go. Other finance +programs use ``categories'', LEDGER uses accounts. So, for +example, if you buy some groceries at Trader Joe's then more groceries +at Whole Foods Markets you might assign the transactions like this +@smallexample +2011/03/15 Trader Joe's + Expenses:Groceries $100.00 + Assets:Checking +2011/03/15 Whole Food Market + Expenses:Groceries $75.00 + Assets:Checking +@end smallexample +In both cases the money goes to the ``Groceries'' account, even though +the payees were different. You can set up your accounts in any way you +choose. + +Enter the beauty of computerized accounting. The purpose of the +LEDGER program is to make general journal accounting simple, by keeping +track of the balances for you. Your only job is to enter the +postings. If a posting does not balance, LEDGER displays an +error and indicates the incorrect posting.@footnote{In some +special cases, it automatically balances this transaction for you.} + +In summary, there are two aspects of LEDGER use: updating the journal +data file, and using the LEDGER tool to view the summarized result of +your transactions. + +And just for the sake of example---as a starting point for those who +want to dive in head-first---here are the journal transactions from above, +formatted as the LEDGER program wishes to see them: + +@smallexample +2004/09/29 Pacific Bell + Expenses:Pacific Bell $23.00 + Assets:Checking +@end smallexample + +The account balances and registers in this file, if saved as +@file{ledger.dat}, could be reported using: + +@example +$ ledger -f ledger.dat balance +$ ledger -f ledger.dat register checking +$ ledger -f ledger.dat register bell +@end example + +An important difference between LEDGER and other finance packages is +that journal will never alter your input file. You can create and edit +that file in any way you prefer, but journal is only for analyzing the +data, not for altering it. + +@section More introduction + +@menu +* Building the Program:: +* Getting Help:: +@end menu + +@node Building the Program, Getting Help, Introduction to Ledger, Introduction to Ledger +@section Building the program + +LEDGER is written in ANSI C++, and should compile on any platform. It +depends on the GNU multiprecision integer library (libgmp), and the +Perl regular expression library (libpcre). It was developed using GNU +make and gcc 3.3, on a PowerBook running OS/X. + +To build and install once you have these libraries on your system, +enter these commands: + +@example +./configure && make install +@end example + +@node Getting Help, , Building the Program, Introduction to Ledger +@section Getting help + +If you need help on how to use LEDGER, or run into problems, you can +join the LEDGER mailing list at the following Web address: + +@example +http://groups.google.com/group/ledger-cli +@end example + +You can also find help at the @samp{#ledger} channel on the IRC server +@samp{irc.freenode.net}. + + +@node Principles of Accounting, Keeping a Journal, Introduction to Ledger, Top +@chapter Principles of Accounting + +@node Keeping a Journal, Command-line Syntax, Principles of Accounting, Top +@chapter Keeping a Journal + +The most important part of accounting is keeping a good journal. If you +have a good journal, tools can be written to work whatever mathematical +tricks you need to better understand your spending patterns. Without a +good journal, no tool, however smart, can help you. + +The LEDGER program aims at making journal transactions as simple as +possible. Since it is a command-line tool, it does not provide a user +interface for keeping a journal. If you like, you may use GnuCash to +maintain your journal, in which case LEDGER will read +GnuCash's data files directly. In that case, read the GnuCash manual +now, and skip to the next chapter. + +If you are not using GnuCash, but a text editor to maintain your +journal, read on. LEDGER has been designed to make data transactions as +simple as possible, by keeping the journal format easy, and also by +automagically determining as much information as possible based on the +nature of your transactions. + +For example, you do not need to tell LEDGER about the accounts you +use. Any time LEDGER sees a posting involving an account it knows +nothing about, it will create it@footnote{This also means if you +misspell an account it will end up getting counted separately from what +you intended. The provided Emacs major mode provides for automatically +filling in account names.}. If you use a commodity that is new to +LEDGER, it will create that commodity, and determine its display +characteristics (placement of the symbol before or after the amount, +display precision, etc) based on how you used the commodity in the +posting. + +@menu +* Most Basic Entry:: +* Commodities:: +* Structuring Your Accounts:: +* Transaction Notes and Tags:: +* File Format:: +* Archiving Previous Years :: +* Ledger Tutorial :: +@end menu + +@node Most Basic Entry, Commodities, Keeping a Journal, Keeping a Journal +@section The Most Basic Entry + +Here is the Pacific Bell example from above, given as a LEDGER +posting, with the additional of a check number: + +@smallexample +9/29 (1023) Pacific Bell + Expenses:Utilities:Phone $23.00 + Assets:Checking $-23.00 +@end smallexample + +As you can see, it is very similar to what would be written on paper, +minus the computed balance totals, and adding in account names that work +better with LEDGER's scheme of things. In fact, since +LEDGER is smart about many things, you don't need to specify the +balanced amount, if it is the same as the first line: + +@smallexample +9/29 (1023) Pacific Bell + Expenses:Utilities:Phone $23.00 + Assets:Checking +@end smallexample + +For this transaction, LEDGER will figure out that $-23.00 must come from +@samp{Assets:Checking} in order to balance the transaction. + +Also note the structure of the account entries. There is an implied +hierarchy established by separating with colons. See +(@pxref{Structuring Your Accounts}) for details and suggestions regarding +your accounts. + + + +@strong{The format is very flexible and it isn't necessary that you +indent and space out things exactly as shown. The only requirements are +that the start of the transaction (the date typically) is at the +beginning of the first line of the transaction, and the accounts are +indented by at least one space. If you omit the leading spaces in the +account lines LEDGER will not count the transaction and will not +give an error. There must be at least two spaces, or a tab, between the +amount and the account. If you do not have adequate separation between +the amount and the account LEDGER will give an error and stop +calculating} + +@node Commodities, Structuring Your Accounts, Most Basic Entry, Keeping a Journal +@section Commodities + +LEDGER is agnostic when it comes to how you value your accounts. +Dollars, Euros, Pounds, Francs, etc. are just ``commodities''. Holdings +in stocks, bonds, mutual funds and other financial instrument can be +label using whatever is convenient for you (stock ticker symbols are +suggested for publicly traded assets).@footnote{you can track ANYTHING, +even time. As long as it cannot be created or destroyed inside your +accounting system.} + +This is fundamentally different than many common accounting packages, +which assume the same currency throughout all of your accounts. This +means if you typically operate in Euros, but travel to the US and has +some expenses, you would have to do the currency conversion BEFORE you +made the entry into your financial system. With ledger this is not +required. In the same journal you can have entries in any or all +commodities you actually hold. You can use the reporting capabilities +to convert all commodities to a single commodity for reporting purposes +without ever changing the underlying entry. + +For example, the following entries reflect transaction made for a +business trip to Europe from the US: + +@smallexample +2011/09/23 Cash in Munich + Assets:Cash 50.00 Euros + Assets:Checking $-66.00 + +2011/09/24 Dinner in Munich + Expenses:Business:Travel 35.00 Euro + Assets:Cash +@end smallexample + +This says that $66.00 came out of checking and turned into 50 Euros. The +implied exchange rate was $1.32. Then 35 Euros was spent on Dinner in Munich. + + +@node Structuring Your Accounts, Transaction Notes and Tags, Commodities, Keeping a Journal +@section Structuring your Accounts + +There really are no requirements for how you do this, but to preserve +your sanity we suggest some very basic structure to your accounting +system. + +At the highest level you have five sorts of accounts: Expenses, Assets, +Income, Liabilities and Equity. Briefly, you can think of these as places money goes, +places money sits, places money comes from and money you owe. + +Starting the structure off this way will make it simpler for you to get +answers to the questions you really need to ask about your finances. + +@node Transaction Notes and Tags, File Format, Structuring Your Accounts, Keeping a Journal +@section Transaction Notes and Tags +LEDGER 3.0 supports entry and transaction ``notes'', which may +contain new metadata and tag markers. Here's an example: + +@smallexample + 2004/05/27 (100) Credit card company + ; This is an entry note! + ; Sample: Value + Liabilities:MasterCard $20.00 + ; This is a transaction note! + ; Sample: Another Value + ; :MyTag: + Assets:Bank:Checking + ; :AnotherTag: +@end smallexample + +An indented paragraph starting with `;' is parsed as a persistent note +for its preceding category. These notes will get printed back to you +with the ``print'' command. They are accessible to value expressions +using the ``note'' variable. + +Further, any occurrence of ``:foo:'' in a note will cause a metadata tag +for "foo" to be registered for that entry. You can then search for +such transactions using: + +@smallexample + ledger reg %foo + ldeger reg tag foo +@end smallexample + +Also, if any word in the note ends (but does not start) with a colon, +the remainder of that line will be taken to be the metadata value for +that tag. That is: + +@smallexample + ; :foo:bar:baz: <-- These are three tags + ; name: value <-- this is a tag with a value +@end smallexample + +Tags with value can be searched for just like tags. In addition, you +can further limit your tag search by looking for only those tags that +have specific values: + +@smallexample + ledger reg %name=value + ledger reg tag name=value +@end smallexample + +The group-by and sort functions also support tags: +@smallexample +ledger --group-by "tag('foo')" bal +@end smallexample +Will produce a balance summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'. + +@smallexample +ledger reg --sort "tag('foo')" %foo +@end smallexample +Produces a register view with the transaction have tag `foo' sorted by the tags value. + +Comments that occur before an entry, or which starts at column +zero, are always ignored and are neither searched nor printed back. + + + +@node File Format, Archiving Previous Years , Transaction Notes and Tags, Keeping a Journal +@section File format + +The ledger file format is quite simple, but also very flexible. It +supports many options, though typically the user can ignore most of +them. They are summarized below. + +The initial character of each line determines what the line means, and +how it should be interpreted. Allowable initial characters are: + +@table @code +@item NUMBER +A line beginning with a number denotes a transaction. It may be followed +by any number of lines, each beginning with whitespace, to denote the +transaction's account postings. The format of the first line is: + +@example +DATE[=EDATE] [*|!] [(CODE)] DESC +@end example + +If @samp{*} appears after the date (with optional effective date), it +indicates the transaction is ``cleared'', which can mean whatever the user +wants it to mean. If @samp{!} appears after the date, it indicates d +the transaction is ``pending''; i.e., tentatively cleared from the user's +point of view, but not yet actually cleared. If a @samp{CODE} appears +in parentheses, it may be used to indicate a check number, or the type +of the posting. Following these is the payee, or a description of +the posting. + +The format of each following posting is: + +@example + ACCOUNT AMOUNT [; NOTE] +@end example + +The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual +postings, or square brackets if it is a virtual postings that +must balance. The @samp{AMOUNT} can be followed by a per-unit +posting cost, by specifying @samp{@@ AMOUNT}, or a complete +posting cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may +specify an actual and/or effective date for the posting by using +the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or +@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}. + +@item = +An automated transaction. A value expression must appear after the equal +sign. + +After this initial line there should be a set of one or more +postings, just as if it were normal transaction. If the amounts of the +postings have no commodity, they will be applied as modifiers to +whichever real posting is matched by the value expression. + +@item ~ +A period transaction. A period expression must appear after the tilde. + +After this initial line there should be a set of one or more +postings, just as if it were normal transaction. + +@item ! +A line beginning with an exclamation mark denotes a command directive. +It must be immediately followed by the command word. The supported +commands are: + +@table @samp +@item !include +Include the stated journal file. + +@item !account +The account name is given is taken to be the parent of all +postings that follow, until @samp{!end} is seen. + +@item !end +Ends an account block. +@end table + +@item ; +A line beginning with a colon indicates a comment, and is +ignored. Comments will not be returned in a ``print'' response. +@item indented ; +If the semi colon is indented and occurs inside a transaction, it is +parsed as a persistent note for its preceding category. These notes or +tags can be used to augment to reporting and filtering capabilities of +LEDGER. +@item Y +If a line begins with a capital Y, it denotes the year used for all +subsequent transactions that give a date without a year. The year should +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 transactions specify a year, however, this command has no effect. + +@item P +Specifies a historical price for a commodity. These are usually found +in a pricing history file (see the @option{-Q} option). The syntax +is: +@example +P DATE SYMBOL PRICE +@end example + +@item N SYMBOL +Indicates that pricing information is to be ignored for a given +symbol, nor will quotes ever be downloaded for that symbol. Useful +with a home currency, such as the dollar ($). It is recommended that +these pricing options be set in the price database file, which +defaults to @file{~/.pricedb}. The syntax for this command is: +@example +N SYMBOL +@end example + +@item D AMOUNT +Specifies the default commodity to use, by specifying an amount in the +expected format. The @command{transaction} command will use this commodity +as the default when none other can be determined. This command may be +used multiple times, to set the default flags for different +commodities; whichever is seen last is used as the default commodity. +For example, to set US dollars as the default commodity, while also +setting the thousands flag and decimal flag for that commodity, use: +@example +D $1,000.00 +@end example + +@item C AMOUNT1 = AMOUNT2 +Specifies a commodity conversion, where the first amount is given to +be equivalent to the second amount. The first amount should use the +decimal precision desired during reporting: +@example +C 1.00 Kb = 1024 bytes +@end example + +@item i, o, b, h +These four 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 + +@node Archiving Previous Years , Ledger Tutorial , File Format, Keeping a Journal +@section Archiving Previous Years + +@node Ledger Tutorial , , Archiving Previous Years , Keeping a Journal +@section Ledger Tutorial + + +@node Command-line Syntax, Basic Reporting Commands, Keeping a Journal, Top +@chapter Command-line Syntax + + +@menu +* Cookbook:: +* Quick Reference:: +* Commands:: +* Options:: +* Period Expressions:: +@end menu + +@node Cookbook, Quick Reference, Command-line Syntax, Command-line Syntax +@section Cookbook + +@subsection Invoking Ledger + +@example +ledger --group-by "tag('trip')" bal +legder reg --sort "tag('foo')" %foo +ledger cleared VWCU NFCU Tithe Misentry +ledger register Joint --uncleared +ledger register NFCUChecking --sort d -d 'd>[2011/04/01]' until 2011/05/25 +@end example +@subsection Ledger Files + +@example += /^Income:Taxable/ + (Liabilities:Tithe Owed) -0.1 += /Noah/ + (Liabilities:Tithe Owed) -0.1 += /Jonah/ + (Liabilities:Tithe Owed) -0.1 += /Tithe/ + (Liabilities:Tithe Owed) -1.0 +@end example + +@node Quick Reference, Commands, Cookbook, Command-line Syntax +@section Quick Reference + +This chapter describes LEDGER's features and serves as a quick +reference. You may wish to survey this to get an overview before diving +in to the @ref{Ledger Tutorial} and more detailed examples that follow. + +LEDGER has a very simple command-line interface, named---enticingly +enough---@command{ledger}. It supports a few reporting commands, and +a large number of options for refining the output from those commands. +The basic syntax of any ledger command is: + +@example +ledger [OPTIONS...] COMMAND [ARGS...] +@end example + +Command options must always precede the command word. After the +command word there may appear any number of arguments. For most +commands, these arguments are regular expressions that cause the +output to relate only to postings matching those regular +expressions. For the @command{transaction} command, the arguments have a +special meaning, described below. + +The regular expressions arguments always match the account name that a +posting refers to. To match on the payee of the transaction instead, +precede the regular expression with @samp{--}. For example, the +following balance command reports account totals for rent, food and +movies, but only those whose payee matches Freddie: + +@example +ledger bal rent food movies -- freddie +@end example + +There are many, many command options available with the +@command{ledger} command, and it takes a while to master them. +However, none of them are required to use the basic reporting +commands. + + +@node Commands, Options, Quick Reference, Command-line Syntax +@section Commands + +@subsection balance + +The @command{balance} command reports the current balance of all +accounts. It accepts a list of optional regexps, which confine the +balance report to the matching accounts. If an account contains +multiple types of commodities, each commodity's total is reported +separately. + +@subsection register + +The @command{register} command displays all the postings occurring +in a single account, line by line. The account regexp must be +specified as the only argument to this command. If any regexps occur +after the required account name, the register will contain only those +postings that match. Very useful for hunting down a particular +posting. + +The output from @command{register} is very close to what a typical +checkbook, or single-account ledger, would look like. It also shows a +running balance. The final running balance of any register should +always be the same as the current balance of that account. + +If you have Gnuplot installed, you may plot the amount or running +total of any register by using the script @file{report}, which is +included in the LEDGER distribution. The only requirement is that you +add either @option{-j} or @option{-J} to your register command, in +order to plot either the amount or total column, respectively. + +@subsection print + +The @command{print} command prints out ledger transactions in a textual +format that can be parsed by LEDGER. They will be properly formatted, +and output in the most economic form possible. The ``print'' command +also takes a list of optional regexps, which will cause only those +postings which match in some way to be printed. + +The @command{print} command can be a handy way to clean up a ledger +file whose formatting has gotten out of hand. + +@subsection output + +The @command{output} command is very similar to the @command{print} +command, except that it attempts to replicate the specified ledger +file exactly. The format of the command is: + +@example +ledger -f FILENAME output FILENAME +@end example + +Where @file{FILENAME} is the name of the ledger file to output. The +reason for specifying this command is that only transactions contained +within that file will be output, and not an included transactions (as can +happen with the @command{print} command). + +@subsection xml + +The @command{xml} command outputs results similar to what +@command{print} and @command{register} display, but as an XML form. +This data can then be read in and processed. Use the +@option{--totals} option to include the running total with each +posting. + +@subsection emacs + +The @command{emacs} command outputs results in a form that can be read +directly by Emacs Lisp. The format of the sexp is: + +@example +((BEG-POS CLEARED DATE CODE PAYEE + (ACCOUNT AMOUNT)...) ; list of postings + ...) ; list of transactions +@end example + +@subsection equity + +The @command{equity} command prints out accounts balances as if they +were transactions. This makes it easy to establish the starting balances +for an account, such as when @ref{Archiving Previous Years}. + +@subsection prices + +The @command{prices} command displays the price history for matching +commodities. The @option{-A} flag is useful with this report, to +display the running average price, or @option{-D} to show each price's +deviation from that average. + +There is also a @command{pricesdb} command which outputs the same +information as @command{prices}, but does in a format that can be +parsed by LEDGER. + +@subsection xact + +The @command{xact} commands simplifies the creation of new transactions. +It works on the principle that 80% of all postings are variants of +earlier postings. Here's how it works: + +Say you currently have this posting in your ledger file: + +@smallexample +2004/03/15 * Viva Italiano + Expenses:Food $12.45 + Expenses:Tips $2.55 + Liabilities:MasterCard $-15.00 +@end smallexample + +Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva +Italiano} again. The exact amounts are different, but the overall +form is the same. With the @command{xact} command you can type: + +@example +ledger xact 2004/4/9 viva food 11 tips 2.50 +@end example + +This produces the following output: + +@smallexample +2004/04/09 Viva Italiano + Expenses:Food $11.00 + Expenses:Tips $2.50 + Liabilities:MasterCard $-13.50 +@end smallexample + +It works by finding a past posting matching the regular expression +@samp{viva}, and assuming that any accounts or amounts specified will +be similar to that earlier posting. If LEDGER does not succeed in +generating a new transaction, an error is printed and the exit code is set +to @samp{1}. + +There is a shell script in the distribution's @file{scripts} directory +called @file{xact}, which simplifies the task of adding a new transaction +to your ledger. It launches @command{vi} to confirm that the transaction +looks appropriate. + +Here are a few more examples of the @command{xact} command, assuming +the above journal transaction: + +@example +ledger xact 4/9 viva 11.50 +ledger xact 4/9 viva 11.50 checking # (from `checking') +ledger xact 4/9 viva food 11.50 tips 8 +ledger xact 4/9 viva food 11.50 tips 8 cash +ledger xact 4/9 viva food $11.50 tips $8 cash +ledger xact 4/9 viva dining "DM 11.50" +@end example + +@node Options, Period Expressions, Commands, Command-line Syntax +@section Options + +With all of the reports, command-line options are useful to modify the +output generated. These command-line options always occur before the +command word. This is done to distinguish options from exclusive +regular expressions, which also begin with a dash. The basic form for +most commands is: + +@example +ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] +@end example + +The @var{OPTIONS} and @var{REGEXPS} expressions are both optional. +You could just use @samp{ledger balance}, without any options---which +prints a summary of all accounts. But for more specific reporting, or +to change the appearance of the output, options are needed. + +@subsection Basic options + +These are the most basic command options. Most likely, the user will +want to set them using environment variables (see @ref{Options}), +instead of using actual command-line options: + +@option{--help} (@option{-h}) prints a summary of all the options, and +what they are used for. This can be a handy way to remember which +options do what. This help screen is also printed if ledger is run +without a command. + +@option{--version} (@option{-v}) prints the current version of ledger +and exits. This is useful for sending bug reports, to let the author +know which version of ledger you are using. + +@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. +This command may be used multiple times. +Typically, the environment variable +@env{LEDGER_FILE} is set, rather than using this command-line option. + +@option{--output FILE} (@option{-o FILE}) redirects output from any +command to @var{FILE}. By default, all output goes to standard +output. + +@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by +ledger before any other ledger file. This file may not contain any +postings, but it may contain option settings. To specify options +in the init file, use the same syntax as the command-line, but put each +option on it's own line. Here's an example init file: + +@smallexample +--price-db ~/finance/.pricedb +--cache /tmp/ledger-cache + +; ~/.ledgerrc ends here +@end smallexample + +Option settings on the command-line or in the environment always take +precedence over settings in the init file. + +@option{--cache FILE} identifies FILE as the default binary cache +file. That is, if the ledger files to be read are specified using the +environment variable @env{LEDGER_FILE}, then whenever a command is +finished a binary copy will be written to the specified cache, to +speed up the loading time of subsequent queries. This filename can +also be given using the environment variable @env{LEDGER_CACHE}, or by +putting the option into your init file. The @option{--no-cache} +option causes LEDGER to always ignore the binary cache. + +@option{--account NAME} (@option{-a NAME}) specifies the default +account which QIF file postings are assumed to relate to. + +@subsection Report filtering + +These options change which postings affect the outcome of a +report, in ways other than just using regular expressions: + +@option{--current}(@option{-c}) displays only transactions occurring on or +before the current date. + +@option{--begin DATE} (@option{-b DATE}) constrains the report to +transactions on or after @var{DATE}. Only transactions after that date will be +calculated, which means that the running total in the balance report +will always start at zero with the first matching transaction. (Note: This +is different from using @option{--display} to constrain what is +displayed). + +@option{--end DATE} (@option{-e DATE}) constrains the report so that +transactions on or after @var{DATE} are not considered. The ending date +is inclusive. + +@option{--period STR} (@option{-p STR}) sets the reporting period +to @var{STR}. This will subtotal all matching transactions within each +period separately, making it easy to see weekly, monthly, quarterly, +etc., posting totals. A period string can even specify the +beginning and end of the report range, using simple terms like ``last +june'' or ``next month''. For more using period expressions, see +@ref{Period Expressions}. + +@option{--period-sort EXPR} sorts the postings within each +reporting period using the value expression @var{EXPR}. This is most +often useful when reporting monthly expenses, in order to view the +highest expense categories at the top of each month: + +@example +ledger -M --period-sort -At reg ^Expenses +@end example + +@option{--cleared} (@option{-C}) displays only postings whose transaction +has been marked ``cleared'' (by placing an asterix to the right of the +date). + +@option{--uncleared} (@option{-U}) displays only postings whose +transaction has not been marked ``cleared'' (i.e., if there is no asterix to +the right of the date). + +@option{--real} (@option{-R}) displays only real postings, not +virtual. (A virtual posting is indicated by surrounding the +account name with parentheses or brackets; see the section on using +virtual postings for more information). + +@option{--actual} (@option{-L}) displays only actual postings, and +not those created due to automated postings. + +@option{--related} (@option{-r}) displays postings that are +related to whichever postings would otherwise have matched the +filtering criteria. In the register report, this shows where money +went to, or the account it came from. In the balance report, it shows +all the accounts affected by transactions having a related posting. +For example, if a file had this transaction: + +@smallexample +2004/03/20 Safeway + Expenses:Food $65.00 + Expenses:Cash $20.00 + Assets:Checking $-85.00 +@end smallexample + +And the register command was: + +@example +ledger -r register food +@end example + +The following would be output, showing the postings related to the +posting that matched: + +@smallexample +2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 + Assets:Checking $85.00 $65.00 +@end smallexample + +@option{--budget} is useful for displaying how close your postings +meet your budget. @option{--add-budget} also shows unbudgeted +postings, while @option{--unbudgeted} shows only those. +@option{--forecast} is a related option that projects your budget into +the future, showing how it will affect future balances. +@xref{Budgeting and Forecasting}. + +@option{--limit EXPR} (@option{-l EXPR}) limits which postings +take part in the calculations of a report. + +@option{--amount EXPR} (@option{-t EXPR}) changes the value expression +used to calculate the ``value'' column in the @command{register} +report, the amount used to calculate account totals in the +@command{balance} report, and the values printed in the +@command{equity} report. @xref{Value Expressions}. + +@option{--total EXPR} (@option{-T EXPR}) sets the value expression +used for the ``totals'' column in the @command{register} and +@command{balance} reports. + +@subsection Output customization + +These options affect only the output, but not which postings are +used to create it: + +@option{--collapse} (@option{-n}) causes transactions in a +@command{register} report with multiple postings to be collapsed +into a single, subtotaled transaction. + +@option{--subtotal} (@option{-s}) causes all transactions in a +@command{register} report to be collapsed into a single, subtotaled +transaction. + +@option{--by-payee} (@option{-P}) reports subtotals by payee. + +@option{--comm-as-payee} (@option{-x}) changes the payee of every +posting to be the commodity used in that posting. This can be +useful when combined with other options, such as @option{-s}. + +@option{--empty} (@option{-E}) includes even empty accounts in the +@command{balance} report. + +@option{--weekly} (@option{-W}) reports posting totals by the +week. The week begins on whichever day of the week begins the month +containing that posting. To set a specific begin date, use a +period string, such as @samp{weekly from DATE}. @option{--monthly} +(@option{-M}) reports posting totals by month; @option{--yearly} +(@option{-Y}) reports posting totals by year. For more complex +period, using the @option{--period} option described above. + +@option{--dow} reports postings totals for each day of the week. +This is an easy way to see if weekend spending is more than on +weekdays. + +@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing +the values determined using the value expression @var{EXPR}. For +example, using @option{-S -UT} in the balance report will sort account +balances from greatest to least, using the absolute value of the +total. For more on how to use value expressions, see @ref{Value +Expressions}. + +@option{--wide} (@option{-w}) causes the default @command{register} +report to assume 132 columns instead of 80. + +@option{--head} causes only the first N transactions to be printed. This +is different from using the command-line utility @command{head}, which +would limit to the first N postings. @option{--tail} outputs only +the last N transactions. Both options may be used simultaneously. If a +negative amount is given, it will invert the meaning of the flag +(instead of the first five transactions being printed, for example, it +would print all but the first five). + +@option{--pager} tells LEDGER to pass its output to the given pager +program---very useful when the output is especially long. This +behavior can be made the default by setting the @env{LEDGER_PAGER} +environment variable. + +@option{--average} (@option{-A}) reports the average posting +value. + +@option{--deviation} (@option{-D}) reports each posting's +deviation from the average. It is only meaningful in the +@command{register} and @command{prices} reports. + +@option{--percentage} (@option{-%}) shows account subtotals in the +@command{balance} report as percentages of the parent account. + +@option{--totals} include running total information in the +@command{xml} report. + +@option{--amount-data} (@option{-j}) changes the @command{register} +report so that it outputs nothing but the date and the value column, +and the latter without commodities. This is only meaningful if the +report uses a single commodity. This data can then be fed to other +programs, which could plot the date, analyze it, etc. + +@option{--total-data} (@option{-J}) changes the @command{register} +report so that it outputs nothing but the date and totals column, +without commodities. + +@option{--display EXPR} (@option{-d EXPR}) limits which postings +or accounts or actually displayed in a report. They might still be +calculated, and be part of the running total of a register report, for +example, but they will not be displayed. This is useful for seeing +last month's checking postings, against a running balance which +includes all posting values: + +@example +ledger -d "d>=[last month]" reg checking +@end example + +The output from this command is very different from the following, +whose running total includes only postings from the last month +onward: + +@example +ledger -p "last month" reg checking +@end example + +Which is more useful depends on what you're looking to know: the total +amount for the reporting range (@option{-p}), or simply a display +restricted to the reporting range (using @option{-d}). + +@option{--date-format STR} (@option{-y STR}) changes the basic date +format used by reports. The default uses a date like 2004/08/01, +which represents the default date format of @samp{%Y/%m/%d}. To +change the way dates are printed in general, the easiest way is to put +@option{--date-format FORMAT} in the LEDGER initialization file +@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). + +@option{--format STR} (@option{-F STR}) sets the reporting format for +whatever report ledger is about to make. @xref{Format Strings}. +There are also specific format commands for each report type: + +@itemize +@item @option{--balance-format STR} +@item @option{--register-format STR} +@item @option{--print-format STR} +@item @option{--plot-amount-format STR} (-j @command{register}) +@item @option{--plot-total-format STR} (-J @command{register}) +@item @option{--equity-format STR} +@item @option{--prices-format STR} +@item @option{--wide-register-format STR} (-w @command{register}) +@end itemize + +@subsection Commodity reporting + +These options affect how commodity values are displayed: + +@option{--price-db FILE} sets the file that is used for recording +downloaded commodity prices. It is always read on startup, to +determine historical prices. Other settings can be placed in this +file manually, to prevent downloading quotes for a specific, for +example. This is done by adding a line like the following: + +@example +; Don't download quotes for the dollar, or timelog values +N $ +N h +@end example + +@option{--price-exp MINS} (@option{-L MINS}) sets the expected +freshness of price quotes, in minutes. That is, if the last known +quote for any commodity is older than this value---and if +@option{--download} is being used---then the Internet will be +consulted again for a newer price. Otherwise, the old price is still +considered to be fresh enough. + +@option{--download} (@option{-Q}) causes quotes to be automagically +downloaded, as needed, by running a script named @command{getquote} +and expecting that script to return a value understood by ledger. A +sample implementation of a @command{getquote} script, implemented in +Perl, is provided in the distribution. Downloaded quote price are +then appended to the price database, usually specified using the +environment variable @env{LEDGER_PRICE_DB}. + +There are several different ways that ledger can report the totals it +displays. The most flexible way to adjust them is by using value +expressions, and the @option{-t} and @option{-T} options. However, +there are also several ``default'' reports, which will satisfy most +users basic reporting needs: + +@table @code +@item -O, --quantity +Reports commodity totals (this is the default) + +@item -B, --basis +Reports the cost basis for all postings. + +@item -V, --market +Reports the last known market value for all commodities. + +@item -G --gain +Reports the net gain/loss for all commodities in the report that have +a price history. +@end table + +@subsection Environment variables + +Every option to ledger may be set using an environment variable. If +an option has a long name such @option{--this-option}, setting the +environment variable @env{LEDGER_THIS_OPTION} will have the same +affect as specifying that option on the command-line. Options on the +command-line always take precedence over environment variable +settings, however. + +Note that you may also permanently specify option values by placing +option settings in the file @file{~/.ledgerrc}, for example: + +@example +--cache /tmp/.mycache +--pager /bin/cat + +@end example + +@node Period Expressions, , Options, Command-line Syntax +@section Period Expressions + +A period expression indicates a span of time, or a reporting interval, +or both. The full syntax is: + +@example +[INTERVAL] [BEGIN] [END] +@end example + +The optional @var{INTERVAL} part may be any one of: + +@example +every day +every week +every monthly +every quarter +every year +every N days # N is any integer +every N weeks +every N months +every N quarters +every N years +daily +weekly +biweekly +monthly +bimonthly +quarterly +yearly +@end example + +After the interval, a begin time, end time, both or neither may be +specified. As for the begin time, it can be either of: + +@example +from +since +@end example + +The end time can be either of: + +@example +to +until +@end example + +Where @var{SPEC} can be any of: + +@example +2004 +2004/10 +2004/10/1 +10/1 +october +oct +this week # or day, month, quarter, year +next week +last week +@end example + +The beginning and ending can be given at the same time, if it spans a +single period. In that case, just use @var{SPEC} by itself. In that +case, the period @samp{oct}, for example, will cover all the days in +october. The possible forms are: + +@example + +in +@end example + +Here are a few examples of period expressions: + +@example +monthly +monthly in 2004 +weekly from oct +weekly from last month +from sep to oct +from 10/1 to 10/5 +monthly until 2005 +from apr +until nov +last oct +weekly last august +@end example + + +@node Basic Reporting Commands, Value Expressions, Command-line Syntax, Top +@chapter Basic Reporting Commands + +@menu +* Budgeting and Forecasting:: +@end menu + +@node Budgeting and Forecasting, , Basic Reporting Commands, Basic Reporting Commands +@section Budgeting and Forecasting + + +@node Value Expressions, Format Strings, Basic Reporting Commands, Top +@chapter Value Expressions + +Value expressions are an expression language used by LEDGER to +calculate values used by the program for many different purposes: + +@enumerate +@item +The values displayed in reports +@item +For predicates (where truth is anything non-zero), to determine which +postings are calculated (@option{-l}) or displayed (@option{-d}). +@item +For sorting criteria, to yield the sort key. +@item +In the matching criteria used by automated postings. +@end enumerate + +Value expressions support most simple math and logic operators, in +addition to a set of one letter functions and variables. A function's +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:UT>100 balance +@end example + +The effect is that account totals are displayed only if: 1) A +Liabilities 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 transactions are printed. For example, the following +command shows only transactions from the beginning of the current month, +while still calculating the running balance based on all transactions: + +@example +ledger -d "d>[this month]" register checking +@end example + +This advantage to this command's complexity is that it prints the +running total in terms of all transactions in the register. The following, +simpler command is similar, but totals only the displayed +postings: + +@example +ledger -b "this month" register checking +@end example + +@menu +* Variables:: +@end menu + +@node Variables, , Value Expressions, Value Expressions +@section Variables + +Below are the one letter variables available in any value expression. +For the register and print commands, these variables relate to +individual postings, and sometimes the account affected by a +posting. For the balance command, these variables relate to +accounts---often with a subtle difference in meaning. The use of each +variable for both is specified. + +@table @code +@item t +This maps to whatever the user specified with @option{-t}. In a +register report, @option{-t} changes the value column; in a balance +report, it has no meaning by default. If @option{-t} was not +specified, the current report style's value expression is used. + +@item T +This maps to whatever the user specified with @option{-T}. In a +register report, @option{-T} changes the totals column; in a balance +report, this is the value given for each account. If @option{-T} was +not specified, the current report style's value expression is used. + +@item m +This is always the present moment/date. +@end table + +@subsection Posting/account details + +@table @code +@item d +A posting's date, as the number of seconds past the epoch. This +is always ``today'' for an account. + +@item a +The posting's amount; the balance of an account, without +considering children. + +@item b +The cost of a posting; the cost of an account, without its +children. + +@item v +The market value of a posting, or an account without its children. + +@item g +The net gain (market value minus cost basis), for a posting or an +account without its children. It is the same as @samp{v-b}. + +@item l +The depth (``level'') of an account. If an account has one parent, +it's depth is one. + +@item n +The index of a posting, or the count of postings affecting an +account. + +@item X +1 if a posting's transaction has been cleared, 0 otherwise. + +@item R +1 if a posting is not virtual, 0 otherwise. + +@item Z +1 if a posting is not automated, 0 otherwise. +@end table + +@subsection Calculated totals + +@table @code +@item O +The total of all postings seen so far, or the total of an account +and all its children. + +@item N +The total count of postings affecting an account and all its +children. + +@item B +The total cost of all postings seen so far; the total cost of an +account and all its children. + +@item V +The market value of all postings seen so far, or of an account and +all its children. + +@item G +The total net gain (market value minus cost basis), for a series of +postings, or an account and its children. It is the same as +@samp{V-B}. +@end table + +@section Functions + +The available one letter functions are: + +@table @code +@item - +Negates the argument. + +@item U +The absolute (unsigned) value of the argument. + +@item S +Strips the commodity from the argument. + +@item A +The arithmetic mean of the argument; @samp{Ax} is the same as +@samp{x/n}. + +@item P +The present market value of the argument. The syntax @samp{P(x,d)} is +supported, which yields the market value at time @samp{d}. If no date +is given, then the current moment is used. +@end table + +@section Operators + +The binary and ternary operators, in order of precedence, are: + +@enumerate +@item @samp{* /} +@item @samp{+ -} +@item @samp{! < > =} +@item @samp{& | ?:} +@end enumerate + +@section Complex expressions + +More complicated expressions are possible using: + +@table @code +@item NUM +A plain integer represents a commodity-less amount. + +@item @{AMOUNT@} +An amount in braces can be any kind of amount supported by ledger, +with or without a commodity. Use this for decimal values. + +@item /REGEXP/ +@item W/REGEXP/ +A regular expression that matches against an account's full name. If +a posting, this will match against the account affected by the +posting. + +@item //REGEXP/ +@item p/REGEXP/ +A regular expression that matches against a transaction's payee name. + +@item ///REGEXP/ +@item w/REGEXP/ +A regular expression that matches against an account's base name. If +a posting, this will match against the account affected by the +posting. + +@item c/REGEXP/ +A regular expression that matches against the transaction code (the text +that occurs between parentheses before the payee name). + +@item e/REGEXP/ +A regular expression that matches against a posting's note, or +comment field. + +@item (EXPR) +A sub-expression is nested in parenthesis. This can be useful passing +more complicated arguments to functions, or for overriding the natural +precedence order of operators. + +@item [DATE] +Useful specifying a date in plain terms. For example, you could say +@samp{[2004/06/01]}. +@end table + + +@node Format Strings, Journal File Format, Value Expressions, Top +@chapter Format Strings + +Format strings may be used to change the output format of reports. +They are specified by passing a formatting string to the +@option{--format} (@option{-F}) option. Within that string, +constructs are allowed which make it possible to display the various +parts of an account or posting in custom ways. + +Within a format strings, a substitution is specified using a percent +character (@samp{%}). The basic format of all substitutions is: + +@example +%[-][MIN WIDTH][.MAX WIDTH]EXPR +@end example + +If the optional minus sign (@samp{-}) follows the percent character, +whatever is substituted will be left justified. The default is right +justified. If a minimum width is given next, the substituted text +will be at least that wide, perhaps wider. If a period and a maximum +width is given, the substituted text will never be wider than this, +and will be truncated to fit. Here are some examples: + +@example +%-P a transaction's payee, left justified +%20P The same, right justified, at least 20 chars wide +%.20P The same, no more than 20 chars wide +%-.20P Left justified, maximum twenty chars wide +@end example + +The expression following the format constraints can be a single +letter, or an expression enclosed in parentheses or brackets. The +allowable expressions are: + +@table @code +@item % +Inserts a percent sign. + +@item t +Inserts the results of the value expression specified by @option{-t}. +If @option{-t} was not specified, the current report style's value +expression is used. + +@item T +Inserts the results of the value expression specified by @option{-T}. +If @option{-T} was not specified, the current report style's value +expression is used. + +@item | +Inserts a single space. This is useful if a width is specified, for +inserting a certain number of spaces. + +@item _ +Inserts a space for each level of an account's depth. That is, if an +account has two parents, this construct will insert two spaces. If a +minimum width is specified, that much space is inserted for each level +of depth. Thus @samp{%5_}, for an account with four parents, will +insert twenty spaces. + +@item (EXPR) +Inserts the amount resulting from the value expression given in +parentheses. To insert five times the total value of an account, for +example, one could say @samp{%12(5*O)}. Note: It's important to put +the five first in that expression, so that the commodity doesn't get +stripped from the total. + +@item [DATEFMT] +Inserts the result of formatting a posting's date with a date +format string, exactly like those supported by @code{strftime}. For +example: @samp{%[%Y/%m/%d %H:%M:%S]}. + +@item S +Insert the pathname of the file from which the transaction's data was read. + +@item B +Inserts the beginning character position of that transaction within the file. + +@item b +Inserts the beginning line of that transaction within the file. + +@item E +Inserts the ending character position of that transaction within the file. + +@item e +Inserts the ending line of that transaction within the file. + +@item D +By default, this is the same as @samp{%[%Y/%m%/d]}. The date format +used can be changed at any time with the @option{-y} flag, however. +Using @samp{%D} gives the user more control over the way dates are +output. + +@item d +This is the same as the @samp{%D} option, unless the transaction has an +effective date, in which case it prints +@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}. + +@item X +If a posting has been cleared, this inserts @samp{*} followed by a +space; otherwise nothing is inserted. + +@item Y +This is the same as @samp{%X}, except that it only displays a state +character if all of the member postings have the same state. + +@item C +Inserts the checking number for a transaction, in parentheses, followed by +a space; if none was specified, nothing is inserted. + +@item P +Inserts the payee related to a posting. + +@item a +Inserts the optimal short name for an account. This is normally used +in balance reports. It prints a parent account's name if that name +has not been printed yet, otherwise it just prints the account's name. + +@item A +Inserts the full name of an account. + +@item W +This is the same as @samp{%A}, except that it first displays the +posting's state @emph{if the transaction's posting states are not +all the same}, followed by the full account name. This is offered as +a printing optimization, so that combined with @samp{%Y}, only the +minimum amount of state detail is printed. + +@item o +Inserts the ``optimized'' form of a posting's amount. This is +used by the print report. In some cases, this inserts nothing; in +others, it inserts the posting amount and its cost. It's use is +not recommend unless you are modifying the print report. + +@item n +Inserts the note associated with a posting, preceded by two spaces +and a semi-colon, if it exists. Thus, no none becomes an empty +string, while the note @samp{foo} is substituted as @samp{ ; foo}. + +@item N +Inserts the note associated with a posting, if one exists. + +@item / +The @samp{%/} construct is special. It separates a format string +between what is printed for the first posting of a transaction, and +what is printed for all subsequent postings. If not used, the +same format string is used for all postings. +@end table + + +@node Journal File Format, Extending with Python, Format Strings, Top +@chapter LEDGER Journal File Format + +This chapter offers a complete description of the journal data format, +suitable for implementors in other languages to follow. For users, +the chapter on keeping a journal is less extensive, but more typical +of common usage (@pxref{Keeping a Journal}). + +Data is collected in the form of @dfn{transactions} which occur in one +or more @dfn{journal files}. Each transaction, in turn, is made up of +one or more @dfn{postings}, which describe how @dfn{amounts} flow from +one @dfn{account} to another. Here is an example of the simplest of +journal files: + +@example +2010/05/31 Just an example + Expenses:Some:Account $100.00 + Income:Another:Account +@end example + +In this example, there is a transaction date, a payee, or description +of the transaction, and two postings. The postings show movement of +one hundred dollars from an account within the Income hierarchy, to +the specified expense account. The name and meaning of these accounts +in arbitrary, with no preferences implied, although you will find it +useful to follow standard accounting practice (@pxref{Principles of +Accounting}). + +Since an amount is missing from the second posting, it is assumed to +be the inverse of the first. This guarantee the cardinal rule of +double-entry accounting: the sum of every transaction must balance to +zero, or it is in error. Whenever Ledger encounters a @dfn{null +posting} in a transaction, it uses it to balance the remainder. + +It is also typical---though not enforced---to think of the first +posting as the destination, and the final as the source. Thus, the +amount of the first posting is typically positive. Consider: + +@example +2010/05/31 An income transaction + Assets:Checking $1,000.00 + Income:Salary + +2010/05/31 An expense transaction + Expenses:Dining $100.00 + Assets:Checking +@end example + +@emph{Note:} It is important to note that there must be at least two spaces between +the end of the post and the beginning of the amount (including and +commdity designator). + +@section Specifying amounts + +The heart of a journal is the amounts it records, and this fact is +reflected in the diversity of amount expressions allowed. All of them +are covered here, though it must be said that sometimes, there are +multiple ways to achieve a desired result. + +@subsection Integer amounts + +In the simplest form, bare decimal numbers are accepted: + +@example +2010/05/31 An income transaction + Assets:Checking 1000.00 + Income:Salary +@end example + +Such amounts may only use an optional period for a decimal point. +These are referred to as @dfn{integer amounts} or @dfn{uncommoditized +amounts}. In most ways they are similar to @dfn{commoditized +amounts}, but for one signficant difference: They always display in +reports with @dfn{full precision}. More on this in a moment. For +now, a word must be said about how Ledger stores numbers. + +Every number parsed by Ledger is stored internally as an +infinite-precision rational value. Floating-point math is never used, +as it cannot be trusted to maintain precision of values. So, in the +case of @samp{1000.00} above, the internal value is @samp{100000/100}. + +While rational numbers are great at not losing precision, the question +arises: How should they be displayed? A number like @samp{100000/100} +is no problem, since it represents a clean decimal fraction. But what +about when the number @samp{1/1} is divided by three? How should one +print @samp{1/3}, an infinitely repeating decimal? + +Ledger gets around this problem by rendering rationals into decimal at +the last possible moment, and only for display. As such, some +rounding must, at times, occur. If this rounding would affect the +calculation of a running total, special accommodation postings are +generated to make you aware it has happened. In practice, it happens +rarely, but even then it does not reflect adjustment of the +@emph{internal amount}, only the displayed amount. + +What has still not been answered is how Ledger rounds values. Should +@samp{1/3} be printed as @samp{0.33} or @samp{0.33333}? For +commoditized amounts, the number of decimal places is decided by +observing how each commodity is used; but in the case of integer +amounts, an arbitrary factor must be chosen. Initially, this factor +is six. Thus, @samp{1/3} is printed back as @samp{0.333333}. +Further, this rounding factor becomes associated with each particular +value, and is carried through mathematical operations. For example, +if that particular number were multiplied by itself, the decimal +precision of the result would be twelve. Addition and subtraction do +not affect precision. + +Since each integer amount retains its own display precision, this is +called @dfn{full precision}, as opposed to commoditized amounts, which +always look to their commodity to know what precision they should +round to, and so use @dfn{commodity precision}. + +@subsection Commoditized amounts + +A @dfn{commoditized amount} is an integer amount which has an +associated commodity. This commodity can appear before or after the +amount, and may or may not be separated from it by a space. Most +characters are allowed in a commodity name, except for the following: + +@itemize +@item Any kind of whitespace +@item Numerical digits +@item Punctuation: @samp{.,;:?!} +@item Mathematical and logical operators: @samp{-+*/^&|=} +@item Bracketing characters: @samp{<>[]()}@{@} +@item The at symbol: @samp{@@} +@end itemize + +And yet, any of these may appear in a commodity name if it is +surrounded by double quotes, for example: + +@example +100 "EUN+133" +@end example + +If a @dfn{quoted commodity} is found, it is displayed in quotes as +well, to avoid any confusion as to which part is the amount, and which +part is the commodity. + +Another feature of commoditized amounts is that they are reported back +in the same form as parsed. If you specify dollar amounts using +@samp{$100}, they will print the same; likewise with @samp{100 $} or +@samp{$100.000}. You may even use decimal commas, such as +@samp{$100,00}, or thousand-marks, as in @samp{$10,000.00}. + +These display characteristics become associated with the commodity, +with the result being that all amounts of the same commodity are +reported consistently. Where this is most noticeable is the +@dfn{display precision}, which is determined by the most precise value +seen for a given commodity. In most cases. + +Ledger makes a distinction by @dfn{observed amounts} and unobserved +amounts. An observed amount is critiqued by Ledger to determine how +amounts using that commodity should be displayed; unobserved amounts +are significant in their value only---no matter how they are +specified, it does not change how other amounts in that commodity will +be displayed. + +An example of this is found in cost expressions, covered next. + +@section Posting costs + +You have seen how to specify either a commoditized or an integer +amount for a posting. But what if the amount you paid for something +was in one commodity, and the amount received was another? There are +two main ways to express this: + +@example +2010/05/31 Farmer's Market + Assets:My Larder 100 apples + Assets:Checking $20.00 +@end example + +In this example, you have paid twenty dollars for one hundred apples. +The cost to you is twenty cents per apple, and Ledger calculates this +implied cost for you. You can also make the cost explicit using a +@dfn{cost amount}: + +@example +2010/05/31 Farmer's Market + Assets:My Larder 100 apples @@ $0.200000 + Assets:Checking +@end example + +Here the @dfn{per-unit cost} is given explicitly in the form of a cost +amount; and since cost amount are @emph{unobserved}, the use of six +decimal places has no effect on how dollar amounts are displayed in +the final report. You can also specify the @dfn{total cost}: + +@example +2010/05/31 Farmer's Market + Assets:My Larder 100 apples @@@@ $20 + Assets:Checking +@end example + +These three forms have identical meaning. In most cases the first is +preferred, but the second two are necessary when more than two +postings are involved: + +@example +2010/05/31 Farmer's Market + Assets:My Larder 100 apples @@ $0.200000 + Assets:My Larder 100 pineapples @@ $0.33 + Assets:My Larder 100 "crab apples" @@ $0.04 + Assets:Checking +@end example + +Here the implied cost is @samp{$57.00}, which is entered into the null +posting automatically so that the transaction balances. + +@subsection Primary commodities + +In every transaction involving more than one commodity, there is +always one which is the @dfn{primary commodity}. This commodity +should be thought of as the exchange commodity, or the commodity used +to buy and sells units of the other commodity. In the fruit examples +above, dollars are the primary commodity. This is decided by Ledger +on the placement of the commodity in the transaction: + +@example +2010/05/31 Sample Transaction + Expenses 100 secondary + Assets 50 primary + +2010/05/31 Sample Transaction + Expenses 100 secondary @@ 0.5 primary + Assets + +2010/05/31 Sample Transaction + Expenses 100 secondary @@@@ 50 primary + Assets +@end example + +The only case where knowledge of primary versus secondary comes into +play is in reports that use the @option{-V} or @option{-B} options. +With these, only primary commodities are shown. + +If a transaction uses only one commodity, this commodity is also +considered a primary. In fact, when Ledger goes about ensures that +all transactions balance to zero, it only ever asks this of primary +commodities. + +@node Extending with Python, , Journal File Format, Top +@chapter Extending with Python + +@bye From cddb9c112d85f07f9bf4dbb06da7ed1ffeacce95 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 28 Sep 2011 14:30:29 -0700 Subject: [PATCH 07/28] Add virtual, automatic and multiple account transactions --- doc/Ledger3.texi | 379 +++++++++++++++++++++++++++++++++++++++-------- doc/sample.dat | 54 ------- 2 files changed, 320 insertions(+), 113 deletions(-) delete mode 100644 doc/sample.dat diff --git a/doc/Ledger3.texi b/doc/Ledger3.texi index b804ee4c..92553cbb 100644 --- a/doc/Ledger3.texi +++ b/doc/Ledger3.texi @@ -41,10 +41,6 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @finalout @end iftex -@macro ledgerprog - @sc{ledger} -@end macro - @titlepage @title LEDGER: Command-Line Accounting @@ -52,7 +48,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @end titlepage @direntry -* Ledger: (ledger). Command-Line Accounting +* Ledger3: (ledger). Command-Line Accounting @end direntry @contents @@ -60,15 +56,17 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @ifnottex @node Top, Copying, (dir), (dir) @top Overview -LEDGER is an accounting tool with the moxie to exist. It provides no -bells or whistles, and returns the user to the days before user -interfaces were even a twinkling in their father's CRT. +LEDGER is a command line accounting tool that provides double-entry +accounting based on a text journal. It provides no bells or whistles, +and returns the user to the days before user interfaces were even a +twinkling in their father's CRT. @c @insertcopying @end ifnottex @menu * Copying:: * Introduction to Ledger:: +* Ledger Tutorial :: * Principles of Accounting:: * Keeping a Journal:: * Command-line Syntax:: @@ -83,9 +81,16 @@ interfaces were even a twinkling in their father's CRT. @chapter Copying @insertcopying -@node Introduction to Ledger, Principles of Accounting, Copying, Top +@node Introduction to Ledger, Ledger Tutorial , Copying, Top @chapter Introduction to Ledger +@menu +* Fat-free Accounting:: +* Building the Program:: +* Getting Help:: +@end menu +@node Fat-free Accounting, Building the Program, Introduction to Ledger, Introduction to Ledger +@section Fat-free Accounting LEDGER is an accounting tool with the moxie to exist. It provides no bells or whistles, and returns the user to the days before user interfaces were even a twinkling in their father's CRT. @@ -97,7 +102,9 @@ fat. Think of it as the Bran Muffin of accounting tools. To use it, you need to start keeping a journal. This is the basis of all accounting, and if you haven't started yet, now is the time to learn. The little booklet that comes with your checkbook is a journal, -so we'll describe double-entry accounting in terms of that. +so we'll describe double-entry accounting in terms of that. If you use +another GUI accounting program like GNUCash, the vast majority of its +functionality is geared towards helping you keep a journal. A checkbook journal records debits (subtractions, or withdrawals) and credits (additions, or deposits) with reference to a single account: @@ -183,7 +190,7 @@ choose. Enter the beauty of computerized accounting. The purpose of the LEDGER program is to make general journal accounting simple, by keeping track of the balances for you. Your only job is to enter the -postings. If a posting does not balance, LEDGER displays an +postings. If an individual posting does not balance, LEDGER displays an error and indicates the incorrect posting.@footnote{In some special cases, it automatically balances this transaction for you.} @@ -215,14 +222,8 @@ that journal will never alter your input file. You can create and edit that file in any way you prefer, but journal is only for analyzing the data, not for altering it. -@section More introduction -@menu -* Building the Program:: -* Getting Help:: -@end menu - -@node Building the Program, Getting Help, Introduction to Ledger, Introduction to Ledger +@node Building the Program, Getting Help, Fat-free Accounting, Introduction to Ledger @section Building the program LEDGER is written in ANSI C++, and should compile on any platform. It @@ -250,8 +251,21 @@ http://groups.google.com/group/ledger-cli You can also find help at the @samp{#ledger} channel on the IRC server @samp{irc.freenode.net}. +@node Ledger Tutorial , Principles of Accounting, Introduction to Ledger, Top +@chapter Ledger Tutorial -@node Principles of Accounting, Keeping a Journal, Introduction to Ledger, Top +@menu +* Start a Journal:: +* Run Some Reports:: +@end menu + +@node Start a Journal, Run Some Reports, Ledger Tutorial , Ledger Tutorial +@section Start a Journal File + +@node Run Some Reports, , Start a Journal, Ledger Tutorial +@section Run a Few Reports + +@node Principles of Accounting, Keeping a Journal, Ledger Tutorial , Top @chapter Principles of Accounting @node Keeping a Journal, Command-line Syntax, Principles of Accounting, Top @@ -288,15 +302,15 @@ posting. @menu * Most Basic Entry:: -* Commodities:: +* Currency and Commodities:: * Structuring Your Accounts:: * Transaction Notes and Tags:: +* Advanced Transactions:: * File Format:: * Archiving Previous Years :: -* Ledger Tutorial :: @end menu -@node Most Basic Entry, Commodities, Keeping a Journal, Keeping a Journal +@node Most Basic Entry, Currency and Commodities, Keeping a Journal, Keeping a Journal @section The Most Basic Entry Here is the Pacific Bell example from above, given as a LEDGER @@ -324,9 +338,7 @@ For this transaction, LEDGER will figure out that $-23.00 must come from @samp{Assets:Checking} in order to balance the transaction. Also note the structure of the account entries. There is an implied -hierarchy established by separating with colons. See -(@pxref{Structuring Your Accounts}) for details and suggestions regarding -your accounts. +hierarchy established by separating with colons (see @pxref{Structuring Your Accounts}). @@ -341,20 +353,23 @@ amount and the account. If you do not have adequate separation between the amount and the account LEDGER will give an error and stop calculating} -@node Commodities, Structuring Your Accounts, Most Basic Entry, Keeping a Journal -@section Commodities +@node Currency and Commodities, Structuring Your Accounts, Most Basic Entry, Keeping a Journal +@section Currency and Commodities LEDGER is agnostic when it comes to how you value your accounts. -Dollars, Euros, Pounds, Francs, etc. are just ``commodities''. Holdings -in stocks, bonds, mutual funds and other financial instrument can be -label using whatever is convenient for you (stock ticker symbols are -suggested for publicly traded assets).@footnote{you can track ANYTHING, -even time. As long as it cannot be created or destroyed inside your -accounting system.} +Dollars, Euros, Pounds, Francs, Shares etc. are just ``commodities''. +Holdings in stocks, bonds, mutual funds and other financial instruments +can be label using whatever is convenient for you (stock ticker symbols +are suggested for publicly traded assets).@footnote{you can track +ANYTHING, even time. As long as it cannot be created or destroyed inside +your accounting system.} + +For the rest of this manual, we will only use the word ``commodities'' +when refering to the units on a transaction value. This is fundamentally different than many common accounting packages, which assume the same currency throughout all of your accounts. This -means if you typically operate in Euros, but travel to the US and has +means if you typically operate in Euros, but travel to the US and have some expenses, you would have to do the currency conversion BEFORE you made the entry into your financial system. With ledger this is not required. In the same journal you can have entries in any or all @@ -366,35 +381,73 @@ For example, the following entries reflect transaction made for a business trip to Europe from the US: @smallexample -2011/09/23 Cash in Munich - Assets:Cash 50.00 Euros - Assets:Checking $-66.00 +2011/09/23 Cash in Munich + Assets:Cash E50.00 + Assets:Checking $-66.00 -2011/09/24 Dinner in Munich - Expenses:Business:Travel 35.00 Euro +2011/09/24 Dinner in Munich + Expenses:Business:Travel E35.00 Assets:Cash @end smallexample This says that $66.00 came out of checking and turned into 50 Euros. The -implied exchange rate was $1.32. Then 35 Euros was spent on Dinner in Munich. +implied exchange rate was $1.32. Then 35.00 Euros was spent on Dinner in Munich. +Running a ledger balance report shows: +@smallexample +macbook-2:$ ledger -f example.dat bal + $-66.00 + E15.00 Assets + E15.00 Cash + $-66.00 Checking + E35.00 Expenses:Business:Travel +-------------------- + $-66.00 + E50.00 +@end smallexample -@node Structuring Your Accounts, Transaction Notes and Tags, Commodities, Keeping a Journal +The top two lines show my current assets as $-66.00 in checking (in this +very short example I didn't establish opening an opening balance for the +checking account) and E15.00. After spending on dinner i have E15.00 in +my wallet. The bottom line balances to zero, but is shown in two lines +since we haven't told ledger to convert commodities. + +@node Structuring Your Accounts, Transaction Notes and Tags, Currency and Commodities, Keeping a Journal @section Structuring your Accounts There really are no requirements for how you do this, but to preserve your sanity we suggest some very basic structure to your accounting system. -At the highest level you have five sorts of accounts: Expenses, Assets, -Income, Liabilities and Equity. Briefly, you can think of these as places money goes, -places money sits, places money comes from and money you owe. +At the highest level you have five sorts of accounts: +@enumerate +@item +Expenses, where money goes +@item +Assets, where money sits +@item +Income, where moeny comes from +@item +Liabilities, money you owe +@item +Equity, the real value of your property. +@end enumerate Starting the structure off this way will make it simpler for you to get answers to the questions you really need to ask about your finances. -@node Transaction Notes and Tags, File Format, Structuring Your Accounts, Keeping a Journal +Beneath these top level accounts you can have any level of detail you +desire. If you want to keep specific track of how much you spend on +burgers and fries, you could have the following: + +@smallexample +Expenses:Food:Hamburgers and Fries +@end smallexample + + +@node Transaction Notes and Tags, Advanced Transactions, Structuring Your Accounts, Keeping a Journal @section Transaction Notes and Tags + LEDGER 3.0 supports entry and transaction ``notes'', which may contain new metadata and tag markers. Here's an example: @@ -421,7 +474,7 @@ such transactions using: @smallexample ledger reg %foo - ldeger reg tag foo + ledger reg tag foo @end smallexample Also, if any word in the note ends (but does not start) with a colon, @@ -446,20 +499,172 @@ The group-by and sort functions also support tags: @smallexample ledger --group-by "tag('foo')" bal @end smallexample -Will produce a balance summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'. +Will produce a balance summary of all transanction with tag `foo' group +by transactions wiht the same value for `foo'. @smallexample ledger reg --sort "tag('foo')" %foo @end smallexample -Produces a register view with the transaction have tag `foo' sorted by the tags value. +Produces a register view with the transaction have tag `foo' sorted by +the tags value. -Comments that occur before an entry, or which starts at column -zero, are always ignored and are neither searched nor printed back. +Comments that occur before an entry, or which starts at column zero, are +always ignored and are neither searched nor printed back. + +@node Advanced Transactions, File Format, Transaction Notes and Tags, Keeping a Journal +@section Advanced Transactions +@menu +* Multiple Account Transactions:: +* Virtual Transactions:: +* Automatic Transactions:: +@end menu + +@node Multiple Account Transactions, Virtual Transactions, Advanced Transactions, Advanced Transactions +@subsection Multiple Account Transactions + +Often times a transaction needs to be split across several accounts. This is trivially simple in a LEDGER journal: + +@smallexample +2011/09/15 * Deposit Acme Bytepumps Monthly Paycheck + Income:Taxable:Acme Bytepumps Inc. $-2500.00 + Assets:Brokerage:Checking $175.00 + Assets:Investments:401K Deferred $250.00 + Expenses:Tax:Medicare $36.25 + Expenses:Tax:Federal Tax $200.00 + Expenses:Tax:State Tax $20.00 + Expenses:Insurance:Life $18.75 + Assets:Credit Union:Joint Checking +@end smallexample + +This is an example of a paycheck entry. THe money comes OUT of your +income account, and is spent into several other accounts. The last line +doesn't require an amount, as ledger will automatically balance the +transaction (it will be $1800 into the Joint Checking account) +@node Virtual Transactions, Automatic Transactions, Multiple Account Transactions, Advanced Transactions +@subsection Virtual Transactions -@node File Format, Archiving Previous Years , Transaction Notes and Tags, Keeping a Journal -@section File format + +A virtual posting is when you, in your mind, see money as moving +to a certain place, when in reality that money has not moved at all. +There are several scenarios in which this type of tracking comes in +handy, and each of them will be discussed in detail. + +To enter a virtual posting, surround the account name in +parentheses. This form of usage does not need to balance. However, +if you want to ensure the virtual posting balances with other +virtual postings in the same transaction, use square brackets. For +example: + +@smallexample +10/2 Paycheck + Assets:Checking $1000.00 + Income:Salary $-1000.00 + (Debt:Alimony) $200.00 +@end smallexample + +In this example, after receiving a paycheck an alimony debt is +increased---even though no money has moved around yet. + +@smallexample +10/2 Paycheck + Assets:Checking $1000.00 + Income:Salary $-1000.00 + [Savings:Trip] $200.00 + [Assets:Checking] $-200.00 +@end smallexample + +In this example, $200 has been deducted from checking toward savings +for a trip. It will appear as though the money has been moved from +the account into @samp{Savings:Trip}, although no money has actually +moved anywhere. + +When balances are displayed, virtual postings will be factored in. +To view balances without any virtual balances factored in, using the +@option{-R} flag, for ``reality''. + + +@node Automatic Transactions, , Virtual Transactions, Advanced Transactions +@subsection Automatic Transactions + +As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets. +It is similar to tithing for Jews and Christians, or to Zakát for +Muslims. The exact details of computing Huqúqu'lláh are somewhat +complex, but if you have further interest, please consult the Web. + +Ledger makes this otherwise difficult law very easy. Just set up an +automated posting at the top of your ledger file: + +@smallexample +; This automated transaction will compute Huqúqu'lláh based on this +; journal's postings. Any that match will affect the +; Liabilities:Huququ'llah account by 19% of the value of that posting. + += /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/ + (Liabilities:Huququ'llah) 0.19 +@end smallexample + +This automated posting works by looking at each posting in the +ledger file. If any match the given value expression, 19% of the +posting's value is applied to the @samp{Liabilities:Huququ'llah} +account. So, if $1000 is earned from @samp{Income:Salary}, $190 is +added to @samp{Liabilities:Huqúqu'lláh}; if $1000 is spent on Rent, +$190 is subtracted. The ultimate balance of Huqúqu'lláh reflects how +much is owed in order to fulfill one's obligation to Huqúqu'lláh. +When ready to pay, just write a check to cover the amount shown in +@samp{Liabilities:Huququ'llah}. That transaction would look like: + +@smallexample +2003/01/01 (101) Baha'i Huqúqu'lláh Trust + Liabilities:Huququ'llah $1,000.00 + Assets:Checking +@end smallexample + +That's it. To see how much Huqúq is currently owed based on your +ledger transactions, use: + +@example +ledger balance Liabilities:Huquq +@end example + +This works fine, but omits one aspect of the law: that Huquq is only +due once the liability exceeds the value of 19 mithqáls of gold (which +is roughly 2.22 ounces). So what we want is for the liability to +appear in the balance report only when it exceeds the present day +value of 2.22 ounces of gold. This can be accomplished using the +command: + +@smallexample +ledger -Q -t "/Liab.*Huquq/?(a/P@{2.22 AU@}<=@{-1.0@}&a):a" -s bal liab +@end smallexample + +With this command, the current price for gold is downloaded, and the +Huqúqu'lláh is reported only if its value exceeds that of 2.22 ounces +of gold. If you wish the liability to be reflected in the parent +subtotal either way, use this instead: + +@smallexample +ledger -Q -T "/Liab.*Huquq/?(O/P@{2.22 AU@}<=@{-1.0@}&O):O" -s bal liab +@end smallexample + +In some cases, you may wish to refer to the account of whichever +posting matched your automated transaction's value expression. To do +this, use the special account name @samp{$account}: + +@smallexample += /^Some:Long:Account:Name/ + [$account] -0.10 + [Savings] 0.10 +@end smallexample + +This example causes 10% of the matching account's total to be deferred +to the @samp{Savings} account---as a balanced virtual posting, +which may be excluded from reports by using @option{--real}. + + +@node File Format, Archiving Previous Years , Advanced Transactions, Keeping a Journal +@section File Format for Users The ledger file format is quite simple, but also very flexible. It supports many options, though typically the user can ignore most of @@ -494,13 +699,13 @@ The format of each following posting is: @end example The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual -postings, or square brackets if it is a virtual postings that +posting, or square brackets if it is a virtual posting that must balance. The @samp{AMOUNT} can be followed by a per-unit posting cost, by specifying @samp{@@ AMOUNT}, or a complete posting cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may specify an actual and/or effective date for the posting by using the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or -@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}. +@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.(See @pxref{Virtual Transactions}) @item = An automated transaction. A value expression must appear after the equal @@ -509,7 +714,7 @@ sign. After this initial line there should be a set of one or more postings, just as if it were normal transaction. If the amounts of the postings have no commodity, they will be applied as modifiers to -whichever real posting is matched by the value expression. +whichever real posting is matched by the value expression(See @pxref{Automatic Transactions}). @item ~ A period transaction. A period expression must appear after the tilde. @@ -593,11 +798,67 @@ timelog files. See the timeclock's documentation for more info on the syntax of its timelog files. @end table -@node Archiving Previous Years , Ledger Tutorial , File Format, Keeping a Journal + +@node Archiving Previous Years , , File Format, Keeping a Journal @section Archiving Previous Years -@node Ledger Tutorial , , Archiving Previous Years , Keeping a Journal -@section Ledger Tutorial + +After a while, your journal can get to be pretty large. While this will +not slow down LEDGER---it's designed to process journals very +quickly---things can start to feel ``messy''; and it's a universal +complaint that when finances feel messy, people avoid them. + +Thus, archiving the data from previous years into their own files can +offer a sense of completion, and freedom from the past. But how to best +accomplish this with the ledger program? There are two commands that +make it very simple: @command{print}, and @command{equity}. + +Let's take an example file, with data ranging from year 2000 until 2004. +We want to archive years 2000 and 2001 to their own file, leaving just +2003 and 2004 in the current file. So, use @command{print} to output +all the earlier transactions to a file called @file{ledger-old.dat}: + +@smallexample +ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat +@end smallexample + +To delete older data from the current ledger file, use @command{print} +again, this time specifying year 2002 as the starting date: + +@example +ledger -f ledger.dat -b 2002 print > x +mv x ledger.dat +@end example + +However, now the current file contains @emph{only} postings from 2002 +onward, which will not yield accurate present-day balances, because the +net income from previous years is no longer being tallied. To +compensate for this, we must append an equity report for the old ledger +at the beginning of the new one: + +@example +ledger -f ledger-old.dat equity > equity.dat +cat equity.dat ledger.dat > x +mv x ledger.dat +rm equity.dat +@end example + +Now the balances reported from @file{ledger.dat} are identical to what +they were before the data was split. + +How often should you split your ledger? You never need to, if you +don't want to. Even eighty years of data will not slow down ledger +much---and that's just using present day hardware! Or, you can keep +the previous and current year in one file, and each year before that +in its own file. It's really up to you, and how you want to organize +your finances. For those who also keep an accurate paper trail, it +might be useful to archive the older years to their own files, then +burn those files to a CD to keep with the paper records---along with +any electronic statements received during the year. In the arena of +organization, just keep in mind this maxim: Do whatever keeps you +doing it. + + @node Command-line Syntax, Basic Reporting Commands, Keeping a Journal, Top @@ -1667,7 +1928,7 @@ same format string is used for all postings. @node Journal File Format, Extending with Python, Format Strings, Top -@chapter LEDGER Journal File Format +@chapter Journal File Format for Developers This chapter offers a complete description of the journal data format, suitable for implementors in other languages to follow. For users, diff --git a/doc/sample.dat b/doc/sample.dat deleted file mode 100644 index 12ac4cb4..00000000 --- a/doc/sample.dat +++ /dev/null @@ -1,54 +0,0 @@ -; -*- ledger -*- - -N $ - -= /^Expenses:Books/ - (Liabilities:Taxes) -0.10 - -~ Monthly - Assets:Bank:Checking $500.00 - Income:Salary - -~ Yearly - Expenses:Donations $100.00 - Assets:Bank:Checking - -2004/05/01 * Checking balance - Assets:Bank:Checking $1,000.00 - Equity:Opening Balances - -2004/05/03=2004/05/01 * Investment balance - Assets:Brokerage 50 AAPL @ $30.00 - Equity:Opening Balances - -2004/05/14 * Páy dày - Assets:Bank:Checking 500.00€ - Income:Salary - -2004/05/14 * Another dày in which there is Páying - Asséts:Bánk:Chécking:Asséts:Bánk:Chécking $500.00 - Income:Salary - -2004/05/14 * Another dày in which there is Páying - Русский язык:Активы:Русский язык:Русский язык $1000.00 - Income:Salary - -tag foo - -2004/05/27 Book Store - Expenses:Books $20.00 - Expenses:Cards $40.00 - Expenses:Docs $30.00 - Liabilities:MasterCard - -end tag - -2004/05/27 (100) Credit card company - ; This is an xact note! - ; Sample: Value - Liabilities:MasterCard $20.00 - ; This is a posting note! - ; Sample: Another Value - ; :MyTag: - Assets:Bank:Checking - ; :AnotherTag: From 96fd425607b7415b99d6944bfb96dfca2e8e5722 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 28 Sep 2011 22:47:43 -0700 Subject: [PATCH 08/28] General document structuring and transfer from older docs --- doc/Ledger3.texi | 899 ++++++++++++++++++++++++++++++++++--------- test/input/drewr.dat | 4 +- 2 files changed, 729 insertions(+), 174 deletions(-) diff --git a/doc/Ledger3.texi b/doc/Ledger3.texi index 92553cbb..0026ecb1 100644 --- a/doc/Ledger3.texi +++ b/doc/Ledger3.texi @@ -75,6 +75,8 @@ twinkling in their father's CRT. * Format Strings:: * Journal File Format:: * Extending with Python:: +* Example Data File:: +* Miscellaneous Notes:: @end menu @node Copying, Introduction to Ledger, Top, Top @@ -262,8 +264,47 @@ You can also find help at the @samp{#ledger} channel on the IRC server @node Start a Journal, Run Some Reports, Ledger Tutorial , Ledger Tutorial @section Start a Journal File +A journal is a record of your financial transactions and will be central +to using LEDGER. For now we just want to get a teast +of what ledger can do. An example journal is included with the source +code distribution, called @file{drewr.dat} (it is copied in @pxref{Example Data File}). +Copy it someplace convenient and open up a terminal window in that directory. + +If you would rather start with your own journal right away please skip +to @xref{Keeping a Journal}. + @node Run Some Reports, , Start a Journal, Ledger Tutorial @section Run a Few Reports +@subsection Balance Report + +Run this command: +@smallexample +ledger -f drewr.dat balance +@end smallexample + +LEDGER will generate: +@smallexample + $ -3,804.00 Assets + $ 1,396.00 Checking + $ 30.00 Business + $ -5,200.00 Savings + $ -1,000.00 Equity:Opening Balances + $ 6,654.00 Expenses + $ 5,500.00 Auto + $ 20.00 Books + $ 300.00 Escrow + $ 334.00 Food:Groceries + $ 500.00 Interest:Mortgage + $ -2,030.00 Income + $ -2,000.00 Salary + $ -30.00 Sales + $ -63.60 Liabilities + $ -20.00 MasterCard + $ 200.00 Mortgage:Principal + $ -243.60 Tithe +-------------------- + $ -243.60 +@end smallexample @node Principles of Accounting, Keeping a Journal, Ledger Tutorial , Top @chapter Principles of Accounting @@ -304,7 +345,6 @@ posting. * Most Basic Entry:: * Currency and Commodities:: * Structuring Your Accounts:: -* Transaction Notes and Tags:: * Advanced Transactions:: * File Format:: * Archiving Previous Years :: @@ -412,7 +452,7 @@ checking account) and E15.00. After spending on dinner i have E15.00 in my wallet. The bottom line balances to zero, but is shown in two lines since we haven't told ledger to convert commodities. -@node Structuring Your Accounts, Transaction Notes and Tags, Currency and Commodities, Keeping a Journal +@node Structuring Your Accounts, Advanced Transactions, Currency and Commodities, Keeping a Journal @section Structuring your Accounts There really are no requirements for how you do this, but to preserve @@ -445,8 +485,20 @@ Expenses:Food:Hamburgers and Fries @end smallexample -@node Transaction Notes and Tags, Advanced Transactions, Structuring Your Accounts, Keeping a Journal -@section Transaction Notes and Tags + + +@node Advanced Transactions, File Format, Structuring Your Accounts, Keeping a Journal +@section Advanced Transactions +@menu +* Transaction Notes and Tags:: +* Multiple Account Transactions:: +* Virtual Transactions:: +* Automatic Transactions:: +* Periodic Transactions:: +@end menu + +@node Transaction Notes and Tags, Multiple Account Transactions, Advanced Transactions, Advanced Transactions +@subsection Transaction Notes and Tags LEDGER 3.0 supports entry and transaction ``notes'', which may contain new metadata and tag markers. Here's an example: @@ -511,15 +563,47 @@ the tags value. Comments that occur before an entry, or which starts at column zero, are always ignored and are neither searched nor printed back. -@node Advanced Transactions, File Format, Transaction Notes and Tags, Keeping a Journal -@section Advanced Transactions -@menu -* Multiple Account Transactions:: -* Virtual Transactions:: -* Automatic Transactions:: -@end menu +If a posting comment is a date (with brackets), it modifies the date for that posting: +@smallexample +2010/02/01 Sample + Assets:Bank $400.00 + Income:Check $-400.00 ; [2010/01/01] +@end smallexample +You can use metadata to override the payee field for individual postings within a transaction: (source) -@node Multiple Account Transactions, Virtual Transactions, Advanced Transactions, Advanced Transactions +@smallexample +2010/06/17 Sample + Assets:Bank $400.00 + Income:Check1 $-100.00 ; Payee: Person One + Income:Check2 $-100.00 ; Payee: Person Two + Income:Check3 $-100.00 ; Payee: Person Three + Income:Check4 $-100.00 ; Payee: Person Four +@end smallexample +Metadata are normally strings, but you can create metadata of other types: + +@smallexample +2010/06/17 Sample + Assets:Bank $400.00 + Income:Check1 $-100.00 + ; Date:: [2010/09/01] + ; Amount:: $100.00 +@end smallexample +(Note that this Date tag is not the same as the posting date.) + +There are now tag/pop directives, to apply metadata to a range of transactions (and their postings). For example, if you wanted a conceptual "page" of transactions relating to business trip to Chicago, you could do this: + +@smallexample + tag Location: Chicago + tag Purpose: Business + + ... transactions go here + + pop + pop +@end smallexample +It would be as if you'd applied "; Location: Chicago", etc., to every transaction. + +@node Multiple Account Transactions, Virtual Transactions, Transaction Notes and Tags, Advanced Transactions @subsection Multiple Account Transactions Often times a transaction needs to be split across several accounts. This is trivially simple in a LEDGER journal: @@ -585,7 +669,7 @@ To view balances without any virtual balances factored in, using the @option{-R} flag, for ``reality''. -@node Automatic Transactions, , Virtual Transactions, Advanced Transactions +@node Automatic Transactions, Periodic Transactions, Virtual Transactions, Advanced Transactions @subsection Automatic Transactions As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets. @@ -662,6 +746,9 @@ This example causes 10% of the matching account's total to be deferred to the @samp{Savings} account---as a balanced virtual posting, which may be excluded from reports by using @option{--real}. +@node Periodic Transactions, , Automatic Transactions, Advanced Transactions +@subsection Periodic Transactions + @node File Format, Archiving Previous Years , Advanced Transactions, Keeping a Journal @section File Format for Users @@ -705,7 +792,7 @@ posting cost, by specifying @samp{@@ AMOUNT}, or a complete posting cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may specify an actual and/or effective date for the posting by using the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or -@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.(See @pxref{Virtual Transactions}) +@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.(See @pxref{Virtual Transactions}) @item = An automated transaction. A value expression must appear after the equal @@ -868,7 +955,6 @@ doing it. @menu * Cookbook:: * Quick Reference:: -* Commands:: * Options:: * Period Expressions:: @end menu @@ -898,7 +984,7 @@ ledger register NFCUChecking --sort d -d 'd>[2011/04/01]' until 2011/05/25 (Liabilities:Tithe Owed) -1.0 @end example -@node Quick Reference, Commands, Cookbook, Command-line Syntax +@node Quick Reference, Options, Cookbook, Command-line Syntax @section Quick Reference This chapter describes LEDGER's features and serves as a quick @@ -937,155 +1023,7 @@ However, none of them are required to use the basic reporting commands. -@node Commands, Options, Quick Reference, Command-line Syntax -@section Commands - -@subsection balance - -The @command{balance} command reports the current balance of all -accounts. It accepts a list of optional regexps, which confine the -balance report to the matching accounts. If an account contains -multiple types of commodities, each commodity's total is reported -separately. - -@subsection register - -The @command{register} command displays all the postings occurring -in a single account, line by line. The account regexp must be -specified as the only argument to this command. If any regexps occur -after the required account name, the register will contain only those -postings that match. Very useful for hunting down a particular -posting. - -The output from @command{register} is very close to what a typical -checkbook, or single-account ledger, would look like. It also shows a -running balance. The final running balance of any register should -always be the same as the current balance of that account. - -If you have Gnuplot installed, you may plot the amount or running -total of any register by using the script @file{report}, which is -included in the LEDGER distribution. The only requirement is that you -add either @option{-j} or @option{-J} to your register command, in -order to plot either the amount or total column, respectively. - -@subsection print - -The @command{print} command prints out ledger transactions in a textual -format that can be parsed by LEDGER. They will be properly formatted, -and output in the most economic form possible. The ``print'' command -also takes a list of optional regexps, which will cause only those -postings which match in some way to be printed. - -The @command{print} command can be a handy way to clean up a ledger -file whose formatting has gotten out of hand. - -@subsection output - -The @command{output} command is very similar to the @command{print} -command, except that it attempts to replicate the specified ledger -file exactly. The format of the command is: - -@example -ledger -f FILENAME output FILENAME -@end example - -Where @file{FILENAME} is the name of the ledger file to output. The -reason for specifying this command is that only transactions contained -within that file will be output, and not an included transactions (as can -happen with the @command{print} command). - -@subsection xml - -The @command{xml} command outputs results similar to what -@command{print} and @command{register} display, but as an XML form. -This data can then be read in and processed. Use the -@option{--totals} option to include the running total with each -posting. - -@subsection emacs - -The @command{emacs} command outputs results in a form that can be read -directly by Emacs Lisp. The format of the sexp is: - -@example -((BEG-POS CLEARED DATE CODE PAYEE - (ACCOUNT AMOUNT)...) ; list of postings - ...) ; list of transactions -@end example - -@subsection equity - -The @command{equity} command prints out accounts balances as if they -were transactions. This makes it easy to establish the starting balances -for an account, such as when @ref{Archiving Previous Years}. - -@subsection prices - -The @command{prices} command displays the price history for matching -commodities. The @option{-A} flag is useful with this report, to -display the running average price, or @option{-D} to show each price's -deviation from that average. - -There is also a @command{pricesdb} command which outputs the same -information as @command{prices}, but does in a format that can be -parsed by LEDGER. - -@subsection xact - -The @command{xact} commands simplifies the creation of new transactions. -It works on the principle that 80% of all postings are variants of -earlier postings. Here's how it works: - -Say you currently have this posting in your ledger file: - -@smallexample -2004/03/15 * Viva Italiano - Expenses:Food $12.45 - Expenses:Tips $2.55 - Liabilities:MasterCard $-15.00 -@end smallexample - -Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva -Italiano} again. The exact amounts are different, but the overall -form is the same. With the @command{xact} command you can type: - -@example -ledger xact 2004/4/9 viva food 11 tips 2.50 -@end example - -This produces the following output: - -@smallexample -2004/04/09 Viva Italiano - Expenses:Food $11.00 - Expenses:Tips $2.50 - Liabilities:MasterCard $-13.50 -@end smallexample - -It works by finding a past posting matching the regular expression -@samp{viva}, and assuming that any accounts or amounts specified will -be similar to that earlier posting. If LEDGER does not succeed in -generating a new transaction, an error is printed and the exit code is set -to @samp{1}. - -There is a shell script in the distribution's @file{scripts} directory -called @file{xact}, which simplifies the task of adding a new transaction -to your ledger. It launches @command{vi} to confirm that the transaction -looks appropriate. - -Here are a few more examples of the @command{xact} command, assuming -the above journal transaction: - -@example -ledger xact 4/9 viva 11.50 -ledger xact 4/9 viva 11.50 checking # (from `checking') -ledger xact 4/9 viva food 11.50 tips 8 -ledger xact 4/9 viva food 11.50 tips 8 cash -ledger xact 4/9 viva food $11.50 tips $8 cash -ledger xact 4/9 viva dining "DM 11.50" -@end example - -@node Options, Period Expressions, Commands, Command-line Syntax +@node Options, Period Expressions, Quick Reference, Command-line Syntax @section Options With all of the reports, command-line options are useful to modify the @@ -1199,10 +1137,10 @@ date). transaction has not been marked ``cleared'' (i.e., if there is no asterix to the right of the date). -@option{--real} (@option{-R}) displays only real postings, not -virtual. (A virtual posting is indicated by surrounding the -account name with parentheses or brackets; see the section on using -virtual postings for more information). +@option{--real} (@option{-R}) displays only real postings, not virtual. +(A virtual posting is indicated by surrounding the account name with +parentheses or brackets; see @ref{Virtual Transactions} for more +information). @option{--actual} (@option{-L}) displays only actual postings, and not those created due to automated postings. @@ -1255,7 +1193,54 @@ report, the amount used to calculate account totals in the used for the ``totals'' column in the @command{register} and @command{balance} reports. -@subsection Output customization +@menu +* Search Terms:: +* Output Customization:: +@end menu + +@node Search Terms, Output Customization, Options, Options +@subsection Search Terms + +Valid LEDGER invocations look like: +@smallexample + ledger [OPTIONS] +@end smallexample + +Where @samp{COMMAND} is any command verb (@pxref{Basic Reporting Commands}), @samp{OPTIONS} can occur +anywhere, and @samp{SEARCH-TERM} is one or more of the following: + +@smallexample + word search for any account containing 'word' + TERM and TERM boolean AND between terms + TERM or TERM boolean OR between terms + not TERM invert the meaning of the term + payee word search for any payee containing 'word' + @@word shorthand for 'payee word' + desc word alternate for 'payee word' + note word search for any note containing 'word' + &word shorthand for 'note word' + tag word search for any metadata tag containing 'word' + tag word=value search for any metadata tag containing 'word' + whose value contains 'value' + %word shorthand for 'tag word' + %word=value shorthand for 'tag word=value' + meta word alternate for 'tag word' + meta word=value alternate for 'tag word=value' + expr 'EXPR' apply the given value expression as a predicate + '=EXPR' shorthand for 'expr EXPR' + \( TERMS \) group terms; useful if using and/or/not +@end smallexample + +So, to list all transaction that charged to ``ffod'' but not ``dining'' for any payee other than ``chang'' the following three commands would be equivalent: + +@smallexample + ledger reg food not dining @@chang + ledger reg food and not dining and not payee chang + ledger reg food not dining expr 'payee =~ /chang/' +@end smallexample + +@node Output Customization, , Search Terms, Options +@subsection Output Customization These options affect only the output, but not which postings are used to create it: @@ -1540,12 +1525,179 @@ weekly last august @node Basic Reporting Commands, Value Expressions, Command-line Syntax, Top @chapter Basic Reporting Commands +@menu +* balance:: +* register:: +* print:: +* output:: +* xml:: +* emacs:: +* equity:: +* prices:: +* xact:: +* Budgeting and Forecasting:: +@end menu + +@node balance, register, Basic Reporting Commands, Basic Reporting Commands +@section balance + +The @command{balance} command reports the current balance of all +accounts. It accepts a list of optional regexps, which confine the +balance report to the matching accounts. If an account contains +multiple types of commodities, each commodity's total is reported +separately. + +@node register, print, balance, Basic Reporting Commands +@section register + +The @command{register} command displays all the postings occurring +in a single account, line by line. The account regexp must be +specified as the only argument to this command. If any regexps occur +after the required account name, the register will contain only those +postings that match. Very useful for hunting down a particular +posting. + +The output from @command{register} is very close to what a typical +checkbook, or single-account ledger, would look like. It also shows a +running balance. The final running balance of any register should +always be the same as the current balance of that account. + +If you have Gnuplot installed, you may plot the amount or running +total of any register by using the script @file{report}, which is +included in the LEDGER distribution. The only requirement is that you +add either @option{-j} or @option{-J} to your register command, in +order to plot either the amount or total column, respectively. + +@node print, output, register, Basic Reporting Commands +@section print + +The @command{print} command prints out ledger transactions in a textual +format that can be parsed by LEDGER. They will be properly formatted, +and output in the most economic form possible. The ``print'' command +also takes a list of optional regexps, which will cause only those +postings which match in some way to be printed. + +The @command{print} command can be a handy way to clean up a ledger +file whose formatting has gotten out of hand. + +@node output, xml, print, Basic Reporting Commands +@section output + +The @command{output} command is very similar to the @command{print} +command, except that it attempts to replicate the specified ledger +file exactly. The format of the command is: + +@example +ledger -f FILENAME output FILENAME +@end example + +Where @file{FILENAME} is the name of the ledger file to output. The +reason for specifying this command is that only transactions contained +within that file will be output, and not an included transactions (as can +happen with the @command{print} command). + +@node xml, emacs, output, Basic Reporting Commands +@section xml + +The @command{xml} command outputs results similar to what +@command{print} and @command{register} display, but as an XML form. +This data can then be read in and processed. Use the +@option{--totals} option to include the running total with each +posting. + +@node emacs, equity, xml, Basic Reporting Commands +@section emacs + +The @command{emacs} command outputs results in a form that can be read +directly by Emacs Lisp. The format of the sexp is: + +@example +((BEG-POS CLEARED DATE CODE PAYEE + (ACCOUNT AMOUNT)...) ; list of postings + ...) ; list of transactions +@end example + +@node equity, prices, emacs, Basic Reporting Commands +@section equity + +The @command{equity} command prints out accounts balances as if they +were transactions. This makes it easy to establish the starting balances +for an account, such as when @ref{Archiving Previous Years}. + +@node prices, xact, equity, Basic Reporting Commands +@section prices + +The @command{prices} command displays the price history for matching +commodities. The @option{-A} flag is useful with this report, to +display the running average price, or @option{-D} to show each price's +deviation from that average. + +There is also a @command{pricesdb} command which outputs the same +information as @command{prices}, but does in a format that can be +parsed by LEDGER. + +@node xact, Budgeting and Forecasting, prices, Basic Reporting Commands +@section xact + +The @command{xact} commands simplifies the creation of new transactions. +It works on the principle that 80% of all postings are variants of +earlier postings. Here's how it works: + +Say you currently have this posting in your ledger file: + +@smallexample +2004/03/15 * Viva Italiano + Expenses:Food $12.45 + Expenses:Tips $2.55 + Liabilities:MasterCard $-15.00 +@end smallexample + +Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva +Italiano} again. The exact amounts are different, but the overall +form is the same. With the @command{xact} command you can type: + +@example +ledger xact 2004/4/9 viva food 11 tips 2.50 +@end example + +This produces the following output: + +@smallexample +2004/04/09 Viva Italiano + Expenses:Food $11.00 + Expenses:Tips $2.50 + Liabilities:MasterCard $-13.50 +@end smallexample + +It works by finding a past posting matching the regular expression +@samp{viva}, and assuming that any accounts or amounts specified will +be similar to that earlier posting. If LEDGER does not succeed in +generating a new transaction, an error is printed and the exit code is set +to @samp{1}. + +There is a shell script in the distribution's @file{scripts} directory +called @file{xact}, which simplifies the task of adding a new transaction +to your ledger. It launches @command{vi} to confirm that the transaction +looks appropriate. + +Here are a few more examples of the @command{xact} command, assuming +the above journal transaction: + +@example +ledger xact 4/9 viva 11.50 +ledger xact 4/9 viva 11.50 checking # (from `checking') +ledger xact 4/9 viva food 11.50 tips 8 +ledger xact 4/9 viva food 11.50 tips 8 cash +ledger xact 4/9 viva food $11.50 tips $8 cash +ledger xact 4/9 viva dining "DM 11.50" +@end example + @menu * Budgeting and Forecasting:: @end menu -@node Budgeting and Forecasting, , Basic Reporting Commands, Basic Reporting Commands +@node Budgeting and Forecasting, , xact, Basic Reporting Commands @section Budgeting and Forecasting @@ -2169,7 +2321,410 @@ considered a primary. In fact, when Ledger goes about ensures that all transactions balance to zero, it only ever asks this of primary commodities. -@node Extending with Python, , Journal File Format, Top +@node Extending with Python, Example Data File, Journal File Format, Top @chapter Extending with Python +@node Example Data File, Miscellaneous Notes, Extending with Python, Top +@appendix Example Journal File: drewr.dat + The following journal file is included with the source distribution of + ledger. It is called @file{drewr.dat} and exhibits many ledger + features, include automatic and virtual transactions, +@example +; -*- ledger -*- + += account =~ /^Income/ + (Liabilities:Tithe) 0.12 + +~ Monthly + Assets:Checking $500.00 + Income:Salary + +2003/12/01 * Checking balance + Assets:Checking $1,000.00 + Equity:Opening Balances + +2003/12/20 Organic Co-op + Expenses:Food:Groceries $ 37.50 ; [=2004/01/01] + Expenses:Food:Groceries $ 37.50 ; [=2004/02/01] + Expenses:Food:Groceries $ 37.50 ; [=2004/03/01] + Expenses:Food:Groceries $ 37.50 ; [=2004/04/01] + Expenses:Food:Groceries $ 37.50 ; [=2004/05/01] + Expenses:Food:Groceries $ 37.50 ; [=2004/06/01] + Assets:Checking $ -225.00 + +2003/12/28=2004/01/01 Acme Mortgage + Liabilities:Mortgage:Principal $ 200.00 + Expenses:Interest:Mortgage $ 500.00 + Expenses:Escrow $ 300.00 + Assets:Checking $ -1000.00 + +2004/01/02 Grocery Store + Expenses:Food:Groceries $ 65.00 + Assets:Checking + +2004/01/05 Employer + Assets:Checking $ 2000.00 + Income:Salary + +2004/01/14 Bank + ; Regular monthly savings transfer + Assets:Savings $ 300.00 + Assets:Checking + +2004/01/19 Grocery Store + Expenses:Food:Groceries $ 44.00 + Assets:Checking + +2004/01/25 Bank + ; Transfer to cover car purchase + Assets:Checking $ 5,500.00 + Assets:Savings + ; :nobudget: + +2004/01/25 Tom's Used Cars + Expenses:Auto $ 5,500.00 + ; :nobudget: + Assets:Checking + +2004/01/27 Book Store + Expenses:Books $20.00 + Liabilities:MasterCard + +2004/02/01 Sale + Assets:Checking:Business $ 30.00 + Income:Sales + +@end example + +@node Miscellaneous Notes, , Example Data File, Top +@appendix Miscellaneous Notes + +Various notes from the discussion list that I haven't incorporated in to the main body of the documentation. + +@menu +* Commodity Pricing Problem:: +@end menu + +@node Commodity Pricing Problem, , Miscellaneous Notes, Miscellaneous Notes +@section Commodity Pricing Problem + +Sun, 26 Dec 2010 04:13:04 -0800 + +One of the things which stalled Ledger development recently is that I'd never +found a truly satisfying way to handle the "commodity pricing problem". That +is, the current day value of a commodity can mean different things to +different people, depending on the accounts involved, the commodities, the +nature of the transactions, etc. + +After experimenting with several different concepts and syntaxes, I found none +of them were either satisfying or general enough. My one attempt at providing +"fixated prices" was too specific, and too inelegant for many usage patterns. + +This morning, however, I think I've finally cracked this nut; and in a way +which fits harmoniously into the Ledger architecture as if it were meant to be +there all along... + +Here's how the new scheme will work: When a user specifies '-V', or '-X COMM', +they are requesting that some or all of the commodities in their Ledger file +be valuated as of today (or whatever --now is set to). But what does such a +valuation mean? This meaning shall be governed by the presence of a "VALUE" +metadata property, whose content is an expression used to compute that value. + +If no VALUE property is specified, each posting is assumed to have a default, +as if you'd specified a global, automated transaction as follows: + +@smallexample + = expr true + ; VALUE:: market(amount, date, exchange) +@end smallexample +This definition emulates the present day behavior of -V and -X (in the case of +-X, the requested commodity is passed via the string 'exchange' above). + +One thing many people have wanted to do is to fixate the valuation of old +European currencies in terms of the Euro after a certain date: + +@smallexample + = expr commodity == "DM" + ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR +@end smallexample + +This says: If --now is some old date, use market prices as they were at that +time; but if --now is past June 2008, use a fixed price for converting Deutsch +Mark to Euro. + +Or how about never re-valuating commodities used in Expenses, since they +cannot have a different future value: + +@smallexample + = /^Expenses:/ + ; VALUE:: market(amount, post.date, exchange) +@end smallexample + +This says the future valuation is the same as the valuation at the time of +posting. post.date equals the posting's date, while just 'date' is the value +of --now (defaults to today). + +Or how about valuating miles based on a reimbursement rate during a specific +time period: + + +@smallexample + = expr commodity == "miles" and date >= [2007] and date < [2008] + ; VALUE:: market($1.05, date, exchange) +@end smallexample + +In this case, miles driven in 2007 will always be valuated at $1.05 each. If +you use -X EUR to expressly request all amounts in Euro, Ledger shall convert +$1.05 to Euro by whatever means are appropriate for dollars. + +Note that you can have a valuation expression specific to a particular posting +or transaction, by overriding these general defaults using specific metadata: + +@smallexample + + 2010-12-26 Example + Expenses:Food $20 + ; Just to be silly, always valuate *these* $20 as 30 DM, no matter what + ; the user asks for with -V or -X + ; VALUE:: 30 DM + Assets:Cash +@end smallexample + +This example demonstrates that your VALUE expression should be as symbolic as +possible, using terms like 'amount' and 'date', rather than specific amounts +and dates. Also, you should pass the amount along to the function 'market' so +it can be further revalued if the user has asked for a specific currency. + +Or, if it better suits your accounting, you can be less symbolic, which allows +you to report most everything in EUR if you use -X EUR, except for certain +accounts or postings which should always be valuated in another currency. For +example: + +@smallexample + = /^Assets:Brokerage:CAD$/ + ; Always report the value of commodities in this account in terms of + ; present day dollars, despite what was asked for on the command-line + ; VALUE:: market(amount, date, '$') +@end smallexample + +I think this scheme, of using predicated value expressions which can be +generalized in automated transactions, and made specific via transaction and +posting-based metadata, provides sufficient flexibility to express most of the +use cases which have occurred on this topic. + + +Ledger presently has no way of handling such things as FIFO and LIFO. + +If you specify an unadorned commodity name, like AAPL, it will balance +against itself. If --lots are not being displayed, then it will appear +to balance against any lot of AAPL. + +If you specify an adorned commodity, like AAPL @{$10.00@}, it will also +balance against itself, and against any AAPL if --lots is not specified. +But if you do specify --lot-prices, for example, then it will balance +against that specific price for AAPL. + +I may, for the sake of reporting *only*, be able to implement some sort +of guessing strategy, based on the order in which transactions appear in +the data file... But I'll have to think about this a lot more, and it +would be a 3.1 thing. + +> b) I don't see how this VALUE property can differentiate between -V +> and -B. Does this imply that you want to get rid of the -B option and +> simply let users define what VALUE they get with -V? If so, I think +> this would be a bad idea... I really like the ability to see different +> valuation methods using command line options (i.e. -B for cost basis +> and -V for market value). (Incidentally, while I initially liked your +> example of using the posting date for Expenses, I later realized that +> I sometimes use -V to see what my expenses (in a foreign currency) +> would have been if I bought everything at today's exchange rate.) + +-V and -B are entirely unrelated. Perhaps I could support a BASIS +property setting, for customizing -B in the same way VALUE +customizes -V... + +> c) I never fully understood what -X does exactly but afaik -X is a +> special version of -V. However, I believe that -X should _only_ do +> conversion. This would allow -X to be combined with other options, +> such as -X and -V. Example: let's say I bought 10 shares for 10.00 +> GBP and they are now worth 15.00. Because my main assets are in EUR, +> I want to see what those shares are worth in EUR. Since I'm +> conservative I want to see the cost basis, i.e. I want to use -B and +> -X EUR together. (This actually works today but I'm told this is an +> accident and won't work in all cases.) + +-V asks for the present day value of all commodities, and lets Ledger +pick the target commodity based on its own hueristics. -X is the same +as -V, except that it overrides those hueristics and forces the target +commodity. (Although, as you've seen, the VALUE property could now +countermand that). + +There are reasons why -X can't be applied to any report. Mainly it has +to do with rounding. For example, let's say I have 10 postings that +each trade 1 DM, and the value of 1 DM is 0.001 EUR. If I add all +10 DM and then apply -X, I get 0.01 EUR. But if I apply -X to each +1 DM and *then* total them, I get 0.00 EUR. + +This becomes very important to Ledger because -X is applied to totals, +not just to individual amounts. I'm going to have to use some magic +internally to avoid this problem with the VALUE property (in most, but +not all, cases). + +And so, -X gets applied after, when the posting-origin of the +commodities has been lost -- required information if a basis cost +calculation is to be deferred. + +The alternative would involve ever-growing lists of individual amounts, +which would slow many parts of Ledger from O(N) to O(N^2). Plus, it +still wouldn't solve the rounding problem. + + +> Ledger presently has no way of handling such things as FIFO and LIFO. + +Yeah, I know... but I think it's a feature that ledger should +eventually get (obviously not for 3.0). + +> If you specify an adorned commodity, like AAPL @{$10.00@}, it will also +> balance against itself, and against any AAPL if --lots is not specified. +> But if you do specify --lot-prices, for example, then it will balance +> against that specific price for AAPL. +> +> I may, for the sake of reporting *only*, be able to implement some sort +> of guessing strategy, based on the order in which transactions appear in +> the data file... + +Why for reporting only? It seems to me that ledger has all the +information to do FIFO and LIFO properly (i.e. to remove the right +commodities from the list). Let's take this example: + +@smallexample + +2011-01-01 * Buy AAA + Assets:Shares 5 AAA @ 10.00 EUR + Assets:Cash + +2011-01-03 * Buy AAA + Assets:Shares 2 AAA @ 10.00 EUR + Assets:Cash + +2011-01-11 * Buy AAA + Assets:Shares 5 AAA @ 12.00 EUR + Assets:Cash + +2011-01-21 * Buy AAA + Assets:Shares 5 AAA @ 13.00 EUR + Assets:Cash +@end smallexample + +So we end up with (ledger --lots): + +@smallexample +5 AAA @{10.00 EUR@} [2011/01/01] +2 AAA @{10.00 EUR@} [2011/01/03] +5 AAA @{12.00 EUR@} [2011/01/11] +5 AAA @{13.00 EUR@} [2011/01/21] Assets:Shares +@end smallexample + +So if I sell 6 shares now, according to FIFO, I would do: + +@smallexample +2011-02-01 * Sell AAA + Assets:Shares -5 AAA @{10.00 EUR@} [2011/01/01] @ +13.50 EUR + Assets:Shares -1 AAA @{10.00 EUR@} [2011/01/03] @ +13.50 EUR + Assets:Cash +@end smallexample + +ledger --lots: + +@smallexample +1 AAA @{10.00 EUR@} [2011/01/03] +5 AAA @{12.00 EUR@} [2011/01/11] +5 AAA @{13.00 EUR@} [2011/01/21] Assets:Shares +@end smallexample + +According to LIFO, I would do this instead: + +@smallexample +2011-02-01 * Sell AAA + Assets:Shares -5 AAA @{13.00 EUR@} [2011/01/21] @ +13.50 EUR + Assets:Shares -1 AAA @{12.00 EUR@} [2011/01/11] @ +13.50 EUR + Assets:Cash +@end smallexample + +In other words, you can manually do FIFO and LIFO with ledger already. +However, it would be great if ledger would make this easier, e.g. that +you could specify: + +@smallexample + 2011-02-01 * Sell AAA + Assets:Shares -6 AAA @{FIFO@} @ 13.50 EUR + Assets:Cash +@end smallexample + +and ledger would iterate through all AAA commodities and take out the +right ones (after all, it knows the date and price). + +The only thing I don't think is possible with ledger at the moment is +average cost. I'm also not sure how --lot-dates should behave for +average cost. + +> There are reasons why -X can't be applied to any report. Mainly it has +> to do with rounding. For example, let's say I have 10 postings that +> each trade 1 DM, and the value of 1 DM is 0.001 EUR. If I add all +> 10 DM and then apply -X, I get 0.01 EUR. But if I apply -X to each +> 1 DM and *then* total them, I get 0.00 EUR. + +Thanks for the explanation... what I was thinking of is that ledger +would just produce a report according to -V or -B or whatever and +*then* convert it with -X. I use a shell script to do this for now: + +@smallexample +GBP2EUR="117/100" + +eurgbp=$(ledger -f $FILE -p "until $YEAR-$NEXT_MONTH-01" -B bal "^assets" +"^liabilities" | egrep " (EUR|GBP)$" | tail -n 2) +eur=$(echo "$eurgbp" | grep "EUR" | sed 's/ EUR//') +gbp=$(echo "$eurgbp" | grep "GBP" | sed 's/ GBP//') +eur=$(echo "$eur" | sed 's/\..*//') +gbp=$(echo "$gbp" | sed 's/\..*//') +gbpineur=$(($gbp*$GBP2EUR)) +echo " " $(($eur + $gbpineur)) " EUR Total" +@end smallexample + +I'm kinda surprised that you no longer think it's a good idea to split +-X from -V. Last time I brought this up on IRC, you thought it was a +good idea: + +@smallexample +10:44 < johnw> I think having -H, in addition to -X, may make what you want + to see both natural and simple +10:45 < johnw> you'd use -H for income/expense accounts, and -X for + assets/liabilities +10:45 < johnw> -H = historical values +10:45 < johnw> -X = current exchange values +10:45 < tbm> so what's the difference between -X and -V again? +10:45 < johnw> -V is an automated version of -X +10:45 < johnw> it tries to figure out what the reported commodity should be +10:45 < johnw> we may then need an automated version of -H, to complete the + reflection +10:46 < johnw> btw, this is just an inside-out version of my "final" + feature :) +10:46 < tbm> why not change the meaning of -X to _only do conversion_? And + then you could combine -X with -B, -V or -H +10:46 < johnw> instead of having it be syntactic, we're moving the semantic + difference to a difference in options +10:46 < johnw> oh HMM +10:46 < johnw> -X with -B, -V and -I +10:46 < johnw> (and -O, incidentally) +10:46 < johnw> O = amount, B = cost, V = market value, I = price +10:47 < johnw> that's really an excellent suggestion +10:48 < johnw> i'd still need a flag to mean "historical" vs "current" +10:48 < johnw> as well as "target commodity" (-X) +@end smallexample + + @bye diff --git a/test/input/drewr.dat b/test/input/drewr.dat index 13b88844..b930de82 100644 --- a/test/input/drewr.dat +++ b/test/input/drewr.dat @@ -1,9 +1,9 @@ ; -*- ledger -*- -= account =~ /^Income/ += /^Income/ (Liabilities:Tithe) 0.12 -~ Monthly +~ monthly in 2004 Assets:Checking $500.00 Income:Salary From f9b114c503c631825c376564b1926032ed9557aa Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 28 Sep 2011 22:54:16 -0700 Subject: [PATCH 09/28] added description of periodic transactions and moved budgeting to a separate chapter --- doc/Ledger3.texi | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/Ledger3.texi b/doc/Ledger3.texi index 0026ecb1..b4ad13f7 100644 --- a/doc/Ledger3.texi +++ b/doc/Ledger3.texi @@ -71,6 +71,7 @@ twinkling in their father's CRT. * Keeping a Journal:: * Command-line Syntax:: * Basic Reporting Commands:: +* Budgeting and Forecasting:: * Value Expressions:: * Format Strings:: * Journal File Format:: @@ -749,6 +750,11 @@ which may be excluded from reports by using @option{--real}. @node Periodic Transactions, , Automatic Transactions, Advanced Transactions @subsection Periodic Transactions +A periodic transaction starts with a ~ followed by a period expression. +Periodic transactions are used for budgeting and forecasting only, they +have no effect withouth the @samp{--budget} option specified. + +See @ref{Budgeting and Forecasting} for exmaples and details. @node File Format, Archiving Previous Years , Advanced Transactions, Keeping a Journal @section File Format for Users @@ -1523,7 +1529,7 @@ weekly last august @end example -@node Basic Reporting Commands, Value Expressions, Command-line Syntax, Top +@node Basic Reporting Commands, Budgeting and Forecasting, Command-line Syntax, Top @chapter Basic Reporting Commands @menu * balance:: @@ -1535,7 +1541,6 @@ weekly last august * equity:: * prices:: * xact:: -* Budgeting and Forecasting:: @end menu @node balance, register, Basic Reporting Commands, Basic Reporting Commands @@ -1636,7 +1641,7 @@ There is also a @command{pricesdb} command which outputs the same information as @command{prices}, but does in a format that can be parsed by LEDGER. -@node xact, Budgeting and Forecasting, prices, Basic Reporting Commands +@node xact, , prices, Basic Reporting Commands @section xact The @command{xact} commands simplifies the creation of new transactions. @@ -1697,11 +1702,11 @@ ledger xact 4/9 viva dining "DM 11.50" * Budgeting and Forecasting:: @end menu -@node Budgeting and Forecasting, , xact, Basic Reporting Commands -@section Budgeting and Forecasting +@node Budgeting and Forecasting, Value Expressions, Basic Reporting Commands, Top +@chapter Budgeting and Forecasting -@node Value Expressions, Format Strings, Basic Reporting Commands, Top +@node Value Expressions, Format Strings, Budgeting and Forecasting, Top @chapter Value Expressions Value expressions are an expression language used by LEDGER to From 0155d67b4faee3ee464f923ca0371ae3891c6648 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 28 Sep 2011 22:55:11 -0700 Subject: [PATCH 10/28] corrected drewr.dat for V3 automatic transaction syntax --- doc/Ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Ledger3.texi b/doc/Ledger3.texi index b4ad13f7..c3a2e183 100644 --- a/doc/Ledger3.texi +++ b/doc/Ledger3.texi @@ -2337,7 +2337,7 @@ commodities. @example ; -*- ledger -*- -= account =~ /^Income/ += /^Income/ (Liabilities:Tithe) 0.12 ~ Monthly From 3dd22719a854d5ae7f75c0fbfa431741507f3ad3 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Thu, 29 Sep 2011 07:55:32 -0700 Subject: [PATCH 11/28] updated to work with V3 --- doc/Ledger3.texi | 9 +++--- test/input/drewr3.dat | 67 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+), 4 deletions(-) create mode 100644 test/input/drewr3.dat diff --git a/doc/Ledger3.texi b/doc/Ledger3.texi index c3a2e183..ae614f56 100644 --- a/doc/Ledger3.texi +++ b/doc/Ledger3.texi @@ -266,10 +266,11 @@ You can also find help at the @samp{#ledger} channel on the IRC server @section Start a Journal File A journal is a record of your financial transactions and will be central -to using LEDGER. For now we just want to get a teast -of what ledger can do. An example journal is included with the source -code distribution, called @file{drewr.dat} (it is copied in @pxref{Example Data File}). -Copy it someplace convenient and open up a terminal window in that directory. +to using LEDGER. For now we just want to get a taste of what LEDGER can +do. An example journal is included with the source code distribution, +called @file{drewr3.dat} (it is copied in @pxref{Example Data File}). +Copy it someplace convenient and open up a terminal window in that +directory. If you would rather start with your own journal right away please skip to @xref{Keeping a Journal}. diff --git a/test/input/drewr3.dat b/test/input/drewr3.dat new file mode 100644 index 00000000..ca4fc6cf --- /dev/null +++ b/test/input/drewr3.dat @@ -0,0 +1,67 @@ +; -*- ledger -*- + += /^Income/ + (Liabilities:Tithe) 0.12 + +~ Monthly + Assets:Checking $500.00 + Income:Salary + +~ Monthly + Expenses:Food $100 + Assets + +2010/12/01 * Checking balance + Assets:Checking $1,000.00 + Equity:Opening Balances + +2010/12/20 Organic Co-op + Expenses:Food:Groceries $ 37.50 ; [=2011/01/01] + Expenses:Food:Groceries $ 37.50 ; [=2011/02/01] + Expenses:Food:Groceries $ 37.50 ; [=2011/03/01] + Expenses:Food:Groceries $ 37.50 ; [=2011/04/01] + Expenses:Food:Groceries $ 37.50 ; [=2011/05/01] + Expenses:Food:Groceries $ 37.50 ; [=2011/06/01] + Assets:Checking $ -225.00 + +2010/12/28=2011/01/01 Acme Mortgage + Liabilities:Mortgage:Principal $ 200.00 + Expenses:Interest:Mortgage $ 500.00 + Expenses:Escrow $ 300.00 + Assets:Checking $ -1000.00 + +2011/01/02 Grocery Store + Expenses:Food:Groceries $ 65.00 + Assets:Checking + +2011/01/05 Employer + Assets:Checking $ 2000.00 + Income:Salary + +2011/01/14 Bank + ; Regular monthly savings transfer + Assets:Savings $ 300.00 + Assets:Checking + +2011/01/19 Grocery Store + Expenses:Food:Groceries $ 44.00 + Assets:Checking + +2011/01/25 Bank + ; Transfer to cover car purchase + Assets:Checking $ 5,500.00 + Assets:Savings + ; :nobudget: + +2011/01/25 Tom's Used Cars + Expenses:Auto $ 5,500.00 + ; :nobudget: + Assets:Checking + +2011/01/27 Book Store + Expenses:Books $20.00 + Liabilities:MasterCard + +2011/12/01 Sale + Assets:Checking:Business $ 30.00 + Income:Sales From bc35c6c07c62dea99a1b93b3704da5f8ca5023db Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Sun, 2 Oct 2011 21:10:21 -0700 Subject: [PATCH 12/28] Ready for first publication --- doc/Ledger3.texi | 1283 ++++++++++++++++++++++++++--------------- doc/gendocs.sh | 5 + test/input/drewr3.dat | 14 +- 3 files changed, 816 insertions(+), 486 deletions(-) create mode 100755 doc/gendocs.sh diff --git a/doc/Ledger3.texi b/doc/Ledger3.texi index ae614f56..d80dc57c 100644 --- a/doc/Ledger3.texi +++ b/doc/Ledger3.texi @@ -214,11 +214,11 @@ formatted as the LEDGER program wishes to see them: The account balances and registers in this file, if saved as @file{ledger.dat}, could be reported using: -@example +@smallexample $ ledger -f ledger.dat balance $ ledger -f ledger.dat register checking -$ ledger -f ledger.dat register bell -@end example +$ ledger -f ledger.dat register Bell +@end smallexample An important difference between LEDGER and other finance packages is that journal will never alter your input file. You can create and edit @@ -237,9 +237,9 @@ make and gcc 3.3, on a PowerBook running OS/X. To build and install once you have these libraries on your system, enter these commands: -@example +@smallexample ./configure && make install -@end example +@end smallexample @node Getting Help, , Building the Program, Introduction to Ledger @section Getting help @@ -247,9 +247,9 @@ enter these commands: If you need help on how to use LEDGER, or run into problems, you can join the LEDGER mailing list at the following Web address: -@example +@smallexample http://groups.google.com/group/ledger-cli -@end example +@end smallexample You can also find help at the @samp{#ledger} channel on the IRC server @samp{irc.freenode.net}. @@ -260,6 +260,7 @@ You can also find help at the @samp{#ledger} channel on the IRC server @menu * Start a Journal:: * Run Some Reports:: +* Command Line Quick Reference:: @end menu @node Start a Journal, Run Some Reports, Ledger Tutorial , Ledger Tutorial @@ -268,23 +269,33 @@ You can also find help at the @samp{#ledger} channel on the IRC server A journal is a record of your financial transactions and will be central to using LEDGER. For now we just want to get a taste of what LEDGER can do. An example journal is included with the source code distribution, -called @file{drewr3.dat} (it is copied in @pxref{Example Data File}). +called @file{drewr3.dat} (@pxref{Example Data File}). Copy it someplace convenient and open up a terminal window in that directory. If you would rather start with your own journal right away please skip to @xref{Keeping a Journal}. -@node Run Some Reports, , Start a Journal, Ledger Tutorial +@node Run Some Reports, Command Line Quick Reference, Start a Journal, Ledger Tutorial @section Run a Few Reports + +@menu +* Balance Report:: +* Register Report:: +* Cleared Report:: +@end menu + +@node Balance Report, Register Report, Run Some Reports, Run Some Reports @subsection Balance Report -Run this command: +To find the balances of all of your accounts, run this command: + @smallexample -ledger -f drewr.dat balance +ledger -f drewr3.dat balance @end smallexample LEDGER will generate: + @smallexample $ -3,804.00 Assets $ 1,396.00 Checking @@ -308,6 +319,237 @@ LEDGER will generate: $ -243.60 @end smallexample +@noindent Showing you the balance of all accounts. Options and search terms can pare this down to show only the accounts you want. + +A more useful report is to show only your Assets and Liabilities: + +@smallexample +$ ledger -f drewr3.dat balance Assets Liabilities + $ -3,804.00 Assets + $ 1,396.00 Checking + $ 30.00 Business + $ -5,200.00 Savings + $ -63.60 Liabilities + $ -20.00 MasterCard + $ 200.00 Mortgage:Principal + $ -243.60 Tithe +-------------------- + $ -3,867.60 +@end smallexample + + +@node Register Report, Cleared Report, Balance Report, Run Some Reports +@subsection Register Report + +To show all transactions and a running total: +@smallexample +ledger -f drewr3.dat register +@end smallexample + +LEDGER will generate: + +@smallexample +10-Dec-01 Checking balance Assets:Checking $ 1,000.00 $ 1,000.00 + Equity:Opening Balances $ -1,000.00 0 +10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 + Expense:Food:Groceries $ 37.50 $ 75.00 + Expense:Food:Groceries $ 37.50 $ 112.50 + Expense:Food:Groceries $ 37.50 $ 150.00 + Expense:Food:Groceries $ 37.50 $ 187.50 + Expense:Food:Groceries $ 37.50 $ 225.00 + Assets:Checking $ -225.00 0 +10-Dec-28 Acme Mortgage Lia:Mortgage:Principal $ 200.00 $ 200.00 + Expe:Interest:Mortgage $ 500.00 $ 700.00 + Expenses:Escrow $ 300.00 $ 1,000.00 + Assets:Checking $ -1,000.00 0 +11-Jan-02 Grocery Store Expense:Food:Groceries $ 65.00 $ 65.00 + Assets:Checking $ -65.00 0 +11-Jan-05 Employer Assets:Checking $ 2,000.00 $ 2,000.00 + Income:Salary $ -2,000.00 0 + (Liabilities:Tithe) $ -240.00 $ -240.00 +11-Jan-14 Bank Assets:Savings $ 300.00 $ 60.00 + Assets:Checking $ -300.00 $ -240.00 +11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ -196.00 + Assets:Checking $ -44.00 $ -240.00 +11-Jan-25 Bank Assets:Checking $ 5,500.00 $ 5,260.00 + Assets:Savings $ -5,500.00 $ -240.00 +11-Jan-25 Tom's Used Cars Expenses:Auto $ 5,500.00 $ 5,260.00 + Assets:Checking $ -5,500.00 $ -240.00 +11-Jan-27 Book Store Expenses:Books $ 20.00 $ -220.00 + Liabilities:MasterCard $ -20.00 $ -240.00 +11-Dec-01 Sale Asse:Checking:Business $ 30.00 $ -210.00 + Income:Sales $ -30.00 $ -240.00 + (Liabilities:Tithe) $ -3.60 $ -243.60 +@end smallexample + +@noindent To limit this to a more useful subset, simply add the accounts you are are interested in seeing transactions for: + +@smallexample +$ ledger -f drewr3.dat register Groceries +10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 + Expense:Food:Groceries $ 37.50 $ 75.00 + Expense:Food:Groceries $ 37.50 $ 112.50 + Expense:Food:Groceries $ 37.50 $ 150.00 + Expense:Food:Groceries $ 37.50 $ 187.50 + Expense:Food:Groceries $ 37.50 $ 225.00 +11-Jan-02 Grocery Store Expense:Food:Groceries $ 65.00 $ 290.00 +11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ 334.00 +@end smallexample + +@noindent Which matches the balance reported for the @samp{Groceries} account: + +@smallexample +$ ledger -f drewr3.dat balance Groceries + $ 334.00 Expenses:Food:Groceries +@end smallexample + +@node Cleared Report, , Register Report, Run Some Reports +@subsection Cleared Report + +A very useful report is to show what your obligations are versus what +expenditures have actually been recorded. It can take several days for +a check to clear, but you should treat it as money spent. The +@samp{cleared} report shows just that: + +@smallexample +$ ledger -f drewr3.dat cleared + $ -3,804.00 $ 775.00 Assets + $ 1,396.00 $ 775.00 10-Dec-20 Checking + $ 30.00 0 Business + $ -5,200.00 0 Savings + $ -1,000.00 $ -1,000.00 10-Dec-01 Equity:Opening Balances + $ 6,654.00 $ 225.00 Expenses + $ 5,500.00 0 Auto + $ 20.00 0 Books + $ 300.00 0 Escrow + $ 334.00 $ 225.00 10-Dec-20 Food:Groceries + $ 500.00 0 Interest:Mortgage + $ -2,030.00 0 Income + $ -2,000.00 0 Salary + $ -30.00 0 Sales + $ -63.60 0 Liabilities + $ -20.00 0 MasterCard + $ 200.00 0 Mortgage:Principal + $ -243.60 0 Tithe +---------------- ---------------- --------- + $ -243.60 0 +@end smallexample + +@noindent The first column shows the outstanding balance, the second column show the ``cleared'' balance. + +@node Command Line Quick Reference, , Run Some Reports, Ledger Tutorial +@section Command Line Quick Reference + +@menu +* Reporting Commands:: +* Basic Options:: +* Report Filtering:: +* Output Customization:: +* Commodity Reporting:: +@end menu + +@node Reporting Commands, Basic Options, Command Line Quick Reference, Command Line Quick Reference +@subsection Reporting Commands +@multitable @columnfractions .2 .8 +@item @strong{Report} @tab @strong{Description} +@item @code{balance} @tab Show account balances +@item @code{register} @tab Show all transactions with running total +@item @code{print} @tab Print transaction in a ledger readable format +@item @code{output} @tab Similar to print without included transactions +@item @code{xml} @tab Produce XML output of the register command +@item @code{emacs} @tab Produce emacs lisp output +@item @code{equity} @tab Print account balances as transactions +@item @code{prices} @tab Print price history for matching commodities +@item @code{pricesdb} @tab Print price history for matching commodities in ledger readable format +@item @code{xact} @tab Used to generate transactions based on previous postings +@end multitable + +@node Basic Options, Report Filtering, Reporting Commands, Command Line Quick Reference +@subsection Basic Options +@multitable @columnfractions .1 .25 .65 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{-h} @tab @code{--help} @tab prints summary of all options +@item @code{-v} @tab @code{--version} @tab prints version of ledger executable +@item @code{-f FILE} @tab @code{--file FILE} @tab read @file{FILE} as a ledger file +@item @code{-o FILE} @tab @code{--output FILE} @tab redirects output to @file{FILE} +@item @code{-i FILE} @tab @code{--init-file FILE} @tab specify options file +@item @tab @code{--cache FILE} @tab specify binary cache file +@item @code{-a NAME} @tab @code{--account NAME} @tab specify default account name for QIF file postings +@end multitable + +@node Report Filtering, Output Customization, Basic Options, Command Line Quick Reference +@subsection Report Filtering +@multitable @columnfractions .1 .25 .65 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{-c} @tab @code{--current} @tab Display transaction on or before the current date +@item @code{-b DATE} @tab @code{--begin DATE} @tab Begin reports on or after @code{DATE} +@item @code{-e DATE} @tab @code{--end DATE} @tab Limits end date od transactions for report +@item @code{-p STR} @tab @code{--period} @tab Set report period to STR +@item @code{ } @tab @code{--period-sort} @tab Sort postings within each period +@item @code{-C} @tab @code{--cleared} @tab Display only cleared postings +@item @code{-U} @tab @code{--uncleared} @tab Display only uncleared postings +@item @code{-R} @tab @code{--real} @tab Display only real postings +@item @code{-L} @tab @code{--actual} @tab Displays only actual postings, not automated +@item @code{-r} @tab @code{--related} @tab Display related postings +@item @code{} @tab @code{--budget} @tab Display how close your postings meet your budget +@item @code{} @tab @code{--add-budget} @tab Shows unbudgeted postings +@item @code{} @tab @code{--unbedgeted} @tab Shows only unbudgeted postings +@item @code{} @tab @code{--forecast} @tab Project balances into the future +@item @code{-l EXPR} @tab @code{--limit EXPR} @tab Limits postings in calculations +@item @code{-t EXPR} @tab @code{--amount} @tab Change value expression reported in register report +@item @code{-T EXPR} @tab @code{--total} @tab Change the value expression used for ``totals'' column in register and balance reports +@end multitable + +@node Output Customization, Commodity Reporting, Report Filtering, Command Line Quick Reference +@subsection Output Customization +@multitable @columnfractions .15 .4 .45 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{-n} @tab @code{--collapse} @tab Collapse transactions with multiple postings +@item @code{-s} @tab @code{--subtotal} @tab Report register as a single subtotal +@item @code{-P} @tab @code{--by-payee} @tab Report subtotals by payee +@item @code{-x} @tab @code{--comm-as-payee} @tab Change the payee of every posting to be the commodity used in that posting +@item @code{-E} @tab @code{--empty} @tab Include empty accounts in report +@item @code{-W} @tab @code{--weekly} @tab Report posting totals by week +@item @code{-Y} @tab @code{--yearly} @tab Report posting totals by year +@item @code{} @tab @code{--dow} @tab report Posting totals by day of week +@item @code{-S EXPR} @tab @code{--sort EXPR} @tab Sorts a report using @code{EXPR} +@item @code{-w} @tab @code{--wide} @tab Assume 132 columns instead of 80 +@item @code{} @tab @code{--head N} @tab Report the first N postings +@item @code{} @tab @code{--tail N} @tab Report the last N postings +@item @code{} @tab @code{--pager prog} @tab Direct output @code{prog} pager program +@item @code{-A} @tab @code{--average} @tab Reports average posting value +@item @code{-D} @tab @code{--deviation} @tab Reports each posting deviation from the average +@item @code{-%} @tab @code{--percentage} @tab Show subtotals in the balance report as percentages +@item @code{} @tab @code{--totals} @tab Include running total in the @code{xml} report +@item @code{-j} @tab @code{--amount-data} @tab Show only date and value column +@item @code{-J} @tab @code{--total-data} @tab Show only dates and totals +@item @code{-d EXPR} @tab @code{--display EXPR} @tab Limit only the display of certain postings +@item @code{-y STR} @tab @code{--date-format STR} @tab Change the basic date format used in reports +@item @code{-F STR} @tab @code{--format STR} @tab Set reporting format +@item @code{} @tab @code{--balance-format STR} @tab +@item @code{} @tab @code{--register-format STR} @tab +@item @code{} @tab @code{--print-format STR} @tab +@item @code{-j register} @tab @code{--plot-amount-format STR} @tab +@item @code{-J register} @tab @code{--plot-total-format STR} @tab +@item @code{} @tab @code{--equity-format STR} @tab +@item @code{} @tab @code{--prices-format STR} @tab +@item @code{-w register} @tab @code{--wide-register-format STR} @tab +@end multitable + +@node Commodity Reporting, , Output Customization, Command Line Quick Reference +@subsection Commodity Reporting + +@multitable @columnfractions .1 .25 .65 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{} @tab @code{--price-db FILE} @tab Use @file{FILE} for retrieving downloaded commodity prices +@item @code{-L MINS} @tab @code{--price-exp MINS} @tab Set expected freshness of prices in minutes +@item @code{-Q} @tab @code{--download} @tab Download quotes using @code{getquote} +@item @code{-O} @tab @code{--quantity} @tab Report commodity totals without conversion +@item @code{-B} @tab @code{--basis} @tab Report cost basis +@item @code{-V} @tab @code{--market} @tab Report last known market value +@item @code{-G} @tab @code{--gain} @tab Report net gain loss for commodities that have a price history +@end multitable + @node Principles of Accounting, Keeping a Journal, Ledger Tutorial , Top @chapter Principles of Accounting @@ -401,10 +643,10 @@ calculating} LEDGER is agnostic when it comes to how you value your accounts. Dollars, Euros, Pounds, Francs, Shares etc. are just ``commodities''. Holdings in stocks, bonds, mutual funds and other financial instruments -can be label using whatever is convenient for you (stock ticker symbols -are suggested for publicly traded assets).@footnote{you can track -ANYTHING, even time. As long as it cannot be created or destroyed inside -your accounting system.} +can be labelled using whatever is convenient for you (stock ticker +symbols are suggested for publicly traded assets).@footnote{you can +track ANYTHING, even time or distance travelled. As long as it cannot be +created or destroyed inside your accounting system.} For the rest of this manual, we will only use the word ``commodities'' when refering to the units on a transaction value. @@ -433,11 +675,12 @@ business trip to Europe from the US: @end smallexample This says that $66.00 came out of checking and turned into 50 Euros. The -implied exchange rate was $1.32. Then 35.00 Euros was spent on Dinner in Munich. +implied exchange rate was $1.32. Then 35.00 Euros was spent on Dinner +in Munich. Running a ledger balance report shows: @smallexample -macbook-2:$ ledger -f example.dat bal +$ ledger -f example.dat bal $-66.00 E15.00 Assets E15.00 Cash @@ -454,6 +697,7 @@ checking account) and E15.00. After spending on dinner i have E15.00 in my wallet. The bottom line balances to zero, but is shown in two lines since we haven't told ledger to convert commodities. + @node Structuring Your Accounts, Advanced Transactions, Currency and Commodities, Keeping a Journal @section Structuring your Accounts @@ -464,24 +708,23 @@ system. At the highest level you have five sorts of accounts: @enumerate @item -Expenses, where money goes +Expenses: where money goes @item -Assets, where money sits +Assets: where money sits @item -Income, where moeny comes from +Income: where moeny comes from @item -Liabilities, money you owe +Liabilities: money you owe @item -Equity, the real value of your property. +Equity: the real value of your property. @end enumerate Starting the structure off this way will make it simpler for you to get answers to the questions you really need to ask about your finances. Beneath these top level accounts you can have any level of detail you -desire. If you want to keep specific track of how much you spend on +desire. For example, if you want to keep specific track of how much you spend on burgers and fries, you could have the following: - @smallexample Expenses:Food:Hamburgers and Fries @end smallexample @@ -497,6 +740,8 @@ Expenses:Food:Hamburgers and Fries * Virtual Transactions:: * Automatic Transactions:: * Periodic Transactions:: +* Recording Commodity Lot Prices:: +* Commodity Pricing Problem:: @end menu @node Transaction Notes and Tags, Multiple Account Transactions, Advanced Transactions, Advanced Transactions @@ -710,9 +955,9 @@ When ready to pay, just write a check to cover the amount shown in That's it. To see how much Huqúq is currently owed based on your ledger transactions, use: -@example +@smallexample ledger balance Liabilities:Huquq -@end example +@end smallexample This works fine, but omits one aspect of the law: that Huquq is only due once the liability exceeds the value of 19 mithqáls of gold (which @@ -748,14 +993,410 @@ This example causes 10% of the matching account's total to be deferred to the @samp{Savings} account---as a balanced virtual posting, which may be excluded from reports by using @option{--real}. -@node Periodic Transactions, , Automatic Transactions, Advanced Transactions +Automated transactions can use the full range of value expressions in +their predicate. If you wanted to specify a transaction only occur to +certain accounts that meet cetain value criteria you could specify: + +@smallexample += /Employees:.*:Payroll$/ and expr (amount >= $1000 and amount < $10000) + Expenses:Tax 0.27 +@end smallexample +In this case, @samp{amount} is tied to the amount of the posting being +tested. + +But, wait! There's more! + +In the short example above we calculated the taxes due for income within +a certain bracket. But in reality this calculation is more difficult. +There are different rate for difference marginal incomes and those taxes +are not easily descirbe by a simple multiplicative coefficient. +Automated transaction can use value expressions in there posting to +determine the ammounts. So to expand the example above for a three tax +bracket system we could enter: + +@smallexample += /Employees:.*:Payroll$/ and expr (amount < $10000.00) + (Expenses:Tax) 0.1 += /Employees:.*:Payroll$/ and expr (amount > $10000.00 and amount < $100000.00 ) + (Expenses:Tax) ($1000.00 + .15 * (amount - $10000.00)) += /Employees:.*:Payroll$/ and expr (amount > $100000.00) + (Expenses:Tax) ($13500.00 + .20 * (amount-$100000.00)) +@end smallexample + + +@node Periodic Transactions, Recording Commodity Lot Prices, Automatic Transactions, Advanced Transactions @subsection Periodic Transactions A periodic transaction starts with a ~ followed by a period expression. Periodic transactions are used for budgeting and forecasting only, they have no effect withouth the @samp{--budget} option specified. -See @ref{Budgeting and Forecasting} for exmaples and details. +See @ref{Budgeting and Forecasting} for examples and details. + +@node Recording Commodity Lot Prices, Commodity Pricing Problem, Periodic Transactions, Advanced Transactions +@subsection Recording Commodity Lot Prices + +If you are tracking investments it is often necessary to keep track of +specific purchases of a commodity bought at difference prices. These +specific purchases are referred to as ``lots''. Tracking lots using ledger +requires some additional info in the journal as well as additional +command-line options when generating reports. + +Say you want to record purchase of two separate lots of ACME, then sell +some shares. The correct way to do this is: + +@smallexample +2010-09-01 * Buy 2 shares of ACME @@ $100 + Assets:Broker 2 ACME @@ $100.00 + Assets:Cash + +2010-09-10 * Buy 2 share of ACME @@ $110 + Assets:Broker 2 ACME @@ $110.00 + Assets:Cash + +2011-09-20 * Sell 2 shares of ACME @@ $150 + Assets:Broker -1 ACME @{$100.00@} @@ $150.00 + Assets:Broker -1 ACME @{$200.00@} @@ $150.00 + Assets:Cash +@end smallexample + +To report which lots of commodities you hold, use the +@samp{--lot-prices} option. For example, after buying the 2 shares at +$100 and 1 at $200 it would show you: +@smallexample +$ ledger balance --lot-prices Assets:Broker until 2011-09-15 + 2 ACME @{$100.00@} + 1 ACME @{$200.00@} Assets:Broker +@end smallexample +@noindent without the @samp{--lot-prices} option you would only see the total number of shares you held: +@smallexample +$ ledger balance Assets:Broker until 2011-09-15 + 3 ACME Assets:Broker +@end smallexample +@noindent and after the sale on @samp{2011-09-20} it would show you: +@smallexample +$ ledger balance --lot-prices Assets:Broker + 1 ACME @{$100.00@} Assets:Broker +@end smallexample + +@node Commodity Pricing Problem, , Recording Commodity Lot Prices, Advanced Transactions +@subsection Commodity Valuation + +[THIS SUBSECTION COULD BELONG IN REPORTING SECTION, OR MAYBE EVEN SPLIT BETWEEN THE TWO] + + +Often you will be more interested in the value of your entire holdings, in +your preferred currency. It might be nice to know you hold 10,000 shares +of PENNY, but you are more interested in whether or not that is worth +$1000.00 or $10,000.00. However, the current day value of a commodity can +mean different things to different people, depending on the accounts +involved, the commodities, the nature of the transactions, etc. + +When you specify @samp{-V}, or @samp{-X COMM}, you are requesting that +some or all of the commodities be valuated as of today (or whatever +@samp{--now} is set to). But what does such a valuation mean? This +meaning is governed by the presence of a @samp{VALUE} metadata +property, whose content is an expression used to compute that value. + +If no VALUE property is specified, each posting is assumed to have a default, +as if you'd specified a global, automated transaction as follows: + +@smallexample + = expr true + ; VALUE:: market(amount, date, exchange) +@end smallexample +This definition emulates the present day behavior of -V and -X (in the case of +-X, the requested commodity is passed via the string 'exchange' above). + +One thing many people have wanted to do is to fixate the valuation of old +European currencies in terms of the Euro after a certain date: + +@smallexample + = expr commodity == "DM" + ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR +@end smallexample + +This says: If --now is some old date, use market prices as they were at that +time; but if --now is past June 2008, use a fixed price for converting Deutsch +Mark to Euro. + +Or how about never re-valuating commodities used in Expenses, since they +cannot have a different future value: + +@smallexample + = /^Expenses:/ + ; VALUE:: market(amount, post.date, exchange) +@end smallexample + +This says the future valuation is the same as the valuation at the time of +posting. post.date equals the posting's date, while just 'date' is the value +of --now (defaults to today). + +Or how about valuating miles based on a reimbursement rate during a specific +time period: + + +@smallexample + = expr commodity == "miles" and date >= [2007] and date < [2008] + ; VALUE:: market($1.05, date, exchange) +@end smallexample + +In this case, miles driven in 2007 will always be valuated at $1.05 each. If +you use -X EUR to expressly request all amounts in Euro, Ledger shall convert +$1.05 to Euro by whatever means are appropriate for dollars. + +Note that you can have a valuation expression specific to a particular posting +or transaction, by overriding these general defaults using specific metadata: + +@smallexample + + 2010-12-26 Example + Expenses:Food $20 + ; Just to be silly, always valuate *these* $20 as 30 DM, no matter what + ; the user asks for with -V or -X + ; VALUE:: 30 DM + Assets:Cash +@end smallexample + +This example demonstrates that your VALUE expression should be as symbolic as +possible, using terms like 'amount' and 'date', rather than specific amounts +and dates. Also, you should pass the amount along to the function 'market' so +it can be further revalued if the user has asked for a specific currency. + +Or, if it better suits your accounting, you can be less symbolic, which allows +you to report most everything in EUR if you use -X EUR, except for certain +accounts or postings which should always be valuated in another currency. For +example: + +@smallexample + = /^Assets:Brokerage:CAD$/ + ; Always report the value of commodities in this account in + ; terms of present day dollars, despite what was asked for + ; on the command-line VALUE:: market(amount, date, '$') +@end smallexample + +I think this scheme, of using predicated value expressions which can be +generalized in automated transactions, and made specific via transaction and +posting-based metadata, provides sufficient flexibility to express most of the +use cases which have occurred on this topic. + + +Ledger presently has no way of handling such things as FIFO and LIFO. + +If you specify an unadorned commodity name, like AAPL, it will balance +against itself. If --lots are not being displayed, then it will appear +to balance against any lot of AAPL. + +If you specify an adorned commodity, like AAPL @{$10.00@}, it will also +balance against itself, and against any AAPL if --lots is not specified. +But if you do specify --lot-prices, for example, then it will balance +against that specific price for AAPL. + +I may, for the sake of reporting *only*, be able to implement some sort +of guessing strategy, based on the order in which transactions appear in +the data file... But I'll have to think about this a lot more, and it +would be a 3.1 thing. + +@smallexample +> b) I don't see how this VALUE property can differentiate between -V +> and -B. Does this imply that you want to get rid of the -B option and +> simply let users define what VALUE they get with -V? If so, I think +> this would be a bad idea... I really like the ability to see different +> valuation methods using command line options (i.e. -B for cost basis +> and -V for market value). (Incidentally, while I initially liked your +> example of using the posting date for Expenses, I later realized that +> I sometimes use -V to see what my expenses (in a foreign currency) +> would have been if I bought everything at today's exchange rate.) +@end smallexample +-V and -B are entirely unrelated. Perhaps I could support a BASIS +property setting, for customizing -B in the same way VALUE +customizes -V... + +@smallexample +> c) I never fully understood what -X does exactly but afaik -X is a +> special version of -V. However, I believe that -X should _only_ do +> conversion. This would allow -X to be combined with other options, +> such as -X and -V. Example: let's say I bought 10 shares for 10.00 +> GBP and they are now worth 15.00. Because my main assets are in EUR, +> I want to see what those shares are worth in EUR. Since I'm +> conservative I want to see the cost basis, i.e. I want to use -B and +> -X EUR together. (This actually works today but I'm told this is an +> accident and won't work in all cases.) +@end smallexample +-V asks for the present day value of all commodities, and lets Ledger +pick the target commodity based on its own hueristics. -X is the same +as -V, except that it overrides those hueristics and forces the target +commodity. (Although, as you've seen, the VALUE property could now +countermand that). + +There are reasons why -X can't be applied to any report. Mainly it has +to do with rounding. For example, let's say I have 10 postings that +each trade 1 DM, and the value of 1 DM is 0.001 EUR. If I add all +10 DM and then apply -X, I get 0.01 EUR. But if I apply -X to each +1 DM and *then* total them, I get 0.00 EUR. + +This becomes very important to Ledger because -X is applied to totals, +not just to individual amounts. I'm going to have to use some magic +internally to avoid this problem with the VALUE property (in most, but +not all, cases). + +And so, -X gets applied after, when the posting-origin of the +commodities has been lost -- required information if a basis cost +calculation is to be deferred. + +The alternative would involve ever-growing lists of individual amounts, +which would slow many parts of Ledger from O(N) to O(N^2). Plus, it +still wouldn't solve the rounding problem. + + +> Ledger presently has no way of handling such things as FIFO and LIFO. + +Yeah, I know... but I think it's a feature that ledger should +eventually get (obviously not for 3.0). + +@smallexample +> If you specify an adorned commodity, like AAPL @{$10.00@}, it will also +> balance against itself, and against any AAPL if --lots is not specified. +> But if you do specify --lot-prices, for example, then it will balance +> against that specific price for AAPL. +> +> I may, for the sake of reporting *only*, be able to implement some sort +> of guessing strategy, based on the order in which transactions appear in +> the data file... +@end smallexample +Why for reporting only? It seems to me that ledger has all the +information to do FIFO and LIFO properly (i.e. to remove the right +commodities from the list). Let's take this example: + +@smallexample + +2011-01-01 * Buy AAA + Assets:Shares 5 AAA @ 10.00 EUR + Assets:Cash + +2011-01-03 * Buy AAA + Assets:Shares 2 AAA @ 10.00 EUR + Assets:Cash + +2011-01-11 * Buy AAA + Assets:Shares 5 AAA @ 12.00 EUR + Assets:Cash + +2011-01-21 * Buy AAA + Assets:Shares 5 AAA @ 13.00 EUR + Assets:Cash +@end smallexample + +So we end up with (ledger --lots): + +@smallexample +5 AAA @{10.00 EUR@} [2011/01/01] +2 AAA @{10.00 EUR@} [2011/01/03] +5 AAA @{12.00 EUR@} [2011/01/11] +5 AAA @{13.00 EUR@} [2011/01/21] Assets:Shares +@end smallexample + +So if I sell 6 shares now, according to FIFO, I would do: + +@smallexample +2011-02-01 * Sell AAA + Assets:Shares -5 AAA @{10.00 EUR@} [2011/01/01] @ +13.50 EUR + Assets:Shares -1 AAA @{10.00 EUR@} [2011/01/03] @ +13.50 EUR + Assets:Cash +@end smallexample + +ledger --lots: + +@smallexample +1 AAA @{10.00 EUR@} [2011/01/03] +5 AAA @{12.00 EUR@} [2011/01/11] +5 AAA @{13.00 EUR@} [2011/01/21] Assets:Shares +@end smallexample + +According to LIFO, I would do this instead: + +@smallexample +2011-02-01 * Sell AAA + Assets:Shares -5 AAA @{13.00 EUR@} [2011/01/21] @ +13.50 EUR + Assets:Shares -1 AAA @{12.00 EUR@} [2011/01/11] @ +13.50 EUR + Assets:Cash +@end smallexample + +In other words, you can manually do FIFO and LIFO with ledger already. +However, it would be great if ledger would make this easier, e.g. that +you could specify: + +@smallexample + 2011-02-01 * Sell AAA + Assets:Shares -6 AAA @{FIFO@} @ 13.50 EUR + Assets:Cash +@end smallexample + +and ledger would iterate through all AAA commodities and take out the +right ones (after all, it knows the date and price). + +The only thing I don't think is possible with ledger at the moment is +average cost. I'm also not sure how --lot-dates should behave for +average cost. + +@smallexample +> There are reasons why -X can't be applied to any report. Mainly it has +> to do with rounding. For example, let's say I have 10 postings that +> each trade 1 DM, and the value of 1 DM is 0.001 EUR. If I add all +> 10 DM and then apply -X, I get 0.01 EUR. But if I apply -X to each +> 1 DM and *then* total them, I get 0.00 EUR. +@end smallexample +Thanks for the explanation... what I was thinking of is that ledger +would just produce a report according to -V or -B or whatever and +*then* convert it with -X. I use a shell script to do this for now: + +@smallexample +GBP2EUR="117/100" + +eurgbp=$(ledger -f $FILE -p "until $YEAR-$NEXT_MONTH-01" -B bal "^assets" +"^liabilities" | egrep " (EUR|GBP)$" | tail -n 2) +eur=$(echo "$eurgbp" | grep "EUR" | sed 's/ EUR//') +gbp=$(echo "$eurgbp" | grep "GBP" | sed 's/ GBP//') +eur=$(echo "$eur" | sed 's/\..*//') +gbp=$(echo "$gbp" | sed 's/\..*//') +gbpineur=$(($gbp*$GBP2EUR)) +echo " " $(($eur + $gbpineur)) " EUR Total" +@end smallexample + +I'm kinda surprised that you no longer think it's a good idea to split +-X from -V. Last time I brought this up on IRC, you thought it was a +good idea: + +@smallexample +10:44 < johnw> I think having -H, in addition to -X, may make what you want + to see both natural and simple +10:45 < johnw> you'd use -H for income/expense accounts, and -X for + assets/liabilities +10:45 < johnw> -H = historical values +10:45 < johnw> -X = current exchange values +10:45 < tbm> so what's the difference between -X and -V again? +10:45 < johnw> -V is an automated version of -X +10:45 < johnw> it tries to figure out what the reported commodity should be +10:45 < johnw> we may then need an automated version of -H, to complete the + reflection +10:46 < johnw> btw, this is just an inside-out version of my "final" + feature :) +10:46 < tbm> why not change the meaning of -X to _only do conversion_? And + then you could combine -X with -B, -V or -H +10:46 < johnw> instead of having it be syntactic, we're moving the semantic + difference to a difference in options +10:46 < johnw> oh HMM +10:46 < johnw> -X with -B, -V and -I +10:46 < johnw> (and -O, incidentally) +10:46 < johnw> O = amount, B = cost, V = market value, I = price +10:47 < johnw> that's really an excellent suggestion +10:48 < johnw> i'd still need a flag to mean "historical" vs "current" +10:48 < johnw> as well as "target commodity" (-X) +@end smallexample @node File Format, Archiving Previous Years , Advanced Transactions, Keeping a Journal @section File Format for Users @@ -773,9 +1414,9 @@ A line beginning with a number denotes a transaction. It may be followed by any number of lines, each beginning with whitespace, to denote the transaction's account postings. The format of the first line is: -@example +@smallexample DATE[=EDATE] [*|!] [(CODE)] DESC -@end example +@end smallexample If @samp{*} appears after the date (with optional effective date), it indicates the transaction is ``cleared'', which can mean whatever the user @@ -788,9 +1429,9 @@ the posting. The format of each following posting is: -@example +@smallexample ACCOUNT AMOUNT [; NOTE] -@end example +@end smallexample The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual posting, or square brackets if it is a virtual posting that @@ -852,9 +1493,9 @@ If all transactions specify a year, however, this command has no effect. Specifies a historical price for a commodity. These are usually found in a pricing history file (see the @option{-Q} option). The syntax is: -@example +@smallexample P DATE SYMBOL PRICE -@end example +@end smallexample @item N SYMBOL Indicates that pricing information is to be ignored for a given @@ -862,9 +1503,9 @@ symbol, nor will quotes ever be downloaded for that symbol. Useful with a home currency, such as the dollar ($). It is recommended that these pricing options be set in the price database file, which defaults to @file{~/.pricedb}. The syntax for this command is: -@example +@smallexample N SYMBOL -@end example +@end smallexample @item D AMOUNT Specifies the default commodity to use, by specifying an amount in the @@ -874,17 +1515,17 @@ used multiple times, to set the default flags for different commodities; whichever is seen last is used as the default commodity. For example, to set US dollars as the default commodity, while also setting the thousands flag and decimal flag for that commodity, use: -@example +@smallexample D $1,000.00 -@end example +@end smallexample @item C AMOUNT1 = AMOUNT2 Specifies a commodity conversion, where the first amount is given to be equivalent to the second amount. The first amount should use the decimal precision desired during reporting: -@example +@smallexample C 1.00 Kb = 1024 bytes -@end example +@end smallexample @item i, o, b, h These four relate to timeclock support, which permits LEDGER to read @@ -919,10 +1560,10 @@ ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat To delete older data from the current ledger file, use @command{print} again, this time specifying year 2002 as the starting date: -@example +@smallexample ledger -f ledger.dat -b 2002 print > x mv x ledger.dat -@end example +@end smallexample However, now the current file contains @emph{only} postings from 2002 onward, which will not yield accurate present-day balances, because the @@ -930,12 +1571,12 @@ net income from previous years is no longer being tallied. To compensate for this, we must append an equity report for the old ledger at the beginning of the new one: -@example +@smallexample ledger -f ledger-old.dat equity > equity.dat cat equity.dat ledger.dat > x mv x ledger.dat rm equity.dat -@end example +@end smallexample Now the balances reported from @file{ledger.dat} are identical to what they were before the data was split. @@ -960,59 +1601,32 @@ doing it. @menu -* Cookbook:: -* Quick Reference:: -* Options:: +* Basic Usage:: +* Detailed Options Description:: * Period Expressions:: @end menu -@node Cookbook, Quick Reference, Command-line Syntax, Command-line Syntax -@section Cookbook +@node Basic Usage, Detailed Options Description, Command-line Syntax, Command-line Syntax +@section Basic Usage -@subsection Invoking Ledger - -@example -ledger --group-by "tag('trip')" bal -legder reg --sort "tag('foo')" %foo -ledger cleared VWCU NFCU Tithe Misentry -ledger register Joint --uncleared -ledger register NFCUChecking --sort d -d 'd>[2011/04/01]' until 2011/05/25 -@end example -@subsection Ledger Files - -@example -= /^Income:Taxable/ - (Liabilities:Tithe Owed) -0.1 -= /Noah/ - (Liabilities:Tithe Owed) -0.1 -= /Jonah/ - (Liabilities:Tithe Owed) -0.1 -= /Tithe/ - (Liabilities:Tithe Owed) -1.0 -@end example - -@node Quick Reference, Options, Cookbook, Command-line Syntax -@section Quick Reference - -This chapter describes LEDGER's features and serves as a quick -reference. You may wish to survey this to get an overview before diving -in to the @ref{Ledger Tutorial} and more detailed examples that follow. +This chapter describes LEDGER's features and options. You may wish to +survey this to get an overview before diving in to the @ref{Ledger +Tutorial} and more detailed examples that follow. LEDGER has a very simple command-line interface, named---enticingly enough---@command{ledger}. It supports a few reporting commands, and a large number of options for refining the output from those commands. The basic syntax of any ledger command is: -@example +@smallexample ledger [OPTIONS...] COMMAND [ARGS...] -@end example +@end smallexample -Command options must always precede the command word. After the -command word there may appear any number of arguments. For most -commands, these arguments are regular expressions that cause the -output to relate only to postings matching those regular -expressions. For the @command{transaction} command, the arguments have a -special meaning, described below. +After the command word there may appear any number of arguments. For +most commands, these arguments are regular expressions that cause the +output to relate only to postings matching those regular expressions. +For the @command{transaction} command, the arguments have a special +meaning, described below. The regular expressions arguments always match the account name that a posting refers to. To match on the payee of the transaction instead, @@ -1020,9 +1634,9 @@ precede the regular expression with @samp{--}. For example, the following balance command reports account totals for rent, food and movies, but only those whose payee matches Freddie: -@example +@smallexample ledger bal rent food movies -- freddie -@end example +@end smallexample There are many, many command options available with the @command{ledger} command, and it takes a while to master them. @@ -1030,18 +1644,22 @@ However, none of them are required to use the basic reporting commands. -@node Options, Period Expressions, Quick Reference, Command-line Syntax -@section Options + + + + + + + +@node Detailed Options Description, Period Expressions, Basic Usage, Command-line Syntax +@section Detailed Option Description With all of the reports, command-line options are useful to modify the -output generated. These command-line options always occur before the -command word. This is done to distinguish options from exclusive -regular expressions, which also begin with a dash. The basic form for -most commands is: +output generated. The basic form for most commands is: -@example +@smallexample ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] -@end example +@end smallexample The @var{OPTIONS} and @var{REGEXPS} expressions are both optional. You could just use @samp{ledger balance}, without any options---which @@ -1051,7 +1669,7 @@ to change the appearance of the output, options are needed. @subsection Basic options These are the most basic command options. Most likely, the user will -want to set them using environment variables (see @ref{Options}), +want to set them using environment variables (see @ref{Environment Variables}), instead of using actual command-line options: @option{--help} (@option{-h}) prints a summary of all the options, and @@ -1132,9 +1750,9 @@ reporting period using the value expression @var{EXPR}. This is most often useful when reporting monthly expenses, in order to view the highest expense categories at the top of each month: -@example +@smallexample ledger -M --period-sort -At reg ^Expenses -@end example +@end smallexample @option{--cleared} (@option{-C}) displays only postings whose transaction has been marked ``cleared'' (by placing an asterix to the right of the @@ -1168,9 +1786,9 @@ For example, if a file had this transaction: And the register command was: -@example +@smallexample ledger -r register food -@end example +@end smallexample The following would be output, showing the postings related to the posting that matched: @@ -1203,9 +1821,11 @@ used for the ``totals'' column in the @command{register} and @menu * Search Terms:: * Output Customization:: +* Commodity Reporting:: +* Environment Variables:: @end menu -@node Search Terms, Output Customization, Options, Options +@node Search Terms, Output Customization, Detailed Options Description, Detailed Options Description @subsection Search Terms Valid LEDGER invocations look like: @@ -1246,7 +1866,7 @@ So, to list all transaction that charged to ``ffod'' but not ``dining'' for any ledger reg food not dining expr 'payee =~ /chang/' @end smallexample -@node Output Customization, , Search Terms, Options +@node Output Customization, Commodity Reporting, Search Terms, Detailed Options Description @subsection Output Customization These options affect only the output, but not which postings are @@ -1334,17 +1954,17 @@ example, but they will not be displayed. This is useful for seeing last month's checking postings, against a running balance which includes all posting values: -@example +@smallexample ledger -d "d>=[last month]" reg checking -@end example +@end smallexample The output from this command is very different from the following, whose running total includes only postings from the last month onward: -@example +@smallexample ledger -p "last month" reg checking -@end example +@end smallexample Which is more useful depends on what you're looking to know: the total amount for the reporting range (@option{-p}), or simply a display @@ -1372,7 +1992,8 @@ There are also specific format commands for each report type: @item @option{--wide-register-format STR} (-w @command{register}) @end itemize -@subsection Commodity reporting +@node Commodity Reporting, Environment Variables, Output Customization, Detailed Options Description +@subsection Commodity Reporting These options affect how commodity values are displayed: @@ -1382,11 +2003,11 @@ determine historical prices. Other settings can be placed in this file manually, to prevent downloading quotes for a specific, for example. This is done by adding a line like the following: -@example +@smallexample ; Don't download quotes for the dollar, or timelog values N $ N h -@end example +@end smallexample @option{--price-exp MINS} (@option{-L MINS}) sets the expected freshness of price quotes, in minutes. That is, if the last known @@ -1424,6 +2045,7 @@ Reports the net gain/loss for all commodities in the report that have a price history. @end table +@node Environment Variables, , Commodity Reporting, Detailed Options Description @subsection Environment variables Every option to ledger may be set using an environment variable. If @@ -1436,25 +2058,25 @@ settings, however. Note that you may also permanently specify option values by placing option settings in the file @file{~/.ledgerrc}, for example: -@example +@smallexample --cache /tmp/.mycache --pager /bin/cat -@end example +@end smallexample -@node Period Expressions, , Options, Command-line Syntax +@node Period Expressions, , Detailed Options Description, Command-line Syntax @section Period Expressions A period expression indicates a span of time, or a reporting interval, or both. The full syntax is: -@example +@smallexample [INTERVAL] [BEGIN] [END] -@end example +@end smallexample The optional @var{INTERVAL} part may be any one of: -@example +@smallexample every day every week every monthly @@ -1472,26 +2094,26 @@ monthly bimonthly quarterly yearly -@end example +@end smallexample After the interval, a begin time, end time, both or neither may be specified. As for the begin time, it can be either of: -@example +@smallexample from since -@end example +@end smallexample The end time can be either of: -@example +@smallexample to until -@end example +@end smallexample Where @var{SPEC} can be any of: -@example +@smallexample 2004 2004/10 2004/10/1 @@ -1501,21 +2123,21 @@ oct this week # or day, month, quarter, year next week last week -@end example +@end smallexample The beginning and ending can be given at the same time, if it spans a single period. In that case, just use @var{SPEC} by itself. In that case, the period @samp{oct}, for example, will cover all the days in october. The possible forms are: -@example +@smallexample in -@end example +@end smallexample Here are a few examples of period expressions: -@example +@smallexample monthly monthly in 2004 weekly from oct @@ -1527,7 +2149,7 @@ from apr until nov last oct weekly last august -@end example +@end smallexample @node Basic Reporting Commands, Budgeting and Forecasting, Command-line Syntax, Top @@ -1593,9 +2215,9 @@ The @command{output} command is very similar to the @command{print} command, except that it attempts to replicate the specified ledger file exactly. The format of the command is: -@example +@smallexample ledger -f FILENAME output FILENAME -@end example +@end smallexample Where @file{FILENAME} is the name of the ledger file to output. The reason for specifying this command is that only transactions contained @@ -1617,11 +2239,11 @@ posting. The @command{emacs} command outputs results in a form that can be read directly by Emacs Lisp. The format of the sexp is: -@example +@smallexample ((BEG-POS CLEARED DATE CODE PAYEE (ACCOUNT AMOUNT)...) ; list of postings ...) ; list of transactions -@end example +@end smallexample @node equity, prices, emacs, Basic Reporting Commands @section equity @@ -1662,9 +2284,9 @@ Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva Italiano} again. The exact amounts are different, but the overall form is the same. With the @command{xact} command you can type: -@example +@smallexample ledger xact 2004/4/9 viva food 11 tips 2.50 -@end example +@end smallexample This produces the following output: @@ -1689,14 +2311,14 @@ looks appropriate. Here are a few more examples of the @command{xact} command, assuming the above journal transaction: -@example +@smallexample ledger xact 4/9 viva 11.50 ledger xact 4/9 viva 11.50 checking # (from `checking') ledger xact 4/9 viva food 11.50 tips 8 ledger xact 4/9 viva food 11.50 tips 8 cash ledger xact 4/9 viva food $11.50 tips $8 cash ledger xact 4/9 viva dining "DM 11.50" -@end example +@end smallexample @menu @@ -1730,9 +2352,9 @@ addition to a set of one letter functions and variables. A function's argument is whatever follows it. The following is a display predicate that I use with the @command{balance} command: -@example +@smallexample ledger -d /^Liabilities/?T<0:UT>100 balance -@end example +@end smallexample The effect is that account totals are displayed only if: 1) A Liabilities account has a total less than zero; or 2) the absolute @@ -1745,18 +2367,18 @@ constrain which transactions are printed. For example, the following command shows only transactions from the beginning of the current month, while still calculating the running balance based on all transactions: -@example +@smallexample ledger -d "d>[this month]" register checking -@end example +@end smallexample This advantage to this command's complexity is that it prints the running total in terms of all transactions in the register. The following, simpler command is similar, but totals only the displayed postings: -@example +@smallexample ledger -b "this month" register checking -@end example +@end smallexample @menu * Variables:: @@ -1948,9 +2570,9 @@ parts of an account or posting in custom ways. Within a format strings, a substitution is specified using a percent character (@samp{%}). The basic format of all substitutions is: -@example +@smallexample %[-][MIN WIDTH][.MAX WIDTH]EXPR -@end example +@end smallexample If the optional minus sign (@samp{-}) follows the percent character, whatever is substituted will be left justified. The default is right @@ -1959,12 +2581,12 @@ will be at least that wide, perhaps wider. If a period and a maximum width is given, the substituted text will never be wider than this, and will be truncated to fit. Here are some examples: -@example +@smallexample %-P a transaction's payee, left justified %20P The same, right justified, at least 20 chars wide %.20P The same, no more than 20 chars wide %-.20P Left justified, maximum twenty chars wide -@end example +@end smallexample The expression following the format constraints can be a single letter, or an expression enclosed in parentheses or brackets. The @@ -2099,11 +2721,11 @@ one or more @dfn{postings}, which describe how @dfn{amounts} flow from one @dfn{account} to another. Here is an example of the simplest of journal files: -@example +@smallexample 2010/05/31 Just an example Expenses:Some:Account $100.00 Income:Another:Account -@end example +@end smallexample In this example, there is a transaction date, a payee, or description of the transaction, and two postings. The postings show movement of @@ -2123,7 +2745,7 @@ It is also typical---though not enforced---to think of the first posting as the destination, and the final as the source. Thus, the amount of the first posting is typically positive. Consider: -@example +@smallexample 2010/05/31 An income transaction Assets:Checking $1,000.00 Income:Salary @@ -2131,7 +2753,7 @@ amount of the first posting is typically positive. Consider: 2010/05/31 An expense transaction Expenses:Dining $100.00 Assets:Checking -@end example +@end smallexample @emph{Note:} It is important to note that there must be at least two spaces between the end of the post and the beginning of the amount (including and @@ -2148,11 +2770,11 @@ multiple ways to achieve a desired result. In the simplest form, bare decimal numbers are accepted: -@example +@smallexample 2010/05/31 An income transaction Assets:Checking 1000.00 Income:Salary -@end example +@end smallexample Such amounts may only use an optional period for a decimal point. These are referred to as @dfn{integer amounts} or @dfn{uncommoditized @@ -2216,9 +2838,9 @@ characters are allowed in a commodity name, except for the following: And yet, any of these may appear in a commodity name if it is surrounded by double quotes, for example: -@example +@smallexample 100 "EUN+133" -@end example +@end smallexample If a @dfn{quoted commodity} is found, it is displayed in quotes as well, to avoid any confusion as to which part is the amount, and which @@ -2252,45 +2874,45 @@ amount for a posting. But what if the amount you paid for something was in one commodity, and the amount received was another? There are two main ways to express this: -@example +@smallexample 2010/05/31 Farmer's Market Assets:My Larder 100 apples Assets:Checking $20.00 -@end example +@end smallexample In this example, you have paid twenty dollars for one hundred apples. The cost to you is twenty cents per apple, and Ledger calculates this implied cost for you. You can also make the cost explicit using a @dfn{cost amount}: -@example +@smallexample 2010/05/31 Farmer's Market Assets:My Larder 100 apples @@ $0.200000 Assets:Checking -@end example +@end smallexample Here the @dfn{per-unit cost} is given explicitly in the form of a cost amount; and since cost amount are @emph{unobserved}, the use of six decimal places has no effect on how dollar amounts are displayed in the final report. You can also specify the @dfn{total cost}: -@example +@smallexample 2010/05/31 Farmer's Market Assets:My Larder 100 apples @@@@ $20 Assets:Checking -@end example +@end smallexample These three forms have identical meaning. In most cases the first is preferred, but the second two are necessary when more than two postings are involved: -@example +@smallexample 2010/05/31 Farmer's Market Assets:My Larder 100 apples @@ $0.200000 Assets:My Larder 100 pineapples @@ $0.33 Assets:My Larder 100 "crab apples" @@ $0.04 Assets:Checking -@end example +@end smallexample Here the implied cost is @samp{$57.00}, which is entered into the null posting automatically so that the transaction balances. @@ -2304,7 +2926,7 @@ to buy and sells units of the other commodity. In the fruit examples above, dollars are the primary commodity. This is decided by Ledger on the placement of the commodity in the transaction: -@example +@smallexample 2010/05/31 Sample Transaction Expenses 100 secondary Assets 50 primary @@ -2316,7 +2938,7 @@ on the placement of the commodity in the transaction: 2010/05/31 Sample Transaction Expenses 100 secondary @@@@ 50 primary Assets -@end example +@end smallexample The only case where knowledge of primary versus secondary comes into play is in reports that use the @option{-V} or @option{-B} options. @@ -2335,7 +2957,7 @@ commodities. The following journal file is included with the source distribution of ledger. It is called @file{drewr.dat} and exhibits many ledger features, include automatic and virtual transactions, -@example +@smallexample ; -*- ledger -*- = /^Income/ @@ -2400,7 +3022,7 @@ commodities. Assets:Checking:Business $ 30.00 Income:Sales -@end example +@end smallexample @node Miscellaneous Notes, , Example Data File, Top @appendix Miscellaneous Notes @@ -2408,329 +3030,32 @@ commodities. Various notes from the discussion list that I haven't incorporated in to the main body of the documentation. @menu -* Commodity Pricing Problem:: +* Cookbook:: @end menu -@node Commodity Pricing Problem, , Miscellaneous Notes, Miscellaneous Notes -@section Commodity Pricing Problem +@node Cookbook, , Miscellaneous Notes, Miscellaneous Notes +@section Cookbook -Sun, 26 Dec 2010 04:13:04 -0800 - -One of the things which stalled Ledger development recently is that I'd never -found a truly satisfying way to handle the "commodity pricing problem". That -is, the current day value of a commodity can mean different things to -different people, depending on the accounts involved, the commodities, the -nature of the transactions, etc. - -After experimenting with several different concepts and syntaxes, I found none -of them were either satisfying or general enough. My one attempt at providing -"fixated prices" was too specific, and too inelegant for many usage patterns. - -This morning, however, I think I've finally cracked this nut; and in a way -which fits harmoniously into the Ledger architecture as if it were meant to be -there all along... - -Here's how the new scheme will work: When a user specifies '-V', or '-X COMM', -they are requesting that some or all of the commodities in their Ledger file -be valuated as of today (or whatever --now is set to). But what does such a -valuation mean? This meaning shall be governed by the presence of a "VALUE" -metadata property, whose content is an expression used to compute that value. - -If no VALUE property is specified, each posting is assumed to have a default, -as if you'd specified a global, automated transaction as follows: +@subsection Invoking Ledger @smallexample - = expr true - ; VALUE:: market(amount, date, exchange) +ledger --group-by "tag('trip')" bal +legder reg --sort "tag('foo')" %foo +ledger cleared VWCU NFCU Tithe Misentry +ledger register Joint --uncleared +ledger register Checking --sort d -d 'd>[2011/04/01]' until 2011/05/25 @end smallexample -This definition emulates the present day behavior of -V and -X (in the case of --X, the requested commodity is passed via the string 'exchange' above). - -One thing many people have wanted to do is to fixate the valuation of old -European currencies in terms of the Euro after a certain date: +@subsection Ledger Files @smallexample - = expr commodity == "DM" - ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR += /^Income:Taxable/ + (Liabilities:Tithe Owed) -0.1 += /Noah/ + (Liabilities:Tithe Owed) -0.1 += /Jonah/ + (Liabilities:Tithe Owed) -0.1 += /Tithe/ + (Liabilities:Tithe Owed) -1.0 @end smallexample -This says: If --now is some old date, use market prices as they were at that -time; but if --now is past June 2008, use a fixed price for converting Deutsch -Mark to Euro. - -Or how about never re-valuating commodities used in Expenses, since they -cannot have a different future value: - -@smallexample - = /^Expenses:/ - ; VALUE:: market(amount, post.date, exchange) -@end smallexample - -This says the future valuation is the same as the valuation at the time of -posting. post.date equals the posting's date, while just 'date' is the value -of --now (defaults to today). - -Or how about valuating miles based on a reimbursement rate during a specific -time period: - - -@smallexample - = expr commodity == "miles" and date >= [2007] and date < [2008] - ; VALUE:: market($1.05, date, exchange) -@end smallexample - -In this case, miles driven in 2007 will always be valuated at $1.05 each. If -you use -X EUR to expressly request all amounts in Euro, Ledger shall convert -$1.05 to Euro by whatever means are appropriate for dollars. - -Note that you can have a valuation expression specific to a particular posting -or transaction, by overriding these general defaults using specific metadata: - -@smallexample - - 2010-12-26 Example - Expenses:Food $20 - ; Just to be silly, always valuate *these* $20 as 30 DM, no matter what - ; the user asks for with -V or -X - ; VALUE:: 30 DM - Assets:Cash -@end smallexample - -This example demonstrates that your VALUE expression should be as symbolic as -possible, using terms like 'amount' and 'date', rather than specific amounts -and dates. Also, you should pass the amount along to the function 'market' so -it can be further revalued if the user has asked for a specific currency. - -Or, if it better suits your accounting, you can be less symbolic, which allows -you to report most everything in EUR if you use -X EUR, except for certain -accounts or postings which should always be valuated in another currency. For -example: - -@smallexample - = /^Assets:Brokerage:CAD$/ - ; Always report the value of commodities in this account in terms of - ; present day dollars, despite what was asked for on the command-line - ; VALUE:: market(amount, date, '$') -@end smallexample - -I think this scheme, of using predicated value expressions which can be -generalized in automated transactions, and made specific via transaction and -posting-based metadata, provides sufficient flexibility to express most of the -use cases which have occurred on this topic. - - -Ledger presently has no way of handling such things as FIFO and LIFO. - -If you specify an unadorned commodity name, like AAPL, it will balance -against itself. If --lots are not being displayed, then it will appear -to balance against any lot of AAPL. - -If you specify an adorned commodity, like AAPL @{$10.00@}, it will also -balance against itself, and against any AAPL if --lots is not specified. -But if you do specify --lot-prices, for example, then it will balance -against that specific price for AAPL. - -I may, for the sake of reporting *only*, be able to implement some sort -of guessing strategy, based on the order in which transactions appear in -the data file... But I'll have to think about this a lot more, and it -would be a 3.1 thing. - -> b) I don't see how this VALUE property can differentiate between -V -> and -B. Does this imply that you want to get rid of the -B option and -> simply let users define what VALUE they get with -V? If so, I think -> this would be a bad idea... I really like the ability to see different -> valuation methods using command line options (i.e. -B for cost basis -> and -V for market value). (Incidentally, while I initially liked your -> example of using the posting date for Expenses, I later realized that -> I sometimes use -V to see what my expenses (in a foreign currency) -> would have been if I bought everything at today's exchange rate.) - --V and -B are entirely unrelated. Perhaps I could support a BASIS -property setting, for customizing -B in the same way VALUE -customizes -V... - -> c) I never fully understood what -X does exactly but afaik -X is a -> special version of -V. However, I believe that -X should _only_ do -> conversion. This would allow -X to be combined with other options, -> such as -X and -V. Example: let's say I bought 10 shares for 10.00 -> GBP and they are now worth 15.00. Because my main assets are in EUR, -> I want to see what those shares are worth in EUR. Since I'm -> conservative I want to see the cost basis, i.e. I want to use -B and -> -X EUR together. (This actually works today but I'm told this is an -> accident and won't work in all cases.) - --V asks for the present day value of all commodities, and lets Ledger -pick the target commodity based on its own hueristics. -X is the same -as -V, except that it overrides those hueristics and forces the target -commodity. (Although, as you've seen, the VALUE property could now -countermand that). - -There are reasons why -X can't be applied to any report. Mainly it has -to do with rounding. For example, let's say I have 10 postings that -each trade 1 DM, and the value of 1 DM is 0.001 EUR. If I add all -10 DM and then apply -X, I get 0.01 EUR. But if I apply -X to each -1 DM and *then* total them, I get 0.00 EUR. - -This becomes very important to Ledger because -X is applied to totals, -not just to individual amounts. I'm going to have to use some magic -internally to avoid this problem with the VALUE property (in most, but -not all, cases). - -And so, -X gets applied after, when the posting-origin of the -commodities has been lost -- required information if a basis cost -calculation is to be deferred. - -The alternative would involve ever-growing lists of individual amounts, -which would slow many parts of Ledger from O(N) to O(N^2). Plus, it -still wouldn't solve the rounding problem. - - -> Ledger presently has no way of handling such things as FIFO and LIFO. - -Yeah, I know... but I think it's a feature that ledger should -eventually get (obviously not for 3.0). - -> If you specify an adorned commodity, like AAPL @{$10.00@}, it will also -> balance against itself, and against any AAPL if --lots is not specified. -> But if you do specify --lot-prices, for example, then it will balance -> against that specific price for AAPL. -> -> I may, for the sake of reporting *only*, be able to implement some sort -> of guessing strategy, based on the order in which transactions appear in -> the data file... - -Why for reporting only? It seems to me that ledger has all the -information to do FIFO and LIFO properly (i.e. to remove the right -commodities from the list). Let's take this example: - -@smallexample - -2011-01-01 * Buy AAA - Assets:Shares 5 AAA @ 10.00 EUR - Assets:Cash - -2011-01-03 * Buy AAA - Assets:Shares 2 AAA @ 10.00 EUR - Assets:Cash - -2011-01-11 * Buy AAA - Assets:Shares 5 AAA @ 12.00 EUR - Assets:Cash - -2011-01-21 * Buy AAA - Assets:Shares 5 AAA @ 13.00 EUR - Assets:Cash -@end smallexample - -So we end up with (ledger --lots): - -@smallexample -5 AAA @{10.00 EUR@} [2011/01/01] -2 AAA @{10.00 EUR@} [2011/01/03] -5 AAA @{12.00 EUR@} [2011/01/11] -5 AAA @{13.00 EUR@} [2011/01/21] Assets:Shares -@end smallexample - -So if I sell 6 shares now, according to FIFO, I would do: - -@smallexample -2011-02-01 * Sell AAA - Assets:Shares -5 AAA @{10.00 EUR@} [2011/01/01] @ -13.50 EUR - Assets:Shares -1 AAA @{10.00 EUR@} [2011/01/03] @ -13.50 EUR - Assets:Cash -@end smallexample - -ledger --lots: - -@smallexample -1 AAA @{10.00 EUR@} [2011/01/03] -5 AAA @{12.00 EUR@} [2011/01/11] -5 AAA @{13.00 EUR@} [2011/01/21] Assets:Shares -@end smallexample - -According to LIFO, I would do this instead: - -@smallexample -2011-02-01 * Sell AAA - Assets:Shares -5 AAA @{13.00 EUR@} [2011/01/21] @ -13.50 EUR - Assets:Shares -1 AAA @{12.00 EUR@} [2011/01/11] @ -13.50 EUR - Assets:Cash -@end smallexample - -In other words, you can manually do FIFO and LIFO with ledger already. -However, it would be great if ledger would make this easier, e.g. that -you could specify: - -@smallexample - 2011-02-01 * Sell AAA - Assets:Shares -6 AAA @{FIFO@} @ 13.50 EUR - Assets:Cash -@end smallexample - -and ledger would iterate through all AAA commodities and take out the -right ones (after all, it knows the date and price). - -The only thing I don't think is possible with ledger at the moment is -average cost. I'm also not sure how --lot-dates should behave for -average cost. - -> There are reasons why -X can't be applied to any report. Mainly it has -> to do with rounding. For example, let's say I have 10 postings that -> each trade 1 DM, and the value of 1 DM is 0.001 EUR. If I add all -> 10 DM and then apply -X, I get 0.01 EUR. But if I apply -X to each -> 1 DM and *then* total them, I get 0.00 EUR. - -Thanks for the explanation... what I was thinking of is that ledger -would just produce a report according to -V or -B or whatever and -*then* convert it with -X. I use a shell script to do this for now: - -@smallexample -GBP2EUR="117/100" - -eurgbp=$(ledger -f $FILE -p "until $YEAR-$NEXT_MONTH-01" -B bal "^assets" -"^liabilities" | egrep " (EUR|GBP)$" | tail -n 2) -eur=$(echo "$eurgbp" | grep "EUR" | sed 's/ EUR//') -gbp=$(echo "$eurgbp" | grep "GBP" | sed 's/ GBP//') -eur=$(echo "$eur" | sed 's/\..*//') -gbp=$(echo "$gbp" | sed 's/\..*//') -gbpineur=$(($gbp*$GBP2EUR)) -echo " " $(($eur + $gbpineur)) " EUR Total" -@end smallexample - -I'm kinda surprised that you no longer think it's a good idea to split --X from -V. Last time I brought this up on IRC, you thought it was a -good idea: - -@smallexample -10:44 < johnw> I think having -H, in addition to -X, may make what you want - to see both natural and simple -10:45 < johnw> you'd use -H for income/expense accounts, and -X for - assets/liabilities -10:45 < johnw> -H = historical values -10:45 < johnw> -X = current exchange values -10:45 < tbm> so what's the difference between -X and -V again? -10:45 < johnw> -V is an automated version of -X -10:45 < johnw> it tries to figure out what the reported commodity should be -10:45 < johnw> we may then need an automated version of -H, to complete the - reflection -10:46 < johnw> btw, this is just an inside-out version of my "final" - feature :) -10:46 < tbm> why not change the meaning of -X to _only do conversion_? And - then you could combine -X with -B, -V or -H -10:46 < johnw> instead of having it be syntactic, we're moving the semantic - difference to a difference in options -10:46 < johnw> oh HMM -10:46 < johnw> -X with -B, -V and -I -10:46 < johnw> (and -O, incidentally) -10:46 < johnw> O = amount, B = cost, V = market value, I = price -10:47 < johnw> that's really an excellent suggestion -10:48 < johnw> i'd still need a flag to mean "historical" vs "current" -10:48 < johnw> as well as "target commodity" (-X) -@end smallexample - - @bye diff --git a/doc/gendocs.sh b/doc/gendocs.sh new file mode 100755 index 00000000..87a83346 --- /dev/null +++ b/doc/gendocs.sh @@ -0,0 +1,5 @@ +#!/bin/bash +echo ++++++++++++++++++++++++++ +makeinfo Ledger3.texi +echo ========================== +texi2pdf Ledger3.texi diff --git a/test/input/drewr3.dat b/test/input/drewr3.dat index ca4fc6cf..fca61d24 100644 --- a/test/input/drewr3.dat +++ b/test/input/drewr3.dat @@ -3,19 +3,19 @@ = /^Income/ (Liabilities:Tithe) 0.12 -~ Monthly - Assets:Checking $500.00 - Income:Salary +;~ Monthly +; Assets:Checking $500.00 +; Income:Salary -~ Monthly - Expenses:Food $100 - Assets +;~ Monthly +; Expenses:Food $100 +; Assets 2010/12/01 * Checking balance Assets:Checking $1,000.00 Equity:Opening Balances -2010/12/20 Organic Co-op +2010/12/20 * Organic Co-op Expenses:Food:Groceries $ 37.50 ; [=2011/01/01] Expenses:Food:Groceries $ 37.50 ; [=2011/02/01] Expenses:Food:Groceries $ 37.50 ; [=2011/03/01] From d04ed9bf5929d55566f20987d534bf090596fddd Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Mon, 3 Oct 2011 08:12:26 -0700 Subject: [PATCH 13/28] correct payee regex flag is @ or 'payee' --- doc/Ledger3.texi | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/doc/Ledger3.texi b/doc/Ledger3.texi index d80dc57c..3d5ab570 100644 --- a/doc/Ledger3.texi +++ b/doc/Ledger3.texi @@ -403,6 +403,18 @@ $ ledger -f drewr3.dat balance Groceries $ 334.00 Expenses:Food:Groceries @end smallexample +@noindent If you would like to find transaction to only a certain payee use @samp{payee} or @@: +@smallexample +$ ledger -f drewr3.dat register payee "Organic" +10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 + Expense:Food:Groceries $ 37.50 $ 75.00 + Expense:Food:Groceries $ 37.50 $ 112.50 + Expense:Food:Groceries $ 37.50 $ 150.00 + Expense:Food:Groceries $ 37.50 $ 187.50 + Expense:Food:Groceries $ 37.50 $ 225.00 + Assets:Checking $ -225.00 0 +@end smallexample + @node Cleared Report, , Register Report, Run Some Reports @subsection Cleared Report @@ -1630,12 +1642,16 @@ meaning, described below. The regular expressions arguments always match the account name that a posting refers to. To match on the payee of the transaction instead, -precede the regular expression with @samp{--}. For example, the +precede the regular expression with @samp{payee} or @@. For example, the following balance command reports account totals for rent, food and movies, but only those whose payee matches Freddie: @smallexample -ledger bal rent food movies -- freddie +ledger bal rent food movies payee freddie +@end smallexample +@noindent or +@smallexample +ledger bal rent food movies @freddie @end smallexample There are many, many command options available with the From 784768759645ecc50fa64d2a94ed88ebeaf6a787 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Mon, 3 Oct 2011 12:21:41 -0700 Subject: [PATCH 14/28] added version information to manual --- doc/Ledger3.texi | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/doc/Ledger3.texi b/doc/Ledger3.texi index 3d5ab570..a7158154 100644 --- a/doc/Ledger3.texi +++ b/doc/Ledger3.texi @@ -44,6 +44,8 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @titlepage @title LEDGER: Command-Line Accounting +@subtitle For Version 3.0 of LEDGER +@subtitle Draft Manual 2011-10-03 @author John Wiegley @end titlepage @@ -453,14 +455,14 @@ $ ledger -f drewr3.dat cleared @section Command Line Quick Reference @menu -* Reporting Commands:: -* Basic Options:: -* Report Filtering:: -* Output Customization:: -* Commodity Reporting:: +* Reporting Commands Quick Reference:: +* Basic Options Quick Reference:: +* Report Filtering Quick Reference:: +* Output Customization Quick Reference:: +* Commodity Reporting Quick Reference:: @end menu -@node Reporting Commands, Basic Options, Command Line Quick Reference, Command Line Quick Reference +@node Reporting Commands Quick Reference, Basic Options Quick Reference, Command Line Quick Reference, Command Line Quick Reference @subsection Reporting Commands @multitable @columnfractions .2 .8 @item @strong{Report} @tab @strong{Description} @@ -476,7 +478,7 @@ $ ledger -f drewr3.dat cleared @item @code{xact} @tab Used to generate transactions based on previous postings @end multitable -@node Basic Options, Report Filtering, Reporting Commands, Command Line Quick Reference +@node Basic Options Quick Reference, Report Filtering Quick Reference, Reporting Commands Quick Reference, Command Line Quick Reference @subsection Basic Options @multitable @columnfractions .1 .25 .65 @item @strong{Short} @tab @strong{Long} @tab @strong{Description} @@ -489,7 +491,7 @@ $ ledger -f drewr3.dat cleared @item @code{-a NAME} @tab @code{--account NAME} @tab specify default account name for QIF file postings @end multitable -@node Report Filtering, Output Customization, Basic Options, Command Line Quick Reference +@node Report Filtering Quick Reference, Output Customization Quick Reference, Basic Options Quick Reference, Command Line Quick Reference @subsection Report Filtering @multitable @columnfractions .1 .25 .65 @item @strong{Short} @tab @strong{Long} @tab @strong{Description} @@ -512,7 +514,7 @@ $ ledger -f drewr3.dat cleared @item @code{-T EXPR} @tab @code{--total} @tab Change the value expression used for ``totals'' column in register and balance reports @end multitable -@node Output Customization, Commodity Reporting, Report Filtering, Command Line Quick Reference +@node Output Customization Quick Reference, Commodity Reporting Quick Reference, Report Filtering Quick Reference, Command Line Quick Reference @subsection Output Customization @multitable @columnfractions .15 .4 .45 @item @strong{Short} @tab @strong{Long} @tab @strong{Description} @@ -548,7 +550,7 @@ $ ledger -f drewr3.dat cleared @item @code{-w register} @tab @code{--wide-register-format STR} @tab @end multitable -@node Commodity Reporting, , Output Customization, Command Line Quick Reference +@node Commodity Reporting Quick Reference, , Output Customization Quick Reference, Command Line Quick Reference @subsection Commodity Reporting @multitable @columnfractions .1 .25 .65 @@ -1651,7 +1653,7 @@ ledger bal rent food movies payee freddie @end smallexample @noindent or @smallexample -ledger bal rent food movies @freddie +ledger bal rent food movies @@freddie @end smallexample There are many, many command options available with the From d7fc30e23cf6e4291a4bba52f53334fa02d2f432 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 4 Oct 2011 21:49:33 -0700 Subject: [PATCH 15/28] changing Ledger3.texi to ledger3.texi step 1 --- doc/{Ledger3.texi => l3.texi} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/{Ledger3.texi => l3.texi} (100%) diff --git a/doc/Ledger3.texi b/doc/l3.texi similarity index 100% rename from doc/Ledger3.texi rename to doc/l3.texi From 5252db50827f0e28641207ee361d4d399d8e96e7 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 4 Oct 2011 21:50:02 -0700 Subject: [PATCH 16/28] changing Ledger3.texi to ledger3.texi step 2 --- doc/{l3.texi => ledger3.texi} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/{l3.texi => ledger3.texi} (100%) diff --git a/doc/l3.texi b/doc/ledger3.texi similarity index 100% rename from doc/l3.texi rename to doc/ledger3.texi From afd018f1eaed25ebe1adc65681c9fa4ad773f44b Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Tue, 4 Oct 2011 21:51:53 -0700 Subject: [PATCH 17/28] changing LEDGER to Ledger per JW request --- doc/gendocs.sh | 4 +- doc/ledger3.texi | 110 +++++++++++++++++++++++------------------------ 2 files changed, 57 insertions(+), 57 deletions(-) diff --git a/doc/gendocs.sh b/doc/gendocs.sh index 87a83346..fb30181c 100755 --- a/doc/gendocs.sh +++ b/doc/gendocs.sh @@ -1,5 +1,5 @@ #!/bin/bash echo ++++++++++++++++++++++++++ -makeinfo Ledger3.texi +makeinfo ledger3.texi echo ========================== -texi2pdf Ledger3.texi +texi2pdf ledger3.texi diff --git a/doc/ledger3.texi b/doc/ledger3.texi index a7158154..aa48b846 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -43,9 +43,9 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @titlepage -@title LEDGER: Command-Line Accounting -@subtitle For Version 3.0 of LEDGER -@subtitle Draft Manual 2011-10-03 +@title Ledger: Command-Line Accounting +@subtitle For Version 3.0 of Ledger +@subtitle Draft Manual 2011-10-04 @author John Wiegley @end titlepage @@ -58,7 +58,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @ifnottex @node Top, Copying, (dir), (dir) @top Overview -LEDGER is a command line accounting tool that provides double-entry +Ledger is a command line accounting tool that provides double-entry accounting based on a text journal. It provides no bells or whistles, and returns the user to the days before user interfaces were even a twinkling in their father's CRT. @@ -96,7 +96,7 @@ twinkling in their father's CRT. @node Fat-free Accounting, Building the Program, Introduction to Ledger, Introduction to Ledger @section Fat-free Accounting -LEDGER is an accounting tool with the moxie to exist. It provides no +Ledger is an accounting tool with the moxie to exist. It provides no bells or whistles, and returns the user to the days before user interfaces were even a twinkling in their father's CRT. @@ -175,9 +175,9 @@ deal with multiple accounts. Here is a good place for an aside on the use of the word `account'. Most private people consider an account to be something that holds money -at an institution for them. LEDGER uses a more general definition +at an institution for them. Ledger uses a more general definition of the word. An account is anywhere money can go. Other finance -programs use ``categories'', LEDGER uses accounts. So, for +programs use ``categories'', Ledger uses accounts. So, for example, if you buy some groceries at Trader Joe's then more groceries at Whole Foods Markets you might assign the transactions like this @smallexample @@ -193,19 +193,19 @@ the payees were different. You can set up your accounts in any way you choose. Enter the beauty of computerized accounting. The purpose of the -LEDGER program is to make general journal accounting simple, by keeping +Ledger program is to make general journal accounting simple, by keeping track of the balances for you. Your only job is to enter the -postings. If an individual posting does not balance, LEDGER displays an +postings. If an individual posting does not balance, Ledger displays an error and indicates the incorrect posting.@footnote{In some special cases, it automatically balances this transaction for you.} -In summary, there are two aspects of LEDGER use: updating the journal -data file, and using the LEDGER tool to view the summarized result of +In summary, there are two aspects of Ledger use: updating the journal +data file, and using the Ledger tool to view the summarized result of your transactions. And just for the sake of example---as a starting point for those who want to dive in head-first---here are the journal transactions from above, -formatted as the LEDGER program wishes to see them: +formatted as the Ledger program wishes to see them: @smallexample 2004/09/29 Pacific Bell @@ -222,7 +222,7 @@ $ ledger -f ledger.dat register checking $ ledger -f ledger.dat register Bell @end smallexample -An important difference between LEDGER and other finance packages is +An important difference between Ledger and other finance packages is that journal will never alter your input file. You can create and edit that file in any way you prefer, but journal is only for analyzing the data, not for altering it. @@ -231,7 +231,7 @@ data, not for altering it. @node Building the Program, Getting Help, Fat-free Accounting, Introduction to Ledger @section Building the program -LEDGER is written in ANSI C++, and should compile on any platform. It +Ledger is written in ANSI C++, and should compile on any platform. It depends on the GNU multiprecision integer library (libgmp), and the Perl regular expression library (libpcre). It was developed using GNU make and gcc 3.3, on a PowerBook running OS/X. @@ -246,8 +246,8 @@ enter these commands: @node Getting Help, , Building the Program, Introduction to Ledger @section Getting help -If you need help on how to use LEDGER, or run into problems, you can -join the LEDGER mailing list at the following Web address: +If you need help on how to use Ledger, or run into problems, you can +join the Ledger mailing list at the following Web address: @smallexample http://groups.google.com/group/ledger-cli @@ -269,7 +269,7 @@ You can also find help at the @samp{#ledger} channel on the IRC server @section Start a Journal File A journal is a record of your financial transactions and will be central -to using LEDGER. For now we just want to get a taste of what LEDGER can +to using Ledger. For now we just want to get a taste of what Ledger can do. An example journal is included with the source code distribution, called @file{drewr3.dat} (@pxref{Example Data File}). Copy it someplace convenient and open up a terminal window in that @@ -296,7 +296,7 @@ To find the balances of all of your accounts, run this command: ledger -f drewr3.dat balance @end smallexample -LEDGER will generate: +Ledger will generate: @smallexample $ -3,804.00 Assets @@ -348,7 +348,7 @@ To show all transactions and a running total: ledger -f drewr3.dat register @end smallexample -LEDGER will generate: +Ledger will generate: @smallexample 10-Dec-01 Checking balance Assets:Checking $ 1,000.00 $ 1,000.00 @@ -575,26 +575,26 @@ have a good journal, tools can be written to work whatever mathematical tricks you need to better understand your spending patterns. Without a good journal, no tool, however smart, can help you. -The LEDGER program aims at making journal transactions as simple as +The Ledger program aims at making journal transactions as simple as possible. Since it is a command-line tool, it does not provide a user interface for keeping a journal. If you like, you may use GnuCash to -maintain your journal, in which case LEDGER will read +maintain your journal, in which case Ledger will read GnuCash's data files directly. In that case, read the GnuCash manual now, and skip to the next chapter. If you are not using GnuCash, but a text editor to maintain your -journal, read on. LEDGER has been designed to make data transactions as +journal, read on. Ledger has been designed to make data transactions as simple as possible, by keeping the journal format easy, and also by automagically determining as much information as possible based on the nature of your transactions. -For example, you do not need to tell LEDGER about the accounts you -use. Any time LEDGER sees a posting involving an account it knows +For example, you do not need to tell Ledger about the accounts you +use. Any time Ledger sees a posting involving an account it knows nothing about, it will create it@footnote{This also means if you misspell an account it will end up getting counted separately from what you intended. The provided Emacs major mode provides for automatically filling in account names.}. If you use a commodity that is new to -LEDGER, it will create that commodity, and determine its display +Ledger, it will create that commodity, and determine its display characteristics (placement of the symbol before or after the amount, display precision, etc) based on how you used the commodity in the posting. @@ -611,7 +611,7 @@ posting. @node Most Basic Entry, Currency and Commodities, Keeping a Journal, Keeping a Journal @section The Most Basic Entry -Here is the Pacific Bell example from above, given as a LEDGER +Here is the Pacific Bell example from above, given as a Ledger posting, with the additional of a check number: @smallexample @@ -622,8 +622,8 @@ posting, with the additional of a check number: As you can see, it is very similar to what would be written on paper, minus the computed balance totals, and adding in account names that work -better with LEDGER's scheme of things. In fact, since -LEDGER is smart about many things, you don't need to specify the +better with Ledger's scheme of things. In fact, since +Ledger is smart about many things, you don't need to specify the balanced amount, if it is the same as the first line: @smallexample @@ -632,7 +632,7 @@ balanced amount, if it is the same as the first line: Assets:Checking @end smallexample -For this transaction, LEDGER will figure out that $-23.00 must come from +For this transaction, Ledger will figure out that $-23.00 must come from @samp{Assets:Checking} in order to balance the transaction. Also note the structure of the account entries. There is an implied @@ -645,16 +645,16 @@ indent and space out things exactly as shown. The only requirements are that the start of the transaction (the date typically) is at the beginning of the first line of the transaction, and the accounts are indented by at least one space. If you omit the leading spaces in the -account lines LEDGER will not count the transaction and will not +account lines Ledger will not count the transaction and will not give an error. There must be at least two spaces, or a tab, between the amount and the account. If you do not have adequate separation between -the amount and the account LEDGER will give an error and stop +the amount and the account Ledger will give an error and stop calculating} @node Currency and Commodities, Structuring Your Accounts, Most Basic Entry, Keeping a Journal @section Currency and Commodities -LEDGER is agnostic when it comes to how you value your accounts. +Ledger is agnostic when it comes to how you value your accounts. Dollars, Euros, Pounds, Francs, Shares etc. are just ``commodities''. Holdings in stocks, bonds, mutual funds and other financial instruments can be labelled using whatever is convenient for you (stock ticker @@ -761,7 +761,7 @@ Expenses:Food:Hamburgers and Fries @node Transaction Notes and Tags, Multiple Account Transactions, Advanced Transactions, Advanced Transactions @subsection Transaction Notes and Tags -LEDGER 3.0 supports entry and transaction ``notes'', which may +Ledger 3.0 supports entry and transaction ``notes'', which may contain new metadata and tag markers. Here's an example: @smallexample @@ -867,7 +867,7 @@ It would be as if you'd applied "; Location: Chicago", etc., to every transactio @node Multiple Account Transactions, Virtual Transactions, Transaction Notes and Tags, Advanced Transactions @subsection Multiple Account Transactions -Often times a transaction needs to be split across several accounts. This is trivially simple in a LEDGER journal: +Often times a transaction needs to be split across several accounts. This is trivially simple in a Ledger journal: @smallexample 2011/09/15 * Deposit Acme Bytepumps Monthly Paycheck @@ -1495,7 +1495,7 @@ ignored. Comments will not be returned in a ``print'' response. If the semi colon is indented and occurs inside a transaction, it is parsed as a persistent note for its preceding category. These notes or tags can be used to augment to reporting and filtering capabilities of -LEDGER. +Ledger. @item Y If a line begins with a capital Y, it denotes the year used for all subsequent transactions that give a date without a year. The year should @@ -1542,7 +1542,7 @@ C 1.00 Kb = 1024 bytes @end smallexample @item i, o, b, h -These four relate to timeclock support, which permits LEDGER to read +These four 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 @@ -1553,7 +1553,7 @@ syntax of its timelog files. After a while, your journal can get to be pretty large. While this will -not slow down LEDGER---it's designed to process journals very +not slow down Ledger---it's designed to process journals very quickly---things can start to feel ``messy''; and it's a universal complaint that when finances feel messy, people avoid them. @@ -1623,11 +1623,11 @@ doing it. @node Basic Usage, Detailed Options Description, Command-line Syntax, Command-line Syntax @section Basic Usage -This chapter describes LEDGER's features and options. You may wish to +This chapter describes Ledger's features and options. You may wish to survey this to get an overview before diving in to the @ref{Ledger Tutorial} and more detailed examples that follow. -LEDGER has a very simple command-line interface, named---enticingly +Ledger has a very simple command-line interface, named---enticingly enough---@command{ledger}. It supports a few reporting commands, and a large number of options for refining the output from those commands. The basic syntax of any ledger command is: @@ -1702,7 +1702,7 @@ know which version of ledger you are using. @option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. This command may be used multiple times. Typically, the environment variable -@env{LEDGER_FILE} is set, rather than using this command-line option. +@env{Ledger_FILE} is set, rather than using this command-line option. @option{--output FILE} (@option{-o FILE}) redirects output from any command to @var{FILE}. By default, all output goes to standard @@ -1726,12 +1726,12 @@ precedence over settings in the init file. @option{--cache FILE} identifies FILE as the default binary cache file. That is, if the ledger files to be read are specified using the -environment variable @env{LEDGER_FILE}, then whenever a command is +environment variable @env{Ledger_FILE}, then whenever a command is finished a binary copy will be written to the specified cache, to speed up the loading time of subsequent queries. This filename can -also be given using the environment variable @env{LEDGER_CACHE}, or by +also be given using the environment variable @env{Ledger_CACHE}, or by putting the option into your init file. The @option{--no-cache} -option causes LEDGER to always ignore the binary cache. +option causes Ledger to always ignore the binary cache. @option{--account NAME} (@option{-a NAME}) specifies the default account which QIF file postings are assumed to relate to. @@ -1846,7 +1846,7 @@ used for the ``totals'' column in the @command{register} and @node Search Terms, Output Customization, Detailed Options Description, Detailed Options Description @subsection Search Terms -Valid LEDGER invocations look like: +Valid Ledger invocations look like: @smallexample ledger [OPTIONS] @end smallexample @@ -1937,9 +1937,9 @@ negative amount is given, it will invert the meaning of the flag (instead of the first five transactions being printed, for example, it would print all but the first five). -@option{--pager} tells LEDGER to pass its output to the given pager +@option{--pager} tells Ledger to pass its output to the given pager program---very useful when the output is especially long. This -behavior can be made the default by setting the @env{LEDGER_PAGER} +behavior can be made the default by setting the @env{Ledger_PAGER} environment variable. @option{--average} (@option{-A}) reports the average posting @@ -1992,8 +1992,8 @@ restricted to the reporting range (using @option{-d}). format used by reports. The default uses a date like 2004/08/01, which represents the default date format of @samp{%Y/%m/%d}. To change the way dates are printed in general, the easiest way is to put -@option{--date-format FORMAT} in the LEDGER initialization file -@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). +@option{--date-format FORMAT} in the Ledger initialization file +@file{~/.ledgerrc} (or the file referred to by @env{Ledger_INIT}). @option{--format STR} (@option{-F STR}) sets the reporting format for whatever report ledger is about to make. @xref{Format Strings}. @@ -2040,7 +2040,7 @@ and expecting that script to return a value understood by ledger. A sample implementation of a @command{getquote} script, implemented in Perl, is provided in the distribution. Downloaded quote price are then appended to the price database, usually specified using the -environment variable @env{LEDGER_PRICE_DB}. +environment variable @env{Ledger_PRICE_DB}. There are several different ways that ledger can report the totals it displays. The most flexible way to adjust them is by using value @@ -2068,7 +2068,7 @@ a price history. Every option to ledger may be set using an environment variable. If an option has a long name such @option{--this-option}, setting the -environment variable @env{LEDGER_THIS_OPTION} will have the same +environment variable @env{Ledger_THIS_OPTION} will have the same affect as specifying that option on the command-line. Options on the command-line always take precedence over environment variable settings, however. @@ -2210,7 +2210,7 @@ always be the same as the current balance of that account. If you have Gnuplot installed, you may plot the amount or running total of any register by using the script @file{report}, which is -included in the LEDGER distribution. The only requirement is that you +included in the Ledger distribution. The only requirement is that you add either @option{-j} or @option{-J} to your register command, in order to plot either the amount or total column, respectively. @@ -2218,7 +2218,7 @@ order to plot either the amount or total column, respectively. @section print The @command{print} command prints out ledger transactions in a textual -format that can be parsed by LEDGER. They will be properly formatted, +format that can be parsed by Ledger. They will be properly formatted, and output in the most economic form possible. The ``print'' command also takes a list of optional regexps, which will cause only those postings which match in some way to be printed. @@ -2280,7 +2280,7 @@ deviation from that average. There is also a @command{pricesdb} command which outputs the same information as @command{prices}, but does in a format that can be -parsed by LEDGER. +parsed by Ledger. @node xact, , prices, Basic Reporting Commands @section xact @@ -2317,7 +2317,7 @@ This produces the following output: It works by finding a past posting matching the regular expression @samp{viva}, and assuming that any accounts or amounts specified will -be similar to that earlier posting. If LEDGER does not succeed in +be similar to that earlier posting. If Ledger does not succeed in generating a new transaction, an error is printed and the exit code is set to @samp{1}. @@ -2350,7 +2350,7 @@ ledger xact 4/9 viva dining "DM 11.50" @node Value Expressions, Format Strings, Budgeting and Forecasting, Top @chapter Value Expressions -Value expressions are an expression language used by LEDGER to +Value expressions are an expression language used by Ledger to calculate values used by the program for many different purposes: @enumerate From de5b34e4f4570e7f9c1bf75196c3c492d05f7685 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 5 Oct 2011 19:20:19 -0700 Subject: [PATCH 18/28] Initial cut atBudgeting and Forecasting chapter --- doc/ledger3.texi | 93 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/doc/ledger3.texi b/doc/ledger3.texi index aa48b846..ddd9a630 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2346,6 +2346,99 @@ ledger xact 4/9 viva dining "DM 11.50" @node Budgeting and Forecasting, Value Expressions, Basic Reporting Commands, Top @chapter Budgeting and Forecasting +@menu +* Budgeting:: +* Forecasting:: +@end menu + +@node Budgeting, Forecasting, Budgeting and Forecasting, Budgeting and Forecasting +@section Budgeting + +Keeping a budget allows you to pay closer attention to your income and +expenses, by reporting how far your actual financial activity is from +your expectations. + +To start keeping a budget, put some periodic transactions +(@pxref{Periodic Transactions}) at the top of your ledger file. A +period transaction is almost identical to a regular transaction, except +that it begins with a tilde and has a period expression in place of a +payee. For example: + +@smallexample +~ Monthly + Expenses:Rent $500.00 + Expenses:Food $450.00 + Expenses:Auto:Gas $120.00 + Expenses:Insurance $150.00 + Expenses:Phone $125.00 + Expenses:Utilities $100.00 + Expenses:Movies $50.00 + Expenses $200.00 ; all other expenses + Assets + +~ Yearly + Expenses:Auto:Repair $500.00 + Assets +@end smallexample + +These two period transactions give the usual monthly expenses, as well as +one typical yearly expense. For help on finding out what your average +monthly expense is for any category, use a command like: + +@example +ledger -p "this year" --monthly --average --subtotal balance ^expenses +@end example + +The reported totals are the current year's average for each account. + +Once these period transactions are defined, creating a budget report is as +easy as adding @option{--budget} to the command-line. For example, a +typical monthly expense report would be: + +@example +ledger --monthly register ^expenses +@end example + +To see the same report balanced against your budget, use: + +@example +ledger --budget --monthly register ^expenses +@end example + +A budget report includes only those accounts that appear in the +budget. To see all expenses balanced against the budget, use +@option{--add-budget}. You can even see only the unbudgeted expenses +using @option{--unbudgeted}: + +@example +ledger --unbudgeted --monthly register ^expenses +@end example + +You can also use these flags with the @command{balance} command. + +@node Forecasting, , Budgeting, Budgeting and Forecasting +@section Forecasting + +Sometimes it's useful to know what your finances will look like in the +future, such as determining when an account will reach zero. Ledger +makes this easy to do, using the same period transactions as are used for +budgeting. An example forecast report can be generated with: + +@example +ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities +@end example + +This report continues outputting postings until the running total +is greater than $-500.00. A final posting is always output, to +show you what the total afterwards would be. + +Forecasting can also be used with the balance report, but by date +only, and not against the running total: + +@example +ledger --forecast "d<[2010]" bal ^assets ^liabilities +@end example + @node Value Expressions, Format Strings, Budgeting and Forecasting, Top @chapter Value Expressions From 2bd6317c5c560da5b27a6b39ce4f5f1243d6dc60 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 5 Oct 2011 19:31:37 -0700 Subject: [PATCH 19/28] Added grouping option section --- doc/ledger3.texi | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/doc/ledger3.texi b/doc/ledger3.texi index ddd9a630..b920d417 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -459,6 +459,7 @@ $ ledger -f drewr3.dat cleared * Basic Options Quick Reference:: * Report Filtering Quick Reference:: * Output Customization Quick Reference:: +* Grouping Options:: * Commodity Reporting Quick Reference:: @end menu @@ -514,7 +515,7 @@ $ ledger -f drewr3.dat cleared @item @code{-T EXPR} @tab @code{--total} @tab Change the value expression used for ``totals'' column in register and balance reports @end multitable -@node Output Customization Quick Reference, Commodity Reporting Quick Reference, Report Filtering Quick Reference, Command Line Quick Reference +@node Output Customization Quick Reference, Grouping Options, Report Filtering Quick Reference, Command Line Quick Reference @subsection Output Customization @multitable @columnfractions .15 .4 .45 @item @strong{Short} @tab @strong{Long} @tab @strong{Description} @@ -550,7 +551,21 @@ $ ledger -f drewr3.dat cleared @item @code{-w register} @tab @code{--wide-register-format STR} @tab @end multitable -@node Commodity Reporting Quick Reference, , Output Customization Quick Reference, Command Line Quick Reference +@node Grouping Options, Commodity Reporting Quick Reference, Output Customization Quick Reference, Command Line Quick Reference +@subsection Grouping Options +@multitable @columnfractions .1 .25 .65 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{-P} @tab @code{--by-payee} @tab Group postings by common payee names +@item @code{-D} @tab @code{--daily} @tab Group postings by day +@item @code{-W} @tab @code{--weekly} @tab Group postings by week +@item @code{-M} @tab @code{--Monthly} @tab Group postings by month +@item @code{} @tab @code{--quarterly} @tab Group postings by quarter +@item @code{-Y} @tab @code{--yearly} @tab Group postings by year +@item @code{-dow} @tab @code{} @tab Group by day of weeks +@item @code{-s} @tab @code{--subtotal} @tab Group posting together, similar to balance report +@end multitable + +@node Commodity Reporting Quick Reference, , Grouping Options, Command Line Quick Reference @subsection Commodity Reporting @multitable @columnfractions .1 .25 .65 From 9790cb9d01888503d3718390a596d0602dd58dd5 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 5 Oct 2011 20:01:11 -0700 Subject: [PATCH 20/28] Started principles of accounting chapter --- doc/ledger3.texi | 832 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 831 insertions(+), 1 deletion(-) diff --git a/doc/ledger3.texi b/doc/ledger3.texi index b920d417..53fe297f 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -580,7 +580,837 @@ $ ledger -f drewr3.dat cleared @end multitable @node Principles of Accounting, Keeping a Journal, Ledger Tutorial , Top -@chapter Principles of Accounting +@chapter Principles of Accounting with Ledger + + +@menu +* Accounting with Ledger:: +* Stating where money goes:: +* Assets and Liabilities:: +* Typical queries:: +* Commodities and Currencies:: +* Accounts and Inventories:: +* Understanding Equity:: +* Dealing with Petty Cash:: +* Working with multiple funds and accounts:: +@end menu + + +@node Accounting with Ledger, Stating where money goes, Principles of Accounting, Principles of Accounting +@section Accounting with Ledger + +Accounting is simply tracking your money. It can range from nothing, +and just waiting for automatic overdraft protection to kick in, or not, +to a full blown double entry accounting system. Ledger accomplishes the +latter. With ledger you can handle your personal finances or you +businesses. Double-entry accounting scales. + + +@node Stating where money goes, Assets and Liabilities, Accounting with Ledger, Principles of Accounting +@section Stating where money goes + +Accountants will talk of ``credits'' and ``debits'', but the meaning +is often different from the layman's understanding. To avoid +confusion, Ledger uses only subtractions and additions, although the +underlying intent is the same as standard accounting principles. + +Recall that every posting will involve two or more accounts. +Money is transferred from one or more accounts to one or more other +accounts. To record the posting, an amount is @emph{subtracted} +from the source accounts, and @emph{added} to the target accounts. + +In order to write a Ledger transaction correctly, you must determine where +the money comes from and where it goes to. For example, when you are +paid a salary, you must add money to your bank account and also +subtract it from an income account: + +@smallexample +9/29 My Employer + Assets:Checking $500.00 + Income:Salary $-500.00 +@end smallexample + +Why is the Income a negative figure? When you look at the balance +totals for your ledger, you may be surprised to see that Expenses are +a positive figure, and Income is a negative figure. It may take some +getting used to, but to properly use a general ledger you must think +in terms of how money moves. Rather than Ledger ``fixing'' the minus +signs, let's understand why they are there. + +When you earn money, the money has to come from somewhere. Let's call +that somewhere ``society''. In order for society to give you an +income, you must take money away (withdraw) from society in order to +put it into (make a payment to) your bank. When you then spend that +money, it leaves your bank account (a withdrawal) and goes back to +society (a payment). This is why Income will appear negative---it +reflects the money you have drawn from society---and why Expenses will +be positive---it is the amount you've given back. These additions and +subtractions will always cancel each other out in the end, because you +don't have the ability to create new money: it must always come from +somewhere, and in the end must always leave. This is the beginning of +economy, after which the explanation gets terribly difficult. + +Based on that explanation, here's another way to look at your balance +report: every negative figure means that that account or person or +place has less money now than when you started your ledger; and every +positive figure means that that account or person or place has more +money now than when you started your ledger. Make sense? + +@node Assets and Liabilities, Typical queries, Stating where money goes, Principles of Accounting +@section Assets and Liabilities + +Assets are money that you have, and Liabilities are money that you +owe. ``Liabilities'' is just a more inclusive name for Debts. + +An Asset is typically increased by transferring money from an Income +account, such as when you get paid. Here is a typical transaction: + +@smallexample +2004/09/29 My Employer + Assets:Checking $500.00 + Income:Salary +@end smallexample + +Money, here, comes from an Income account belonging to ``My +Employer'', and is transferred to your checking account. The money is +now yours, which makes it an Asset. + +Liabilities track money owed to others. This can happen when you +borrow money to buy something, or if you owe someone money. Here is +an example of increasing a MasterCard liability by spending money with +it: + +@smallexample +2004/09/30 Restaurant + Expenses:Dining $25.00 + Liabilities:MasterCard +@end smallexample + +The Dining account balance now shows $25 spent on Dining, and a +corresponding $25 owed on the MasterCard---and therefore shown as +$-25.00. The MasterCard liability shows up as negative because it +offsets the value of your assets. + +The combined total of your Assets and Liabilities is your net worth. +So to see your current net worth, use this command: + +@example +ledger balance ^assets ^liabilities +@end example + +Relatedly, your Income accounts show up negative, because they +transfer money @emph{from} an account in order to increase your +assets. Your Expenses show up positive because that is where the +money went to. The combined total of Income and Expenses is your cash +flow. A positive cash flow means you are spending more than you make, +since income is always a negative figure. To see your current cash +flow, use this command: + +@example +ledger balance ^income ^expenses +@end example + +Another common question to ask of your expenses is: How much do I +spend each month on X? Ledger provides a simple way of displaying +monthly totals for any account. Here is an example that summarizes +your monthly automobile expenses: + +@example +ledger -M register expenses:auto +@end example + +This assumes, of course, that you use account names like +@samp{Expenses:Auto:Gas} and @samp{Expenses:Auto:Repair}. + +@menu +* Tracking reimbursable expenses:: +@end menu + +@node Tracking reimbursable expenses, , Assets and Liabilities, Assets and Liabilities +@subsection Tracking reimbursable expenses + +Sometimes you will want to spend money on behalf of someone else, +which will eventually get repaid. Since the money is still ``yours'', +it is really an asset. And since the expenditure was for someone +else, you don't want it contaminating your Expenses reports. You will +need to keep an account for tracking reimbursements. + +This is fairly easy to do in ledger. When spending the money, spend +it @emph{to} your Assets:Reimbursements, using a different account for +each person or business that you spend money for. For example: + +@smallexample +2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard +@end smallexample + +This shows $100.00 spent on a MasterCard at Circuit City, with the +expense was made on behalf of Company XYZ. Later, when Company XYZ +pays the amount back, the money will transfer from that reimbursement +account back to a regular asset account: + +@smallexample +2004/09/29 Company XYZ + Assets:Checking $100.00 + Assets:Reimbursements:Company XYZ +@end smallexample + +This deposits the money owed from Company XYZ into a checking account, +presumably because they paid the amount back with a check. + +But what to do if you run your own business, and you want to keep +track of expenses made on your own behalf, while still tracking +everything in a single ledger file? This is more complex, because you +need to track two separate things: 1) The fact that the money should +be reimbursed to you, and 2) What the expense account was, so that you +can later determine where your company is spending its money. + +This kind of posting is best handled with mirrored postings in +two different files, one for your personal accounts, and one for your +company accounts. But keeping them in one file involves the same +kinds of postings, so those are what is shown here. First, the +personal transaction, which shows the need for reimbursement: + +@smallexample +2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard +@end smallexample + +This is the same as above, except that you own Company XYZ, and are +keeping track of its expenses in the same ledger file. This transaction +should be immediately followed by an equivalent transaction, which shows the +kind of expense, and also notes the fact that $100.00 is now payable +to you: + +@smallexample +2004/09/29 Circuit City + Company XYZ:Expenses:Computer:Software $100.00 + Company XYZ:Accounts Payable:Your Name +@end smallexample + +This second transaction shows that Company XYZ has just spent $100.00 on +software, and that this $100.00 came from Your Name, which must be +paid back. + +These two transactions can also be merged, to make things a little clearer. +Note that all amounts must be specified now: + +@smallexample +2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard $-100.00 + Company XYZ:Expenses:Computer:Software $100.00 + Company XYZ:Accounts Payable:Your Name $-100.00 +@end smallexample + +To ``pay back'' the reimbursement, just reverse the order of +everything, except this time drawing the money from a company asset, +paying it to accounts payable, and then drawing it again from the +reimbursement account, and paying it to your personal asset account. +It's easier shown than said: + +@smallexample +2004/10/15 Company XYZ + Assets:Checking $100.00 + Assets:Reimbursements:Company XYZ $-100.00 + Company XYZ:Accounts Payable:Your Name $100.00 + Company XYZ:Assets:Checking $-100.00 +@end smallexample + +And now the reimbursements account is paid off, accounts payable is +paid off, and $100.00 has been effectively transferred from the +company's checking account to your personal checking account. The +money simply ``waited''---in both @samp{Assets:Reimbursements:Company +XYZ}, and @samp{Company XYZ:Accounts Payable:Your Name}---until such +time as it could be paid off. + +The value of tracking expenses from both sides like that is that you +do not contaminate your personal expense report with expenses made on +behalf of others, while at the same time making it possible to +generate accurate reports of your company's expenditures. It is more +verbose than just paying for things with your personal assets, but it +gives you a very accurate information trail. + +The advantage to keep these doubled transactions together is that they +always stay in sync. The advantage to keeping them apart is that it +clarifies the transfer's point of view. To keep the postings in +separate files, just separate the two transactions that were joined above. +For example, for both the expense and the pay-back shown above, the +following four transactions would be created. Two in your personal ledger +file: + +@smallexample +2004/09/29 Circuit City + Assets:Reimbursements:Company XYZ $100.00 + Liabilities:MasterCard $-100.00 + +2004/10/15 Company XYZ + Assets:Checking $100.00 + Assets:Reimbursements:Company XYZ $-100.00 +@end smallexample + +And two in your company ledger file: + +@smallexample +!account Company XYZ + +2004/09/29 Circuit City + Expenses:Computer:Software $100.00 + Accounts Payable:Your Name $-100.00 + +2004/10/15 Company XYZ + Accounts Payable:Your Name $100.00 + Assets:Checking $-100.00 + +!end +@end smallexample + +(Note: The @samp{!account} above means that all accounts mentioned in +the file are children of that account. In this case it means that all +activity in the file relates to Company XYZ). + +After creating these transactions, you will always know that $100.00 was +spent using your MasterCard on behalf of Company XYZ, and that Company +XYZ spent the money on computer software and paid it back about two +weeks later. + +@node Typical queries, Commodities and Currencies, Assets and Liabilities, Principles of Accounting +@section Typical queries + +A query such as the following shows all expenses since last +October, sorted by total: + +@example +ledger -b "last oct" -s -S T bal ^expenses +@end example + +From left to right the options mean: Show transactions since October, 2003; +show all sub-accounts; sort by the absolute value of the total; and +report the balance for all expenses. + +@menu +* Reporting monthly expenses:: +* Visualizing with Gnuplot:: +@end menu + +@node Reporting monthly expenses, Visualizing with Gnuplot, Typical queries, Typical queries +@subsection Reporting monthly expenses + +The following query makes it easy to see monthly expenses, with each +month's expenses sorted by the amount: + +@example +ledger -M --period-sort t reg ^expenses +@end example + +Now, you might wonder where the money came from to pay for these +things. To see that report, add @option{-r}, which shows the +``related account'' postings: + +@example +ledger -M --period-sort t -r reg ^expenses +@end example + +But maybe this prints too much information. You might just want to +see how much you're spending with your MasterCard. That kind of query +requires the use of a display predicate, since the postings +calculated must match @samp{^expenses}, while the postings +displayed must match @samp{mastercard}. The command would be: + +@example +ledger -M -r -d /mastercard/ reg ^expenses +@end example + +This query says: Report monthly subtotals; report the ``related +account'' postings; display only related postings whose +account matches @samp{mastercard}, and base the calculation on +postings matching @samp{^expenses}. + +This works just as well for report the overall total, too: + +@example +ledger -s -r -d /mastercard/ reg ^expenses +@end example + +The @option{-s} option subtotals all postings, just as @option{-M} +subtotaled by the month. The running total in both cases is off, +however, since a display expression is being used. + +@node Visualizing with Gnuplot, , Reporting monthly expenses, Typical queries +@subsection Visualizing with Gnuplot + +If you have @command{Gnuplot} installed, you can graph any of the +above register reports. The script to do this is included in the +ledger distribution, and is named @file{scripts/report}. Install +@file{report} anywhere along your @env{PATH}, and then use +@command{report} instead of @command{ledger} when doing a register +report. The only thing to keep in mind is that you must specify +@option{-j} or @option{-J} to indicate whether Gnuplot should plot the +amount, or the running total. For example, this command plots total +monthly expenses made on your MasterCard. + +@example +report -j -M -r -d /mastercard/ reg ^expenses +@end example + +The @command{report} script is a very simple Bourne shell script, that +passes a set of scripted commands to Gnuplot. Feel free to modify the +script to your liking, since you may prefer histograms to line plots, +for example. + +@menu +* Typical plots:: +@end menu + +@node Typical plots, , Visualizing with Gnuplot, Visualizing with Gnuplot +@subsubsection Typical plots + +Here are some useful plots: + +@smallexample +report -j -M reg ^expenses # monthly expenses +report -J reg checking # checking account balance +report -J reg ^income ^expenses # cash flow report + +# net worth report, ignoring non-$ postings + +report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab + +# net worth report starting last February. the use of a display +# predicate (-d) is needed, otherwise the balance will start at +# zero, and thus the y-axis will not reflect the true balance + +report -J -l "Ua>=@{\$0.01@}" -d "d>=[last feb]" reg ^assets ^liab +@end smallexample + +The last report uses both a calculation predicate (@option{-l}) and a +display predicate (@option{-d}). The calculation predicates limits +the report to postings whose amount is greater than $1 (which can +only happen if the posting amount is in dollars). The display +predicate limits the transactions @emph{displayed} to just those since last +February, even those transactions from before then will be computed as part +of the balance. + + +@node Commodities and Currencies, Accounts and Inventories, Typical queries, Principles of Accounting +@section Commodities and Currencies + +Ledger makes no assumptions about the commodities you use; it only +requires that you specify a commodity. The commodity may be any +non-numeric string that does not contain a period, comma, forward +slash or at-sign. It may appear before or after the amount, although +it is assumed that symbols appearing before the amount refer to +currencies, while non-joined symbols appearing after the amount refer +to commodities. Here are some valid currency and commodity +specifiers: + +@example +$20.00 ; currency: twenty US dollars +40 AAPL ; commodity: 40 shares of Apple stock +60 DM ; currency: 60 Deutsch Mark +£50 ; currency: 50 British pounds +50 EUR ; currency: 50 Euros (or use appropriate symbol) +@end example + +Ledger will examine the first use of any commodity to determine how +that commodity should be printed on reports. It pays attention to +whether the name of commodity was separated from the amount, whether +it came before or after, the precision used in specifying the amount, +whether thousand marks were used, etc. This is done so that printing +the commodity looks the same as the way you use it. + +An account may contain multiple commodities, in which case it will +have separate totals for each. For example, if your brokerage account +contains both cash, gold, and several stock quantities, the balance +might look like: + +@smallexample + $200.00 +100.00 AU + AAPL 40 + BORL 100 + FEQTX 50 Assets:Brokerage +@end smallexample + +This balance report shows how much of each commodity is in your +brokerage account. + +Sometimes, you will want to know the current street value of your +balance, and not the commodity totals. For this to happen, you must +specify what the current price is for each commodity. The price can +be any commodity, in which case the balance will be computed in terms +of that commodity. The usual way to specify prices is with a price +history file, which might look like this: + +@smallexample +P 2004/06/21 02:18:01 FEQTX $22.49 +P 2004/06/21 02:18:01 BORL $6.20 +P 2004/06/21 02:18:02 AAPL $32.91 +P 2004/06/21 02:18:02 AU $400.00 +@end smallexample + +Specify the price history to use with the @option{--price-db} option, +with the @option{-V} option to report in terms of current market +value: + +@example +ledger --price-db prices.db -V balance brokerage +@end example + +The balance for your brokerage account will be reported in US dollars, +since the prices database uses that currency. + +@smallexample +$40880.00 Assets:Brokerage +@end smallexample + +You can convert from any commodity to any other commodity. Let's say +you had $5000 in your checking account, and for whatever reason you +wanted to know many ounces of gold that would buy, in terms of the +current price of gold: + +@example +ledger -T "@{1 AU@}*(O/P@{1 AU@})" balance checking +@end example + +Although the total expression appears complex, it is simply saying +that the reported total should be in multiples of AU units, where the +quantity is the account total divided by the price of one AU. Without +the initial multiplication, the reported total would still use the +dollars commodity, since multiplying or dividing amounts always keeps +the left value's commodity. The result of this command might be: + +@smallexample +14.01 AU Assets:Checking +@end smallexample + +@menu +* Commodity Price Histories:: +* Commodity equivalencies:: +@end menu + +@node Commodity Price Histories, Commodity equivalencies, Commodities and Currencies, Commodities and Currencies +@subsection Commodity price histories + +Whenever a commodity is purchased using a different commodity (such as +a share of common stock using dollars), it establishes a price for +that commodity on that day. It is also possible, by recording price +details in a ledger file, to specify other prices for commodities at +any given time. Such price transactions might look like those below: + +@smallexample +P 2004/06/21 02:17:58 TWCUX $27.76 +P 2004/06/21 02:17:59 AGTHX $25.41 +P 2004/06/21 02:18:00 OPTFX $39.31 +P 2004/06/21 02:18:01 FEQTX $22.49 +P 2004/06/21 02:18:02 AAPL $32.91 +@end smallexample + +By default, ledger will not consider commodity prices when generating +its various reports. It will always report balances in terms of the +commodity total, rather than the current value of those commodities. +To enable pricing reports, use one of the commodity reporting options. + +@node Commodity equivalencies, , Commodity Price Histories, Commodities and Currencies +@subsection Commodity equivalencies + +Sometimes a commodity has several forms which are all equivalent. An +example of this is time. Whether tracked in terms of minutes, hours +or days, it should be possible to convert between the various forms. +Doing this requires the use of commodity equivalencies. + +For example, you might have the following two postings, one which +transfers an hour of time into a @samp{Billable} account, and another +which decreases the same account by ten minutes. The resulting report +will indicate that fifty minutes remain: + +@smallexample +2005/10/01 Work done for company + Billable:Client 1h + Project:XYZ + +2005/10/02 Return ten minutes to the project + Project:XYZ 10m + Billable:Client +@end smallexample + +Reporting the balance for this ledger file produces: + +@smallexample + 50.0m Billable:Client + -50.0m Project:XYZ +@end smallexample + +This example works because ledger already knows how to handle seconds, +minutes and hours, as part of its time tracking support. Defining +other equivalencies is simple. The following is an example that +creates data equivalencies, helpful for tracking bytes, kilobytes, +megabytes, and more: + +@smallexample +C 1.00 Kb = 1024 b +C 1.00 Mb = 1024 Kb +C 1.00 Gb = 1024 Mb +C 1.00 Tb = 1024 Gb +@end smallexample + +Each of these definitions correlates a commodity (such as @samp{Kb}) +and a default precision, with a certain quantity of another commodity. +In the above example, kilobytes are reporetd with two decimal places +of precision and each kilobyte is equal to 1024 bytes. + +Equivalency chains can be as long as desired. Whenever a commodity +would report as a decimal amount (less than @samp{1.00}), the next +smallest commodity is used. If a commodity could be reported in terms +of a higher commodity without resulting to a partial fraction, then +the larger commodity is used. + +@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Principles of Accounting +@section Accounts and Inventories + +Since Ledger's accounts and commodity system is so flexible, you can +have accounts that don't really exist, and use commodities that no one +else recognizes. For example, let's say you are buying and selling +various items in EverQuest, and want to keep track of them using a +ledger. Just add items of whatever quantity you wish into your +EverQuest account: + +@smallexample +9/29 Get some stuff at the Inn + Places:Black's Tavern -3 Apples + Places:Black's Tavern -5 Steaks + EverQuest:Inventory +@end smallexample + +Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The +amounts are negative, because you are taking @emph{from} Black's +Tavern in order to add to your Inventory account. Note that you don't +have to use @samp{Places:Black's Tavern} as the source account. You +could use @samp{EverQuest:System} to represent the fact that you +acquired them online. The only purpose for choosing one kind of +source account over another is for generate more informative reports +later on. The more you know, the better analysis you can perform. + +If you later sell some of these items to another player, the transaction +would look like: + +@smallexample +10/2 Sturm Brightblade + EverQuest:Inventory -2 Steaks + EverQuest:Inventory 15 Gold +@end smallexample + +Now you've turned 2 steaks into 15 gold, courtesy of your customer, +Sturm Brightblade. + +@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Principles of Accounting +@section Understanding Equity + +The most confusing transaction in any ledger will be your equity account--- +because starting balances can't come out of nowhere. + +When you first start your ledger, you will likely already have money +in some of your accounts. Let's say there's $100 in your checking +account; then add a transaction to your ledger to reflect this amount. +Where will money come from? The answer: your equity. + +@smallexample +10/2 Opening Balance + Assets:Checking $100.00 + Equity:Opening Balances +@end smallexample + +But what is equity? You may have heard of equity when people talked +about house mortgages, as ``the part of the house that you own''. +Basically, equity is like the value of something. If you own a car +worth $5000, then you have $5000 in equity in that car. In order to +turn that car (a commodity) into a cash flow, or a credit to your bank +account, you will have to debit the equity by selling it. + +When you start a ledger, you are probably already worth something. +Your net worth is your current equity. By transferring the money in +the ledger from your equity to your bank accounts, you are crediting +the ledger account based on your prior equity. That is why, when you +look at the balance report, you will see a large negative number for +Equity that never changes: Because that is what you were worth (what +you debited from yourself in order to start the ledger) before the +money started moving around. If the total positive value of your +assets is greater than the absolute value of your starting equity, it +means you are making money. + +Clear as mud? Keep thinking about it. Until you figure it out, put +@samp{-Equity} at the end of your balance command, to remove the +confusing figure from the total. + +@node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Principles of Accounting +@section Dealing with Petty Cash + +Something that stops many people from keeping a ledger at all is the +insanity of tracking small cash expenses. They rarely generate a +receipt, and there are often a lot of small postings, rather than +a few large ones, as with checks. + +One solution is: don't bother. Move your spending to a debit card, +but in general ignore cash. Once you withdraw it from the ATM, mark +it as already spent to an @samp{Expenses:Cash} category: + +@smallexample +2004/03/15 ATM + Expenses:Cash $100.00 + Assets:Checking +@end smallexample + +If at some point you make a large cash expense that you want to track, +just ``move'' the amount of the expense from @samp{Expenses:Cash} into +the target account: + +@smallexample +2004/03/20 Somebody + Expenses:Food $65.00 + Expenses:Cash +@end smallexample + +This way, you can still track large cash expenses, while ignoring all +of the smaller ones. + +@node Working with multiple funds and accounts, , Dealing with Petty Cash, Principles of Accounting +@section Working with multiple funds and accounts + +There are situations when the accounts you're tracking are different +between your clients and the financial institutions where money is +kept. An example of this is working as the treasurer for a religious +institution. From the secular point of view, you might be working +with three different accounts: + +@itemize +@item Checking +@item Savings +@item Credit Card +@end itemize + +From a religious point of view, the community expects to divide its +resources into multiple ``funds'', from which it makes purchases or +reserves resources for later: + +@itemize +@item School fund +@item Building fund +@item Community fund +@end itemize + +The problem with this kind of setup is that when you spend money, it +comes from two or more places at once: the account and the fund. And +yet, the correlation of amounts between funds and accounts is rarely +one-to-one. What if the school fund has @samp{$500.00}, but +@samp{$400.00} of that comes from Checking, and @samp{$100.00} from +Savings? + +Traditional finance packages require that the money reside in only one +place. But there are really two ``views'' of the data: from the +account point of view and from the fund point of view -- yet both sets +should reflect the same overall expenses and cash flow. It's simply +where the money resides that differs. + +This situation can be handled one of two ways. The first is using +virtual postings to represent the fact that money is moving to and +from two kind of accounts at the same time: + +@smallexample +2004/03/20 Contributions + Assets:Checking $500.00 + Income:Donations + +2004/03/25 Distribution of donations + [Funds:School] $300.00 + [Funds:Building] $200.00 + [Assets:Checking] $-500.00 +@end smallexample + +The use of square brackets in the second transaction ensures that the +virtual postings balance to zero. Now money can be spent directly +from a fund at the same time as money is drawn from a physical +account: + +@smallexample +2004/03/25 Payment for books (paid from Checking) + Expenses:Books $100.00 + Assets:Checking $-100.00 + (Funds:School) $-100.00 +@end smallexample + +When reports are generated, by default they'll appear in terms of the +funds. In this case, you will likely want to mask out your +@samp{Assets} account, because otherwise the balance won't make much +sense: + +@example +ledger bal -^Assets +@end example + +If the @option{--real} option is used, the report will be in terms of +the real accounts: + +@example +ledger --real bal +@end example + +If more asset accounts are needed as the source of a posting, just +list them as you would normally, for example: + +@smallexample +2004/03/25 Payment for books (paid from Checking) + Expenses:Books $100.00 + Assets:Checking $-50.00 + Liabilities:Credit Card $-50.00 + (Funds:School) $-100.00 +@end smallexample + +The second way of tracking funds is to use transaction codes. In this +respect the codes become like virtual accounts that embrace the entire +set of postings. Basically, we are associating a transaction with a +fund by setting its code. Here are two transactions that desposit money +into, and spend money from, the @samp{Funds:School} fund: + +@smallexample +2004/03/25 (Funds:School) Donations + Assets:Checking $100.00 + Income:Donations + +2004/04/25 (Funds:School) Payment for books + Expenses:Books $50.00 + Assets:Checking +@end smallexample + +Note how the accounts now relate only to the real accounts, and any +balance or registers reports will reflect this. That the transactions +relate to a particular fund is kept only in the code. + +How does this become a fund report? By using the +@option{--code-as-payee} option, you can generate a register report +where the payee for each posting shows the code. Alone, this is +not terribly interesting; but when combined with the +@option{--by-payee} option, you will now see account subtotals for any +postings related to a specific fund. So, to see the current +monetary balances of all funds, the command would be: + +@smallexample +ledger --code-as-payee -P reg ^Assets +@end smallexample + +Or to see a particular funds expenses, the @samp{School} fund in this +case: + +@smallexample +ledger --code-as-payee -P reg ^Expenses -- School +@end smallexample + +Both approaches yield different kinds of flexibility, depending on how +you prefer to think of your funds: as virtual accounts, or as tags +associated with particular transactions. Your own tastes will decide which +is best for your situation. + @node Keeping a Journal, Command-line Syntax, Principles of Accounting, Top @chapter Keeping a Journal From 30e20e344000d9e945e4e41d981703cd8ffaef54 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 5 Oct 2011 20:25:49 -0700 Subject: [PATCH 21/28] Updated draft version on manual --- doc/ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 53fe297f..1896ebac 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -45,7 +45,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @titlepage @title Ledger: Command-Line Accounting @subtitle For Version 3.0 of Ledger -@subtitle Draft Manual 2011-10-04 +@subtitle Draft Manual 2011-10-05 @author John Wiegley @end titlepage From e9ccb012c2c5ffe0e9f4916ee859bda95d9d4248 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 5 Oct 2011 22:11:36 -0700 Subject: [PATCH 22/28] added auto timestamp to draft version --- doc/ledger3.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 1896ebac..44af50d3 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -45,7 +45,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @titlepage @title Ledger: Command-Line Accounting @subtitle For Version 3.0 of Ledger -@subtitle Draft Manual 2011-10-05 +@subtitle Draft Manual Time-stamp: <2011-10-05 22:09 (cpearls)> @author John Wiegley @end titlepage From f99bb40a64852ef3f56639a04a111ae7eb3c1b72 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Sun, 9 Oct 2011 15:41:44 -0700 Subject: [PATCH 23/28] added --anon option to documentation --- doc/ledger3.texi | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 44af50d3..a7b4a66c 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -549,6 +549,7 @@ $ ledger -f drewr3.dat cleared @item @code{} @tab @code{--equity-format STR} @tab @item @code{} @tab @code{--prices-format STR} @tab @item @code{-w register} @tab @code{--wide-register-format STR} @tab +@item @code{} @tab @code{--anon} @tab Print the ledger register with anonymized accounts and payees, usefule for filing bug reports @end multitable @node Grouping Options, Commodity Reporting Quick Reference, Output Customization Quick Reference, Command Line Quick Reference From 95cb4e86b5130e224e004f3e41cf399f6cad8452 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 12 Oct 2011 15:14:07 -0700 Subject: [PATCH 24/28] Corrected typo on pricedb command --- doc/ledger3.texi | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/ledger3.texi b/doc/ledger3.texi index a7b4a66c..7281814b 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -45,7 +45,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @titlepage @title Ledger: Command-Line Accounting @subtitle For Version 3.0 of Ledger -@subtitle Draft Manual Time-stamp: <2011-10-05 22:09 (cpearls)> +@subtitle Draft Manual Time-stamp: <2011-10-12 15:13 (cpearls)> @author John Wiegley @end titlepage @@ -475,7 +475,7 @@ $ ledger -f drewr3.dat cleared @item @code{emacs} @tab Produce emacs lisp output @item @code{equity} @tab Print account balances as transactions @item @code{prices} @tab Print price history for matching commodities -@item @code{pricesdb} @tab Print price history for matching commodities in ledger readable format +@item @code{pricedb} @tab Print price history for matching commodities in ledger readable format @item @code{xact} @tab Used to generate transactions based on previous postings @end multitable @@ -3124,7 +3124,7 @@ commodities. The @option{-A} flag is useful with this report, to display the running average price, or @option{-D} to show each price's deviation from that average. -There is also a @command{pricesdb} command which outputs the same +There is also a @command{pricedb} command which outputs the same information as @command{prices}, but does in a format that can be parsed by Ledger. From d9f72c01eec1971108ad9c6848fd8fa4cd31b8ea Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 19 Oct 2011 20:20:06 -0700 Subject: [PATCH 25/28] Added section about forcing balance checking --- doc/ledger3.texi | 45 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 7281814b..ec0699e5 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -45,7 +45,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @titlepage @title Ledger: Command-Line Accounting @subtitle For Version 3.0 of Ledger -@subtitle Draft Manual Time-stamp: <2011-10-12 15:13 (cpearls)> +@subtitle Draft Manual Time-stamp: <2011-10-19 20:20 (cpearls)> @author John Wiegley @end titlepage @@ -1497,6 +1497,28 @@ amount and the account. If you do not have adequate separation between the amount and the account Ledger will give an error and stop calculating} +@menu +* Checking Balances:: +@end menu + +@node Checking Balances, , Most Basic Entry, Most Basic Entry +@subsection Checking balances + + +Ledger 3.0 has a new feature for confirming +known past balances. Here's an example entry: + +@smallexample + 2008/11/26 (Interest) EXTND INS SWEEP ACCT(FDIC-INS) + * Assets:Brokerage $0.07 = $970.64 + Income:Interest $-0.07 +@end smallexample + +What this says is that as of 11/26/08 (bank perspective), the +Assets:Brokerage account was known to equal $970.64. It @strong{must} +equal this amount at this point in the Ledger file, or there will be a +balancing error. + @node Currency and Commodities, Structuring Your Accounts, Most Basic Entry, Keeping a Journal @section Currency and Commodities @@ -4015,4 +4037,25 @@ ledger register Checking --sort d -d 'd>[2011/04/01]' until 2011/05/25 (Liabilities:Tithe Owed) -1.0 @end smallexample +@subsection --balance-format +On Apr 29, 2010, at 7:58 AM, Peter Ross wrote: + +> All I've found is an email which mentions using %(account), but no +> other information. + +> Is there any documentation anywhere? + +Not yet. Essentialy the new format is %[-][MAX][.MIN](VALEXPR). But it can get a little crazy due to its flexibility, so that the default balance format looks like this: + + "%(justify(scrub(display_total), 20, -1, true, color))" + " %(!options.flat ? depth_spacer : \"\")" + "%-(ansify_if(partial_account(options.flat), blue if color))\n%/" + "%$1\n%/" + "--------------------\n" + +Just imagine the strings concatenated. + +John + + @bye From 8edc4ebf43dbeea56f08f2c9d72c76456dc4b2e0 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 19 Oct 2011 20:28:28 -0700 Subject: [PATCH 26/28] Added section detailing --balance-format --- doc/ledger3.texi | 52 ++++++++++++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/doc/ledger3.texi b/doc/ledger3.texi index ec0699e5..54ddf7e2 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -45,7 +45,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @titlepage @title Ledger: Command-Line Accounting @subtitle For Version 3.0 of Ledger -@subtitle Draft Manual Time-stamp: <2011-10-19 20:20 (cpearls)> +@subtitle Draft Manual Time-stamp: <2011-10-19 20:27 (cpearls)> @author John Wiegley @end titlepage @@ -3540,17 +3540,25 @@ Useful specifying a date in plain terms. For example, you could say @node Format Strings, Journal File Format, Value Expressions, Top @chapter Format Strings +@menu +* Basics:: +* Format Expressions:: +* --balance-format:: +@end menu + +@node Basics, Format Expressions, Format Strings, Format Strings +@section Format String Basics Format strings may be used to change the output format of reports. They are specified by passing a formatting string to the @option{--format} (@option{-F}) option. Within that string, constructs are allowed which make it possible to display the various parts of an account or posting in custom ways. -Within a format strings, a substitution is specified using a percent +Within a format string, a substitution is specified using a percent character (@samp{%}). The basic format of all substitutions is: @smallexample -%[-][MIN WIDTH][.MAX WIDTH]EXPR +%[-][MIN WIDTH][.MAX WIDTH](VALEXPR) @end smallexample If the optional minus sign (@samp{-}) follows the percent character, @@ -3568,7 +3576,12 @@ and will be truncated to fit. Here are some examples: @end smallexample The expression following the format constraints can be a single -letter, or an expression enclosed in parentheses or brackets. The +letter, or an expression enclosed in parentheses or brackets. + +@node Format Expressions, --balance-format, Basics, Format Strings +@section Format Expressions + + The allowable expressions are: @table @code @@ -3685,6 +3698,19 @@ what is printed for all subsequent postings. If not used, the same format string is used for all postings. @end table +@node --balance-format, , Format Expressions, Format Strings +@section --balance-format + +As an example of how flexible the --format strings can be, the default balance format looks like this: + +@smallexample + "%(justify(scrub(display_total), 20, -1, true, color))'' + " %(!options.flat ? depth_spacer : \"\")" + "%-(ansify_if(partial_account(options.flat), blue if color))\n%/" + "%$1\n%/" + "--------------------\n" +@end smallexample + @node Journal File Format, Extending with Python, Format Strings, Top @chapter Journal File Format for Developers @@ -4037,25 +4063,7 @@ ledger register Checking --sort d -d 'd>[2011/04/01]' until 2011/05/25 (Liabilities:Tithe Owed) -1.0 @end smallexample -@subsection --balance-format -On Apr 29, 2010, at 7:58 AM, Peter Ross wrote: -> All I've found is an email which mentions using %(account), but no -> other information. - -> Is there any documentation anywhere? - -Not yet. Essentialy the new format is %[-][MAX][.MIN](VALEXPR). But it can get a little crazy due to its flexibility, so that the default balance format looks like this: - - "%(justify(scrub(display_total), 20, -1, true, color))" - " %(!options.flat ? depth_spacer : \"\")" - "%-(ansify_if(partial_account(options.flat), blue if color))\n%/" - "%$1\n%/" - "--------------------\n" - -Just imagine the strings concatenated. - -John @bye From 884e55afca26f6d1e7cfe8f63e29b1621582dbd3 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Wed, 19 Oct 2011 20:40:27 -0700 Subject: [PATCH 27/28] Added sections describing the payees and accounts commands --- doc/ledger3.texi | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 54ddf7e2..b376840c 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -45,7 +45,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @titlepage @title Ledger: Command-Line Accounting @subtitle For Version 3.0 of Ledger -@subtitle Draft Manual Time-stamp: <2011-10-19 20:27 (cpearls)> +@subtitle Draft Manual Time-stamp: <2011-10-19 20:36 (cpearls)> @author John Wiegley @end titlepage @@ -3206,6 +3206,16 @@ ledger xact 4/9 viva food $11.50 tips $8 cash ledger xact 4/9 viva dining "DM 11.50" @end smallexample +@node payees +@section payees +The @command{payees} reports all of the unique payees in the journal + +@node accounts +@section accounts + +The @command{accounts} reports all of the accounts in the journal. +Following the command with a regular expression will limit the output to +accounts matching the regex. @menu * Budgeting and Forecasting:: From 071d23d821c680880e873752d37df980d173d355 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Sat, 22 Oct 2011 07:09:18 -0700 Subject: [PATCH 28/28] fixed bug 555, stats now properly reports postings per day --- doc/ledger3.texi | 12 +++++++----- src/stats.cc | 4 ++-- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/ledger3.texi b/doc/ledger3.texi index b376840c..922e683c 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -45,7 +45,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. @titlepage @title Ledger: Command-Line Accounting @subtitle For Version 3.0 of Ledger -@subtitle Draft Manual Time-stamp: <2011-10-19 20:36 (cpearls)> +@subtitle Draft Manual Time-stamp: <2011-10-21 21:33 (cpearls)> @author John Wiegley @end titlepage @@ -3050,6 +3050,8 @@ weekly last august * equity:: * prices:: * xact:: +* payees:: +* accounts:: @end menu @node balance, register, Basic Reporting Commands, Basic Reporting Commands @@ -3150,7 +3152,7 @@ There is also a @command{pricedb} command which outputs the same information as @command{prices}, but does in a format that can be parsed by Ledger. -@node xact, , prices, Basic Reporting Commands +@node xact, payees, prices, Basic Reporting Commands @section xact The @command{xact} commands simplifies the creation of new transactions. @@ -3206,11 +3208,11 @@ ledger xact 4/9 viva food $11.50 tips $8 cash ledger xact 4/9 viva dining "DM 11.50" @end smallexample -@node payees +@node payees, accounts, xact, Basic Reporting Commands @section payees -The @command{payees} reports all of the unique payees in the journal +The @command{payees} reports all of the unique payees in the journal. -@node accounts +@node accounts, , payees, Basic Reporting Commands @section accounts The @command{accounts} reports all of the accounts in the journal. diff --git a/src/stats.cc b/src/stats.cc index 172971aa..8899ddf5 100644 --- a/src/stats.cc +++ b/src/stats.cc @@ -88,8 +88,8 @@ value_t report_statistics(call_scope_t& args) out << " ("; out.precision(2); - out << (double((statistics.latest_post - statistics.earliest_post).days()) / - double(statistics.posts_count)) << _(" per day)") << std::endl; + out << (double(statistics.posts_count)/ + double((statistics.latest_post - statistics.earliest_post).days())) << _(" per day)") << std::endl; out << _(" Uncleared postings: "); out.width(6);