diff options
Diffstat (limited to 'doc/L3-JournalFormat.texi')
-rw-r--r-- | doc/L3-JournalFormat.texi | 242 |
1 files changed, 0 insertions, 242 deletions
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. |