/usr/share/doc/ledger/ledger.html/Using-XML.html is in ledger 2.6.2-3.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 | <html lang="en">
<head>
<title>Using XML - Ledger: Command-Line Accounting</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="description" content="Ledger: Command-Line Accounting">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="prev" href="Keeping-a-ledger.html#Keeping-a-ledger" title="Keeping a ledger">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (c) 2003-2009, 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.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Using-XML"></a>
<p>
Previous: <a rel="previous" accesskey="p" href="Keeping-a-ledger.html#Keeping-a-ledger">Keeping a ledger</a>,
Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<hr>
</div>
<h2 class="chapter">4 Using XML</h2>
<p>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.
<p>The general format used for Ledger data is:
<pre class="smallexample"> <?xml version="1.0"?>
<ledger>
<entry>...</entry>
<entry>...</entry>
<entry>...</entry>...
</ledger>
</pre>
<p>The data stream is enclosed in a ‘<samp><span class="samp">ledger</span></samp>’ tag, which contains a
series of one or more entries. Each ‘<samp><span class="samp">entry</span></samp>’ describes the entry
and contains a series of one or more transactions:
<pre class="smallexample"> <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>
</pre>
<p>The date format for ‘<samp><span class="samp">en:date</span></samp>’ is always ‘<samp><span class="samp">YYYY/MM/DD</span></samp>’. The
‘<samp><span class="samp">en:cleared</span></samp>’ tag is optional, and indicates whether the
transaction has been cleared or not. There is also an
‘<samp><span class="samp">en:pending</span></samp>’ tag, for marking pending transactions. The
‘<samp><span class="samp">en:code</span></samp>’ and ‘<samp><span class="samp">en:payee</span></samp>’ tags both contain whatever text the
user wishes.
<p>After the initial entry data, there must follow a set of transactions
marked with ‘<samp><span class="samp">en:transactions</span></samp>’. Typically these transactions will
all balance each other, but if not they will be automatically balanced
into an account named ‘<samp><span class="samp"><Unknown></span></samp>’.
<p>Within the ‘<samp><span class="samp">en:transactions</span></samp>’ tag is a series of one or more
‘<samp><span class="samp">transaction</span></samp>’'s, which have the following form:
<pre class="smallexample"> <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>
</pre>
<p>This is a basic transaction. It may also be begin with
‘<samp><span class="samp">tr:virtual</span></samp>’ and/or ‘<samp><span class="samp">tr:generated</span></samp>’ tags, to indicate virtual
and auto-generated transactions. Then follows the ‘<samp><span class="samp">tr:account</span></samp>’
tag, which contains the full name of the account the transaction is
related to. Colons separate parent from child in an account name.
<p>Lastly follows the amount of the transaction, indicated by
‘<samp><span class="samp">tr:amount</span></samp>’. Within this tag is a ‘<samp><span class="samp">value</span></samp>’ tag, of which
there are four different kinds, each with its own format:
<ol type=1 start=1>
<li>boolean
<li>integer
<li>amount
<li>balance
</ol>
<p>The format of a boolean value is ‘<samp><span class="samp">true</span></samp>’ or ‘<samp><span class="samp">false</span></samp>’
surrounded by a ‘<samp><span class="samp">boolean</span></samp>’ tag, for example:
<pre class="smallexample"> <boolean>true</boolean>
</pre>
<p>The format of an integer value is the numerical value surrounded by an
‘<samp><span class="samp">integer</span></samp>’ tag, for example:
<pre class="smallexample"> <integer>12036</integer>
</pre>
<p>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:
<dl>
<dt><strong>P</strong><dd>The commodity is prefixed to the value.
<br><dt><strong>S</strong><dd>The commodity is separated from the value by a space.
<br><dt><strong>T</strong><dd>Thousands markers are used to display the amount.
<br><dt><strong>E</strong><dd>The format of the amount is European, with period used as a thousands
marker, and comma used as the decimal point.
</dl>
<p>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:
<pre class="smallexample"> <value type="amount">
<amount>
<commodity flags="PT">$</commodity>
<quantity>90.00</quantity>
</amount>
</value>
</pre>
<p>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:
<pre class="smallexample"> <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>
</pre>
<p>That is the extent of the XML data format used by Ledger. It will
output such data if the <samp><span class="command">xml</span></samp> command is used, and can read
the same data as long as the <samp><span class="file">expat</span></samp> library was available
when Ledger was built.
</body></html>
|