diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 5 | ||||
| -rw-r--r-- | doc/gawk.info | 282 | ||||
| -rw-r--r-- | doc/gawk.texi | 8 | ||||
| -rw-r--r-- | doc/gawktexi.in | 8 |
4 files changed, 166 insertions, 137 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 879be20a..7bebbd1e 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2016-12-05 Andrew J. Schorr <aschorr@telemetry-investments.com> + + * gawktexi.in: Explain why an API extension function might want + to use the AWK_STRNUM type to return data. + 2016-12-23 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Update API table of type requested / type returned. diff --git a/doc/gawk.info b/doc/gawk.info index dd920c6d..ee2b5f13 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -23684,6 +23684,14 @@ 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. + This is useful in cases where an extension function would like to do +something comparable to the 'split()' function which sets the user input +attribute on the array elements it creates. For example, an extension +that implements CSV splitting would want to use this feature. This is +also useful for a function that retrieves a data item from a database. +The PostgreSQL 'PQgetvalue()' function, for example, returns a string +that may be numeric or textual depending on the contents. + 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 @@ -35862,142 +35870,142 @@ Ref: figure-call-new-function948497 Node: Extension API Description950559 Node: Extension API Functions Introduction952201 Node: General Data Types957512 -Ref: General Data Types-Footnote-1964234 -Node: Memory Allocation Functions964533 -Ref: Memory Allocation Functions-Footnote-1967378 -Node: Constructor Functions967477 -Node: Registration Functions970476 -Node: Extension Functions971161 -Node: Exit Callback Functions976359 -Node: Extension Version String977609 -Node: Input Parsers978272 -Node: Output Wrappers988154 -Node: Two-way processors992666 -Node: Printing Messages994931 -Ref: Printing Messages-Footnote-1996102 -Node: Updating ERRNO996255 -Node: Requesting Values996994 -Ref: table-value-types-returned997731 -Node: Accessing Parameters998667 -Node: Symbol Table Access999902 -Node: Symbol table by name1000414 -Node: Symbol table by cookie1002203 -Ref: Symbol table by cookie-Footnote-11006388 -Node: Cached values1006452 -Ref: Cached values-Footnote-11009988 -Node: Array Manipulation1010079 -Ref: Array Manipulation-Footnote-11011170 -Node: Array Data Types1011207 -Ref: Array Data Types-Footnote-11013865 -Node: Array Functions1013957 -Node: Flattening Arrays1018352 -Node: Creating Arrays1025293 -Node: Redirection API1030062 -Node: Extension API Variables1032893 -Node: Extension Versioning1033526 -Ref: gawk-api-version1033963 -Node: Extension API Informational Variables1035691 -Node: Extension API Boilerplate1036755 -Node: Changes from API V11040617 -Node: Finding Extensions1041277 -Node: Extension Example1041836 -Node: Internal File Description1042634 -Node: Internal File Ops1046714 -Ref: Internal File Ops-Footnote-11058114 -Node: Using Internal File Ops1058254 -Ref: Using Internal File Ops-Footnote-11060637 -Node: Extension Samples1060911 -Node: Extension Sample File Functions1062440 -Node: Extension Sample Fnmatch1070089 -Node: Extension Sample Fork1071576 -Node: Extension Sample Inplace1072794 -Node: Extension Sample Ord1076004 -Node: Extension Sample Readdir1076840 -Ref: table-readdir-file-types1077729 -Node: Extension Sample Revout1078534 -Node: Extension Sample Rev2way1079123 -Node: Extension Sample Read write array1079863 -Node: Extension Sample Readfile1081805 -Node: Extension Sample Time1082900 -Node: Extension Sample API Tests1084248 -Node: gawkextlib1084740 -Node: Extension summary1087187 -Node: Extension Exercises1090889 -Node: Language History1092387 -Node: V7/SVR3.11094043 -Node: SVR41096195 -Node: POSIX1097629 -Node: BTL1099008 -Node: POSIX/GNU1099737 -Node: Feature History1105599 -Node: Common Extensions1119969 -Node: Ranges and Locales1121252 -Ref: Ranges and Locales-Footnote-11125868 -Ref: Ranges and Locales-Footnote-21125895 -Ref: Ranges and Locales-Footnote-31126130 -Node: Contributors1126351 -Node: History summary1131911 -Node: Installation1133291 -Node: Gawk Distribution1134235 -Node: Getting1134719 -Node: Extracting1135680 -Node: Distribution contents1137318 -Node: Unix Installation1143660 -Node: Quick Installation1144342 -Node: Shell Startup Files1146756 -Node: Additional Configuration Options1147834 -Node: Configuration Philosophy1149639 -Node: Non-Unix Installation1152008 -Node: PC Installation1152468 -Node: PC Binary Installation1153306 -Node: PC Compiling1153741 -Node: PC Using1154858 -Node: Cygwin1157903 -Node: MSYS1158673 -Node: VMS Installation1159174 -Node: VMS Compilation1159965 -Ref: VMS Compilation-Footnote-11161194 -Node: VMS Dynamic Extensions1161252 -Node: VMS Installation Details1162937 -Node: VMS Running1165190 -Node: VMS GNV1169469 -Node: VMS Old Gawk1170204 -Node: Bugs1170675 -Node: Bug address1171338 -Node: Usenet1173735 -Node: Maintainers1174510 -Node: Other Versions1175886 -Node: Installation summary1182470 -Node: Notes1183505 -Node: Compatibility Mode1184370 -Node: Additions1185152 -Node: Accessing The Source1186077 -Node: Adding Code1187512 -Node: New Ports1193731 -Node: Derived Files1198219 -Ref: Derived Files-Footnote-11203704 -Ref: Derived Files-Footnote-21203739 -Ref: Derived Files-Footnote-31204337 -Node: Future Extensions1204451 -Node: Implementation Limitations1205109 -Node: Extension Design1206292 -Node: Old Extension Problems1207446 -Ref: Old Extension Problems-Footnote-11208964 -Node: Extension New Mechanism Goals1209021 -Ref: Extension New Mechanism Goals-Footnote-11212385 -Node: Extension Other Design Decisions1212574 -Node: Extension Future Growth1214687 -Node: Old Extension Mechanism1215523 -Node: Notes summary1217286 -Node: Basic Concepts1218468 -Node: Basic High Level1219149 -Ref: figure-general-flow1219431 -Ref: figure-process-flow1220116 -Ref: Basic High Level-Footnote-11223417 -Node: Basic Data Typing1223602 -Node: Glossary1226930 -Node: Copying1258877 -Node: GNU Free Documentation License1296416 -Node: Index1321534 +Ref: General Data Types-Footnote-1964721 +Node: Memory Allocation Functions965020 +Ref: Memory Allocation Functions-Footnote-1967865 +Node: Constructor Functions967964 +Node: Registration Functions970963 +Node: Extension Functions971648 +Node: Exit Callback Functions976846 +Node: Extension Version String978096 +Node: Input Parsers978759 +Node: Output Wrappers988641 +Node: Two-way processors993153 +Node: Printing Messages995418 +Ref: Printing Messages-Footnote-1996589 +Node: Updating ERRNO996742 +Node: Requesting Values997481 +Ref: table-value-types-returned998218 +Node: Accessing Parameters999154 +Node: Symbol Table Access1000389 +Node: Symbol table by name1000901 +Node: Symbol table by cookie1002690 +Ref: Symbol table by cookie-Footnote-11006875 +Node: Cached values1006939 +Ref: Cached values-Footnote-11010475 +Node: Array Manipulation1010566 +Ref: Array Manipulation-Footnote-11011657 +Node: Array Data Types1011694 +Ref: Array Data Types-Footnote-11014352 +Node: Array Functions1014444 +Node: Flattening Arrays1018839 +Node: Creating Arrays1025780 +Node: Redirection API1030549 +Node: Extension API Variables1033380 +Node: Extension Versioning1034013 +Ref: gawk-api-version1034450 +Node: Extension API Informational Variables1036178 +Node: Extension API Boilerplate1037242 +Node: Changes from API V11041104 +Node: Finding Extensions1041764 +Node: Extension Example1042323 +Node: Internal File Description1043121 +Node: Internal File Ops1047201 +Ref: Internal File Ops-Footnote-11058601 +Node: Using Internal File Ops1058741 +Ref: Using Internal File Ops-Footnote-11061124 +Node: Extension Samples1061398 +Node: Extension Sample File Functions1062927 +Node: Extension Sample Fnmatch1070576 +Node: Extension Sample Fork1072063 +Node: Extension Sample Inplace1073281 +Node: Extension Sample Ord1076491 +Node: Extension Sample Readdir1077327 +Ref: table-readdir-file-types1078216 +Node: Extension Sample Revout1079021 +Node: Extension Sample Rev2way1079610 +Node: Extension Sample Read write array1080350 +Node: Extension Sample Readfile1082292 +Node: Extension Sample Time1083387 +Node: Extension Sample API Tests1084735 +Node: gawkextlib1085227 +Node: Extension summary1087674 +Node: Extension Exercises1091376 +Node: Language History1092874 +Node: V7/SVR3.11094530 +Node: SVR41096682 +Node: POSIX1098116 +Node: BTL1099495 +Node: POSIX/GNU1100224 +Node: Feature History1106086 +Node: Common Extensions1120456 +Node: Ranges and Locales1121739 +Ref: Ranges and Locales-Footnote-11126355 +Ref: Ranges and Locales-Footnote-21126382 +Ref: Ranges and Locales-Footnote-31126617 +Node: Contributors1126838 +Node: History summary1132398 +Node: Installation1133778 +Node: Gawk Distribution1134722 +Node: Getting1135206 +Node: Extracting1136167 +Node: Distribution contents1137805 +Node: Unix Installation1144147 +Node: Quick Installation1144829 +Node: Shell Startup Files1147243 +Node: Additional Configuration Options1148321 +Node: Configuration Philosophy1150126 +Node: Non-Unix Installation1152495 +Node: PC Installation1152955 +Node: PC Binary Installation1153793 +Node: PC Compiling1154228 +Node: PC Using1155345 +Node: Cygwin1158390 +Node: MSYS1159160 +Node: VMS Installation1159661 +Node: VMS Compilation1160452 +Ref: VMS Compilation-Footnote-11161681 +Node: VMS Dynamic Extensions1161739 +Node: VMS Installation Details1163424 +Node: VMS Running1165677 +Node: VMS GNV1169956 +Node: VMS Old Gawk1170691 +Node: Bugs1171162 +Node: Bug address1171825 +Node: Usenet1174222 +Node: Maintainers1174997 +Node: Other Versions1176373 +Node: Installation summary1182957 +Node: Notes1183992 +Node: Compatibility Mode1184857 +Node: Additions1185639 +Node: Accessing The Source1186564 +Node: Adding Code1187999 +Node: New Ports1194218 +Node: Derived Files1198706 +Ref: Derived Files-Footnote-11204191 +Ref: Derived Files-Footnote-21204226 +Ref: Derived Files-Footnote-31204824 +Node: Future Extensions1204938 +Node: Implementation Limitations1205596 +Node: Extension Design1206779 +Node: Old Extension Problems1207933 +Ref: Old Extension Problems-Footnote-11209451 +Node: Extension New Mechanism Goals1209508 +Ref: Extension New Mechanism Goals-Footnote-11212872 +Node: Extension Other Design Decisions1213061 +Node: Extension Future Growth1215174 +Node: Old Extension Mechanism1216010 +Node: Notes summary1217773 +Node: Basic Concepts1218955 +Node: Basic High Level1219636 +Ref: figure-general-flow1219918 +Ref: figure-process-flow1220603 +Ref: Basic High Level-Footnote-11223904 +Node: Basic Data Typing1224089 +Node: Glossary1227417 +Node: Copying1259364 +Node: GNU Free Documentation License1296903 +Node: Index1322021 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 25468301..e78134cb 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -32618,6 +32618,14 @@ 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. +This is useful in cases where an extension function would like to do something +comparable to the @code{split()} function which sets the user input attribute +on the array elements it creates. For example, an extension that implements +CSV splitting would want to use this feature. This is also useful for a +function that retrieves a data item from a database. The PostgreSQL +@code{PQgetvalue()} function, for example, returns a string that may be numeric +or textual depending on the contents. + 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, diff --git a/doc/gawktexi.in b/doc/gawktexi.in index d8f10f76..9967c5a2 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -31632,6 +31632,14 @@ 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. +This is useful in cases where an extension function would like to do something +comparable to the @code{split()} function which sets the user input attribute +on the array elements it creates. For example, an extension that implements +CSV splitting would want to use this feature. This is also useful for a +function that retrieves a data item from a database. The PostgreSQL +@code{PQgetvalue()} function, for example, returns a string that may be numeric +or textual depending on the contents. + 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, |