diff options
Diffstat (limited to 'doc/doc.html')
| -rw-r--r-- | doc/doc.html | 190 |
1 files changed, 69 insertions, 121 deletions
diff --git a/doc/doc.html b/doc/doc.html index 1f2774d..c68b447 100644 --- a/doc/doc.html +++ b/doc/doc.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> <head> -<!-- 2022-02-15 mar 08:20 --> +<!-- 2022-02-22 mar 07:37 --> <meta http-equiv="Content-Type" content="text/html;charset=utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Taler-Util Library</title> @@ -247,41 +247,40 @@ for the JavaScript code in this tag. <h2>Table of Contents</h2> <div id="text-table-of-contents"> <ul> -<li><a href="#org02f1529">1. classes overview</a> +<li><a href="#org25ea71b">1. classes overview</a> <ul> -<li><a href="#orgf8d22b2">1.1. amount (currency + value + fraction)</a></li> -<li><a href="#orge70d263">1.2. logging</a></li> -<li><a href="#org69c7ded">1.3. ‘payto’ URI particularities</a></li> -<li><a href="#orga275dd5">1.4. configuration</a></li> +<li><a href="#orgb49dd7e">1.1. amount (currency + value + fraction)</a></li> +<li><a href="#orgb7c6fb1">1.2. logging</a></li> +<li><a href="#org4307498">1.3. ‘payto’ URI particularities</a></li> +<li><a href="#org44d03ed">1.4. configuration</a></li> </ul> </li> -<li><a href="#org3c63bce">2. classes for handling currency plus value plus fraction</a> +<li><a href="#orgd6a98cd">2. classes for handling currency plus value plus fraction</a> <ul> -<li><a href="#org8038926">2.1. class <code>Amount</code></a></li> -<li><a href="#org8292d6a">2.2. class <code>SignedAmount</code></a></li> +<li><a href="#org5d287dc">2.1. class <code>Amount</code></a></li> +<li><a href="#org56a0ae4">2.2. class <code>SignedAmount</code></a></li> </ul> </li> -<li><a href="#org195d8b6">3. classes <code>LogDefinition</code>, <code>GnunetLoglevel</code></a></li> -<li><a href="#org7de92e5">4. class <code>GnunetLogger</code></a> +<li><a href="#orgb9b4b04">3. classes <code>LogDefinition</code>, <code>GnunetLoglevel</code></a></li> +<li><a href="#orga6828fa">4. class <code>GnunetLogger</code></a> <ul> -<li><a href="#org7009ddc">4.1. log definition, environment variables</a></li> -<li><a href="#org1798ccd">4.2. environment variable <code>GNUNET_FORCE_LOGFILE</code></a></li> -<li><a href="#org06b279d">4.3. constructor</a></li> -<li><a href="#org80aed03">4.4. method <code>log</code></a></li> +<li><a href="#org8d3839f">4.1. log definition, environment variables</a></li> +<li><a href="#org9a2a746">4.2. environment variable <code>GNUNET_FORCE_LOGFILE</code></a></li> +<li><a href="#orga5014e4">4.3. constructor</a></li> +<li><a href="#orgfb9a8c1">4.4. method <code>log</code></a></li> </ul> </li> -<li><a href="#orgf7c8bc6">5. ‘payto’ URI parsing</a></li> -<li><a href="#org072c5f1">6. class <code>TalerConfig</code></a> +<li><a href="#orgaadd9a7">5. ‘payto’ URI parsing</a></li> +<li><a href="#orgdf9cef8">6. class <code>TalerConfig</code></a> <ul> -<li><a href="#org0599319">6.1. reading</a></li> -<li><a href="#orga822452">6.2. value types</a></li> -<li><a href="#org7064493">6.3. retrieving values</a> +<li><a href="#org03f14e5">6.1. reading</a></li> +<li><a href="#orgd929224">6.2. value types</a></li> +<li><a href="#orgc4601e4">6.3. retrieving values</a> <ul> -<li><a href="#orgc5df650">6.3.1. specific values</a></li> -<li><a href="#orga41143a">6.3.2. entire set</a></li> +<li><a href="#org76aedbb">6.3.1. specific values</a></li> +<li><a href="#org1feca74">6.3.2. entire set</a></li> </ul> </li> -<li><a href="#orge6a4a6a">6.4. usage as a program</a></li> </ul> </li> </ul> @@ -300,8 +299,8 @@ documentation, we can convert it to Sphinx (or whatever) format. Ongoing discussion: <a href="https://bugs.gnunet.org/view.php?id=6649">https://bugs.gnunet.org/view.php?id=6649</a> </p> -<div id="outline-container-org02f1529" class="outline-2"> -<h2 id="org02f1529"><span class="section-number-2">1</span> classes overview</h2> +<div id="outline-container-org25ea71b" class="outline-2"> +<h2 id="org25ea71b"><span class="section-number-2">1</span> classes overview</h2> <div class="outline-text-2" id="text-1"> <p> These are grouped according to area of concern, which (uncoincidentally) @@ -314,8 +313,8 @@ The rest are <i>leaf classes</i>. </p> </div> -<div id="outline-container-orgf8d22b2" class="outline-3"> -<h3 id="orgf8d22b2"><span class="section-number-3">1.1</span> amount (currency + value + fraction)</h3> +<div id="outline-container-orgb49dd7e" class="outline-3"> +<h3 id="orgb49dd7e"><span class="section-number-3">1.1</span> amount (currency + value + fraction)</h3> <div class="outline-text-3" id="text-1-1"> <ul class="org-ul"> <li>CurrencyMismatchError(Exception)</li> @@ -327,8 +326,8 @@ The rest are <i>leaf classes</i>. </div> </div> -<div id="outline-container-orge70d263" class="outline-3"> -<h3 id="orge70d263"><span class="section-number-3">1.2</span> logging</h3> +<div id="outline-container-orgb7c6fb1" class="outline-3"> +<h3 id="orgb7c6fb1"><span class="section-number-3">1.2</span> logging</h3> <div class="outline-text-3" id="text-1-2"> <ul class="org-ul"> <li>LogDefinition</li> @@ -338,8 +337,8 @@ The rest are <i>leaf classes</i>. </div> </div> -<div id="outline-container-org69c7ded" class="outline-3"> -<h3 id="org69c7ded"><span class="section-number-3">1.3</span> ‘payto’ URI particularities</h3> +<div id="outline-container-org4307498" class="outline-3"> +<h3 id="org4307498"><span class="section-number-3">1.3</span> ‘payto’ URI particularities</h3> <div class="outline-text-3" id="text-1-3"> <ul class="org-ul"> <li>PaytoFormatError(Exception)</li> @@ -348,8 +347,8 @@ The rest are <i>leaf classes</i>. </div> </div> -<div id="outline-container-orga275dd5" class="outline-3"> -<h3 id="orga275dd5"><span class="section-number-3">1.4</span> configuration</h3> +<div id="outline-container-org44d03ed" class="outline-3"> +<h3 id="org44d03ed"><span class="section-number-3">1.4</span> configuration</h3> <div class="outline-text-3" id="text-1-4"> <ul class="org-ul"> <li>TalerConfig</li> @@ -358,8 +357,8 @@ The rest are <i>leaf classes</i>. </div> </div> -<div id="outline-container-org3c63bce" class="outline-2"> -<h2 id="org3c63bce"><span class="section-number-2">2</span> classes for handling currency plus value plus fraction</h2> +<div id="outline-container-orgd6a98cd" class="outline-2"> +<h2 id="orgd6a98cd"><span class="section-number-2">2</span> classes for handling currency plus value plus fraction</h2> <div class="outline-text-2" id="text-2"> <p> The <code>Amount</code> and <code>SignedAmount</code> handle Taler <i>amounts</i>, @@ -388,8 +387,8 @@ the constructor throws an <code>AmountOverflowError</code> exception. </p> </div> -<div id="outline-container-org8038926" class="outline-3"> -<h3 id="org8038926"><span class="section-number-3">2.1</span> class <code>Amount</code></h3> +<div id="outline-container-org5d287dc" class="outline-3"> +<h3 id="org5d287dc"><span class="section-number-3">2.1</span> class <code>Amount</code></h3> <div class="outline-text-3" id="text-2-1"> <p> The constructor takes three args: <code>currency</code>, <code>value</code>, <code>fraction</code>. @@ -509,8 +508,8 @@ False </div> </div> -<div id="outline-container-org8292d6a" class="outline-3"> -<h3 id="org8292d6a"><span class="section-number-3">2.2</span> class <code>SignedAmount</code></h3> +<div id="outline-container-org56a0ae4" class="outline-3"> +<h3 id="org56a0ae4"><span class="section-number-3">2.2</span> class <code>SignedAmount</code></h3> <div class="outline-text-3" id="text-2-2"> <p> A <code>SignedAmount</code> object is an <i>amount with a sign</i>. @@ -589,8 +588,8 @@ True </div> </div> -<div id="outline-container-org195d8b6" class="outline-2"> -<h2 id="org195d8b6"><span class="section-number-2">3</span> classes <code>LogDefinition</code>, <code>GnunetLoglevel</code></h2> +<div id="outline-container-orgb9b4b04" class="outline-2"> +<h2 id="orgb9b4b04"><span class="section-number-2">3</span> classes <code>LogDefinition</code>, <code>GnunetLoglevel</code></h2> <div class="outline-text-2" id="text-3"> <p> These two classes are deliberately undocumented (until further notice). @@ -599,8 +598,8 @@ They exist primarily to support the <code>GnunetLogger</code> class. </div> </div> -<div id="outline-container-org7de92e5" class="outline-2"> -<h2 id="org7de92e5"><span class="section-number-2">4</span> class <code>GnunetLogger</code></h2> +<div id="outline-container-orga6828fa" class="outline-2"> +<h2 id="orga6828fa"><span class="section-number-2">4</span> class <code>GnunetLogger</code></h2> <div class="outline-text-2" id="text-4"> <p> The <code>GnunetLogger</code> class wraps the native <code>logging</code> module and provides @@ -610,8 +609,8 @@ It supports the usual list of <i>log levels</i>: </p> </div> -<div id="outline-container-org7009ddc" class="outline-3"> -<h3 id="org7009ddc"><span class="section-number-3">4.1</span> log definition, environment variables</h3> +<div id="outline-container-org8d3839f" class="outline-3"> +<h3 id="org8d3839f"><span class="section-number-3">4.1</span> log definition, environment variables</h3> <div class="outline-text-3" id="text-4-1"> <p> What to log is controlled by a <i>log definition</i>, lists of @@ -672,8 +671,8 @@ variable <code>GNUNET_FORCE_LOGFILE</code>. </div> </div> -<div id="outline-container-org1798ccd" class="outline-3"> -<h3 id="org1798ccd"><span class="section-number-3">4.2</span> environment variable <code>GNUNET_FORCE_LOGFILE</code></h3> +<div id="outline-container-org9a2a746" class="outline-3"> +<h3 id="org9a2a746"><span class="section-number-3">4.2</span> environment variable <code>GNUNET_FORCE_LOGFILE</code></h3> <div class="outline-text-3" id="text-4-2"> <p> The filename specified by <code>GNUNET_FORCE_LOGFILE</code> can @@ -707,8 +706,8 @@ then the expansion might be: </div> </div> -<div id="outline-container-org06b279d" class="outline-3"> -<h3 id="org06b279d"><span class="section-number-3">4.3</span> constructor</h3> +<div id="outline-container-orga5014e4" class="outline-3"> +<h3 id="orga5014e4"><span class="section-number-3">4.3</span> constructor</h3> <div class="outline-text-3" id="text-4-3"> <p> The <code>GnunetLogger</code> constructor takes one argument, <code>component</code>. @@ -722,8 +721,8 @@ The <code>GnunetLogger</code> constructor takes one argument, <code>component</c </div> </div> -<div id="outline-container-org80aed03" class="outline-3"> -<h3 id="org80aed03"><span class="section-number-3">4.4</span> method <code>log</code></h3> +<div id="outline-container-orgfb9a8c1" class="outline-3"> +<h3 id="orgfb9a8c1"><span class="section-number-3">4.4</span> method <code>log</code></h3> <div class="outline-text-3" id="text-4-4"> <p> The <code>log</code> method takes two arguments, <code>message</code> (a string) @@ -739,8 +738,8 @@ INFO:ui:user clicked button </div> </div> -<div id="outline-container-orgf7c8bc6" class="outline-2"> -<h2 id="orgf7c8bc6"><span class="section-number-2">5</span> ‘payto’ URI parsing</h2> +<div id="outline-container-orgaadd9a7" class="outline-2"> +<h2 id="orgaadd9a7"><span class="section-number-2">5</span> ‘payto’ URI parsing</h2> <div class="outline-text-2" id="text-5"> <p> The <code>PaytoParse</code> class has only one entry point, its constructor. @@ -759,7 +758,7 @@ On successful parse, the object has the following properties: <dt><code>bank</code></dt><dd>bank handling the payment</dd> <dt><code>authority</code></dt><dd>payment type (e.g., <code>iban</code>)</dd> <dt><code>message</code></dt><dd>short human-readable description of the payment</dd> -<dt><code>amount</code></dt><dd>in <code>CUR:X.Y</code> format (<a href="#org8038926">2.1</a>)</dd> +<dt><code>amount</code></dt><dd>in <code>CUR:X.Y</code> format (<a href="#org5d287dc">2.1</a>)</dd> </dl> <p> @@ -810,8 +809,8 @@ Amount(currency='EUR', value=200, fraction=0) </div> </div> -<div id="outline-container-org072c5f1" class="outline-2"> -<h2 id="org072c5f1"><span class="section-number-2">6</span> class <code>TalerConfig</code></h2> +<div id="outline-container-orgdf9cef8" class="outline-2"> +<h2 id="orgdf9cef8"><span class="section-number-2">6</span> class <code>TalerConfig</code></h2> <div class="outline-text-2" id="text-6"> <p> The <code>TalerConfig</code> class represents a <i>Taler configuration</i>, a set @@ -827,8 +826,8 @@ For more information, see the taler-config(5) manpage. </p> </div> -<div id="outline-container-org0599319" class="outline-3"> -<h3 id="org0599319"><span class="section-number-3">6.1</span> reading</h3> +<div id="outline-container-org03f14e5" class="outline-3"> +<h3 id="org03f14e5"><span class="section-number-3">6.1</span> reading</h3> <div class="outline-text-3" id="text-6-1"> <p> The standard way to construct a <code>TalerConfig</code> object is to start @@ -878,16 +877,6 @@ For example, if <code>TALER_PREFIX</code> is <code>/usr/local/lib</code>, then The same would result if <code>TALER_PREFIX</code> were <code>/usr/local</code> (the suffixing is unconditional). </p></li> - -<li><p> -if module <code>talerpaths</code> exists and exports <code>TALER_DATADIR</code>, then the -directory named by suffixing its value with <code>share/taler/config.d</code> -</p> - -<p> -FIXME: Comment in code: "not clear if this is a good idea" – -Maybe we should remove this functionality or leave it undocumented? -</p></li> </ul> <p> @@ -910,8 +899,8 @@ the process to exit with exit value <code>3</code>. </div> </div> -<div id="outline-container-orga822452" class="outline-3"> -<h3 id="orga822452"><span class="section-number-3">6.2</span> value types</h3> +<div id="outline-container-orgd929224" class="outline-3"> +<h3 id="orgd929224"><span class="section-number-3">6.2</span> value types</h3> <div class="outline-text-3" id="text-6-2"> <p> There are three types of values in a Taler configuration: <code>int</code> (integer), @@ -931,10 +920,8 @@ These mimic shell-style variable expansion. In all these constructs, the value of <code>X</code> replaces the construct. In the second one only, if the value of <code>X</code> is empty, use the value of <code>Y</code> instead. -</p> - -<p> -FIXME: Can the second type be nested (i.e., <code>${X:-${Y:-Z}}</code>)? +Also, the second type can be nested, i.e., <code>${X:-${Y:-Z}}</code>. +That is, if <code>X</code> is empty, try <code>Y</code>, and if <code>Y</code> is empty, try <code>Z</code>. </p> <p> @@ -945,8 +932,8 @@ simply <code>/tmp/taler-test</code>. </div> </div> -<div id="outline-container-org7064493" class="outline-3"> -<h3 id="org7064493"><span class="section-number-3">6.3</span> retrieving values</h3> +<div id="outline-container-orgc4601e4" class="outline-3"> +<h3 id="orgc4601e4"><span class="section-number-3">6.3</span> retrieving values</h3> <div class="outline-text-3" id="text-6-3"> <p> Once a Taler configuration is read, you can retrieve specific @@ -954,8 +941,8 @@ values from it, or display the entire set to stdout. </p> </div> -<div id="outline-container-orgc5df650" class="outline-4"> -<h4 id="orgc5df650"><span class="section-number-4">6.3.1</span> specific values</h4> +<div id="outline-container-org76aedbb" class="outline-4"> +<h4 id="org76aedbb"><span class="section-number-4">6.3.1</span> specific values</h4> <div class="outline-text-4" id="text-6-3-1"> <p> Each type <i>foo</i> has a <code>value_foo</code> method (e.g., <code>value_int</code> for integer). @@ -987,8 +974,8 @@ arguments, but they are ignored.) </div> </div> -<div id="outline-container-orga41143a" class="outline-4"> -<h4 id="orga41143a"><span class="section-number-4">6.3.2</span> entire set</h4> +<div id="outline-container-org1feca74" class="outline-4"> +<h4 id="org1feca74"><span class="section-number-4">6.3.2</span> entire set</h4> <div class="outline-text-4" id="text-6-3-2"> <p> The <code>dump</code> method takes no arguments. @@ -998,55 +985,16 @@ in the format: <pre class="example"> [section] -option = value # FIXME (what is location?) +option = value # filename & line number pair </pre> </div> </div> </div> - -<div id="outline-container-orge6a4a6a" class="outline-3"> -<h3 id="orge6a4a6a"><span class="section-number-3">6.4</span> usage as a program</h3> -<div class="outline-text-3" id="text-6-4"> -<p> -FIXME: Is this supposed to be documented? -Seems out of place in a library. -Maybe it's there only for testing purposes? -Another idea is to move it to its own utility program. -</p> - -<p> -If <code>talerconfig.py</code> is invoked from the command-line, it functions -as a program that displays either a specific value or dumps the entire set, -depending on the command-line args given. -</p> - -<p> -Options are: -</p> - -<dl class="org-dl"> -<dt><code>-c, --config FILE</code></dt><dd>Read Taler configuration from <code>FILE</code>. -See <code>from_file</code> (above) for behavior if unspecified.</dd> - -<dt><code>-s, --section SECTION</code></dt><dd>Look for option in section <code>SECTION</code>.</dd> - -<dt><code>-o, --option OPTION</code></dt><dd>Display value associated with option <code>OPTION</code>.</dd> - -<dt><code>-f, --filename</code></dt><dd>If the value is a string, do shell-style -variable expansion (see above) on it.</dd> -</dl> - -<p> -If both <code>SECTION</code> and <code>OPTION</code> are omitted, display the entire set -of values using the <code>dump</code> method (see above). -</p> -</div> -</div> </div> </div> <div id="postamble" class="status"> <p class="author">Author: Taler Contributors</p> -<p class="date">Created: 2022-02-15 mar 08:20</p> +<p class="date">Created: 2022-02-22 mar 07:37</p> <p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p> </div> </body> |