4 Using XML

By default, Ledger uses a human-readable data format, and displays its reports in a manner meant to be read on screen. For the purpose of writing tools which use Ledger, however, it is possible to read and display data using XML. This chapter documents that format.

The general format used for Ledger data is:

<?xml version="1.0"?>
<ledger>
  <entry>...</entry>
  <entry>...</entry>
  <entry>...</entry>...
</ledger>

The data stream is enclosed in a ‘ledger’ tag, which contains a series of one or more entries. Each ‘entry’ describes the entry and contains a series of one or more transactions:

<entry>
  <en:date>2004/03/01</en:date>
  <en:cleared/>
  <en:code>100</en:code>
  <en:payee>John Wiegley</en:payee>
  <en:transactions>
    <transaction>...</transaction>
    <transaction>...</transaction>
    <transaction>...</transaction>...
  </en:transactions>
</entry>

The date format for ‘en:date’ is always ‘YYYY/MM/DD’. The ‘en:cleared’ tag is optional, and indicates whether the transaction has been cleared or not. There is also an ‘en:pending’ tag, for marking pending transactions. The ‘en:code’ and ‘en:payee’ tags both contain whatever text the user wishes.

After the initial entry data, there must follow a set of transactions marked with ‘en:transactions’. Typically these transactions will all balance each other, but if not they will be automatically balanced into an account named ‘<Unknown>’.

Within the ‘en:transactions’ tag is a series of one or more ‘transaction’’s, which have the following form:

<transaction>
  <tr:account>Expenses:Computer:Hardware</tr:account>
  <tr:amount>
    <value type="amount">
      <amount>
        <commodity flags="PT">$</commodity>
        <quantity>90.00</quantity>
      </amount>
    </value>
  </tr:amount>
</transaction>

This is a basic transaction. It may also be begin with ‘tr:virtual’ and/or ‘tr:generated’ tags, to indicate virtual and auto-generated transactions. Then follows the ‘tr:account’ tag, which contains the full name of the account the transaction is related to. Colons separate parent from child in an account name.

Lastly follows the amount of the transaction, indicated by ‘tr:amount’. Within this tag is a ‘value’ tag, of which there are four different kinds, each with its own format:

1. boolean
2. integer
3. amount
4. balance

The format of a boolean value is ‘true’ or ‘false’ surrounded by a ‘boolean’ tag, for example:

<boolean>true</boolean>

The format of an integer value is the numerical value surrounded by an ‘integer’ tag, for example:

<integer>12036</integer>

The format of an amount contains two members, the commodity and the quantity. The commodity can have a set of flags that indicate how to display it. The meaning of the flags (all of which are optional) are:

P

The commodity is prefixed to the value.

S

The commodity is separated from the value by a space.

T

Thousands markers are used to display the amount.

E

The format of the amount is European, with period used as a thousands marker, and comma used as the decimal point.

The actual quantity for an amount is an integer of arbitrary size. Ledger uses the GNU multi-precision math library to handle such values. The XML format assumes the reader to be equally capable. Here is an example amount:

<value type="amount">
  <amount>
    <commodity flags="PT">$</commodity>
    <quantity>90.00</quantity>
  </amount>
</value>

Lastly, a balance value contains a series of amounts, each with a different commodity. Unlike the name, such a value does need to balance. It is called a balance because it sums several amounts. For example:

<value type="balance">
  <balance>
    <amount>
      <commodity flags="PT">$</commodity>
      <quantity>90.00</quantity>
    </amount>
    <amount>
      <commodity flags="TE">DM</commodity>
      <quantity>200.00</quantity>
    </amount>
  </balance>
</value>

That is the extent of the XML data format used by Ledger. It will output such data if the xml command is used, and can read the same data as long as the expat library was available when Ledger was built.