summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorArnold D. Robbins <arnold@skeeve.com>2023-12-26 09:30:54 +0200
committerArnold D. Robbins <arnold@skeeve.com>2023-12-26 09:30:54 +0200
commit945885a715e968e0a914f2330dbb3320e58a4251 (patch)
tree3a8af9a11640906a3529edd2ef9d55ab2020527f
parentd7d5eaf86aee4b638dd423a2e48970c776610fed (diff)
parent92f32a62595bc534a112ed408ba4e2c2dcd6b02d (diff)
downloadgawk-945885a715e968e0a914f2330dbb3320e58a4251.tar.gz
Merge branch 'master' into porting
-rw-r--r--ChangeLog6
-rw-r--r--doc/ChangeLog5
-rw-r--r--doc/gawk.info276
-rw-r--r--doc/gawk.texi31
-rw-r--r--gawkapi.c43
5 files changed, 209 insertions, 152 deletions
diff --git a/ChangeLog b/ChangeLog
index 7753741..156994a 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 d2c49cc..9eca98e 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 da65b23..48b9f44 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 4d088fd..2ed5f13 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 20d131a..fe6573e 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;