regenerate doc.{html,txt}

1 files changed, 174 insertions, 8 deletions

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