aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/ChangeLog26
-rw-r--r--doc/gawk.info365
-rw-r--r--doc/gawk.texi115
-rw-r--r--doc/gawktexi.in115
4 files changed, 411 insertions, 210 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog
index c9c618d2..3a4978d9 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2016-12-22 Arnold D. Robbins <arnold@skeeve.com>
+
+ * gawktexi.in: Minor edits after merging branches and some
+ additional work in the code.
+
2016-12-17 Arnold D. Robbins <arnold@skeeve.com>
* gawktexi.in: Further API clarifications and edits, add a
@@ -12,6 +17,27 @@
* gawktexi.in: Update description of awk_ext_func_t structure.
+2016-12-05 Andrew J. Schorr <aschorr@telemetry-investments.com>
+
+ * gawktexi.in: Document strnum changes as relates to API.
+ Still stuff left to do -- tables for type conversions need
+ to be updated to show new strnum and regex rows and columns.
+
+2016-12-04 Andrew J. Schorr <aschorr@telemetry-investments.com>
+
+ * gawktexi.in: Remove make_regex and replace it with make_const_regex
+ and make_malloced_regex.
+
+2016-12-04 Andrew J. Schorr <aschorr@telemetry-investments.com>
+
+ * gawktexi.in: Document new flatten_array_typed API function, and
+ indicate that the old flatten_array function has been superseded.
+
+2016-11-30 Arnold D. Robbins <arnold@skeeve.com>
+
+ * gawktexi.in: Document typed regex changes as relates to API.
+ Still stuff left to do.
+
2016-11-21 Arnold D. Robbins <arnold@skeeve.com>
* gawktexi.in: Finish off discussion of strongly typed regexp
diff --git a/doc/gawk.info b/doc/gawk.info
index 9033acab..3169ff0c 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -23625,6 +23625,8 @@ use them.
' AWK_UNDEFINED,'
' AWK_NUMBER,'
' AWK_STRING,'
+' AWK_REGEX,'
+' AWK_STRNUM,'
' AWK_ARRAY,'
' AWK_SCALAR, /* opaque access to a variable */'
' AWK_VALUE_COOKIE /* for updating a previously created value */'
@@ -23647,6 +23649,8 @@ use them.
type.
'#define str_value u.s'
+'#define strnum_value str_value'
+'#define regex_value str_value'
'#define num_value u.d'
'#define array_cookie u.a'
'#define scalar_cookie u.scl'
@@ -23665,15 +23669,27 @@ use them.
This is also discussed in a general fashion in the text following
this list, and in more detail in *note Cached values::.
- Scalar values in 'awk' are either numbers or strings. The
-'awk_value_t' struct represents values. The 'val_type' member indicates
-what is in the 'union'.
+ Scalar values in 'awk' are numbers, strings, strnums, or typed
+regexps. The 'awk_value_t' struct represents values. The 'val_type'
+member indicates what is in the 'union'.
Representing numbers is easy--the API uses a C 'double'. Strings
require more work. Because 'gawk' allows embedded NUL bytes in string
values, a string must be represented as a pair containing a data pointer
and length. This is the 'awk_string_t' type.
+ A strnum (numeric string) value is represented as a string and
+consists of user input data that appears to be numeric. When an
+extension creates a strnum value, the result is a string flagged as user
+input. Subsequent parsing by 'gawk' then determines whether it looks
+like a number and should be treated as a strnum, or as a regular string.
+
+ Typed regexp values (*note Strong Regexp Constants::) are not of much
+use to extension functions. Extension functions can tell that they've
+received them, and create them for scalar values. Otherwise, they can
+examine the text of the regexp through 'regex_value.str' and
+'regex_value.len'.
+
Identifiers (i.e., the names of global variables) can be associated
with either scalar values or with arrays. In addition, 'gawk' provides
true arrays of arrays, where any given array element can itself be an
@@ -23833,6 +23849,31 @@ code would use them:
This function simply creates a numeric value in the 'awk_value_t'
variable pointed to by 'result'.
+'static inline awk_value_t *'
+'make_const_user_input(const char *string, size_t length, awk_value_t *result);'
+ This function is identical to 'make_const_string()', but the string
+ is flagged as user input that should be treated as a strnum value
+ if the contents of the string are numeric.
+
+'static inline awk_value_t *'
+'make_malloced_user_input(const char *string, size_t length, awk_value_t *result);'
+ This function is identical to 'make_malloced_string()', but the
+ string is flagged as user input that should be treated as a strnum
+ value if the contents of the string are numeric.
+
+'static inline awk_value_t *'
+'make_const_regex(const char *string, size_t length, awk_value_t *result);'
+ This function creates a strongly typed regexp value by allocating a
+ copy of the string. 'string' is the regular expression of length
+ 'len'.
+
+'static inline awk_value_t *'
+'make_malloced_regex(const char *string, size_t length, awk_value_t *result);'
+ This function creates a strongly typed regexp value. 'string' is
+ the regular expression of length 'len'. It expects 'string' to be
+ a 'char *' value pointing to data previously obtained from
+ 'gawk_malloc()', 'gawk_calloc()', or 'gawk_realloc()'.
+

File: gawk.info, Node: Registration Functions, Next: Printing Messages, Prev: Constructor Functions, Up: Extension API Description
@@ -24580,8 +24621,9 @@ was discussed earlier, in *note General Data Types::.
'awk_bool_t sym_update_scalar(awk_scalar_t cookie, awk_value_t *value);'
Update the value associated with a scalar cookie. Return false if
- the new value is not of type 'AWK_STRING' or 'AWK_NUMBER'. Here
- too, the predefined variables may not be updated.
+ the new value is not of type 'AWK_STRING', 'AWK_STRNUM',
+ 'AWK_REGEX', or 'AWK_NUMBER'. Here too, the predefined variables
+ may not be updated.
It is not obvious at first glance how to work with scalar cookies or
what their raison d'e^tre really is. In theory, the 'sym_lookup()' and
@@ -24695,10 +24737,10 @@ follows:
'awk_bool_t create_value(awk_value_t *value, awk_value_cookie_t *result);'
Create a cached string or numeric value from 'value' for efficient
- later assignment. Only values of type 'AWK_NUMBER' and
- 'AWK_STRING' are allowed. Any other type is rejected.
- 'AWK_UNDEFINED' could be allowed, but doing so would result in
- inferior performance.
+ later assignment. Only values of type 'AWK_NUMBER', 'AWK_REGEX',
+ 'AWK_STRNUM', and 'AWK_STRING' are allowed. Any other type is
+ rejected. 'AWK_UNDEFINED' could be allowed, but doing so would
+ result in inferior performance.
'awk_bool_t release_value(awk_value_cookie_t vc);'
Release the memory associated with a value cookie obtained from
@@ -24925,12 +24967,21 @@ The following functions relate to individual array elements:
array, but after calling this function, it has no elements. This
is equivalent to using the 'delete' statement (*note Delete::).
+'awk_bool_t flatten_array_typed(awk_array_t a_cookie, awk_flat_array_t **data, awk_valtype_t index_type, awk_valtype_t value_type);'
+ For the array represented by 'a_cookie', create an
+ 'awk_flat_array_t' structure and fill it in with indices and values
+ of the requested types. Set the pointer whose address is passed as
+ 'data' to point to this structure. Return true upon success, or
+ false otherwise. *Note Flattening Arrays::, for a discussion of
+ how to flatten an array and work with it.
+
'awk_bool_t flatten_array(awk_array_t a_cookie, awk_flat_array_t **data);'
For the array represented by 'a_cookie', create an
- 'awk_flat_array_t' structure and fill it in. Set the pointer whose
- address is passed as 'data' to point to this structure. Return
- true upon success, or false otherwise. *Note Flattening Arrays::,
- for a discussion of how to flatten an array and work with it.
+ 'awk_flat_array_t' structure and fill it in with 'AWK_STRING'
+ indices and 'AWK_UNDEFINED' values. This is superseded by
+ 'flatten_array_typed()'. It is provided as a macro, and remains
+ convenience and for source code compatibility with the previous
+ version of the API.
'awk_bool_t release_flattened_array(awk_array_t a_cookie,'
' awk_flat_array_t *data);'
@@ -25032,7 +25083,7 @@ count of elements in the array and print it:
double-check that the count in the 'awk_flat_array_t' is the same as the
count just retrieved:
- if (! flatten_array(value2.array_cookie, & flat_array)) {
+ if (! flatten_array_typed(value2.array_cookie, & flat_array, AWK_STRING, AWK_UNDEFINED)) {
printf("dump_array_and_delete: could not flatten array\n");
goto out;
}
@@ -25348,7 +25399,7 @@ versions are available at compile time as C preprocessor defines to
support conditional compilation, and as enum constants to facilitate
debugging:
-API Version C preprocessor define enum constant
+API Version C Preprocessor Define enum constant
--------------------------------------------------------------------
Major 'gawk_api_major_version' 'GAWK_API_MAJOR_VERSION'
Minor 'gawk_api_minor_version' 'GAWK_API_MINOR_VERSION'
@@ -28141,6 +28192,12 @@ to different non-Unix operating systems:
Various '.c', '.y', and '.h' files
These files contain the actual 'gawk' source code.
+'support/*'
+ C header and source files for routines that 'gawk' uses, but that
+ are not part of its core functionality. For example, argument
+ parsing, regular expression matching, and random number generating
+ routines are all kept here.
+
'ABOUT-NLS'
A file containing information about GNU 'gettext' and translations.
@@ -32665,7 +32722,7 @@ Index
* arrays, unassigned elements: Reference to Elements.
(line 18)
* artificial intelligence, gawk and: Distribution contents.
- (line 52)
+ (line 58)
* ASCII: Ordinal Functions. (line 45)
* ASCII <1>: Glossary. (line 196)
* asort: String Functions. (line 42)
@@ -35144,7 +35201,7 @@ Index
* Texinfo <2>: Dupword Program. (line 17)
* Texinfo <3>: Extract Program. (line 12)
* Texinfo <4>: Distribution contents.
- (line 77)
+ (line 83)
* Texinfo <5>: Adding Code. (line 100)
* Texinfo, chapter beginnings in files: Regexp Operators. (line 22)
* Texinfo, extracting programs from source files: Extract Program.
@@ -35806,142 +35863,142 @@ Ref: figure-call-new-function948497
Node: Extension API Description950559
Node: Extension API Functions Introduction952201
Node: General Data Types957512
-Ref: General Data Types-Footnote-1963467
-Node: Memory Allocation Functions963766
-Ref: Memory Allocation Functions-Footnote-1966611
-Node: Constructor Functions966710
-Node: Registration Functions968455
-Node: Extension Functions969140
-Node: Exit Callback Functions974338
-Node: Extension Version String975588
-Node: Input Parsers976251
-Node: Output Wrappers986133
-Node: Two-way processors990645
-Node: Printing Messages992910
-Ref: Printing Messages-Footnote-1994081
-Node: Updating ERRNO994234
-Node: Requesting Values994973
-Ref: table-value-types-returned995710
-Node: Accessing Parameters996593
-Node: Symbol Table Access997828
-Node: Symbol table by name998340
-Node: Symbol table by cookie1000129
-Ref: Symbol table by cookie-Footnote-11004281
-Node: Cached values1004345
-Ref: Cached values-Footnote-11007852
-Node: Array Manipulation1007943
-Ref: Array Manipulation-Footnote-11009034
-Node: Array Data Types1009071
-Ref: Array Data Types-Footnote-11011729
-Node: Array Functions1011821
-Node: Flattening Arrays1015679
-Node: Creating Arrays1022587
-Node: Redirection API1027356
-Node: Extension API Variables1030187
-Node: Extension Versioning1030820
-Ref: gawk-api-version1031257
-Node: Extension API Informational Variables1032985
-Node: Extension API Boilerplate1034049
-Node: Changes from API V11037911
-Node: Finding Extensions1038571
-Node: Extension Example1039130
-Node: Internal File Description1039928
-Node: Internal File Ops1044008
-Ref: Internal File Ops-Footnote-11055408
-Node: Using Internal File Ops1055548
-Ref: Using Internal File Ops-Footnote-11057931
-Node: Extension Samples1058205
-Node: Extension Sample File Functions1059734
-Node: Extension Sample Fnmatch1067383
-Node: Extension Sample Fork1068870
-Node: Extension Sample Inplace1070088
-Node: Extension Sample Ord1073298
-Node: Extension Sample Readdir1074134
-Ref: table-readdir-file-types1075023
-Node: Extension Sample Revout1075828
-Node: Extension Sample Rev2way1076417
-Node: Extension Sample Read write array1077157
-Node: Extension Sample Readfile1079099
-Node: Extension Sample Time1080194
-Node: Extension Sample API Tests1081542
-Node: gawkextlib1082034
-Node: Extension summary1084481
-Node: Extension Exercises1088183
-Node: Language History1089681
-Node: V7/SVR3.11091337
-Node: SVR41093489
-Node: POSIX1094923
-Node: BTL1096302
-Node: POSIX/GNU1097031
-Node: Feature History1102893
-Node: Common Extensions1117263
-Node: Ranges and Locales1118546
-Ref: Ranges and Locales-Footnote-11123162
-Ref: Ranges and Locales-Footnote-21123189
-Ref: Ranges and Locales-Footnote-31123424
-Node: Contributors1123645
-Node: History summary1129205
-Node: Installation1130585
-Node: Gawk Distribution1131529
-Node: Getting1132013
-Node: Extracting1132974
-Node: Distribution contents1134612
-Node: Unix Installation1140697
-Node: Quick Installation1141379
-Node: Shell Startup Files1143793
-Node: Additional Configuration Options1144871
-Node: Configuration Philosophy1146676
-Node: Non-Unix Installation1149045
-Node: PC Installation1149505
-Node: PC Binary Installation1150343
-Node: PC Compiling1150778
-Node: PC Using1151895
-Node: Cygwin1154940
-Node: MSYS1155710
-Node: VMS Installation1156211
-Node: VMS Compilation1157002
-Ref: VMS Compilation-Footnote-11158231
-Node: VMS Dynamic Extensions1158289
-Node: VMS Installation Details1159974
-Node: VMS Running1162227
-Node: VMS GNV1166506
-Node: VMS Old Gawk1167241
-Node: Bugs1167712
-Node: Bug address1168375
-Node: Usenet1170772
-Node: Maintainers1171547
-Node: Other Versions1172923
-Node: Installation summary1179507
-Node: Notes1180542
-Node: Compatibility Mode1181407
-Node: Additions1182189
-Node: Accessing The Source1183114
-Node: Adding Code1184549
-Node: New Ports1190768
-Node: Derived Files1195256
-Ref: Derived Files-Footnote-11200741
-Ref: Derived Files-Footnote-21200776
-Ref: Derived Files-Footnote-31201374
-Node: Future Extensions1201488
-Node: Implementation Limitations1202146
-Node: Extension Design1203329
-Node: Old Extension Problems1204483
-Ref: Old Extension Problems-Footnote-11206001
-Node: Extension New Mechanism Goals1206058
-Ref: Extension New Mechanism Goals-Footnote-11209422
-Node: Extension Other Design Decisions1209611
-Node: Extension Future Growth1211724
-Node: Old Extension Mechanism1212560
-Node: Notes summary1214323
-Node: Basic Concepts1215505
-Node: Basic High Level1216186
-Ref: figure-general-flow1216468
-Ref: figure-process-flow1217153
-Ref: Basic High Level-Footnote-11220454
-Node: Basic Data Typing1220639
-Node: Glossary1223967
-Node: Copying1255914
-Node: GNU Free Documentation License1293453
-Node: Index1318571
+Ref: General Data Types-Footnote-1964235
+Node: Memory Allocation Functions964534
+Ref: Memory Allocation Functions-Footnote-1967379
+Node: Constructor Functions967478
+Node: Registration Functions970477
+Node: Extension Functions971162
+Node: Exit Callback Functions976360
+Node: Extension Version String977610
+Node: Input Parsers978273
+Node: Output Wrappers988155
+Node: Two-way processors992667
+Node: Printing Messages994932
+Ref: Printing Messages-Footnote-1996103
+Node: Updating ERRNO996256
+Node: Requesting Values996995
+Ref: table-value-types-returned997732
+Node: Accessing Parameters998615
+Node: Symbol Table Access999850
+Node: Symbol table by name1000362
+Node: Symbol table by cookie1002151
+Ref: Symbol table by cookie-Footnote-11006336
+Node: Cached values1006400
+Ref: Cached values-Footnote-11009936
+Node: Array Manipulation1010027
+Ref: Array Manipulation-Footnote-11011118
+Node: Array Data Types1011155
+Ref: Array Data Types-Footnote-11013813
+Node: Array Functions1013905
+Node: Flattening Arrays1018300
+Node: Creating Arrays1025241
+Node: Redirection API1030010
+Node: Extension API Variables1032841
+Node: Extension Versioning1033474
+Ref: gawk-api-version1033911
+Node: Extension API Informational Variables1035639
+Node: Extension API Boilerplate1036703
+Node: Changes from API V11040565
+Node: Finding Extensions1041225
+Node: Extension Example1041784
+Node: Internal File Description1042582
+Node: Internal File Ops1046662
+Ref: Internal File Ops-Footnote-11058062
+Node: Using Internal File Ops1058202
+Ref: Using Internal File Ops-Footnote-11060585
+Node: Extension Samples1060859
+Node: Extension Sample File Functions1062388
+Node: Extension Sample Fnmatch1070037
+Node: Extension Sample Fork1071524
+Node: Extension Sample Inplace1072742
+Node: Extension Sample Ord1075952
+Node: Extension Sample Readdir1076788
+Ref: table-readdir-file-types1077677
+Node: Extension Sample Revout1078482
+Node: Extension Sample Rev2way1079071
+Node: Extension Sample Read write array1079811
+Node: Extension Sample Readfile1081753
+Node: Extension Sample Time1082848
+Node: Extension Sample API Tests1084196
+Node: gawkextlib1084688
+Node: Extension summary1087135
+Node: Extension Exercises1090837
+Node: Language History1092335
+Node: V7/SVR3.11093991
+Node: SVR41096143
+Node: POSIX1097577
+Node: BTL1098956
+Node: POSIX/GNU1099685
+Node: Feature History1105547
+Node: Common Extensions1119917
+Node: Ranges and Locales1121200
+Ref: Ranges and Locales-Footnote-11125816
+Ref: Ranges and Locales-Footnote-21125843
+Ref: Ranges and Locales-Footnote-31126078
+Node: Contributors1126299
+Node: History summary1131859
+Node: Installation1133239
+Node: Gawk Distribution1134183
+Node: Getting1134667
+Node: Extracting1135628
+Node: Distribution contents1137266
+Node: Unix Installation1143608
+Node: Quick Installation1144290
+Node: Shell Startup Files1146704
+Node: Additional Configuration Options1147782
+Node: Configuration Philosophy1149587
+Node: Non-Unix Installation1151956
+Node: PC Installation1152416
+Node: PC Binary Installation1153254
+Node: PC Compiling1153689
+Node: PC Using1154806
+Node: Cygwin1157851
+Node: MSYS1158621
+Node: VMS Installation1159122
+Node: VMS Compilation1159913
+Ref: VMS Compilation-Footnote-11161142
+Node: VMS Dynamic Extensions1161200
+Node: VMS Installation Details1162885
+Node: VMS Running1165138
+Node: VMS GNV1169417
+Node: VMS Old Gawk1170152
+Node: Bugs1170623
+Node: Bug address1171286
+Node: Usenet1173683
+Node: Maintainers1174458
+Node: Other Versions1175834
+Node: Installation summary1182418
+Node: Notes1183453
+Node: Compatibility Mode1184318
+Node: Additions1185100
+Node: Accessing The Source1186025
+Node: Adding Code1187460
+Node: New Ports1193679
+Node: Derived Files1198167
+Ref: Derived Files-Footnote-11203652
+Ref: Derived Files-Footnote-21203687
+Ref: Derived Files-Footnote-31204285
+Node: Future Extensions1204399
+Node: Implementation Limitations1205057
+Node: Extension Design1206240
+Node: Old Extension Problems1207394
+Ref: Old Extension Problems-Footnote-11208912
+Node: Extension New Mechanism Goals1208969
+Ref: Extension New Mechanism Goals-Footnote-11212333
+Node: Extension Other Design Decisions1212522
+Node: Extension Future Growth1214635
+Node: Old Extension Mechanism1215471
+Node: Notes summary1217234
+Node: Basic Concepts1218416
+Node: Basic High Level1219097
+Ref: figure-general-flow1219379
+Ref: figure-process-flow1220064
+Ref: Basic High Level-Footnote-11223365
+Node: Basic Data Typing1223550
+Node: Glossary1226878
+Node: Copying1258825
+Node: GNU Free Documentation License1296364
+Node: Index1321482

End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 4998f81e..2a7f1c58 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -32557,6 +32557,8 @@ multibyte encoding.
@itemx @ @ @ @ AWK_UNDEFINED,
@itemx @ @ @ @ AWK_NUMBER,
@itemx @ @ @ @ AWK_STRING,
+@itemx @ @ @ @ AWK_REGEX,
+@itemx @ @ @ @ AWK_STRNUM,
@itemx @ @ @ @ AWK_ARRAY,
@itemx @ @ @ @ AWK_SCALAR,@ @ @ @ @ @ @ @ @ /* opaque access to a variable */
@itemx @ @ @ @ AWK_VALUE_COOKIE@ @ @ @ /* for updating a previously created value */
@@ -32579,6 +32581,8 @@ The @code{val_type} member indicates what kind of value the
@code{union} holds, and each member is of the appropriate type.
@item #define str_value@ @ @ @ @ @ u.s
+@itemx #define strnum_value@ @ @ @ str_value
+@itemx #define regex_value@ @ @ @ str_value
@itemx #define num_value@ @ @ @ @ @ u.d
@itemx #define array_cookie@ @ @ u.a
@itemx #define scalar_cookie@ @ u.scl
@@ -32599,7 +32603,7 @@ and in more detail in @ref{Cached values}.
@end table
-Scalar values in @command{awk} are either numbers or strings. The
+Scalar values in @command{awk} are numbers, strings, strnums, or typed regexps. The
@code{awk_value_t} struct represents values. The @code{val_type} member
indicates what is in the @code{union}.
@@ -32608,6 +32612,18 @@ require more work. Because @command{gawk} allows embedded @sc{nul} bytes
in string values, a string must be represented as a pair containing a
data pointer and length. This is the @code{awk_string_t} type.
+A strnum (numeric string) value is represented as a string and consists
+of user input data that appears to be numeric.
+When an extension creates a strnum value, the result is a string flagged
+as user input. Subsequent parsing by @command{gawk} then determines whether it
+looks like a number and should be treated as a strnum, or as a regular string.
+
+Typed regexp values (@pxref{Strong Regexp Constants}) are not of
+much use to extension functions. Extension functions can tell that
+they've received them, and create them for scalar values. Otherwise,
+they can examine the text of the regexp through @code{regex_value.str}
+and @code{regex_value.len}.
+
Identifiers (i.e., the names of global variables) can be associated
with either scalar values or with arrays. In addition, @command{gawk}
provides true arrays of arrays, where any given array element can
@@ -32774,6 +32790,31 @@ It returns @code{result}.
@itemx make_number(double num, awk_value_t *result);
This function simply creates a numeric value in the @code{awk_value_t} variable
pointed to by @code{result}.
+
+@item static inline awk_value_t *
+@itemx make_const_user_input(const char *string, size_t length, awk_value_t *result);
+This function is identical to @code{make_const_string()}, but the string is
+flagged as user input that should be treated as a strnum value if the contents
+of the string are numeric.
+
+@item static inline awk_value_t *
+@itemx make_malloced_user_input(const char *string, size_t length, awk_value_t *result);
+This function is identical to @code{make_malloced_string()}, but the string is
+flagged as user input that should be treated as a strnum value if the contents
+of the string are numeric.
+
+@item static inline awk_value_t *
+@itemx make_const_regex(const char *string, size_t length, awk_value_t *result);
+This function creates a strongly typed regexp value by allocating a copy of the string.
+@code{string} is the regular expression of length @code{len}.
+
+@item static inline awk_value_t *
+@itemx make_malloced_regex(const char *string, size_t length, awk_value_t *result);
+This function creates a strongly typed regexp value.
+@code{string} is the regular expression of length @code{len}.
+It expects @code{string} to be a @samp{char *}
+value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}.
+
@end table
@node Registration Functions
@@ -33458,6 +33499,7 @@ value type, as appropriate. This behavior is summarized in
@float Table,table-value-types-returned
@caption{API value types returned}
+@c FIXME: This needs doing.
@docbook
<informaltable>
<tgroup cols="6">
@@ -33533,6 +33575,7 @@ value type, as appropriate. This behavior is summarized in
</informaltable>
@end docbook
+@c FIXME: This needs doing.
@ifnotplaintext
@ifnotdocbook
@multitable @columnfractions .50 .50
@@ -33555,27 +33598,28 @@ value type, as appropriate. This behavior is summarized in
@end ifnotplaintext
@ifplaintext
@example
- +-------------------------------------------------+
- | Type of Actual Value: |
- +------------+------------+-----------+-----------+
- | String | Number | Array | Undefined |
-+-----------+-----------+------------+------------+-----------+-----------+
-| | String | String | String | False | False |
-| |-----------+------------+------------+-----------+-----------+
-| | Number | Number if | Number | False | False |
-| | | can be | | | |
-| | | converted, | | | |
-| | | else false | | | |
-| |-----------+------------+------------+-----------+-----------+
-| Type | Array | False | False | Array | False |
-| Requested |-----------+------------+------------+-----------+-----------+
-| | Scalar | Scalar | Scalar | False | False |
-| |-----------+------------+------------+-----------+-----------+
-| | Undefined | String | Number | Array | Undefined |
-| |-----------+------------+------------+-----------+-----------+
-| | Value | False | False | False | False |
-| | cookie | | | | |
-+-----------+-----------+------------+------------+-----------+-----------+
+ +-------------------------------------------------------+
+ | Type of Actual Value: |
+ +--------+--------+--------+--------+-------+-----------+
+ | String | Strnum | Number | Regex | Array | Undefined |
++-----------+-----------+--------+--------+--------+--------+-------+-----------+
+| | String | String | String | String | String | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Strnum | false | Strnum | Strnum | false | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Number | Number | Number | Number | false | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Regex | false | false | false | Regex | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| Type | Array | false | false | false | false | Array | false |
+| Requested +-----------+--------+--------+--------+--------+-------+-----------+
+| | Scalar | Scalar | Scalar | Scalar | Scalar | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Undefined | String | Strnum | Number | Regex | Array | Undefined |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Value | false | false | false | false | false | false |
+| | Cookie | | | | | | |
++-----------+-----------+--------+--------+--------+--------+-------+-----------+
@end example
@end ifplaintext
@end float
@@ -33675,7 +33719,7 @@ Return false if the value cannot be retrieved.
@item awk_bool_t sym_update_scalar(awk_scalar_t cookie, awk_value_t *value);
Update the value associated with a scalar cookie. Return false if
-the new value is not of type @code{AWK_STRING} or @code{AWK_NUMBER}.
+the new value is not of type @code{AWK_STRING}, @code{AWK_STRNUM}, @code{AWK_REGEX}, or @code{AWK_NUMBER}.
Here too, the predefined variables may not be updated.
@end table
@@ -33796,7 +33840,7 @@ is what the routines in this @value{SECTION} let you do. The functions are as f
@table @code
@item awk_bool_t create_value(awk_value_t *value, awk_value_cookie_t *result);
Create a cached string or numeric value from @code{value} for
-efficient later assignment. Only values of type @code{AWK_NUMBER}
+efficient later assignment. Only values of type @code{AWK_NUMBER}, @code{AWK_REGEX}, @code{AWK_STRNUM},
and @code{AWK_STRING} are allowed. Any other type is rejected.
@code{AWK_UNDEFINED} could be allowed, but doing so would result in
inferior performance.
@@ -34022,9 +34066,10 @@ The array remains an array, but after calling this function, it
has no elements. This is equivalent to using the @code{delete}
statement (@pxref{Delete}).
-@item awk_bool_t flatten_array(awk_array_t a_cookie, awk_flat_array_t **data);
+@item awk_bool_t flatten_array_typed(awk_array_t a_cookie, awk_flat_array_t **data, awk_valtype_t index_type, awk_valtype_t value_type);
For the array represented by @code{a_cookie}, create an @code{awk_flat_array_t}
-structure and fill it in. Set the pointer whose address is passed as @code{data}
+structure and fill it in with indices and values of the requested types.
+Set the pointer whose address is passed as @code{data}
to point to this structure.
Return true upon success, or false otherwise.
@ifset FOR_PRINT
@@ -34036,6 +34081,14 @@ See the next @value{SECTION}
for a discussion of how to
flatten an array and work with it.
+@item awk_bool_t flatten_array(awk_array_t a_cookie, awk_flat_array_t **data);
+For the array represented by @code{a_cookie}, create an @code{awk_flat_array_t}
+structure and fill it in with @code{AWK_STRING} indices and
+@code{AWK_UNDEFINED} values.
+This is superseded by @code{flatten_array_typed()}.
+It is provided as a macro, and remains convenience and for source code
+compatibility with the previous version of the API.
+
@item awk_bool_t release_flattened_array(awk_array_t a_cookie,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_flat_array_t *data);
When done with a flattened array, release the storage using this function.
@@ -34148,7 +34201,7 @@ to double-check that the count in the @code{awk_flat_array_t}
is the same as the count just retrieved:
@example
- if (! flatten_array(value2.array_cookie, & flat_array)) @{
+ if (! flatten_array_typed(value2.array_cookie, & flat_array, AWK_STRING, AWK_UNDEFINED)) @{
printf("dump_array_and_delete: could not flatten array\n");
goto out;
@}
@@ -34540,7 +34593,7 @@ debugging:
@float Table,gawk-api-version
@caption{gawk API version constants}
@multitable {@b{API Version}} {@code{gawk_api_major_version}} {@code{GAWK_API_MAJOR_VERSION}}
-@headitem API Version @tab C preprocessor define @tab enum constant
+@headitem API Version @tab C Preprocessor Define @tab enum constant
@item Major @tab @code{gawk_api_major_version} @tab @code{GAWK_API_MAJOR_VERSION}
@item Minor @tab @code{gawk_api_minor_version} @tab @code{GAWK_API_MINOR_VERSION}
@end multitable
@@ -38196,6 +38249,12 @@ These files contain the actual @command{gawk} source code.
@end table
@table @file
+@item support/*
+C header and source files for routines that @command{gawk}
+uses, but that are not part of its core functionality.
+For example, argument parsing, regular expression matching,
+and random number generating routines are all kept here.
+
@item ABOUT-NLS
A file containing information about GNU @command{gettext} and translations.
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index ca571514..c8c66d2d 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -31571,6 +31571,8 @@ multibyte encoding.
@itemx @ @ @ @ AWK_UNDEFINED,
@itemx @ @ @ @ AWK_NUMBER,
@itemx @ @ @ @ AWK_STRING,
+@itemx @ @ @ @ AWK_REGEX,
+@itemx @ @ @ @ AWK_STRNUM,
@itemx @ @ @ @ AWK_ARRAY,
@itemx @ @ @ @ AWK_SCALAR,@ @ @ @ @ @ @ @ @ /* opaque access to a variable */
@itemx @ @ @ @ AWK_VALUE_COOKIE@ @ @ @ /* for updating a previously created value */
@@ -31593,6 +31595,8 @@ The @code{val_type} member indicates what kind of value the
@code{union} holds, and each member is of the appropriate type.
@item #define str_value@ @ @ @ @ @ u.s
+@itemx #define strnum_value@ @ @ @ str_value
+@itemx #define regex_value@ @ @ @ str_value
@itemx #define num_value@ @ @ @ @ @ u.d
@itemx #define array_cookie@ @ @ u.a
@itemx #define scalar_cookie@ @ u.scl
@@ -31613,7 +31617,7 @@ and in more detail in @ref{Cached values}.
@end table
-Scalar values in @command{awk} are either numbers or strings. The
+Scalar values in @command{awk} are numbers, strings, strnums, or typed regexps. The
@code{awk_value_t} struct represents values. The @code{val_type} member
indicates what is in the @code{union}.
@@ -31622,6 +31626,18 @@ require more work. Because @command{gawk} allows embedded @sc{nul} bytes
in string values, a string must be represented as a pair containing a
data pointer and length. This is the @code{awk_string_t} type.
+A strnum (numeric string) value is represented as a string and consists
+of user input data that appears to be numeric.
+When an extension creates a strnum value, the result is a string flagged
+as user input. Subsequent parsing by @command{gawk} then determines whether it
+looks like a number and should be treated as a strnum, or as a regular string.
+
+Typed regexp values (@pxref{Strong Regexp Constants}) are not of
+much use to extension functions. Extension functions can tell that
+they've received them, and create them for scalar values. Otherwise,
+they can examine the text of the regexp through @code{regex_value.str}
+and @code{regex_value.len}.
+
Identifiers (i.e., the names of global variables) can be associated
with either scalar values or with arrays. In addition, @command{gawk}
provides true arrays of arrays, where any given array element can
@@ -31788,6 +31804,31 @@ It returns @code{result}.
@itemx make_number(double num, awk_value_t *result);
This function simply creates a numeric value in the @code{awk_value_t} variable
pointed to by @code{result}.
+
+@item static inline awk_value_t *
+@itemx make_const_user_input(const char *string, size_t length, awk_value_t *result);
+This function is identical to @code{make_const_string()}, but the string is
+flagged as user input that should be treated as a strnum value if the contents
+of the string are numeric.
+
+@item static inline awk_value_t *
+@itemx make_malloced_user_input(const char *string, size_t length, awk_value_t *result);
+This function is identical to @code{make_malloced_string()}, but the string is
+flagged as user input that should be treated as a strnum value if the contents
+of the string are numeric.
+
+@item static inline awk_value_t *
+@itemx make_const_regex(const char *string, size_t length, awk_value_t *result);
+This function creates a strongly typed regexp value by allocating a copy of the string.
+@code{string} is the regular expression of length @code{len}.
+
+@item static inline awk_value_t *
+@itemx make_malloced_regex(const char *string, size_t length, awk_value_t *result);
+This function creates a strongly typed regexp value.
+@code{string} is the regular expression of length @code{len}.
+It expects @code{string} to be a @samp{char *}
+value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}.
+
@end table
@node Registration Functions
@@ -32472,6 +32513,7 @@ value type, as appropriate. This behavior is summarized in
@float Table,table-value-types-returned
@caption{API value types returned}
+@c FIXME: This needs doing.
@docbook
<informaltable>
<tgroup cols="6">
@@ -32547,6 +32589,7 @@ value type, as appropriate. This behavior is summarized in
</informaltable>
@end docbook
+@c FIXME: This needs doing.
@ifnotplaintext
@ifnotdocbook
@multitable @columnfractions .50 .50
@@ -32569,27 +32612,28 @@ value type, as appropriate. This behavior is summarized in
@end ifnotplaintext
@ifplaintext
@example
- +-------------------------------------------------+
- | Type of Actual Value: |
- +------------+------------+-----------+-----------+
- | String | Number | Array | Undefined |
-+-----------+-----------+------------+------------+-----------+-----------+
-| | String | String | String | False | False |
-| |-----------+------------+------------+-----------+-----------+
-| | Number | Number if | Number | False | False |
-| | | can be | | | |
-| | | converted, | | | |
-| | | else false | | | |
-| |-----------+------------+------------+-----------+-----------+
-| Type | Array | False | False | Array | False |
-| Requested |-----------+------------+------------+-----------+-----------+
-| | Scalar | Scalar | Scalar | False | False |
-| |-----------+------------+------------+-----------+-----------+
-| | Undefined | String | Number | Array | Undefined |
-| |-----------+------------+------------+-----------+-----------+
-| | Value | False | False | False | False |
-| | cookie | | | | |
-+-----------+-----------+------------+------------+-----------+-----------+
+ +-------------------------------------------------------+
+ | Type of Actual Value: |
+ +--------+--------+--------+--------+-------+-----------+
+ | String | Strnum | Number | Regex | Array | Undefined |
++-----------+-----------+--------+--------+--------+--------+-------+-----------+
+| | String | String | String | String | String | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Strnum | false | Strnum | Strnum | false | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Number | Number | Number | Number | false | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Regex | false | false | false | Regex | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| Type | Array | false | false | false | false | Array | false |
+| Requested +-----------+--------+--------+--------+--------+-------+-----------+
+| | Scalar | Scalar | Scalar | Scalar | Scalar | false | false |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Undefined | String | Strnum | Number | Regex | Array | Undefined |
+| +-----------+--------+--------+--------+--------+-------+-----------+
+| | Value | false | false | false | false | false | false |
+| | Cookie | | | | | | |
++-----------+-----------+--------+--------+--------+--------+-------+-----------+
@end example
@end ifplaintext
@end float
@@ -32689,7 +32733,7 @@ Return false if the value cannot be retrieved.
@item awk_bool_t sym_update_scalar(awk_scalar_t cookie, awk_value_t *value);
Update the value associated with a scalar cookie. Return false if
-the new value is not of type @code{AWK_STRING} or @code{AWK_NUMBER}.
+the new value is not of type @code{AWK_STRING}, @code{AWK_STRNUM}, @code{AWK_REGEX}, or @code{AWK_NUMBER}.
Here too, the predefined variables may not be updated.
@end table
@@ -32810,7 +32854,7 @@ is what the routines in this @value{SECTION} let you do. The functions are as f
@table @code
@item awk_bool_t create_value(awk_value_t *value, awk_value_cookie_t *result);
Create a cached string or numeric value from @code{value} for
-efficient later assignment. Only values of type @code{AWK_NUMBER}
+efficient later assignment. Only values of type @code{AWK_NUMBER}, @code{AWK_REGEX}, @code{AWK_STRNUM},
and @code{AWK_STRING} are allowed. Any other type is rejected.
@code{AWK_UNDEFINED} could be allowed, but doing so would result in
inferior performance.
@@ -33036,9 +33080,10 @@ The array remains an array, but after calling this function, it
has no elements. This is equivalent to using the @code{delete}
statement (@pxref{Delete}).
-@item awk_bool_t flatten_array(awk_array_t a_cookie, awk_flat_array_t **data);
+@item awk_bool_t flatten_array_typed(awk_array_t a_cookie, awk_flat_array_t **data, awk_valtype_t index_type, awk_valtype_t value_type);
For the array represented by @code{a_cookie}, create an @code{awk_flat_array_t}
-structure and fill it in. Set the pointer whose address is passed as @code{data}
+structure and fill it in with indices and values of the requested types.
+Set the pointer whose address is passed as @code{data}
to point to this structure.
Return true upon success, or false otherwise.
@ifset FOR_PRINT
@@ -33050,6 +33095,14 @@ See the next @value{SECTION}
for a discussion of how to
flatten an array and work with it.
+@item awk_bool_t flatten_array(awk_array_t a_cookie, awk_flat_array_t **data);
+For the array represented by @code{a_cookie}, create an @code{awk_flat_array_t}
+structure and fill it in with @code{AWK_STRING} indices and
+@code{AWK_UNDEFINED} values.
+This is superseded by @code{flatten_array_typed()}.
+It is provided as a macro, and remains convenience and for source code
+compatibility with the previous version of the API.
+
@item awk_bool_t release_flattened_array(awk_array_t a_cookie,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_flat_array_t *data);
When done with a flattened array, release the storage using this function.
@@ -33162,7 +33215,7 @@ to double-check that the count in the @code{awk_flat_array_t}
is the same as the count just retrieved:
@example
- if (! flatten_array(value2.array_cookie, & flat_array)) @{
+ if (! flatten_array_typed(value2.array_cookie, & flat_array, AWK_STRING, AWK_UNDEFINED)) @{
printf("dump_array_and_delete: could not flatten array\n");
goto out;
@}
@@ -33554,7 +33607,7 @@ debugging:
@float Table,gawk-api-version
@caption{gawk API version constants}
@multitable {@b{API Version}} {@code{gawk_api_major_version}} {@code{GAWK_API_MAJOR_VERSION}}
-@headitem API Version @tab C preprocessor define @tab enum constant
+@headitem API Version @tab C Preprocessor Define @tab enum constant
@item Major @tab @code{gawk_api_major_version} @tab @code{GAWK_API_MAJOR_VERSION}
@item Minor @tab @code{gawk_api_minor_version} @tab @code{GAWK_API_MINOR_VERSION}
@end multitable
@@ -37210,6 +37263,12 @@ These files contain the actual @command{gawk} source code.
@end table
@table @file
+@item support/*
+C header and source files for routines that @command{gawk}
+uses, but that are not part of its core functionality.
+For example, argument parsing, regular expression matching,
+and random number generating routines are all kept here.
+
@item ABOUT-NLS
A file containing information about GNU @command{gettext} and translations.
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-06 20:18:37 +0000