diff options
| author | Arnold D. Robbins <arnold@skeeve.com> | 2023-12-26 09:30:01 +0200 |
|---|---|---|
| committer | Arnold D. Robbins <arnold@skeeve.com> | 2023-12-26 09:30:01 +0200 |
| commit | 7bd2bc9e8cc16d1c0dfa37f355290f76ed6de3f8 (patch) | |
| tree | f8601af5aa3764cce668c3b7dd8e23df193dce45 | |
| parent | 93333bd8d23a7c87f1980310afd5274c33311c36 (diff) | |
| download | gawk-7bd2bc9e8cc16d1c0dfa37f355290f76ed6de3f8.tar.gz | |
Fixes in the API and its doc.
| -rw-r--r-- | ChangeLog | 6 | ||||
| -rw-r--r-- | doc/ChangeLog | 5 | ||||
| -rw-r--r-- | doc/gawk.info | 276 | ||||
| -rw-r--r-- | doc/gawk.texi | 31 | ||||
| -rw-r--r-- | gawkapi.c | 43 |
5 files changed, 209 insertions, 152 deletions
@@ -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 @@ -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; |
