Fix lint stuff, arg checking. Add a data pointer. Pass finfo to functions.

1 files changed, 167 insertions, 143 deletions

diff --git a/doc/gawk.info b/doc/gawk.info
index 3bb2f352..c197aa14 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -23859,8 +23859,13 @@ Extension functions are described by the following record:
 
      typedef struct awk_ext_func {
          const char *name;
-         awk_value_t *(*function)(int num_actual_args, awk_value_t *result);
-         size_t max_expected_args;
+         awk_value_t *(*const function)(int num_actual_args,
+                                        awk_value_t *result,
+                                        struct awk_ext_func *finfo);
+         const size_t min_required_args;
+         const size_t max_expected_args;
+         awk_bool_t suppress_lint;
+         void *data;        /* opaque pointer to any extra state */
      } awk_ext_func_t;
 
    The fields are:
@@ -23874,7 +23879,7 @@ Extension functions are described by the following record:
      which may be followed by any number of letters, digits, and
      underscores.  Letter case in function names is significant.
 
-'awk_value_t *(*function)(int num_actual_args, awk_value_t *result);'
+'awk_value_t *(*const function)(int num_actual_args, awk_value_t *result, struct awk_ext_func *finfo);'
      This is a pointer to the C function that provides the extension's
      functionality.  The function must fill in '*result' with either a
      number or a string.  'gawk' takes ownership of any string memory.
@@ -23884,20 +23889,39 @@ Extension functions are described by the following record:
      The 'num_actual_args' argument tells the C function how many actual
      parameters were passed from the calling 'awk' code.
 
+     The 'finfo' parameter is a pointer to the 'awk_ext_func_t' for this
+     function.  The called function may access data within it as
+     desired, or not.
+
      The function must return the value of 'result'.  This is for the
      convenience of the calling code inside 'gawk'.
 
-'size_t max_expected_args;'
-     This is the maximum number of arguments the function expects to
-     receive.  Each extension function may decide what to do if the
-     number of arguments isn't what it expected.  As with real 'awk'
-     functions, it is likely OK to ignore extra arguments.  This value
-     does not affect actual program execution.
+'const size_t min_required_args;'
+     This is the minimum number of arguments the function expects to
+     receive.  If called with fewer arguments, 'gawk' prints a fatal
+     error message and exits.
 
-     Extension functions should compare this value to the number of
-     actual arguments passed and possibly issue a lint warning if there
-     is an undesirable mismatch.  Of course, if '--lint=fatal' is used,
-     this would cause the program to exit.
+'const size_t max_expected_args;'
+     This is the maximum number of arguments the function expects to
+     receive.  If called with more arguments than this, and if lint
+     checking has been enabled, then 'gawk' prints a warning message.
+     For more information, see the next item in this list.
+
+'awk_bool_t suppress_lint;'
+     This flag tells 'gawk' not to print a lint message if lint checking
+     has been enabled and if more arguments were supplied in the call
+     than expected.  An extension function can tell if 'gawk' already
+     printed at least one such message by checking if 'num_actual_args >
+     finfo->max_expected_args'.  If so, and the function does not want
+     more lint messages to be printed, it should set
+     'finfo->suppress_lint' to 'awk_true'.
+
+'void *data;'
+     This is an opaque pointer to any data that an extension function
+     may wish to have available when called.  Passing the
+     'awk_ext_funct_t' structure to the extension function, and having
+     this pointer available in it enables writing a single C or C++
+     function that implements multiple 'awk'-level extension functions.
 
    Once you have a record representing your extension function, you
 register it with 'gawk' using this API function:
@@ -35758,135 +35782,135 @@ Ref: Memory Allocation Functions-Footnote-1966474
 Node: Constructor Functions966573
 Node: Registration Functions968318
 Node: Extension Functions969003
-Node: Exit Callback Functions971626
-Node: Extension Version String972876
-Node: Input Parsers973539
-Node: Output Wrappers983421
-Node: Two-way processors987933
-Node: Printing Messages990198
-Ref: Printing Messages-Footnote-1991369
-Node: Updating ERRNO991522
-Node: Requesting Values992261
-Ref: table-value-types-returned992998
-Node: Accessing Parameters993881
-Node: Symbol Table Access995116
-Node: Symbol table by name995628
-Node: Symbol table by cookie997649
-Ref: Symbol table by cookie-Footnote-11001801
-Node: Cached values1001865
-Ref: Cached values-Footnote-11005372
-Node: Array Manipulation1005463
-Ref: Array Manipulation-Footnote-11006554
-Node: Array Data Types1006591
-Ref: Array Data Types-Footnote-11009249
-Node: Array Functions1009341
-Node: Flattening Arrays1013199
-Node: Creating Arrays1020107
-Node: Redirection API1024876
-Node: Extension API Variables1027707
-Node: Extension Versioning1028340
-Ref: gawk-api-version1028777
-Node: Extension API Informational Variables1030533
-Node: Extension API Boilerplate1031597
-Node: Finding Extensions1035411
-Node: Extension Example1035970
-Node: Internal File Description1036768
-Node: Internal File Ops1040848
-Ref: Internal File Ops-Footnote-11052610
-Node: Using Internal File Ops1052750
-Ref: Using Internal File Ops-Footnote-11055133
-Node: Extension Samples1055407
-Node: Extension Sample File Functions1056936
-Node: Extension Sample Fnmatch1064585
-Node: Extension Sample Fork1066072
-Node: Extension Sample Inplace1067290
-Node: Extension Sample Ord1070500
-Node: Extension Sample Readdir1071336
-Ref: table-readdir-file-types1072225
-Node: Extension Sample Revout1073030
-Node: Extension Sample Rev2way1073619
-Node: Extension Sample Read write array1074359
-Node: Extension Sample Readfile1076301
-Node: Extension Sample Time1077396
-Node: Extension Sample API Tests1078744
-Node: gawkextlib1079236
-Node: Extension summary1081683
-Node: Extension Exercises1085385
-Node: Language History1086883
-Node: V7/SVR3.11088539
-Node: SVR41090691
-Node: POSIX1092125
-Node: BTL1093504
-Node: POSIX/GNU1094233
-Node: Feature History1100095
-Node: Common Extensions1114465
-Node: Ranges and Locales1115748
-Ref: Ranges and Locales-Footnote-11120364
-Ref: Ranges and Locales-Footnote-21120391
-Ref: Ranges and Locales-Footnote-31120626
-Node: Contributors1120847
-Node: History summary1126407
-Node: Installation1127787
-Node: Gawk Distribution1128731
-Node: Getting1129215
-Node: Extracting1130176
-Node: Distribution contents1131814
-Node: Unix Installation1137899
-Node: Quick Installation1138581
-Node: Shell Startup Files1140995
-Node: Additional Configuration Options1142073
-Node: Configuration Philosophy1143878
-Node: Non-Unix Installation1146247
-Node: PC Installation1146707
-Node: PC Binary Installation1147545
-Node: PC Compiling1147980
-Node: PC Using1149097
-Node: Cygwin1152142
-Node: MSYS1152912
-Node: VMS Installation1153413
-Node: VMS Compilation1154204
-Ref: VMS Compilation-Footnote-11155433
-Node: VMS Dynamic Extensions1155491
-Node: VMS Installation Details1157176
-Node: VMS Running1159429
-Node: VMS GNV1163708
-Node: VMS Old Gawk1164443
-Node: Bugs1164914
-Node: Bug address1165577
-Node: Usenet1167974
-Node: Maintainers1168749
-Node: Other Versions1170125
-Node: Installation summary1176709
-Node: Notes1177744
-Node: Compatibility Mode1178609
-Node: Additions1179391
-Node: Accessing The Source1180316
-Node: Adding Code1181751
-Node: New Ports1187970
-Node: Derived Files1192458
-Ref: Derived Files-Footnote-11197943
-Ref: Derived Files-Footnote-21197978
-Ref: Derived Files-Footnote-31198576
-Node: Future Extensions1198690
-Node: Implementation Limitations1199348
-Node: Extension Design1200531
-Node: Old Extension Problems1201685
-Ref: Old Extension Problems-Footnote-11203203
-Node: Extension New Mechanism Goals1203260
-Ref: Extension New Mechanism Goals-Footnote-11206624
-Node: Extension Other Design Decisions1206813
-Node: Extension Future Growth1208926
-Node: Old Extension Mechanism1209762
-Node: Notes summary1211525
-Node: Basic Concepts1212707
-Node: Basic High Level1213388
-Ref: figure-general-flow1213670
-Ref: figure-process-flow1214355
-Ref: Basic High Level-Footnote-11217656
-Node: Basic Data Typing1217841
-Node: Glossary1221169
-Node: Copying1253116
-Node: GNU Free Documentation License1290655
-Node: Index1315773
+Node: Exit Callback Functions972816
+Node: Extension Version String974066
+Node: Input Parsers974729
+Node: Output Wrappers984611
+Node: Two-way processors989123
+Node: Printing Messages991388
+Ref: Printing Messages-Footnote-1992559
+Node: Updating ERRNO992712
+Node: Requesting Values993451
+Ref: table-value-types-returned994188
+Node: Accessing Parameters995071
+Node: Symbol Table Access996306
+Node: Symbol table by name996818
+Node: Symbol table by cookie998839
+Ref: Symbol table by cookie-Footnote-11002991
+Node: Cached values1003055
+Ref: Cached values-Footnote-11006562
+Node: Array Manipulation1006653
+Ref: Array Manipulation-Footnote-11007744
+Node: Array Data Types1007781
+Ref: Array Data Types-Footnote-11010439
+Node: Array Functions1010531
+Node: Flattening Arrays1014389
+Node: Creating Arrays1021297
+Node: Redirection API1026066
+Node: Extension API Variables1028897
+Node: Extension Versioning1029530
+Ref: gawk-api-version1029967
+Node: Extension API Informational Variables1031723
+Node: Extension API Boilerplate1032787
+Node: Finding Extensions1036601
+Node: Extension Example1037160
+Node: Internal File Description1037958
+Node: Internal File Ops1042038
+Ref: Internal File Ops-Footnote-11053800
+Node: Using Internal File Ops1053940
+Ref: Using Internal File Ops-Footnote-11056323
+Node: Extension Samples1056597
+Node: Extension Sample File Functions1058126
+Node: Extension Sample Fnmatch1065775
+Node: Extension Sample Fork1067262
+Node: Extension Sample Inplace1068480
+Node: Extension Sample Ord1071690
+Node: Extension Sample Readdir1072526
+Ref: table-readdir-file-types1073415
+Node: Extension Sample Revout1074220
+Node: Extension Sample Rev2way1074809
+Node: Extension Sample Read write array1075549
+Node: Extension Sample Readfile1077491
+Node: Extension Sample Time1078586
+Node: Extension Sample API Tests1079934
+Node: gawkextlib1080426
+Node: Extension summary1082873
+Node: Extension Exercises1086575
+Node: Language History1088073
+Node: V7/SVR3.11089729
+Node: SVR41091881
+Node: POSIX1093315
+Node: BTL1094694
+Node: POSIX/GNU1095423
+Node: Feature History1101285
+Node: Common Extensions1115655
+Node: Ranges and Locales1116938
+Ref: Ranges and Locales-Footnote-11121554
+Ref: Ranges and Locales-Footnote-21121581
+Ref: Ranges and Locales-Footnote-31121816
+Node: Contributors1122037
+Node: History summary1127597
+Node: Installation1128977
+Node: Gawk Distribution1129921
+Node: Getting1130405
+Node: Extracting1131366
+Node: Distribution contents1133004
+Node: Unix Installation1139089
+Node: Quick Installation1139771
+Node: Shell Startup Files1142185
+Node: Additional Configuration Options1143263
+Node: Configuration Philosophy1145068
+Node: Non-Unix Installation1147437
+Node: PC Installation1147897
+Node: PC Binary Installation1148735
+Node: PC Compiling1149170
+Node: PC Using1150287
+Node: Cygwin1153332
+Node: MSYS1154102
+Node: VMS Installation1154603
+Node: VMS Compilation1155394
+Ref: VMS Compilation-Footnote-11156623
+Node: VMS Dynamic Extensions1156681
+Node: VMS Installation Details1158366
+Node: VMS Running1160619
+Node: VMS GNV1164898
+Node: VMS Old Gawk1165633
+Node: Bugs1166104
+Node: Bug address1166767
+Node: Usenet1169164
+Node: Maintainers1169939
+Node: Other Versions1171315
+Node: Installation summary1177899
+Node: Notes1178934
+Node: Compatibility Mode1179799
+Node: Additions1180581
+Node: Accessing The Source1181506
+Node: Adding Code1182941
+Node: New Ports1189160
+Node: Derived Files1193648
+Ref: Derived Files-Footnote-11199133
+Ref: Derived Files-Footnote-21199168
+Ref: Derived Files-Footnote-31199766
+Node: Future Extensions1199880
+Node: Implementation Limitations1200538
+Node: Extension Design1201721
+Node: Old Extension Problems1202875
+Ref: Old Extension Problems-Footnote-11204393
+Node: Extension New Mechanism Goals1204450
+Ref: Extension New Mechanism Goals-Footnote-11207814
+Node: Extension Other Design Decisions1208003
+Node: Extension Future Growth1210116
+Node: Old Extension Mechanism1210952
+Node: Notes summary1212715
+Node: Basic Concepts1213897
+Node: Basic High Level1214578
+Ref: figure-general-flow1214860
+Ref: figure-process-flow1215545
+Ref: Basic High Level-Footnote-11218846
+Node: Basic Data Typing1219031
+Node: Glossary1222359
+Node: Copying1254306
+Node: GNU Free Documentation License1291845
+Node: Index1316963
 
 End Tag Table