[gnunet-scheme] 287/324: doc: Document how the read values from a configuration.

[gnunet]

This is an automated email from the git hooks/post-receive script.

maxime-devos pushed a commit to branch master
in repository gnunet-scheme.

commit b2790f0da94366dd68d991e603143d342ebe1fc0
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Mon Sep 13 18:59:21 2021 +0200

    doc: Document how the read values from a configuration.
    
    * doc/scheme-gnunet.tm (Configuration): Demonstrate 'read-value' and
      'set-value!'.
---
 doc/scheme-gnunet.tm | 66 ++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 62 insertions(+), 4 deletions(-)

diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index 9415e50..e302382 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -93,6 +93,68 @@
 
   <section|Configuration>
 
+  There are a number of modules for accessing GNUnet
+  configurations.<space|1em>Firstly, there is <scm|(gnu gnunet config db)>,
+  which is the module library code would typically use.<space|1em>For
+  testing, one can create an empty configuration with the procedure
+  <scm|hash-\<gtr\>configuration> from that module and <scm|make-hashtable>
+  from <scm|(rnrs hashtables)>, using <scm|hash-key> as hash function and
+  <scm|key=?> as comparison function:
+
+  <\scm-code>
+    (import (gnu gnunet config db)
+
+    \ \ \ \ \ \ \ \ (gnu gnunet config value-parser)
+
+    \ \ \ \ \ \ \ \ (rnrs hashtables))
+
+    (define config (hash-\<gtr\>configuration (make-hashtable hash-key
+    key=?))
+  </scm-code>
+
+  The resulting configuration <scm|config> is initially empty, so set some
+  <with|font-shape|italic|keys> in the <with|font-shape|italic|section>
+  <verbatim|nse>, to configure the network-size estimation service:
+
+  <\scm-code>
+    (set-value! identity config "nse" "UNIXPATH" "/tmp/nse.sock")
+
+    (set-value! number-\<gtr\>string config "cadet" "MAX_ROUTES" 5000)
+
+    ;; TODO: IP address, time durations, booleans, ...
+  </scm-code>
+
+  Now read these values back:
+
+  <\scm-code>
+    (read-value value-\<gtr\>file-name config "nse" "UNIXPATH")
+
+    ;; -\<gtr\> /tmp/nse.sock
+
+    (read-value value-\<gtr\>natural config "cadet" "MAX_ROUTES")
+
+    ;; -\<gtr\> 5000
+  </scm-code>
+
+  What if the configuration doesn't have a value for the specified section
+  and key?<space|1em>Then an <scm|&undefined-key-error> results:
+
+  <\scm-code>
+    (read-value value-\<gtr\>natural config "kated" "MAX_ROUTES")
+
+    ;; -\<gtr\>
+
+    ;; ice-9/boot-9.scm:1685:16: In procedure raise-exception:
+
+    ;; ERROR:
+
+    ;; \ \ 1. &undefined-key-error:
+
+    ;; \ \ \ \ \ \ section: "kated"
+
+    ;; \ \ \ \ \ \ key: "MAX_ROUTES"
+  </scm-code>
+
   <subsection|Locating configuration files>
 
   There are two \U possibly non-existent \U configuration files: the
@@ -192,10 +254,6 @@
   Applications (whether graphical or textual) are recommended to use
   <scm|load-configuration> by default, as it largely just works.
 
-  <subsection|Value types>
-
-  TODO
-
   <section|Manipulation of network structures>
 
   <index|network structure><index|netstruct>The modules <scm|(gnu gnunet

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.