[SCM] gawk branch, gawk-5.3-stable, updated. gawk-4.1.0-5444-g7bd2bc9e

[Arnold Robbins]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".

The branch, gawk-5.3-stable has been updated
       via  7bd2bc9e8cc16d1c0dfa37f355290f76ed6de3f8 (commit)
      from  93333bd8d23a7c87f1980310afd5274c33311c36 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=7bd2bc9e8cc16d1c0dfa37f355290f76ed6de3f8

commit 7bd2bc9e8cc16d1c0dfa37f355290f76ed6de3f8
Author: Arnold D. Robbins <arnold@skeeve.com>
Date:   Tue Dec 26 09:30:01 2023 +0200

    Fixes in the API and its doc.

diff --git a/ChangeLog b/ChangeLog
index 77537418..156994ae 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2023-12-26         Arnold D. Robbins     <arnold@skeeve.com>
+
+       * gawkapi.c (api_get_argument): Sync handling of AWK_UNDEFINED
+       with the doc.
+       (node_to_awk_value): Similar.
+
 2023-12-25         Arnold D. Robbins     <arnold@skeeve.com>
 
        * debug.c (serialize_list): Fix a compiler warning about
diff --git a/doc/ChangeLog b/doc/ChangeLog
index d2c49cc1..9eca98e9 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2023-12-26         Arnold D. Robbins     <arnold@skeeve.com>
+
+       * gawk.texi (Requesting Values): Add more text to clarify the
+       behavior.
+
 2023-12-03         Arnold D. Robbins     <arnold@skeeve.com>
 
        * gawk.texi: Change references to gawktexi.in to gawk.texi and
diff --git a/doc/gawk.info b/doc/gawk.info
index da65b233..48b9f448 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -27593,6 +27593,28 @@ Requested   Bool        false    false    false    
false   Bool     false   fals
 
 Table 17.2: API value types returned
 
+   There are a number of points of note:
+
+   • A request for ‘AWK_UNDEFINED’ always returns true, filling in the
+     actual type of the particular value.  You can think of this as a
+     sort of "wildcard" request.
+
+   • Requesting an ‘AWK_STRING’ causes ‘gawk’ to convert any scalar
+     value to a string result, and that is what is retuned.
+
+   • Requesting an ‘AWK_NUMBER’ causes ‘gawk’ to convert any scalar
+     value, except for a regexp, to a numeric result, and that is what
+     is retuned.
+
+     Conversion between string and number in the API thus parallels how
+     ‘gawk’ behaves in running code.
+
+   • The API functions do _not_ distinguish between ‘"undefined"’ and
+     ‘"unassigned"’ as returned by ‘typeof()’ (*note Dynamic Typing
+     Gawk::).  ‘AWK_UNDEFINED’ serves for both.  This is unlikely to
+     change, as the documentation and code are already complicated
+     enough.
+
 
 File: gawk.info,  Node: Accessing Parameters,  Next: Symbol Table Access,  
Prev: Requesting Values,  Up: Extension API Description
 
@@ -40283,133 +40305,133 @@ Ref: Printing Messages-Footnote-11158513
 Node: Updating ERRNO1158666
 Node: Requesting Values1159465
 Ref: table-value-types-returned1160218
-Node: Accessing Parameters1161326
-Node: Symbol Table Access1162607
-Node: Symbol table by name1163119
-Ref: Symbol table by name-Footnote-11166320
-Node: Symbol table by cookie1166452
-Ref: Symbol table by cookie-Footnote-11170721
-Node: Cached values1170785
-Ref: Cached values-Footnote-11174417
-Node: Array Manipulation1174574
-Ref: Array Manipulation-Footnote-11175673
-Node: Array Data Types1175710
-Ref: Array Data Types-Footnote-11178528
-Node: Array Functions1178624
-Node: Flattening Arrays1183653
-Node: Creating Arrays1190701
-Node: Redirection API1195543
-Node: Extension API Variables1198560
-Node: Extension Versioning1199283
-Ref: gawk-api-version1199712
-Node: Extension GMP/MPFR Versioning1201499
-Node: Extension API Informational Variables1203203
-Node: Extension API Boilerplate1204456
-Node: Changes from API V11208586
-Node: Finding Extensions1210218
-Node: Extension Example1210793
-Node: Internal File Description1211615
-Node: Internal File Ops1215907
-Ref: Internal File Ops-Footnote-11227457
-Node: Using Internal File Ops1227605
-Ref: Using Internal File Ops-Footnote-11230036
-Node: Extension Samples1230314
-Node: Extension Sample File Functions1231883
-Node: Extension Sample Fnmatch1240008
-Node: Extension Sample Fork1241603
-Node: Extension Sample Inplace1242879
-Node: Extension Sample Ord1246545
-Node: Extension Sample Readdir1247421
-Ref: table-readdir-file-types1248210
-Node: Extension Sample Revout1249566
-Node: Extension Sample Rev2way1250163
-Node: Extension Sample Read write array1250915
-Node: Extension Sample Readfile1254189
-Node: Extension Sample Time1255320
-Node: Extension Sample API Tests1257320
-Node: gawkextlib1257828
-Node: Extension summary1260860
-Node: Extension Exercises1264708
-Node: Language History1265978
-Node: V7/SVR3.11267690
-Node: SVR41270040
-Node: POSIX1271572
-Node: BTL1272997
-Node: POSIX/GNU1273764
-Node: Feature History1280419
-Node: Common Extensions1300221
-Node: Ranges and Locales1301696
-Ref: Ranges and Locales-Footnote-11306481
-Ref: Ranges and Locales-Footnote-21306508
-Ref: Ranges and Locales-Footnote-31306743
-Node: Contributors1306966
-Node: History summary1313157
-Node: Installation1314599
-Node: Gawk Distribution1315563
-Node: Getting1316055
-Node: Extracting1317054
-Node: Distribution contents1318760
-Node: Unix Installation1326650
-Node: Quick Installation1327470
-Node: Compiling with MPFR1330010
-Node: Shell Startup Files1330716
-Node: Additional Configuration Options1331873
-Node: Configuration Philosophy1334256
-Node: Compiling from Git1336756
-Node: Building the Documentation1337315
-Node: Non-Unix Installation1338727
-Node: PC Installation1339203
-Node: PC Binary Installation1340072
-Node: PC Compiling1340965
-Node: PC Using1342143
-Node: Cygwin1345859
-Node: MSYS1347111
-Node: OpenVMS Installation1347737
-Node: OpenVMS Compilation1348418
-Ref: OpenVMS Compilation-Footnote-11349901
-Node: OpenVMS Dynamic Extensions1349959
-Node: OpenVMS Installation Details1351595
-Node: OpenVMS Running1354026
-Node: OpenVMS GNV1358163
-Node: Bugs1358918
-Node: Bug definition1359838
-Node: Bug address1363439
-Node: Usenet1367008
-Node: Performance bugs1368221
-Node: Asking for help1371237
-Node: Maintainers1373224
-Node: Other Versions1374251
-Node: Installation summary1383855
-Node: Notes1385237
-Node: Compatibility Mode1386047
-Node: Additions1386869
-Node: Accessing The Source1387814
-Node: Adding Code1389345
-Node: New Ports1396456
-Node: Derived Files1400959
-Ref: Derived Files-Footnote-11406770
-Ref: Derived Files-Footnote-21406805
-Ref: Derived Files-Footnote-31407416
-Node: Future Extensions1407530
-Node: Implementation Limitations1408200
-Node: Extension Design1409442
-Node: Old Extension Problems1410602
-Ref: Old Extension Problems-Footnote-11412174
-Node: Extension New Mechanism Goals1412235
-Ref: Extension New Mechanism Goals-Footnote-11415705
-Node: Extension Other Design Decisions1415906
-Node: Extension Future Growth1418103
-Node: Notes summary1418723
-Node: Basic Concepts1419933
-Node: Basic High Level1420618
-Ref: figure-general-flow1420900
-Ref: figure-process-flow1421602
-Ref: Basic High Level-Footnote-11424972
-Node: Basic Data Typing1425161
-Node: Glossary1428569
-Node: Copying1461448
-Node: GNU Free Documentation License1499006
-Node: Index1524129
+Node: Accessing Parameters1162275
+Node: Symbol Table Access1163556
+Node: Symbol table by name1164068
+Ref: Symbol table by name-Footnote-11167269
+Node: Symbol table by cookie1167401
+Ref: Symbol table by cookie-Footnote-11171670
+Node: Cached values1171734
+Ref: Cached values-Footnote-11175366
+Node: Array Manipulation1175523
+Ref: Array Manipulation-Footnote-11176622
+Node: Array Data Types1176659
+Ref: Array Data Types-Footnote-11179477
+Node: Array Functions1179573
+Node: Flattening Arrays1184602
+Node: Creating Arrays1191650
+Node: Redirection API1196492
+Node: Extension API Variables1199509
+Node: Extension Versioning1200232
+Ref: gawk-api-version1200661
+Node: Extension GMP/MPFR Versioning1202448
+Node: Extension API Informational Variables1204152
+Node: Extension API Boilerplate1205405
+Node: Changes from API V11209535
+Node: Finding Extensions1211167
+Node: Extension Example1211742
+Node: Internal File Description1212564
+Node: Internal File Ops1216856
+Ref: Internal File Ops-Footnote-11228406
+Node: Using Internal File Ops1228554
+Ref: Using Internal File Ops-Footnote-11230985
+Node: Extension Samples1231263
+Node: Extension Sample File Functions1232832
+Node: Extension Sample Fnmatch1240957
+Node: Extension Sample Fork1242552
+Node: Extension Sample Inplace1243828
+Node: Extension Sample Ord1247494
+Node: Extension Sample Readdir1248370
+Ref: table-readdir-file-types1249159
+Node: Extension Sample Revout1250515
+Node: Extension Sample Rev2way1251112
+Node: Extension Sample Read write array1251864
+Node: Extension Sample Readfile1255138
+Node: Extension Sample Time1256269
+Node: Extension Sample API Tests1258269
+Node: gawkextlib1258777
+Node: Extension summary1261809
+Node: Extension Exercises1265657
+Node: Language History1266927
+Node: V7/SVR3.11268639
+Node: SVR41270989
+Node: POSIX1272521
+Node: BTL1273946
+Node: POSIX/GNU1274713
+Node: Feature History1281368
+Node: Common Extensions1301170
+Node: Ranges and Locales1302645
+Ref: Ranges and Locales-Footnote-11307430
+Ref: Ranges and Locales-Footnote-21307457
+Ref: Ranges and Locales-Footnote-31307692
+Node: Contributors1307915
+Node: History summary1314106
+Node: Installation1315548
+Node: Gawk Distribution1316512
+Node: Getting1317004
+Node: Extracting1318003
+Node: Distribution contents1319709
+Node: Unix Installation1327599
+Node: Quick Installation1328419
+Node: Compiling with MPFR1330959
+Node: Shell Startup Files1331665
+Node: Additional Configuration Options1332822
+Node: Configuration Philosophy1335205
+Node: Compiling from Git1337705
+Node: Building the Documentation1338264
+Node: Non-Unix Installation1339676
+Node: PC Installation1340152
+Node: PC Binary Installation1341021
+Node: PC Compiling1341914
+Node: PC Using1343092
+Node: Cygwin1346808
+Node: MSYS1348060
+Node: OpenVMS Installation1348686
+Node: OpenVMS Compilation1349367
+Ref: OpenVMS Compilation-Footnote-11350850
+Node: OpenVMS Dynamic Extensions1350908
+Node: OpenVMS Installation Details1352544
+Node: OpenVMS Running1354975
+Node: OpenVMS GNV1359112
+Node: Bugs1359867
+Node: Bug definition1360787
+Node: Bug address1364388
+Node: Usenet1367957
+Node: Performance bugs1369170
+Node: Asking for help1372186
+Node: Maintainers1374173
+Node: Other Versions1375200
+Node: Installation summary1384804
+Node: Notes1386186
+Node: Compatibility Mode1386996
+Node: Additions1387818
+Node: Accessing The Source1388763
+Node: Adding Code1390294
+Node: New Ports1397405
+Node: Derived Files1401908
+Ref: Derived Files-Footnote-11407719
+Ref: Derived Files-Footnote-21407754
+Ref: Derived Files-Footnote-31408365
+Node: Future Extensions1408479
+Node: Implementation Limitations1409149
+Node: Extension Design1410391
+Node: Old Extension Problems1411551
+Ref: Old Extension Problems-Footnote-11413123
+Node: Extension New Mechanism Goals1413184
+Ref: Extension New Mechanism Goals-Footnote-11416654
+Node: Extension Other Design Decisions1416855
+Node: Extension Future Growth1419052
+Node: Notes summary1419672
+Node: Basic Concepts1420882
+Node: Basic High Level1421567
+Ref: figure-general-flow1421849
+Ref: figure-process-flow1422551
+Ref: Basic High Level-Footnote-11425921
+Node: Basic Data Typing1426110
+Node: Glossary1429518
+Node: Copying1462397
+Node: GNU Free Documentation License1499955
+Node: Index1525078
 
 End Tag Table
 
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 4d088fd3..2ed5f131 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -37019,10 +37019,14 @@ value type, as appropriate.  This behavior is 
summarized in
 @multitable @columnfractions .50 .50
 @headitem @tab Type of Actual Value
 @end multitable
+@ignore
+@c 12/2023: Texinfo.tex has morphed enough that this produces
+@c bad output, so comment it out.
 @c 10/2014: Thanks to Karl Berry for this bit to reduce the space:
 @tex
 \vglue-1.1\baselineskip
 @end tex
+@end ignore
 @c @multitable @columnfractions .166 .166 .198 .15 .15 .166
 @multitable {Requested} {Undefined} {Number} {Number} {Scalar} {Regex} 
{Number} {Array} {Undefined}
 @headitem @tab @tab String @tab Strnum @tab Number @tab Regex @tab Bool @tab 
Array @tab Undefined
@@ -37068,6 +37072,33 @@ value type, as appropriate.  This behavior is 
summarized in
 @end ifplaintext
 @end float
 
+There are a number of points of note:
+
+@itemize @bullet
+@item
+A request for @code{AWK_UNDEFINED} always returns true, filling in
+the actual type of the particular value.  You can think of this
+as a sort of ``wildcard'' request.
+
+@item
+Requesting an @code{AWK_STRING} causes @command{gawk} to convert any
+scalar value to a string result, and that is what is retuned.
+
+@item
+Requesting an @code{AWK_NUMBER} causes @command{gawk} to convert any
+scalar value, except for a regexp, to a numeric result, and
+that is what is retuned.
+
+Conversion between string and number in the API thus parallels how
+@command{gawk} behaves in running code.
+
+@item
+The API functions do @emph{not} distinguish between @code{"undefined"}
+and @code{"unassigned"} as returned by @code{typeof()} (@pxref{Dynamic
+Typing Gawk}).  @code{AWK_UNDEFINED} serves for both. This is unlikely
+to change, as the documentation and code are already complicated enough.
+@end itemize
+
 @node Accessing Parameters
 @subsection Accessing and Updating Parameters
 
diff --git a/gawkapi.c b/gawkapi.c
index 20d131aa..fe6573e0 100644
--- a/gawkapi.c
+++ b/gawkapi.c
@@ -72,16 +72,17 @@ api_get_argument(awk_ext_id_t id, size_t count,
        if (arg->type == Node_var_new || arg->type == Node_elem_new) {
                if (wanted == AWK_UNDEFINED)
                        return awk_true;
-               else if (wanted == AWK_ARRAY) {
+               else if (wanted == AWK_ARRAY)
                        goto array;
-               } else {
+               else
                        goto scalar;
-               }
        }
 
        /* at this point, we have real type */
        if (arg->type == Node_var_array || arg->type == Node_array_ref) {
-               if (wanted != AWK_ARRAY && wanted != AWK_UNDEFINED)
+               if (wanted == AWK_UNDEFINED)
+                       return awk_true;
+               else if (wanted != AWK_ARRAY)
                        return awk_false;
                goto array;
        } else
@@ -624,11 +625,9 @@ node_to_awk_value(NODE *node, awk_value_t *val, 
awk_valtype_t wanted)
                                val->val_type = AWK_REGEX;
                                break;
                        case NUMBER|STRING:
-                               if (node == Nnull_string) {
-                                       val->val_type = AWK_UNDEFINED;
-                                       break;
-                               }
-                               /* fall through */
+                               // this can come from a Node_elem_new, as well 
as Nnull_string
+                               val->val_type = AWK_UNDEFINED;
+                               break;
                        default:
                                warning(_("node_to_awk_value detected invalid 
flags combination `%s'; please file a bug report"), flags2str(node->flags));
                                val->val_type = AWK_UNDEFINED;
@@ -661,11 +660,9 @@ node_to_awk_value(NODE *node, awk_value_t *val, 
awk_valtype_t wanted)
                                ret = awk_true;
                                break;
                        case NUMBER|STRING:
-                               if (node == Nnull_string) {
-                                       val->val_type = AWK_UNDEFINED;
-                                       break;
-                               }
-                               /* fall through */
+                               // this can come from a Node_elem_new, as well 
as Nnull_string
+                               val->val_type = AWK_UNDEFINED;
+                               break;
                        default:
                                warning(_("node_to_awk_value detected invalid 
flags combination `%s'; please file a bug report"), flags2str(node->flags));
                                val->val_type = AWK_UNDEFINED;
@@ -691,11 +688,9 @@ node_to_awk_value(NODE *node, awk_value_t *val, 
awk_valtype_t wanted)
                                val->val_type = AWK_REGEX;
                                break;
                        case NUMBER|STRING:
-                               if (node == Nnull_string) {
-                                       val->val_type = AWK_UNDEFINED;
-                                       break;
-                               }
-                               /* fall through */
+                               // this can come from a Node_elem_new, as well 
as Nnull_string
+                               val->val_type = AWK_UNDEFINED;
+                               break;
                        default:
                                warning(_("node_to_awk_value detected invalid 
flags combination `%s'; please file a bug report"), flags2str(node->flags));
                                val->val_type = AWK_UNDEFINED;
@@ -727,12 +722,10 @@ node_to_awk_value(NODE *node, awk_value_t *val, 
awk_valtype_t wanted)
                                ret = awk_true;
                                break;
                        case NUMBER|STRING:
-                               if (node == Nnull_string) {
-                                       val->val_type = AWK_UNDEFINED;
-                                       ret = awk_true;
-                                       break;
-                               }
-                               /* fall through */
+                               // this can come from a Node_elem_new, as well 
as Nnull_string
+                               val->val_type = AWK_UNDEFINED;
+                               ret = awk_true;
+                               break;
                        default:
                                warning(_("node_to_awk_value detected invalid 
flags combination `%s'; please file a bug report"), flags2str(node->flags));
                                val->val_type = AWK_UNDEFINED;

-----------------------------------------------------------------------

Summary of changes:
 ChangeLog     |   6 ++
 doc/ChangeLog |   5 ++
 doc/gawk.info | 276 +++++++++++++++++++++++++++++++---------------------------
 doc/gawk.texi |  31 +++++++
 gawkapi.c     |  43 ++++-----
 5 files changed, 209 insertions(+), 152 deletions(-)


hooks/post-receive
-- 
gawk