diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,30 @@ +Copyright (c) 2011-2012 Omari Norman. +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 Omari Norman 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 +HOLDER 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. diff --git a/Setup.hs b/Setup.hs new file mode 100644 --- /dev/null +++ b/Setup.hs @@ -0,0 +1,2 @@ +import Distribution.Simple +main = defaultMain diff --git a/penny-bin.cabal b/penny-bin.cabal new file mode 100644 --- /dev/null +++ b/penny-bin.cabal @@ -0,0 +1,61 @@ +Name: penny-bin +Version: 0.2.0.0 +Cabal-version: >=1.8 +Build-Type: Simple +License: MIT +Copyright: 2012 Omari Norman. +author: Omari Norman +maintainer: omari@smileystation.com +stability: Experimental +homepage: http://www.github.com/massysett/penny +bug-reports: omari@smileystation.com +Category: Console, Finance +License-File: LICENSE +synopsis: Extensible double-entry accounting system - binary + +description: Penny is a double-entry accounting system. It is inspired + by, but incompatible with, John Wiegley's Ledger, which is available + at . Installing this package with cabal + install will install the executable program and the necessary + libraries. For more information, see the page for the Penny library, + at . + + . + + Penny currently is designed only for UNIX-like operating systems. + + . + + You can install this binary simply by typing "cabal install + penny-bin", which will install this binary along with all the + necessary dependencies. However, this will not install any of the + documentation. To get the documentation, you will want to manually + download the "penny-bin-*.tar.gz" file, available at the bottom of the + Hackage page (probably the bottom of the page you are looking at + now.) Alternatively, you can figure out where the "cabal" utility + stored the archive file for you. After unpacking the archive you + will find a file, "penny.1", which is the manual page. You may copy + this file to the appropriate location on your system (maybe + \/usr\/share\/man\/man1) or you can simply view it by giving the + appropriate path to the UNIX "man" command. You will also find the + file "samplePennyFile", which will show you a sample ledger. + +extra-source-files: penny.1 samplePennyFile + +source-repository head + type: git + location: git://github.com/massysett/penny.git + +Executable penny + Build-depends: + base ==4.*, + penny-lib ==0.2.* + + Main-is: penny.hs + GHC-Options: -Wall + if flag(debug) + GHC-Options: -rtsopts -auto-all -caf-all + +Flag debug + Description: Turns on debugging options + Default: False diff --git a/penny.1 b/penny.1 new file mode 100644 --- /dev/null +++ b/penny.1 @@ -0,0 +1,599 @@ +.TH penny 1 + +.SH NAME +penny - report on postings in financial ledger + +.SH SYNOPSIS +penny [posting filter expression] report name [report options] FILE... + +.SH DESCRIPTION + +The +.B penny +program prepares reports based upon the +.B postings +in your ledger file. Each transaction has at least two postings. After +.B penny +verifies that your ledger file is +.I balanced +(that is, every transaction has debits and credits that are equal) +.B penny +splits each transaction into its component postings. After this point, +.B penny +for the most part deals only with postings, not with transactions. + +You may specify a +.I filter expression +that determines which postings are ultimately used for the report. The +filter expression may also contain additional options that perform +tasks other than filtering. For example, you may specify how to +perform text matching (for instance, you may want to use regular +expressions) or you may specify that you want to sort the postings (by +default, they are not sorted and are left in the order in which they +were found in the input ledger). + +Next you must specify a +.IR report . +Currently there are two reports: +.BR postings , +which shows information about each posting, like a checkbook register, and +.BR balance , +which shows you information about the balance of each account. The +report is based only upon the postings that the filter expression +returned. + +You may then specify options pertaining to the report. The +.BR postings +report takes many options that format its output and that specify +which postings are shown in the report; however, postings that the +filter expression returned that are not shown in the report still +affect the running balance. This can be useful if, for example, you +want to see the total balance in your bank account and how some +transactions affect it but you do not want to see all transactions +since the beginning of time. The +.BR balance +report takes many fewer options. + +Finally you may specify one or more files from which to draw the +data. If you do not specify a file, standard input is used. + +The report is always printed to standard output. By default, +.BR penny +sees whether its standard output is a terminal. If so, +.BR penny 's +output is sized to fit the width of the +.BR COLUMNS +environment variable (if it is set) and is printed in color. If +standard output is not a terminal, by default the output is not in +color and will be 80 characters wide. This behavior can be overridden +on the command line. + +Entering the data into the ledger files is your responsibility; +.B penny +will never modify this data. To see how to enter data into the file, +see the file +.BR samplePennyFile , +which is included inside the package for +.BR penny-bin . + +.SH COMPARERS + +Many options perform comparisons; for example, the +.B --date +option compares postings to a date you specify to determine +which postings to keep and which to reject. Where +.I comparer +appears below, you must supply one of the following strings. +You will need to quote many of them, because many of these +characters will have special meaning for your shell. + +.TS +tab(:); +l l l +- - - +lB lB l. +Primary form:Alternate form:Comparison performed +<::Less than +<=::Less than or equal to +==:T{ += +T}:Equals +>::Greater than +>=::Greater than or equal to +/=:!=:Not equal to +.TE + +.SH POSTING FILTERS +.SS Dates + +.TP +.BI "--date | -d " "comparer timespec" + +The date of the posting must be within the time frame given. +.BR date +is the same format as dates in the +.B penny +file and +is either a date alone, such as +.BR 2012-04-25 , +or a date and a time, such as +.BR "2012-04-25 14:25 -0400" . + +.TP +.B --current +Same as +.BI "--date <= " "right now" + +.SS Serials +These perform matching based on serials. For more on serials, +see the section +.B SERIALS +below. Each option takes the form +.IR "option comparer number" . +.TP +.B --globalTransaction +.TQ +.B --revGlobalTransaction +.TQ +.B --globalPosting +.TQ +.B --revGlobalPosting +.TQ +.B --fileTransaction +.TQ +.B --revFileTransaction +.TQ +.B --filePosting +.TQ +.B --revFilePosting + +.SS Pattern matching + +These options allow you to filter postings by specifying a pattern +that must match a particular component of the posting. By default the simple +.I within +matcher is used, and matches are case-insensitive. + +.TP +.BI "--account | -a " pattern +The sub-accounts of the account are separated with colons, and the +match succeeds if the pattern matches this entire colon-separated +name. + +.TP +.BI "--account-level " "number pattern" +The account is separated into sub-accounts, which are numbered +beginning at zero. The match succeeds if the posting has a sub-account +numbered at the given level, and if that sub account matches the given +pattern. + +.TP +.BI --account-any " pattern" +The account is separated into sub-accounts. The match succeeds if the +pattern matches any of a posting's sub-accounts. + +.TP +.BI "--payee | -p " pattern +Succeeds if the pattern matches the posting's payee. If the posting +has no payee, the payee of the parent transaction is used (if there is +one). + +.TP +.BI "--tag | -t " pattern +Succeeds if any one of the posting's tags matches the given pattern. + +.TP +.BI --number " pattern" +Succeeds if the posting's number matches the given pattern. (This is +the number that you specify in parentheses in your ledger file, not +the line number or any of the serial numbers.) If the posting has no +number, the number of the parent transaction is used (if there is +one). + +.TP +.BI --flag " pattern" +Succeeds if the posting's flag matches the given pattern. If the +posting has no number, the flag of the parent transaction is used +(if there is one). + +.TP +.BI --commodity " pattern" +The commodity is separated into colon-separated sub-commodities, and +the test succeeds if the pattern matches the full colon-separated +commodity name. + +.TP +.BI "--commodity-level " "number pattern" +The commodity is separated into sub-commodities, which are numbered +beginning at zero. The match succeeds if the posting has a sub-commodity +numbered at the given level, and if that sub-commodity matches the given +pattern. + +.TP +.BI "--commodity-any " pattern +The commodity is separated into sub-commodities. The match succeeds if +the pattern matches any of a posting's sub-commodities. + +.TP +.BI "--posting-memo " pattern +The posting memo must match the given pattern. + +.TP +.BI "--transaction-memo " pattern +The transaction memo must match the given pattern. + +.SS Other posting characteristics + +.B --debit +The entry must be a debit. + +.B --credit +The entry must be a credit. + +.BI --qty " comparer number" +The entry's quantity must fall within the given range. + +.SS Operators + +Each of the options above is a single operand. If you have multiple +operands, you must join them together using operators. These +operators are specified below, from highest to lowest precedence. All +operators are left associative. + +.TP +.BI "--open " expr " --close" +Force precedence using parentheses. Enclose a complete expression +between the +.B --open +and +.B --close +options. + +.TP +.BI "--not " expr +True if +.I expr +is false. + +.TP +.IB expr1 " --and " expr2 +True if +.I expr1 +and +.I expr2 +are both true. + +.TP +.IB expr1 " --or " expr2 +True if +.I expr1 +or +.I expr2 +is true. + +.SS Options affecting patterns + +These options affect how patterns are interpreted. The order of the +.B penny +command line is significant; each of these options only affects +patterns that appear after it on the command line. + +.TP +.B "-i | --case-insensitive" +Patterns are case insensitive (default) + +.TP +.B "-I | --case-sensitive" +Patterns are case sensitive + +.TP +.B --within +Use the "within" matcher (default), which matches if the pattern given +appears anywhere within the target text. This is a simple +letter-for-letter match, not a regular expression, though its case +sensitivity is affected by the +.B --case-insensitive +and +.B --case-sensitive +options. + +.TP +.B --pcre +Use the "pcre" matcher, which uses Perl-compatible regular expressions (see +.BR pcresyntax "(1) and " pcrepattern (1)) + +.TP +.B --posix +Use the "posix" matcher, which uses POSIX regular expressions (see +.BR regex (7)) + +.TP +.B --exact +Use the "exact" matcher, which matches if the given pattern is a +letter-for-letter match of the target text, with case sensitivity +determined by the +.B --case-insensitive +and +.B --case-sensitive +options. + +.SH Removing postings after sorting and filtering + +.TP +.BI "--head " n +Keep only the first +.I n +postings. + +.TP +.BI "--tail " n +Keep only the last +.I n +postings. + +.SH Sorting + +.TP +.BI "--sort | -s " key +Sorts postings according to a key. Use multiple +.B --sort +options to sort by more than one key. Valid keys are: payee, date, +flag, number, account, drCr, qty, commodity, postingMemo, +transactionMemo. + +The postings are sorted in ascending order if the first letter of the +key is lowercase; descending order if the first letter of the key is +uppercase. + +.SH POSTINGS REPORT + +The +.B postings +report, or +.B pos +for short, shows postings in order with a running balance. This report +takes all the options shown above in the categories from "Posting +filters" to "Removing postings after sorting and filtering." These +options affect which postings are shown in the report. Postings that +are not shown in the report but which were not filtered out in the +filtering stage still affect the report's running balance. + +Additional options for the +.B postings +report: + +.SS Additional serial filtering options +These options affect which postings are shown. Postings that were not +filtered in the filtering stage but that are not shown still affect +the running balance. In addition to using the same options that are +used for filtering, these additional options are available that are +based on some additional serials. They take the form +.IR "option comparer number " . +For more information on serials, see the +.B SERIALS +section below. + +.TP +.B --filtered +filtered serial, forward component +.TQ +.B --revFiltered +filtered serial, reverse component +.TQ +.B --sorted +sorted serial, forward component +.TQ +.B --revSorted +sorted serial, reverse component + +.SS Other additional options for the balance report + +.TP +.BR --color " yes|no|auto|256" +Controls which colors are shown. +.B yes +always shows 8 colors. +.B no +never shows colors. +.B auto +first examines whether standard output is a terminal. If standard output is not a terminal, +.B penny +does not show any colors. If standard output is a terminal, examines +the value of the TERM environment variable. If TERM is +"xterm-256color", uses 256 colors. If TERM is any other value, or if +TERM is not set, uses 8 colors. + +.TP +.BR --background " light|dark" +Pick a color scheme for a light or dark terminal background (by +default, a dark color scheme is used.) + +.TP +.BI --width " num" +Gives a hint for roughly how wide the report should be, in +columns. Sometimes the report will be narrower than the specified +width; however, it will never be wider than the specified width. + +.TP +.BI "--show" " field" +.TQ +.BI "--hide" " field" +Show or hide fields from the displayed report. Fields are displayed in +a fixed order, which is the same as the order that the table below is +in. Fields with an asterisk are shown by default. + +.\" Do not precede the empty fields in the table with any spaces. This +.\" will cause GNU tbl to segfault. +.\" See +.\" http://lists.gnu.org/archive/html/groff/2010-11/msg00014.html +.\" Apparently the bug has been fixed but who knows how long that will +.\" take to propogate. + +.TS +tab(:); +lB lB l. +:globalTransaction:globalTransaction serial, forward component +:revGlobalTransaction:globalTransaction serial, reverse component +:globalPosting:globalPosting serial, forward component +:revGlobalPosting:globalPosting serial, reverse component +:fileTransaction:fileTransaction serial, forward component +:revFileTransaction:fileTransaction serial, reverse component +:filePosting:filePosting serial, forward component +:revFilePosting:filePosting serial, reverse component +:filtered:filtered serial, forward component +:revFiltered:revFiltered serial, reverse component +:sorted:sorted serial, forward component +:revSorted:sorted serial, reverse component +:visible:visible serial, forward component +:revVisible:visible serial, reverse component +:lineNum:line number (starting from 1) +*:date:transaction's date +:flag:posting or transaction flag +:number:posting or transaction's number +*:payee:posting or transaction's payee +*:account:posting's account +*:postingDrCr:whether the posting is a debit or credit +*:postingCmdty:posting's commodity +*:postingQty:posting's quantity +*:totalDrCr:whether the running total is a debit or credit +*:totalCommodity:commodity of the running total +*:totalQty:quantity of the running total +:tags:posting's tags +:memo:the posting and transaction memo +:filename:filename where the posting came from +.TE + +.TP +.B --show-all +Show all fields + +.TP +.B --hide-all +Hide all fields + +.TP +.B --show-zero-balances +Shows the balance of all commodities in the +.IR totalDrCr ", " totalCommodity ", and " totalQty +fields, even if that balance is zero. + +.TP +.B --hide-zero-balances +Hides the balance of commodities in the +.IR totalDrCr ", " totalCommodity ", and " totalQty +fields if they are zero (default) + +.SH BALANCE REPORT +The +.B balance +report summarizes the balances in each account that is represented in +the postings that remain after the filtering specifications are +carried out. You can use sorting specifications with the balance +report, but they will have no effect. The accounts are shown +hierarchically. This report is also useful for converting from one +commodity to another. + +The +.B balance +report accepts the following options: + +.TP +.BI --color " yes|no|auto|256" +Controls how many colors to display: + +.TS +tab(:); +lB l. +yes:always show 8 colors +no:never show any colors +auto:T{ +show 8 or 256 colors, but only if standard output is a terminal. +If standard output is a terminal, shows 256 colors if the value +of the TERM environment variable is \fIxterm-256color\fR; +otherwise, shows 8 colors. +T} +256:always show 256 colors +.TE + +.TP +.BI --background " light|dark" +Use appropriate color scheme for the given terminal background + +.TP +.BI --convert " commodity dateTime" +Convert all commodities to the given commodity using their price as of +the given date and, optionally, time. +.IR commodity " and " dateTime +follow the same format as the respective items in a ledger file. If +any commodity does not have a matching price, +.B penny +will fail and give you an error message. + +.TP +.BI -c " commodity" +Same as +.BI "--convert " "commodity [right now]" + +.SH SERIALS + +Each posting is assigned several +.IR serials , +each of which is a pair of ordinal numbers. The first number in the +pair, or +.IR "forward component" , +is assigned by numbering the transactions or postings from +beginning to end beginning at zero, while the second number in the +pair, or +.IR "reverse component" , +is assigned by numbering the transactions or postings from end to +beginning, beginning at zero. Here are all the serials that are +assigned to each posting. + +.TP +.B globalTransaction +All transactions are numbered in order, beginning with those in the +first file specified on the command line and ending with the last +file. Occurs before the transactions are split into postings. + +.TP +.B fileTransaction +Like +.IR globalTransaction , +but numbering restarts with each new file. + +.TP +.B globalPosting +All postings are numbered in order, beginning with those in the first +file specified on the command line and ending with the last file. + +.TP +.B filePosting +Like +.IR globalPosting , +but numbering restarts with each new file. + +.TP +.B filtered +Postings are numbered after first removing the postings as specified +by the filtering options specified on the command line. + +.TP +.B sorted +Postings are numbered in order after the sorting options have been +applied, which occurs after the filtering options have been applied. + +.TP +.B visible +Postings are numbered in order after removing the postings as +specified by the options to the +.I postings +report. (Does not apply to the +.I balance +report.) + +.SH SEE ALSO +The file +.B samplePennyFile +in the tarball for the +.B penny-bin +package shows you how to write a ledger file. diff --git a/penny.hs b/penny.hs new file mode 100644 --- /dev/null +++ b/penny.hs @@ -0,0 +1,7 @@ +module Main where + +import Penny + +main :: IO () +main = defaultPenny utcDefault periodComma + diff --git a/samplePennyFile b/samplePennyFile new file mode 100644 --- /dev/null +++ b/samplePennyFile @@ -0,0 +1,300 @@ +# Sample Penny file. Penny is a double-entry accounting +# system. Penny uses traditional accounting terminology, +# which means that every transaction will have "debits" +# and "credits". In every single transaction, debits +# must equal credits, or this file will not parse +# and Penny will quit with an error. + +# Penny has no concept of negative numbers. All numbers +# are positive or zero. + +# To learn double-entry accounting, pick up a used accounting +# textbook at your favorite online used book retailer. +# They can be had for under 10 U.S. dollars, as college +# students cast aside old editions that are perfectly good. +# This website is also excellent and is free: +# http://www.principlesofaccounting.com/ + +# As you can see, single line comments begin with +# a hash mark, like a shell script. Currently there +# is no way to make a multi-line comment. + +# Here is a sample transaction to start things off. + +2011/12/15 Salts Deluxe + Assets:Checking Dr $2000.00 + 'Payday + Income:Salary Cr $1500.00 + Expenses:Taxes Cr $500.00 + +; This is a transaction memo. It is associated +; with the transaction, and the penny program lets you +; search their contents. Transaction memos appear immediately +; before a transaction and their lines begin with +; semicolons. +2012/01/01 Payee Name + Assets:Checking Cr $5.00 + Expenses:Food + +# Tags are only one word. Precede each tag with an asterisk. +# Postings can have one or more "tags". These allow you to +# classify postings by tag as well as by account. For example +# you might take a vacation. Various postings might be scattered +# across multiple accounts (Expenses:Food, Expenses:Gas, etc.) +# but you can give them all a *vacation tag. + +# Transactions and postings can have an optional flag. +# The flag is one or more letters. +# It is wrapped in square brackets. +# For instance, this can be used to indicate a posting +# is cleared. + +# Penny uses spaces to separate different parts of the +# transaction. If you want to include spaces in the name +# of an account, you must enclose it in curly braces +# as shown in the next transaction. + +2012/01/02 [C] (302) GreenGas + {Liabilities:Credit Card} Cr $5.00 + Expenses:Car *gas *trips + +# Though the posting lines in this file are nicely indented for +# readability, Penny does not require this. + +; This transaction has a posting with a different payee. +; You can do this by enclosing the payee in greater than +; and less than signs as shown. +; The last posting has a memo. +; These begin with an apostrophe. As with posting lines, the +; indentation is nice for readability, but it is not required. +; (It does have to be on a new line though.) +2012/01/03 Flathead + [R] (905) Expenses:Pet Dr $10.00 + Assets:Checking Cr $5.00 + [*] (2313) {Liabilities:Credit Card} Cr $5.00 + 'This interest rate is too high + +# Flags can be more than one letter. Actually they can include +# any character except ']'. +2012/01/06 [Flagger] Flagged Up Transaction + Expenses:Flags Dr $200.00 + Assets:Checking Cr $200.00 + + +# By default, the digit grouping character is the comma and +# the radix point character is the period. You can configure these +# (somewhat) easily by making changes to the source code (not +# as bad as it sounds, believe it or not.) The digit grouping +# character is really for your benefit; Penny mostly ignores +# it. The radix point is of course quite significant. + +# Commodity names may be before or after the commodity amount. +# They can be separated from the amount by one optional space. + +# To use multiple commodities, use a trading account. +# The best explanation of trading accounts is here: +# http://www.mscs.dal.ca/~selinger/accounting/tutorial.html +# For this transaction, the debits and credits all add up to zero, +# as they always must. If they do not, parsing of the ledger +# file will fail. + +2012/01/05 Stockbroker + Assets:Brokerage Dr 1,000 LUV + Assets:Current:Checking Cr $ 2,000.00 + {Income:Brokerage Trading Account} Cr 1,000 LUV + {Income:Brokerage Trading Account} Dr $ 2,000.00 + +# Prices allow you to specify how to convert one commodity +# to another. Prices do not affect the way any of your +# transactions are parsed. Even if you specify prices, +# you still must ensure that the debits equal the credits +# in every transaction; if they do not, the parser will fail. + +# The balance report uses price information for the --convert and -c +# options. This allows you to convert all commodities in the file to a +# single commodity. Typically you would use this to see what the +# balance of all your accounts is in your home currency. + +# Prices specify that ONE unit of the given commodity +# equals the given quantity of the other commodity. Here +# are some examples. + +@ 2012/01/05 17:55:55 -0500 LUV $9.62 +@ 2012/01/05 Gold $1738.35 + +# Prices only work one way. For instance the first +# price tells you how many dollars one euro is worth, and allows +# reports to convert from euro to dollars. To convert from +# dollars to euro, you must specify another price. +@ 2012/01/05 € $1.3207 +@ 2012/01/05 $ €0.7572 +@ 2012/01/05 ¥ 0.6418 INR + +; Commodities can have several components in their names, +; just as accounts can. Subsequent parts can be viewed as +; sub-commodities. This can be handy if different commodities +; have something in common and you want to group them together. +; For example, let's say you bought shares in T in +; 2007 and in 2012. For tax purposes you want to track them separately +; in your reports (this can matter for capital gains taxes) yet +; shares in T have the same price whether you bought them in 2007 +; or in 2012. So you can have two different symbols, as the following +; two transactions show: +2007/02/01 Bought stock + Assets:Brokerage Dr 100 T:2007 + '$37.75 per share + Assets:Checking Cr $3775 + {Income:Brokerage Trading} Cr 100 T:2007 + {Income:Brokerage Trading} Dr $3775 + +2012/01/12 Bought stock + Assets:Brokerage Dr 100 T:2012 + '$30.12 per share + Assets:Checking Cr $3012 + {Income:Brokerage Trading} Cr 100 T:2012 + {Income:Brokerage Trading} Dr $3012 + +# and some prices to go along with the T example. Because no +# different prices are specified for T:2012 and for T:2007, +# the balance report will use the price for T for both these +# commodities if you use the --convert or -c options. +@ 2007/06/01 T $40.53 +@ 2012/01/27 T $29.16 + +# As the examples above show with the currency symbols, +# Penny works fine with Unicode. +# Your ledger file should be encoded in your system's default +# encoding. On my system this is UTF-8, as it is on most +# recent Linux systems, but some systems use other encodings. +# I know that Slackware was recently using ISO-8859-1. Non-Unicode +# encodings should work fine as well, as Penny will convert them +# to Unicode internally. + +# If your ledger file is encoded in UTF-8 +# and you still have Unicode problems, +# it is a bug. Please report it to me. + +# If you have no idea what all this encoding stuff is about, +# the first thing to remember is that there is no such thing +# as plain text. Read this: +# http://www.joelonsoftware.com/articles/Unicode.html + +# The Penny program will not change your input file. It cannot +# change your input file as it is opened read-only. + +############################################################## + +# Dates - as one example with the prices suggested, dates +# need not be just a date. They can also include a time. +# Internally, Penny records all dates as both dates and times. +# If you give a date but do not give a time, the time is assumed +# to be midnight. +# Of course you cannot have times without timezones. Penny +# assumes each time is in the DefaultTimeZone, which you can configure +# or which you can configure as being in whatever time zone your +# system is set to use. Or of course you can specify the time +# zone by specifying the number of hours and minutes the +# time differs from UTC. To specify UTC, use +0000 or -0000. In the +# default configuration, the DefaultTimeZone is UTC. + +; Transaction that specifies a time. The time zone is the +; DefaultTimeZone, which you can configure. Times must be specified +; using 24 hour time. Leading zeroes are optional for the hours; +; they are mandatory for the minutes and seconds. +2012/01/28 09:58 King Arthur Flour + Expenses:Food Dr $5.25 + 'Sourdough starter! + Assets:Current:Checking + +; Transaction specifying a local time zone +2012/01/28 17:26:44 -0500 Exactamundo + Expenses:Amusements Dr $400 + {Liabilities:Credit Card} Cr $300 + Assets:Current:Checking Cr $100 + +; Transaction specifying UTC. Also, you can always +; spell out "Debit" or "Credit" if you want to. +2012/01/28 23:30 +0000 Pacific Dispatch + Expenses:Newspapers Debit $1.25 + Assets:Cash Credit $1.25 + + +# There are many different ways to write an amount. First, some +# terminology. Some of these terms are specific to Penny; if these +# terms are inconsistent with usual accounting terminology or if +# they don't make sense, please let me know. +# +# A commodity is a thing of value you track in Penny. Typically this +# will be a currency (like $ or €, but it can be whatever you like, +# such as a ticker symbol or some letters to represent your house. + +# A quantity is a number, such as 3 or 65.2 or 33.80. Notice that +# it does not have a commodity. + +# An amount is a quantity and a commodity. + +# An entry is an amount combined with an indication of Debit +# or Credit. + +# You can write commodities and quantities in one of four ways: +# +# * Commodity first, without a separating space. E.g. $100, F25, €59, +# In this case the commodity name CANNOT have any digits. +# +# * Commodity first, with a separating space. E.g. $ 100, € 59. +# +# * Commodity last, without separating space. E.g. 59€. +# +# * Commodity last, with separating space. E.g. 59 €. +# +# In the last three cases, the commodity name can include digits. +# If you want to include spaces in the name of a commodity, surround +# it with "quotes". +# In all cases the commodity name can use sub-commodities by +# using colons. + +# A commodity's identity is determined by the characters you use +# when you type the commodity. Thus EUR 100 and 100 EUR mean the +# same thing, except for the fact that they are formatted differently. + +# The Penny parser does remember the order in which you specified +# the commodity and the quantity for every posting, but currently +# nothing is done with this information. For instance, in the +# postings report, the commodity is always shown first. + +# Here's an example. Note that the transaction balances +# because the commodity is the same whether written before or after +# the quantity. + +2012/01/30 Benny Broker + Assets:Brokerage Dr MSFT100 + Assets:Current:Checking Cr 2959 $ + {Income:Stock Trading Account} Cr 100 MSFT + {Income:Stock Trading Acccount} Dr $2959 + + +# What's the difference between transaction memos, posting +# memos, and comments? Here I will draw a distinction between +# penny (lower case), which is the command-line executable +# program, and the Penny parser (upper case), which is the Haskell +# module that parses your Penny ledger file. Thus penny lower-case +# is the binary; Penny is broader and encompasses the library +# as well as the program. + +# So, the Penny parser does see and remember transaction memos, +# posting memos, and comments. However, it does not pass +# comments along to the rest of the penny command-line program. +# The penny command-line program only deals with transactions +# and postings; transactions and postings can have +# memos associated with them. + +# Therefore, using the penny command-line program, you can only +# search memos, not comments. However, the fact that the Penny +# parser does see comments might be useful if you are going to +# write your own Haskell code using the parser. For instance, +# you might want to transform your Penny ledger (maybe to +# automatically reconcile your checking account statement). +# By writing your own code using the Penny parser, you can +# do transformations like this while still keeping your comments +# intact. Pretty neat. +