From 3c168985bc7351d6b7b9ce789c57aae189e8f99a Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 22 Feb 2022 07:37:46 -0500 Subject: regenerate doc.{html,txt} --- doc/doc.html | 190 ++++++++++++++++++++++------------------------------------- doc/doc.txt | 94 +++++++++-------------------- 2 files changed, 97 insertions(+), 187 deletions(-) (limited to 'doc') 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"> - + Taler-Util Library @@ -247,41 +247,40 @@ for the JavaScript code in this tag.

Table of Contents

@@ -300,8 +299,8 @@ documentation, we can convert it to Sphinx (or whatever) format. Ongoing discussion: https://bugs.gnunet.org/view.php?id=6649

-
-

1 classes overview

+
+

1 classes overview

These are grouped according to area of concern, which (uncoincidentally) @@ -314,8 +313,8 @@ The rest are leaf classes.

-
-

1.1 amount (currency + value + fraction)

+
+

1.1 amount (currency + value + fraction)

  • CurrencyMismatchError(Exception)
    • @@ -327,8 +326,8 @@ The rest are leaf classes.
-
-

1.2 logging

+
+

1.2 logging

  • LogDefinition
    • @@ -338,8 +337,8 @@ The rest are leaf classes.
-
-

1.3 ‘payto’ URI particularities

+
+

1.3 ‘payto’ URI particularities

  • PaytoFormatError(Exception)
    • @@ -348,8 +347,8 @@ The rest are leaf classes.
-
-

1.4 configuration

+
+

1.4 configuration

  • TalerConfig
    • @@ -358,8 +357,8 @@ The rest are leaf classes.
-
-

2 classes for handling currency plus value plus fraction

+
+

2 classes for handling currency plus value plus fraction

The Amount and SignedAmount handle Taler amounts, @@ -388,8 +387,8 @@ the constructor throws an AmountOverflowError exception.

-
-

2.1 class Amount

+
+

2.1 class Amount

The constructor takes three args: currency, value, fraction. @@ -509,8 +508,8 @@ False

-
-

2.2 class SignedAmount

+
+

2.2 class SignedAmount

A SignedAmount object is an amount with a sign. @@ -589,8 +588,8 @@ True

-
-

3 classes LogDefinition, GnunetLoglevel

+
+

3 classes LogDefinition, GnunetLoglevel

These two classes are deliberately undocumented (until further notice). @@ -599,8 +598,8 @@ They exist primarily to support the GnunetLogger class.

-
-

4 class GnunetLogger

+
+

4 class GnunetLogger

The GnunetLogger class wraps the native logging module and provides @@ -610,8 +609,8 @@ It supports the usual list of log levels:

-
-

4.1 log definition, environment variables

+
+

4.1 log definition, environment variables

What to log is controlled by a log definition, lists of @@ -672,8 +671,8 @@ variable GNUNET_FORCE_LOGFILE.

-
-

4.2 environment variable GNUNET_FORCE_LOGFILE

+
+

4.2 environment variable GNUNET_FORCE_LOGFILE

The filename specified by GNUNET_FORCE_LOGFILE can @@ -707,8 +706,8 @@ then the expansion might be:

-
-

4.3 constructor

+
+

4.3 constructor

The GnunetLogger constructor takes one argument, component. @@ -722,8 +721,8 @@ The GnunetLogger constructor takes one argument, component

-
-

4.4 method log

+
+

4.4 method log

The log method takes two arguments, message (a string) @@ -739,8 +738,8 @@ INFO:ui:user clicked button

-
-

5 ‘payto’ URI parsing

+
+

5 ‘payto’ URI parsing

The PaytoParse class has only one entry point, its constructor. @@ -759,7 +758,7 @@ On successful parse, the object has the following properties:

bank
bank handling the payment
authority
payment type (e.g., iban)
message
short human-readable description of the payment
-
amount
in CUR:X.Y format (2.1)
+
amount
in CUR:X.Y format (2.1)

@@ -810,8 +809,8 @@ Amount(currency='EUR', value=200, fraction=0)

-
-

6 class TalerConfig

+
+

6 class TalerConfig

The TalerConfig class represents a Taler configuration, a set @@ -827,8 +826,8 @@ For more information, see the taler-config(5) manpage.

-
-

6.1 reading

+
+

6.1 reading

The standard way to construct a TalerConfig object is to start @@ -878,16 +877,6 @@ For example, if TALER_PREFIX is /usr/local/lib, then 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? -

    • @@ -910,8 +899,8 @@ the process to exit with exit value 3.

    -
    -

    6.2 value types

    +
    +

    6.2 value types

    There are three types of values in a Taler configuration: int (integer), @@ -931,10 +920,8 @@ 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}})? +Also, the second type can be nested, i.e., ${X:-${Y:-Z}}. +That is, if X is empty, try Y, and if Y is empty, try Z.

    @@ -945,8 +932,8 @@ simply /tmp/taler-test.

    -
    -

    6.3 retrieving values

    +
    +

    6.3 retrieving values

    Once a Taler configuration is read, you can retrieve specific @@ -954,8 +941,8 @@ values from it, or display the entire set to stdout.

    -
    -

    6.3.1 specific values

    +
    +

    6.3.1 specific values

    Each type foo has a value_foo method (e.g., value_int for integer). @@ -987,8 +974,8 @@ arguments, but they are ignored.)

    -
    -

    6.3.2 entire set

    +
    +

    6.3.2 entire set

    The dump method takes no arguments. @@ -998,55 +985,16 @@ in the format: 

     [section]
-option = value # FIXME (what is location?)
+option = value # filename & line number pair
    - -
    -

    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: Taler Contributors

    -

    Created: 2022-02-15 mar 08:20

    +

    Created: 2022-02-22 mar 07:37

    Validate

    diff --git a/doc/doc.txt b/doc/doc.txt index 82c32a3..9248a83 100644 --- a/doc/doc.txt +++ b/doc/doc.txt @@ -29,7 +29,6 @@ Table of Contents .. 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 @@ -113,10 +112,10 @@ Ongoing discussion: ┌──── │ >>> from taler.util.amount import Amount, SignedAmount - │ + │ │ # KUDOS 10.50 │ >>> amt = Amount ("KUDOS", 10, 50000000) - │ + │ │ >>> amt │ Amount(currency='KUDOS', value=10, fraction=50000000) └──── @@ -148,9 +147,9 @@ Ongoing discussion: ┌──── │ >>> amt + amt │ Amount(currency='KUDOS', value=21, fraction=0) - │ + │ │ >>> another = Amount ("KUDOS", 5, 42) - │ + │ │ >>> amt - another │ Amount(currency='KUDOS', value=5, fraction=49999958) └──── @@ -177,13 +176,13 @@ Ongoing discussion: ┌──── │ >>> str (amt) │ 'KUDOS:10.5' - │ + │ │ >>> amt.stringify() │ 'KUDOS:10.5' - │ + │ │ >>> amt.stringify(pretty=True) │ '10.5 KUDOS' - │ + │ │ >>> (amt + amt).stringify(pretty=True) │ '21 KUDOS' └──── @@ -205,7 +204,7 @@ Ongoing discussion: ┌──── │ >>> amt > another │ True - │ + │ │ >>> amt == another │ False └──── @@ -220,10 +219,10 @@ Ongoing discussion: ┌──── │ >>> p = amt.as_signed () - │ + │ │ >>> p.is_positive │ True - │ + │ │ >>> p.amount │ Amount(currency='KUDOS', value=10, fraction=50000000) └──── @@ -234,10 +233,10 @@ Ongoing discussion: ┌──── │ >>> q = another.as_signed () - │ + │ │ >>> (p - q).is_positive │ True - │ + │ │ >>> (q - p).is_positive │ False └──── @@ -249,7 +248,7 @@ Ongoing discussion: ┌──── │ >>> (p - q).stringify (pretty=False) │ '+KUDOS:5.49999958' - │ + │ │ >>> (q - p).stringify (pretty=True) │ '-5.49999958 KUDOS' └──── @@ -269,10 +268,10 @@ Ongoing discussion: ┌──── │ >>> n = q - p - │ + │ │ >>> n.is_positive │ False - │ + │ │ >>> (- n).is_positive │ True └──── @@ -378,7 +377,7 @@ Ongoing discussion: ┌──── │ >>> from taler.util.gnunet_log import GnunetLogger - │ + │ │ >>> l = GnunetLogger ("ui") └──── @@ -422,10 +421,10 @@ Ongoing discussion: ┌──── │ >>> from taler.util.payto import PaytoParse - │ + │ │ # from RFC 8905 │ >>> uri = "payto://iban/DE75512108001245126199?amount=EUR:200.0&message=hello" - │ + │ │ >>> p = PaytoParse (uri) │ Traceback (most recent call last): │ File "", line 1, in @@ -441,21 +440,21 @@ Ongoing discussion: ┌──── │ >>> uri = "payto://iban/SOGEDEFFXXX/DE75512108001245126199?amount=EUR:200.0&message=hello" - │ + │ │ >>> p = PaytoParse (uri) - │ + │ │ >>> p.target │ 'DE75512108001245126199' - │ + │ │ >>> p.bank │ 'SOGEDEFFXXX' - │ + │ │ >>> p.authority │ 'iban' - │ + │ │ >>> p.message │ 'hello' - │ + │ │ >>> p.amount │ Amount(currency='EUR', value=200, fraction=0) └──── @@ -510,12 +509,6 @@ Ongoing discussion: 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". @@ -541,9 +534,9 @@ Ongoing discussion: 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}}’)? + the value of ‘X’ is empty, use the value of ‘Y’ instead. Also, the + second type can be nested, i.e., ‘${X:-${Y:-Z}}’. That is, if ‘X’ is + empty, try ‘Y’, and if ‘Y’ is empty, try ‘Z’. For example, ‘${TMPDIR:-/tmp}/taler-test’ expands to ‘/var/tmp/taler-test’ if environment variable ‘TMPDIR’ has value @@ -591,36 +584,5 @@ Ongoing discussion: ┌──── │ [section] - │ option = value # FIXME (what is location?) + │ option = value # filename & line number pair └──── - - -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). -- cgit v1.2.3