Next: , Previous: Assets and Liabilities, Up: Keeping a ledger


3.3 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:

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

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:

       $200.00
     100.00 AU
       AAPL 40
      BORL 100
      FEQTX 50  Assets:Brokerage

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:

     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

Specify the price history to use with the --price-db option, with the -V option to report in terms of current market value:

     ledger --price-db prices.db -V balance brokerage

The balance for your brokerage account will be reported in US dollars, since the prices database uses that currency.

     $40880.00  Assets:Brokerage

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:

     ledger -T "{1 AU}*(O/P{1 AU})" balance checking

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:

     14.01 AU  Assets:Checking

3.3.1 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 entries might look like those below:

     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

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.

3.3.2 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 transactions, one which transfers an hour of time into a ‘Billable’ account, and another which decreases the same account by ten minutes. The resulting report will indicate that fifty minutes remain:

     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

Reporting the balance for this ledger file produces:

            50.0m  Billable:Client
           -50.0m  Project:XYZ

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:

     C 1.00 Kb = 1024 b
     C 1.00 Mb = 1024 Kb
     C 1.00 Gb = 1024 Mb
     C 1.00 Tb = 1024 Gb

Each of these definitions correlates a commodity (such as ‘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 ‘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.