Enhance rwarray extension to add writeall and readall functions for dumping and reloading global state.

5 files changed, 188 insertions, 92 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 66251098..6c5439be 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2021-12-08         Andrew J. Schorr      <aschorr@telemetry-investments.com>
+
+	* gawktexi.in: Document new rwarray functions writeall and readall.
+	* wordlist: Add readall and writeall.
+
 2021-11-25         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in: Add missing @item for AWKgo. Thanks to Antonio
diff --git a/doc/gawk.info b/doc/gawk.info
index 4f768252..6aaff404 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -29128,8 +29128,8 @@ File: gawk.info,  Node: Extension Sample Read write array,  Next: Extension Samp
 17.7.9 Dumping and Restoring an Array
 -------------------------------------
 
-The 'rwarray' extension adds two functions, named 'writea()' and
-'reada()', as follows:
+The 'rwarray' extension adds four functions, named 'writea()',
+'reada()', 'writeall()' and 'readall()', as follows:
 
 '@load "rwarray"'
      This is how you load the extension.
@@ -29146,6 +29146,20 @@ The 'rwarray' extension adds two functions, named 'writea()' and
      argument.  It clears the array first.  Here too, the return value
      is one on success, or zero upon failure.
 
+'ret = writeall(file)'
+     This function takes a string argument, which is the name of the
+     file to which to dump the state of all variables.  Calling this
+     function is completely equivalent to calling 'writea(file,
+     SYMTAB)'.  It returns one on success, or zero upon failure
+
+'ret = writeall(file)'
+     This function takes a string argument, which is the name of the
+     file from which to read the contents of various global variables.
+     For each variable in the file, the data is loaded unless the
+     variable already exists.  If the variable already exists, the data
+     for that variable in the file is ignored.  It returns one on
+     success, or zero upon failure.
+
    The array created by 'reada()' is identical to that written by
 'writea()' in the sense that the contents are the same.  However, due to
 implementation issues, the array traversal order of the re-created array
@@ -29161,6 +29175,13 @@ written as native binary data.  Thus, arrays containing only string data
 can theoretically be dumped on systems with one byte order and restored
 on systems with a different one, but this has not been tried.
 
+   Note that the 'writeall()' and 'readall()' functions provide a
+mechanism for maintaining persistent state across repeated invocations
+of a program.  If, for example, a program calculates some statistics
+based on the data in a series of files, it could save state using
+'writeall()' after processing N files, and then reload the state using
+'readall()' when the N+1st file arrives to update the results.
+
    Here is an example:
 
      @load "rwarray"
@@ -29168,6 +29189,10 @@ on systems with a different one, but this has not been tried.
      ret = writea("arraydump.bin", array)
      ...
      ret = reada("arraydump.bin", array)
+     ...
+     ret = writeall("globalstate.bin")
+     ...
+     ret = readall("globalstate.bin")
 
 
 File: gawk.info,  Node: Extension Sample Readfile,  Next: Extension Sample Time,  Prev: Extension Sample Read write array,  Up: Extension Samples
@@ -37998,6 +38023,8 @@ Index
                                                               (line  18)
 * readable data files, checking:         File Checking.       (line   6)
 * readable.awk program:                  File Checking.       (line  11)
+* readall() extension function:          Extension Sample Read write array.
+                                                              (line  30)
 * readdir extension:                     Extension Sample Readdir.
                                                               (line   9)
 * readfile() extension function:         Extension Sample Readfile.
@@ -38711,6 +38738,8 @@ Index
 * words, usage counts, generating:       Word Sorting.        (line   6)
 * writea() extension function:           Extension Sample Read write array.
                                                               (line  12)
+* writeall() extension function:         Extension Sample Read write array.
+                                                              (line  24)
 * xgettext utility:                      String Extraction.   (line  13)
 * xor:                                   Bitwise Functions.   (line  58)
 * XOR bitwise operation:                 Bitwise Functions.   (line   6)
@@ -39246,92 +39275,92 @@ Ref: table-readdir-file-types1174550
 Node: Extension Sample Revout1175618
 Node: Extension Sample Rev2way1176207
 Node: Extension Sample Read write array1176947
-Node: Extension Sample Readfile1178889
-Node: Extension Sample Time1179984
-Node: Extension Sample API Tests1181736
-Node: gawkextlib1182228
-Node: Extension summary1185146
-Node: Extension Exercises1188848
-Node: Language History1190090
-Node: V7/SVR3.11191746
-Node: SVR41193898
-Node: POSIX1195332
-Node: BTL1196713
-Node: POSIX/GNU1197442
-Node: Feature History1203220
-Node: Common Extensions1220395
-Node: Ranges and Locales1221678
-Ref: Ranges and Locales-Footnote-11226294
-Ref: Ranges and Locales-Footnote-21226321
-Ref: Ranges and Locales-Footnote-31226556
-Node: Contributors1226779
-Node: History summary1232776
-Node: Installation1234156
-Node: Gawk Distribution1235100
-Node: Getting1235584
-Node: Extracting1236547
-Node: Distribution contents1238185
-Node: Unix Installation1245246
-Node: Quick Installation1246050
-Node: Compiling with MPFR1248470
-Node: Shell Startup Files1249160
-Node: Additional Configuration Options1250249
-Node: Configuration Philosophy1252564
-Node: Compiling from Git1254960
-Node: Building the Documentation1255515
-Node: Non-Unix Installation1256899
-Node: PC Installation1257359
-Node: PC Binary Installation1258197
-Node: PC Compiling1259070
-Node: PC Using1260187
-Node: Cygwin1263740
-Node: MSYS1264964
-Node: VMS Installation1265566
-Node: VMS Compilation1266285
-Ref: VMS Compilation-Footnote-11267514
-Node: VMS Dynamic Extensions1267572
-Node: VMS Installation Details1269257
-Node: VMS Running1271519
-Node: VMS GNV1275798
-Node: Bugs1276512
-Node: Bug definition1277424
-Node: Bug address1280360
-Node: Usenet1283748
-Node: Performance bugs1284937
-Node: Asking for help1287858
-Node: Maintainers1289825
-Node: Other Versions1291019
-Node: Installation summary1299183
-Node: Notes1300547
-Node: Compatibility Mode1301341
-Node: Additions1302123
-Node: Accessing The Source1303048
-Node: Adding Code1304485
-Node: New Ports1310677
-Node: Derived Files1315052
-Ref: Derived Files-Footnote-11320712
-Ref: Derived Files-Footnote-21320747
-Ref: Derived Files-Footnote-31321345
-Node: Future Extensions1321459
-Node: Implementation Limitations1322117
-Node: Extension Design1323327
-Node: Old Extension Problems1324471
-Ref: Old Extension Problems-Footnote-11325989
-Node: Extension New Mechanism Goals1326046
-Ref: Extension New Mechanism Goals-Footnote-11329410
-Node: Extension Other Design Decisions1329599
-Node: Extension Future Growth1331712
-Node: Notes summary1332318
-Node: Basic Concepts1333476
-Node: Basic High Level1334157
-Ref: figure-general-flow1334439
-Ref: figure-process-flow1335125
-Ref: Basic High Level-Footnote-11338427
-Node: Basic Data Typing1338612
-Node: Glossary1341940
-Node: Copying1373827
-Node: GNU Free Documentation License1411370
-Node: Index1436490
+Node: Extension Sample Readfile1180113
+Node: Extension Sample Time1181208
+Node: Extension Sample API Tests1182960
+Node: gawkextlib1183452
+Node: Extension summary1186370
+Node: Extension Exercises1190072
+Node: Language History1191314
+Node: V7/SVR3.11192970
+Node: SVR41195122
+Node: POSIX1196556
+Node: BTL1197937
+Node: POSIX/GNU1198666
+Node: Feature History1204444
+Node: Common Extensions1221619
+Node: Ranges and Locales1222902
+Ref: Ranges and Locales-Footnote-11227518
+Ref: Ranges and Locales-Footnote-21227545
+Ref: Ranges and Locales-Footnote-31227780
+Node: Contributors1228003
+Node: History summary1234000
+Node: Installation1235380
+Node: Gawk Distribution1236324
+Node: Getting1236808
+Node: Extracting1237771
+Node: Distribution contents1239409
+Node: Unix Installation1246470
+Node: Quick Installation1247274
+Node: Compiling with MPFR1249694
+Node: Shell Startup Files1250384
+Node: Additional Configuration Options1251473
+Node: Configuration Philosophy1253788
+Node: Compiling from Git1256184
+Node: Building the Documentation1256739
+Node: Non-Unix Installation1258123
+Node: PC Installation1258583
+Node: PC Binary Installation1259421
+Node: PC Compiling1260294
+Node: PC Using1261411
+Node: Cygwin1264964
+Node: MSYS1266188
+Node: VMS Installation1266790
+Node: VMS Compilation1267509
+Ref: VMS Compilation-Footnote-11268738
+Node: VMS Dynamic Extensions1268796
+Node: VMS Installation Details1270481
+Node: VMS Running1272743
+Node: VMS GNV1277022
+Node: Bugs1277736
+Node: Bug definition1278648
+Node: Bug address1281584
+Node: Usenet1284972
+Node: Performance bugs1286161
+Node: Asking for help1289082
+Node: Maintainers1291049
+Node: Other Versions1292243
+Node: Installation summary1300407
+Node: Notes1301771
+Node: Compatibility Mode1302565
+Node: Additions1303347
+Node: Accessing The Source1304272
+Node: Adding Code1305709
+Node: New Ports1311901
+Node: Derived Files1316276
+Ref: Derived Files-Footnote-11321936
+Ref: Derived Files-Footnote-21321971
+Ref: Derived Files-Footnote-31322569
+Node: Future Extensions1322683
+Node: Implementation Limitations1323341
+Node: Extension Design1324551
+Node: Old Extension Problems1325695
+Ref: Old Extension Problems-Footnote-11327213
+Node: Extension New Mechanism Goals1327270
+Ref: Extension New Mechanism Goals-Footnote-11330634
+Node: Extension Other Design Decisions1330823
+Node: Extension Future Growth1332936
+Node: Notes summary1333542
+Node: Basic Concepts1334700
+Node: Basic High Level1335381
+Ref: figure-general-flow1335663
+Ref: figure-process-flow1336349
+Ref: Basic High Level-Footnote-11339651
+Node: Basic Data Typing1339836
+Node: Glossary1343164
+Node: Copying1375051
+Node: GNU Free Documentation License1412594
+Node: Index1437714
 
 End Tag Table
 
diff --git a/doc/gawk.texi b/doc/gawk.texi
index d476b74c..cb7ad4c3 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -39729,8 +39729,9 @@ is:
 @node Extension Sample Read write array
 @subsection Dumping and Restoring an Array
 
-The @code{rwarray} extension adds two functions,
-named @code{writea()} and @code{reada()}, as follows:
+The @code{rwarray} extension adds four functions,
+named @code{writea()}, @code{reada()},
+@code{writeall()} and @code{readall()}, as follows:
 
 @table @code
 @item @@load "rwarray"
@@ -39749,6 +39750,24 @@ success, or zero upon failure.
 it reads the file named as its first argument, filling in
 the array named as the second argument. It clears the array first.
 Here too, the return value is one on success, or zero upon failure.
+
+@cindex @code{writeall()} extension function
+@item ret = writeall(file)
+This function takes a string argument, which is the name of the file
+to which to dump the state of all variables.
+Calling this function
+is completely equivalent to calling
+@code{writea(file, SYMTAB)}.
+It returns one on success, or zero upon failure
+
+@cindex @code{readall()} extension function
+@item ret = writeall(file)
+This function takes a string argument, which is the name of the
+file from which to read the contents of various global variables.
+For each variable in the file, the data is loaded unless the variable
+already exists. If the variable already exists, the data for that variable
+in the file is ignored.
+It returns one on success, or zero upon failure.
 @end table
 
 The array created by @code{reada()} is identical to that written by
@@ -39766,6 +39785,13 @@ as native binary data.  Thus, arrays containing only string data can
 theoretically be dumped on systems with one byte order and restored on
 systems with a different one, but this has not been tried.
 
+Note that the @code{writeall()} and @code{readall()} functions provide
+a mechanism for maintaining persistent state across repeated invocations of a
+program. If, for example, a program calculates some statistics based on the
+data in a series of files, it could save state using @code{writeall()} after
+processing N files, and then reload the state using @code{readall()} when
+the N+1st file arrives to update the results.
+
 Here is an example:
 
 @example
@@ -39774,6 +39800,10 @@ Here is an example:
 ret = writea("arraydump.bin", array)
 @dots{}
 ret = reada("arraydump.bin", array)
+@dots{}
+ret = writeall("globalstate.bin")
+@dots{}
+ret = readall("globalstate.bin")
 @end example
 
 @node Extension Sample Readfile
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index f3720f1d..97d21f04 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -38572,8 +38572,9 @@ is:
 @node Extension Sample Read write array
 @subsection Dumping and Restoring an Array
 
-The @code{rwarray} extension adds two functions,
-named @code{writea()} and @code{reada()}, as follows:
+The @code{rwarray} extension adds four functions,
+named @code{writea()}, @code{reada()},
+@code{writeall()} and @code{readall()}, as follows:
 
 @table @code
 @item @@load "rwarray"
@@ -38592,6 +38593,24 @@ success, or zero upon failure.
 it reads the file named as its first argument, filling in
 the array named as the second argument. It clears the array first.
 Here too, the return value is one on success, or zero upon failure.
+
+@cindex @code{writeall()} extension function
+@item ret = writeall(file)
+This function takes a string argument, which is the name of the file
+to which to dump the state of all variables.
+Calling this function
+is completely equivalent to calling
+@code{writea(file, SYMTAB)}.
+It returns one on success, or zero upon failure
+
+@cindex @code{readall()} extension function
+@item ret = writeall(file)
+This function takes a string argument, which is the name of the
+file from which to read the contents of various global variables.
+For each variable in the file, the data is loaded unless the variable
+already exists. If the variable already exists, the data for that variable
+in the file is ignored.
+It returns one on success, or zero upon failure.
 @end table
 
 The array created by @code{reada()} is identical to that written by
@@ -38609,6 +38628,13 @@ as native binary data.  Thus, arrays containing only string data can
 theoretically be dumped on systems with one byte order and restored on
 systems with a different one, but this has not been tried.
 
+Note that the @code{writeall()} and @code{readall()} functions provide
+a mechanism for maintaining persistent state across repeated invocations of a
+program. If, for example, a program calculates some statistics based on the
+data in a series of files, it could save state using @code{writeall()} after
+processing N files, and then reload the state using @code{readall()} when
+the N+1st file arrives to update the results.
+
 Here is an example:
 
 @example
@@ -38617,6 +38643,10 @@ Here is an example:
 ret = writea("arraydump.bin", array)
 @dots{}
 ret = reada("arraydump.bin", array)
+@dots{}
+ret = writeall("globalstate.bin")
+@dots{}
+ret = readall("globalstate.bin")
 @end example
 
 @node Extension Sample Readfile
diff --git a/doc/wordlist b/doc/wordlist
index 1ad1c429..fd7c181e 100644
--- a/doc/wordlist
+++ b/doc/wordlist
@@ -1510,6 +1510,7 @@ rapidjson
 rdev
 rdquo
 reada
+readall
 readdir
 readfile
 readline
@@ -1796,6 +1797,7 @@ wnewmail
 wordfreq
 wr
 writea
+writeall
 www
 wy
 xA