diff options
Diffstat (limited to 'doc/gawk.info')
| -rw-r--r-- | doc/gawk.info | 365 |
1 files changed, 211 insertions, 154 deletions
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 |