regenerate doc.{html,txt}

author: Thien-Thi Nguyen <ttn@gnu.org> 2022-02-15 08:21:14 -0500
committer: Thien-Thi Nguyen <ttn@gnu.org> 2022-02-15 08:21:14 -0500
commit: 932f8dc2f0f58c715f0de48af7341a5c4e07c634 (patch)
tree: d8ad3062d8e88d5f0ab4d9191cc7f4e4bd7a04f0
parent: 943817d37b8dcaf26771879c415e7a8841ec3e1a (diff)
download: taler-util-932f8dc2f0f58c715f0de48af7341a5c4e07c634.tar.gz
taler-util-932f8dc2f0f58c715f0de48af7341a5c4e07c634.tar.bz2
taler-util-932f8dc2f0f58c715f0de48af7341a5c4e07c634.zip
2 files changed, 470 insertions, 63 deletions
diff --git a/doc/doc.html b/doc/doc.html
index 8a8bfa3..1f2774d 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-10 gio 19:44 -->
+<!-- 2022-02-15 mar 08:20 -->
 <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,30 +247,43 @@ for the JavaScript code in this tag.
 <h2>Table of Contents</h2>
 <div id="text-table-of-contents">
 <ul>
-<li><a href="#orgca83dbe">1. classes overview</a>
+<li><a href="#org02f1529">1. classes overview</a>
 <ul>
-<li><a href="#org5d66d83">1.1. amount (currency + value + fraction)</a></li>
-<li><a href="#org44f0451">1.2. logging</a></li>
-<li><a href="#org6c994e8">1.3. ‘payto’ URI particularities</a></li>
-<li><a href="#org25aab70">1.4. configuration</a></li>
+<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>
 </ul>
 </li>
-<li><a href="#org1f4e090">2. classes for handling currency plus value plus fraction</a>
+<li><a href="#org3c63bce">2. classes for handling currency plus value plus fraction</a>
 <ul>
-<li><a href="#orgc5c5b05">2.1. class <code>Amount</code></a></li>
-<li><a href="#org75fe6af">2.2. class <code>SignedAmount</code></a></li>
+<li><a href="#org8038926">2.1. class <code>Amount</code></a></li>
+<li><a href="#org8292d6a">2.2. class <code>SignedAmount</code></a></li>
 </ul>
 </li>
-<li><a href="#orgc5d0f9f">3. classes <code>LogDefinition</code>, <code>GnunetLoglevel</code></a></li>
-<li><a href="#orga09fc8a">4. class <code>GnunetLogger</code></a>
+<li><a href="#org195d8b6">3. classes <code>LogDefinition</code>, <code>GnunetLoglevel</code></a></li>
+<li><a href="#org7de92e5">4. class <code>GnunetLogger</code></a>
 <ul>
-<li><a href="#org39a01ca">4.1. log definition, environment variables</a></li>
-<li><a href="#org2f6906d">4.2. environment variable <code>GNUNET_FORCE_LOGFILE</code></a></li>
-<li><a href="#org9663b14">4.3. constructor</a></li>
-<li><a href="#org2f746c8">4.4. method <code>log</code></a></li>
+<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>
+</ul>
+</li>
+<li><a href="#orgf7c8bc6">5. ‘payto’ URI parsing</a></li>
+<li><a href="#org072c5f1">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>
+<ul>
+<li><a href="#orgc5df650">6.3.1. specific values</a></li>
+<li><a href="#orga41143a">6.3.2. entire set</a></li>
+</ul>
+</li>
+<li><a href="#orge6a4a6a">6.4. usage as a program</a></li>
 </ul>
 </li>
-<li><a href="#org9a25003">5. ‘payto’ URI parsing</a></li>
 </ul>
 </div>
 </div>
@@ -287,8 +300,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-orgca83dbe" class="outline-2">
-<h2 id="orgca83dbe"><span class="section-number-2">1</span> classes overview</h2>
+<div id="outline-container-org02f1529" class="outline-2">
+<h2 id="org02f1529"><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)
@@ -296,14 +309,13 @@ is also how the source code is organized.
 </p>
 
 <p>
-Several of these derive from the <code>Exception</code> class, and two
-of them derive from the <code>collections.defaultdict</code> class.
+Several of these derive from the <code>Exception</code> class.
 The rest are <i>leaf classes</i>.
 </p>
 </div>
 
-<div id="outline-container-org5d66d83" class="outline-3">
-<h3 id="org5d66d83"><span class="section-number-3">1.1</span> amount (currency + value + fraction)</h3>
+<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 class="outline-text-3" id="text-1-1">
 <ul class="org-ul">
 <li>CurrencyMismatchError(Exception)</li>
@@ -315,8 +327,8 @@ The rest are <i>leaf classes</i>.
 </div>
 </div>
 
-<div id="outline-container-org44f0451" class="outline-3">
-<h3 id="org44f0451"><span class="section-number-3">1.2</span> logging</h3>
+<div id="outline-container-orge70d263" class="outline-3">
+<h3 id="orge70d263"><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>
@@ -326,8 +338,8 @@ The rest are <i>leaf classes</i>.
 </div>
 </div>
 
-<div id="outline-container-org6c994e8" class="outline-3">
-<h3 id="org6c994e8"><span class="section-number-3">1.3</span> ‘payto’ URI particularities</h3>
+<div id="outline-container-org69c7ded" class="outline-3">
+<h3 id="org69c7ded"><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>
@@ -336,23 +348,18 @@ The rest are <i>leaf classes</i>.
 </div>
 </div>
 
-<div id="outline-container-org25aab70" class="outline-3">
-<h3 id="org25aab70"><span class="section-number-3">1.4</span> configuration</h3>
+<div id="outline-container-orga275dd5" class="outline-3">
+<h3 id="orga275dd5"><span class="section-number-3">1.4</span> configuration</h3>
 <div class="outline-text-3" id="text-1-4">
 <ul class="org-ul">
-<li>ConfigurationError(Exception)</li>
-<li>ExpansionSyntaxError(Exception)</li>
-<li>Entry</li>
-<li>OptionDict(collections.defaultdict)</li>
-<li>SectionDict(collections.defaultdict)</li>
 <li>TalerConfig</li>
 </ul>
 </div>
 </div>
 </div>
 
-<div id="outline-container-org1f4e090" class="outline-2">
-<h2 id="org1f4e090"><span class="section-number-2">2</span> classes for handling currency plus value plus fraction</h2>
+<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 class="outline-text-2" id="text-2">
 <p>
 The <code>Amount</code> and <code>SignedAmount</code> handle Taler <i>amounts</i>,
@@ -381,8 +388,8 @@ the constructor throws an <code>AmountOverflowError</code> exception.
 </p>
 </div>
 
-<div id="outline-container-orgc5c5b05" class="outline-3">
-<h3 id="orgc5c5b05"><span class="section-number-3">2.1</span> class <code>Amount</code></h3>
+<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 class="outline-text-3" id="text-2-1">
 <p>
 The constructor takes three args: <code>currency</code>, <code>value</code>, <code>fraction</code>.
@@ -502,8 +509,8 @@ False
 </div>
 </div>
 
-<div id="outline-container-org75fe6af" class="outline-3">
-<h3 id="org75fe6af"><span class="section-number-3">2.2</span> class <code>SignedAmount</code></h3>
+<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 class="outline-text-3" id="text-2-2">
 <p>
 A <code>SignedAmount</code> object is an <i>amount with a sign</i>.
@@ -582,8 +589,8 @@ True
 </div>
 </div>
 
-<div id="outline-container-orgc5d0f9f" class="outline-2">
-<h2 id="orgc5d0f9f"><span class="section-number-2">3</span> classes <code>LogDefinition</code>, <code>GnunetLoglevel</code></h2>
+<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 class="outline-text-2" id="text-3">
 <p>
 These two classes are deliberately undocumented (until further notice).
@@ -592,8 +599,8 @@ They exist primarily to support the <code>GnunetLogger</code> class.
 </div>
 </div>
 
-<div id="outline-container-orga09fc8a" class="outline-2">
-<h2 id="orga09fc8a"><span class="section-number-2">4</span> class <code>GnunetLogger</code></h2>
+<div id="outline-container-org7de92e5" class="outline-2">
+<h2 id="org7de92e5"><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
@@ -603,8 +610,8 @@ It supports the usual list of <i>log levels</i>:
 </p>
 </div>
 
-<div id="outline-container-org39a01ca" class="outline-3">
-<h3 id="org39a01ca"><span class="section-number-3">4.1</span> log definition, environment variables</h3>
+<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 class="outline-text-3" id="text-4-1">
 <p>
 What to log is controlled by a <i>log definition</i>, lists of
@@ -665,8 +672,8 @@ variable <code>GNUNET_FORCE_LOGFILE</code>.
 </div>
 </div>
 
-<div id="outline-container-org2f6906d" class="outline-3">
-<h3 id="org2f6906d"><span class="section-number-3">4.2</span> environment variable <code>GNUNET_FORCE_LOGFILE</code></h3>
+<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 class="outline-text-3" id="text-4-2">
 <p>
 The filename specified by <code>GNUNET_FORCE_LOGFILE</code> can
@@ -700,8 +707,8 @@ then the expansion might be:
 </div>
 </div>
 
-<div id="outline-container-org9663b14" class="outline-3">
-<h3 id="org9663b14"><span class="section-number-3">4.3</span> constructor</h3>
+<div id="outline-container-org06b279d" class="outline-3">
+<h3 id="org06b279d"><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>.
@@ -715,8 +722,8 @@ The <code>GnunetLogger</code> constructor takes one argument, <code>component</c
 </div>
 </div>
 
-<div id="outline-container-org2f746c8" class="outline-3">
-<h3 id="org2f746c8"><span class="section-number-3">4.4</span> method <code>log</code></h3>
+<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 class="outline-text-3" id="text-4-4">
 <p>
 The <code>log</code> method takes two arguments, <code>message</code> (a string)
@@ -732,8 +739,8 @@ INFO:ui:user clicked button
 </div>
 </div>
 
-<div id="outline-container-org9a25003" class="outline-2">
-<h2 id="org9a25003"><span class="section-number-2">5</span> ‘payto’ URI parsing</h2>
+<div id="outline-container-orgf7c8bc6" class="outline-2">
+<h2 id="orgf7c8bc6"><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.
@@ -752,7 +759,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="#orgc5c5b05">2.1</a>)</dd>
+<dt><code>amount</code></dt><dd>in <code>CUR:X.Y</code> format (<a href="#org8038926">2.1</a>)</dd>
 </dl>
 
 <p>
@@ -802,10 +809,244 @@ Amount(currency='EUR', value=200, fraction=0)
 </pre>
 </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 class="outline-text-2" id="text-6">
+<p>
+The <code>TalerConfig</code> class represents a <i>Taler configuration</i>, a set
+of <i>sections</i> with <i>options</i> and associated <i>values</i> (basically,
+a nested dictionary), and provides methods for initializing,
+and accessing those values, keyed by section and option.
+</p>
+
+<p>
+When a Taler configuration is written to a file (the usual case),
+it follows the typical Windows INI format.
+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 class="outline-text-3" id="text-6-1">
+<p>
+The standard way to construct a <code>TalerConfig</code> object is to start
+with one of two initialization methods: <code>from_file</code> or <code>from_env</code>.
+The former reads the configuration from a file, given its name.
+If no name is provided (it is <code>None</code>), <code>from_file</code> first tries
+to find <code>taler.conf</code> in two directories:
+</p>
+
+<ul class="org-ul">
+<li>directory named by environment variable <code>XDG_CONFIG_HOME</code></li>
+
+<li><code>$HOME/.config</code> (where <code>HOME</code> is the user's home directory)</li>
+</ul>
+
+<p>
+The <code>from_env</code> initialization method first determines a filename
+by consulting environment variable <code>TALER_CONFIG_FILE</code> and then
+uses <code>from_file</code> on that.
+</p>
+
+<p>
+Both initialization methods take keyword arg <code>load_defaults</code>
+(default <code>True</code>) that directs the method to also call
+the <code>load_defaults</code> method before reading the file.
+</p>
+
+<p>
+The <code>load_defaults</code> method takes no arguments.
+It looks in the canonical locations (directories) and
+uses method <code>load_dir</code> on them.
+Once it finds a specified dir, it stops searching.
+The canonical locations are:
+</p>
+
+<ul class="org-ul">
+<li>environment variable <code>TALER_BASE_CONFIG</code></li>
+
+<li><p>
+environment variable <code>TALER_PREFIX</code>, with any trailing component
+<code>lib</code> discarded, and suffixed with <code>share/taler/config.d</code>
+</p>
+
+<p>
+For example, if <code>TALER_PREFIX</code> is <code>/usr/local/lib</code>, then
+<code>load_defaults</code> would look in <code>/usr/local/share/taler/config.d</code>.
+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" &#x2013;
+Maybe we should remove this functionality or leave it undocumented?
+</p></li>
+</ul>
+
+<p>
+If <code>load_defaults</code> cannot find something to load it logs a warning
+"no base directory found".
+</p>
+
+<p>
+The <code>load_dir</code> method takes one argument <code>dirname</code>, and
+uses <code>load_file</code> on all files that directory whose name ends
+with <code>.conf</code>.
+</p>
+
+<p>
+At its core, all file reading uses method <code>load_file</code>,
+which takes one argument, the <code>filename</code> to read.
+If <code>filename</code> cannot be found, <code>load_file</code> causes
+the process to exit with exit value <code>3</code>.
+</p>
+</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 class="outline-text-3" id="text-6-2">
+<p>
+There are three types of values in a Taler configuration: <code>int</code> (integer),
+<code>string</code> and <code>filename</code>.
+The <code>int</code> and <code>string</code> types are self-explanatory.
+The <code>filename</code> type is a string that has certain constructs expanded:
+</p>
+
+<ul class="org-ul">
+<li><code>${X}</code></li>
+<li><code>${X:-Y}</code></li>
+<li><code>$X</code></li>
+</ul>
+
+<p>
+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>)?
+</p>
+
+<p>
+For example, <code>${TMPDIR:-/tmp}/taler-test</code> expands to <code>/var/tmp/taler-test</code>
+if environment variable <code>TMPDIR</code> has value <code>/var/tmp</code>, otherwise
+simply <code>/tmp/taler-test</code>.
+</p>
+</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 class="outline-text-3" id="text-6-3">
+<p>
+Once a Taler configuration is read, you can retrieve specific
+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 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).
+The method takes two required arguments, the <code>section</code> and <code>option</code>,
+both strings.
+Case does not matter.
+</p>
+
+<p>
+In addition to the required arguments, <code>value_string</code> accepts
+the following keyword arguments:
+</p>
+
+<dl class="org-dl">
+<dt><code>default</code></dt><dd>If the requested value is not found, return this
+value instead.  Default is no default.  :-D</dd>
+
+<dt><code>required</code></dt><dd>If the requested value is not found, print an error
+message and cause the process to exit with exit value <code>1</code>.</dd>
+
+<dt><code>warn</code></dt><dd>If the requested value is not found, log a warning.
+If <code>default</code> is also given, return that, otherwise return <code>None</code>.</dd>
+</dl>
+
+<p>
+(Both <code>value_int</code> and <code>value_filename</code> also accept these keyword
+arguments, but they are ignored.)
+</p>
+</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 class="outline-text-4" id="text-6-3-2">
+<p>
+The <code>dump</code> method takes no arguments.
+It displays to stdout each section and its options (and values)
+in the format:
+</p>
+
+<pre class="example">
+[section]
+option = value # FIXME (what is location?)
+</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-10 gio 19:44</p>
+<p class="date">Created: 2022-02-15 mar 08:20</p>
 <p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
 </div>
 </body>
diff --git a/doc/doc.txt b/doc/doc.txt
index b3b3350..82c32a3 100644
--- a/doc/doc.txt
+++ b/doc/doc.txt
@@ -23,6 +23,13 @@ Table of Contents
 .. 3. constructor
 .. 4. method ‘log’
 5. ‘payto’ URI parsing
+6. class ‘TalerConfig’
+.. 1. reading
+.. 2. value types
+.. 3. retrieving values
+..... 1. specific values
+..... 2. entire set
+.. 4. usage as a program
 
 
 The Taler-Util library provides several classes that deal with various
@@ -41,9 +48,8 @@ Ongoing discussion: <https://bugs.gnunet.org/view.php?id=6649>
   These are grouped according to area of concern, which
   (uncoincidentally) is also how the source code is organized.
 
-  Several of these derive from the ‘Exception’ class, and two of them
-  derive from the ‘collections.defaultdict’ class.  The rest are /leaf
-  classes/.
+  Several of these derive from the ‘Exception’ class.  The rest are
+  /leaf classes/.
 
 
 1.1 amount (currency + value + fraction)
@@ -74,11 +80,6 @@ Ongoing discussion: <https://bugs.gnunet.org/view.php?id=6649>
 1.4 configuration
 ─────────────────
 
-  • ConfigurationError(Exception)
-  • ExpansionSyntaxError(Exception)
-  • Entry
-  • OptionDict(collections.defaultdict)
-  • SectionDict(collections.defaultdict)
   • TalerConfig
 
 
@@ -458,3 +459,168 @@ Ongoing discussion: <https://bugs.gnunet.org/view.php?id=6649>
   │ >>> p.amount
   │ Amount(currency='EUR', value=200, fraction=0)
   └────
+
+
+6 class ‘TalerConfig’
+═════════════════════
+
+  The ‘TalerConfig’ class represents a /Taler configuration/, a set of
+  /sections/ with /options/ and associated /values/ (basically, a nested
+  dictionary), and provides methods for initializing, and accessing
+  those values, keyed by section and option.
+
+  When a Taler configuration is written to a file (the usual case), it
+  follows the typical Windows INI format.  For more information, see the
+  taler-config(5) manpage.
+
+
+6.1 reading
+───────────
+
+  The standard way to construct a ‘TalerConfig’ object is to start with
+  one of two initialization methods: ‘from_file’ or ‘from_env’.  The
+  former reads the configuration from a file, given its name.  If no
+  name is provided (it is ‘None’), ‘from_file’ first tries to find
+  ‘taler.conf’ in two directories:
+
+  • directory named by environment variable ‘XDG_CONFIG_HOME’
+
+  • ‘$HOME/.config’ (where ‘HOME’ is the user's home directory)
+
+  The ‘from_env’ initialization method first determines a filename by
+  consulting environment variable ‘TALER_CONFIG_FILE’ and then uses
+  ‘from_file’ on that.
+
+  Both initialization methods take keyword arg ‘load_defaults’ (default
+  ‘True’) that directs the method to also call the ‘load_defaults’
+  method before reading the file.
+
+  The ‘load_defaults’ method takes no arguments.  It looks in the
+  canonical locations (directories) and uses method ‘load_dir’ on them.
+  Once it finds a specified dir, it stops searching.  The canonical
+  locations are:
+
+  • environment variable ‘TALER_BASE_CONFIG’
+
+  • environment variable ‘TALER_PREFIX’, with any trailing component
+    ‘lib’ discarded, and suffixed with ‘share/taler/config.d’
+
+    For example, if ‘TALER_PREFIX’ is ‘/usr/local/lib’, then
+    ‘load_defaults’ would look in ‘/usr/local/share/taler/config.d’.
+    The same would result if ‘TALER_PREFIX’ were ‘/usr/local’ (the
+    suffixing is unconditional).
+
+  • if module ‘talerpaths’ exists and exports ‘TALER_DATADIR’, then the
+    directory named by suffixing its value with ‘share/taler/config.d’
+
+    FIXME: Comment in code: "not clear if this is a good idea" – Maybe
+    we should remove this functionality or leave it undocumented?
+
+  If ‘load_defaults’ cannot find something to load it logs a warning "no
+  base directory found".
+
+  The ‘load_dir’ method takes one argument ‘dirname’, and uses
+  ‘load_file’ on all files that directory whose name ends with ‘.conf’.
+
+  At its core, all file reading uses method ‘load_file’, which takes one
+  argument, the ‘filename’ to read.  If ‘filename’ cannot be found,
+  ‘load_file’ causes the process to exit with exit value ‘3’.
+
+
+6.2 value types
+───────────────
+
+  There are three types of values in a Taler configuration: ‘int’
+  (integer), ‘string’ and ‘filename’.  The ‘int’ and ‘string’ types are
+  self-explanatory.  The ‘filename’ type is a string that has certain
+  constructs expanded:
+
+  • ‘${X}’
+  • ‘${X:-Y}’
+  • ‘$X’
+
+  These mimic shell-style variable expansion.  In all these constructs,
+  the value of ‘X’ replaces the construct.  In the second one only, if
+  the value of ‘X’ is empty, use the value of ‘Y’ instead.
+
+  FIXME: Can the second type be nested (i.e., ‘${X:-${Y:-Z}}’)?
+
+  For example, ‘${TMPDIR:-/tmp}/taler-test’ expands to
+  ‘/var/tmp/taler-test’ if environment variable ‘TMPDIR’ has value
+  ‘/var/tmp’, otherwise simply ‘/tmp/taler-test’.
+
+
+6.3 retrieving values
+─────────────────────
+
+  Once a Taler configuration is read, you can retrieve specific values
+  from it, or display the entire set to stdout.
+
+
+6.3.1 specific values
+╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
+
+  Each type /foo/ has a ‘value_foo’ method (e.g., ‘value_int’ for
+  integer).  The method takes two required arguments, the ‘section’ and
+  ‘option’, both strings.  Case does not matter.
+
+  In addition to the required arguments, ‘value_string’ accepts the
+  following keyword arguments:
+
+  ‘default’
+        If the requested value is not found, return this value instead.
+        Default is no default.  :-D
+
+  ‘required’
+        If the requested value is not found, print an error message and
+        cause the process to exit with exit value ‘1’.
+
+  ‘warn’
+        If the requested value is not found, log a warning.  If
+        ‘default’ is also given, return that, otherwise return ‘None’.
+
+  (Both ‘value_int’ and ‘value_filename’ also accept these keyword
+  arguments, but they are ignored.)
+
+
+6.3.2 entire set
+╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
+
+  The ‘dump’ method takes no arguments.  It displays to stdout each
+  section and its options (and values) in the format:
+
+  ┌────
+  │ [section]
+  │ option = value # FIXME (what is location?)
+  └────
+
+
+6.4 usage as a program
+──────────────────────
+
+  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.
+
+  If ‘talerconfig.py’ 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.
+
+  Options are:
+
+  ‘-c, --config FILE’
+        Read Taler configuration from ‘FILE’.  See ‘from_file’ (above)
+        for behavior if unspecified.
+
+  ‘-s, --section SECTION’
+        Look for option in section ‘SECTION’.
+
+  ‘-o, --option OPTION’
+        Display value associated with option ‘OPTION’.
+
+  ‘-f, --filename’
+        If the value is a string, do shell-style variable expansion (see
+        above) on it.
+
+  If both ‘SECTION’ and ‘OPTION’ are omitted, display the entire set of
+  values using the ‘dump’ method (see above).
author	Thien-Thi Nguyen <ttn@gnu.org>	2022-02-15 08:21:14 -0500
committer	Thien-Thi Nguyen <ttn@gnu.org>	2022-02-15 08:21:14 -0500
commit	932f8dc2f0f58c715f0de48af7341a5c4e07c634 (patch)
tree	d8ad3062d8e88d5f0ab4d9191cc7f4e4bd7a04f0
parent	943817d37b8dcaf26771879c415e7a8841ec3e1a (diff)
download	taler-util-932f8dc2f0f58c715f0de48af7341a5c4e07c634.tar.gz taler-util-932f8dc2f0f58c715f0de48af7341a5c4e07c634.tar.bz2 taler-util-932f8dc2f0f58c715f0de48af7341a5c4e07c634.zip