[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawk-diffs] [SCM] gawk branch, master, updated. adb0a3271736be1b8c9a899
|
From: |
Arnold Robbins |
|
Subject: |
[gawk-diffs] [SCM] gawk branch, master, updated. adb0a3271736be1b8c9a899d7e42ac9777837688 |
|
Date: |
Fri, 16 Nov 2012 11:57:20 +0000 |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".
The branch, master has been updated
via adb0a3271736be1b8c9a899d7e42ac9777837688 (commit)
from c9e416d0703fc11828a1d175002805b326029735 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=adb0a3271736be1b8c9a899d7e42ac9777837688
commit adb0a3271736be1b8c9a899d7e42ac9777837688
Author: Arnold D. Robbins <address@hidden>
Date: Fri Nov 16 13:56:45 2012 +0200
First pass on Nelson's comments on API chapter.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index e660758..4c21c6f 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2012-11-16 Arnold D. Robbins <address@hidden>
+
+ * gawk.texi: Minor edits in API chapter.
+ Thanks to Nelson Beebe.
+
2012-11-14 Arnold D. Robbins <address@hidden>
* gawk.texi: Minor edits in API chapter.
diff --git a/doc/gawk.info b/doc/gawk.info
index 6bd26e9..b74c023 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -21352,9 +21352,8 @@ File: gawk.info, Node: Dynamic Extensions, Next:
Language History, Prev: Arbi
It is possible to add new built-in functions to `gawk' using
dynamically loaded libraries. This facility is available on systems
-(such as GNU/Linux) that support the C `dlopen()' and `dlsym()'
-functions. This major node describes how to create extensions using
-code written in C or C++.
+that support the C `dlopen()' and `dlsym()' functions. This major node
+describes how to create extensions using code written in C or C++.
If you don't know anything about C programming, you can safely skip
this major node, although you may wish to review the documentation on
@@ -21397,8 +21396,8 @@ write in C or C++, you can write an extension to do it!
Extensions are written in C or C++, using the "Application
Programming Interface" (API) defined for this purpose by the `gawk'
developers. The rest of this major node explains the design decisions
-behind the API, the facilities it provides and how to use them, and
-presents a small sample extension. In addition, it documents the
+behind the API, the facilities that it provides and how to use them,
+and presents a small sample extension. In addition, it documents the
sample extensions included in the `gawk' distribution, and describes
the `gawkextlib' project.
@@ -21557,7 +21556,7 @@ File: gawk.info, Node: Extension Other Design
Decisions, Next: Extension Mecha
16.3.3 Other Design Decisions
-----------------------------
-As an "arbitrary" design decision, extensions can read the values of
+As an arbitrary design decision, extensions can read the values of
built-in variables and arrays (such as `ARGV' and `FS'), but cannot
change them, with the exception of `PROCINFO'.
@@ -21583,6 +21582,13 @@ being brought out to the API in order to keep things
simple and close to
traditional `awk' semantics. (In fact, arrays indexed internally by
integers are so transparent that they aren't even documented!)
+ Additionally, all functions in the API check that their pointer
+input parameters are not `NULL'. If they are, they return an error.
+(It is a good idea for extension code to verify that pointers received
+from `gawk' are not `NULL'. Such a thing should not happen, but the
+`gawk' developers are only human, and they have been known to
+occasionally make mistakes.)
+
With time, the API will undoubtedly evolve; the `gawk' developers
expect this to be driven by user needs. For now, the current API seems
to provide a minimal yet powerful set of features for creating
@@ -21686,10 +21692,10 @@ printing messages, setting `ERRNO', and so on.
through the function pointers look like regular function calls so that
extension code is quite readable and understandable.
- Although all of this sounds medium complicated, the result is that
-extension code is quite clean and straightforward. This can be seen in
-the sample extensions `filefuncs.c' (*note Extension Example::) and
-also the `testext.c' code for testing the APIs.
+ Although all of this sounds somewhat complicated, the result is that
+extension code is quite straightforward to write and to read. You can
+see this in the sample extensions `filefuncs.c' (*note Extension
+Example::) and also the `testext.c' code for testing the APIs.
Some other bits and pieces:
@@ -21711,16 +21717,17 @@ File: gawk.info, Node: Extension Future Growth,
Prev: Extension Mechanism Outl
16.3.5 Room For Future Growth
-----------------------------
-The API provides room for future growth, in two ways.
+The API can later be expanded, in two ways:
- An "extension id" is passed into the extension when its loaded. This
-extension id is then passed back to `gawk' with each function call.
-This allows `gawk' to identify the extension calling into it, should it
-need to know.
+ * `gawk' passes an "extension id" into the extension when it first
+ loads the extension. The extension then passes this id back to
+ `gawk' with each function call. This mechanism allows `gawk' to
+ identify the extension calling into it, should it need to know.
- A "name space" is passed into `gawk' when an extension function is
-registered. This provides for a future mechanism for grouping
-extension functions and possibly avoiding name conflicts.
+ * Similarly, the extension passes a "name space" into `gawk' when it
+ registers each extension function. This allows a future mechanism
+ for grouping extension functions and possibly avoiding name
+ conflicts.
Of course, as of this writing, no decisions have been made with
respect to any of the above.
@@ -21815,6 +21822,9 @@ operations:
pass reasonable integer values for `ERRNO', you will need to
include `<errno.h>'.
+ * The `gawkapi.h' file may be included more than once without ill
+ effect. Doing so, however, is poor coding practice.
+
* Although the API only uses ISO C 90 features, there is an
exception; the "constructor" functions use the `inline' keyword.
If your compiler does not support this keyword, you should either
@@ -21852,8 +21862,8 @@ operations:
While you may call the API functions by using the function pointers
directly, the interface is not so pretty. To make extension code look
-more like regular code, the `gawkapi.h' header file defines a number of
-macros which you should use in your code. This minor node presents the
+more like regular code, the `gawkapi.h' header file defines several
+macros that you should use in your code. This minor node presents the
macros as if they were functions.
@@ -22223,8 +22233,8 @@ By default, `gawk' reads text files as its input. It
uses the value of
`FIELDWIDTHS') to split it into fields (*note Reading Files::).
Additionally, it sets the value of `RT' (*note Built-in Variables::).
- If you want, you can provide your own, custom, input parser. An
-input parser's job is to return a record to the `gawk' record processing
+ If you want, you can provide your own custom input parser. An input
+parser's job is to return a record to the `gawk' record processing
code, along with indicators for the value and length of the data to be
used for `RT', if any.
@@ -22689,7 +22699,7 @@ termed a "symbol table".
Changing types (scalar to array or vice versa) of an existing
variable is _not_ allowed, nor may this routine be used to update
- an array. This routine cannot be be used to update any of the
+ an array. This routine cannot be used to update any of the
predefined variables (such as `ARGC' or `NF').
`awk_bool_t sym_constant(const char *name, awk_value_t *value);'
@@ -22699,7 +22709,7 @@ termed a "symbol table".
extension may change the value of `name''s variable with
subsequent calls to this routine, and may also convert a variable
created by `sym_update()' into a constant. However, once a
- variable becomes a constant it cannot later be reverted into a
+ variable becomes a constant, it cannot later be reverted into a
mutable variable.
---------- Footnotes ----------
@@ -22734,7 +22744,7 @@ was discussed earlier, in *note General Data Types::.
too, the built-in variables may not be updated.
It is not obvious at first glance how to work with scalar cookies or
-what their raison d'etre really is. In theory, the `sym_lookup()' and
+what their raison de^tre really is. In theory, the `sym_lookup()' and
`sym_update()' routines are all you really need to work with variables.
For example, you might have code that looked up the value of a
variable, evaluated a condition, and then possibly changed the value of
@@ -22900,7 +22910,11 @@ if `awk' code assigns a new value to `VAR1', are all
the others be
changed too?"
That's a great question. The answer is that no, it's not a problem.
-`gawk' is smart enough to avoid such problems.
+Internally, `gawk' uses reference-counted strings. This means that many
+variables can share the same string, and `gawk' keeps track of the
+usage. When a variable's value changes, `gawk' simply decrements the
+reference count on the old value and updates the variable to use the
+new value.
Finally, as part of your clean up action (*note Exit Callback
Functions::) you should release any cached values that you created,
@@ -22973,15 +22987,15 @@ The data types associated with arrays are listed
below.
`struct awk_element *next;'
This pointer is for the convenience of extension writers. It
allows an extension to create a linked list of new elements
- which can then be added to an array in a loop that traverses
+ that can then be added to an array in a loop that traverses
the list.
`enum { ... } flags;'
A set of flag values that convey information between `gawk'
and the extension. Currently there is only one:
- `AWK_ELEMENT_DELETE', which the extension can set to cause
- `gawk' to delete the element from the original array upon
- release of the flattened array.
+ `AWK_ELEMENT_DELETE'. Setting it causes `gawk' to delete the
+ element from the original array upon release of the flattened
+ array.
`index'
`value'
@@ -23098,9 +23112,9 @@ as a nice example to show how to use the APIs.
@load "testext"
BEGIN {
n = split("blacky rusty sophie raincloud lucky", pets)
- printf "pets has %d elements\n", length(pets)
+ printf("pets has %d elements\n", length(pets))
ret = dump_array_and_delete("pets", "3")
- printf "dump_array_and_delete(pets) returned %d\n", ret
+ printf("dump_array_and_delete(pets) returned %d\n", ret)
if ("3" in pets)
printf("dump_array_and_delete() did NOT remove index \"3\"!\n")
else
@@ -23280,8 +23294,8 @@ code:
Thus, the correct way to build an array is to work "top down."
Create the array, and immediately install it in `gawk''s symbol
table using `sym_update()', or install it as an element in a
- previously existing array using `set_element()'. Example code is
- coming shortly.
+ previously existing array using `set_element()'. We show example
+ code shortly.
2. Due to gawk internals, after using `sym_update()' to install an
array into `gawk', you have to retrieve the array cookie from the
@@ -24537,8 +24551,8 @@ Letter File Type
On systems without the file type information, calling
`readdir_do_ftype("stat")' causes the extension to use the `lstat()'
-system call to retrieve the appropriate information. This is not the
-default, since `lstat()' is a potentially expensive operation. By
+system call to retrieve the appropriate information. That is not the
+default, because `lstat()' is a potentially expensive operation. By
calling `readdir_do_ftype("never")' one can ensure that the file type
information is never displayed, even when readily available in the
directory entry.
@@ -24699,10 +24713,10 @@ your script.
Return the time in seconds that has elapsed since 1970-01-01 UTC
as a floating point value. If the time is unavailable on this
platform, return -1 and set `ERRNO'. The returned time should
- have sub-second precision, but the actual precision will vary
- based on the platform. If the standard C `gettimeofday()' system
- call is available on this platform, then it simply returns the
- value. Otherwise, if on Windows, it tries to use
+ have sub-second precision, but the actual precision may vary based
+ on the platform. If the standard C `gettimeofday()' system call
+ is available on this platform, then it simply returns the value.
+ Otherwise, if on Windows, it tries to use
`GetSystemTimeAsFileTime()'.
`result = sleep(SECONDS)'
@@ -32107,132 +32121,132 @@ Node: Exact Arithmetic855493
Node: Arbitrary Precision Integers858601
Ref: Arbitrary Precision Integers-Footnote-1861601
Node: Dynamic Extensions861748
-Node: Extension Intro863154
-Node: Plugin License864357
-Node: Extension Design865031
-Node: Old Extension Problems866102
-Ref: Old Extension Problems-Footnote-1867612
-Node: Extension New Mechanism Goals867669
-Ref: Extension New Mechanism Goals-Footnote-1870381
-Node: Extension Other Design Decisions870567
-Node: Extension Mechanism Outline872314
-Ref: load-extension873339
-Ref: load-new-function874817
-Ref: call-new-function875798
-Node: Extension Future Growth877779
-Node: Extension API Description878521
-Node: Extension API Functions Introduction879849
-Node: General Data Types883924
-Ref: General Data Types-Footnote-1889557
-Node: Requesting Values889856
-Ref: table-value-types-returned890587
-Node: Constructor Functions891541
-Node: Registration Functions894537
-Node: Extension Functions895222
-Node: Exit Callback Functions897041
-Node: Extension Version String898284
-Node: Input Parsers898934
-Node: Output Wrappers907515
-Node: Two-way processors911908
-Node: Printing Messages914030
-Ref: Printing Messages-Footnote-1915107
-Node: Updating `ERRNO'915259
-Node: Accessing Parameters915998
-Node: Symbol Table Access917228
-Node: Symbol table by name917740
-Ref: Symbol table by name-Footnote-1919912
-Node: Symbol table by cookie919992
-Ref: Symbol table by cookie-Footnote-1924121
-Node: Cached values924184
-Ref: Cached values-Footnote-1927385
-Node: Array Manipulation927476
-Ref: Array Manipulation-Footnote-1928574
-Node: Array Data Types928613
-Ref: Array Data Types-Footnote-1931335
-Node: Array Functions931427
-Node: Flattening Arrays935193
-Node: Creating Arrays942024
-Node: Extension API Variables946820
-Node: Extension Versioning947456
-Node: Extension API Informational Variables949357
-Node: Extension API Boilerplate950443
-Node: Finding Extensions954277
-Node: Extension Example954824
-Node: Internal File Description955562
-Node: Internal File Ops959250
-Ref: Internal File Ops-Footnote-1970334
-Node: Using Internal File Ops970474
-Ref: Using Internal File Ops-Footnote-1972830
-Node: Extension Samples973096
-Node: Extension Sample File Functions974539
-Node: Extension Sample Fnmatch982908
-Node: Extension Sample Fork984634
-Node: Extension Sample Ord985848
-Node: Extension Sample Readdir986624
-Node: Extension Sample Revout988962
-Node: Extension Sample Rev2way989555
-Node: Extension Sample Read write array990245
-Node: Extension Sample Readfile992128
-Node: Extension Sample API Tests992883
-Node: Extension Sample Time993408
-Node: gawkextlib994717
-Node: Language History997098
-Node: V7/SVR3.1998620
-Node: SVR41000941
-Node: POSIX1002383
-Node: BTL1003391
-Node: POSIX/GNU1004125
-Node: Common Extensions1009660
-Node: Ranges and Locales1010767
-Ref: Ranges and Locales-Footnote-11015385
-Ref: Ranges and Locales-Footnote-21015412
-Ref: Ranges and Locales-Footnote-31015672
-Node: Contributors1015893
-Node: Installation1020189
-Node: Gawk Distribution1021083
-Node: Getting1021567
-Node: Extracting1022393
-Node: Distribution contents1024085
-Node: Unix Installation1029307
-Node: Quick Installation1029924
-Node: Additional Configuration Options1031886
-Node: Configuration Philosophy1033363
-Node: Non-Unix Installation1035705
-Node: PC Installation1036163
-Node: PC Binary Installation1037462
-Node: PC Compiling1039310
-Node: PC Testing1042254
-Node: PC Using1043430
-Node: Cygwin1047615
-Node: MSYS1048615
-Node: VMS Installation1049129
-Node: VMS Compilation1049732
-Ref: VMS Compilation-Footnote-11050739
-Node: VMS Installation Details1050797
-Node: VMS Running1052432
-Node: VMS Old Gawk1054039
-Node: Bugs1054513
-Node: Other Versions1058365
-Node: Notes1063680
-Node: Compatibility Mode1064267
-Node: Additions1065050
-Node: Accessing The Source1065977
-Node: Adding Code1067403
-Node: New Ports1073445
-Node: Derived Files1077580
-Ref: Derived Files-Footnote-11082888
-Ref: Derived Files-Footnote-21082922
-Ref: Derived Files-Footnote-31083522
-Node: Future Extensions1083620
-Node: Basic Concepts1085107
-Node: Basic High Level1085788
-Ref: figure-general-flow1086059
-Ref: figure-process-flow1086658
-Ref: Basic High Level-Footnote-11089887
-Node: Basic Data Typing1090072
-Node: Glossary1093427
-Node: Copying1118738
-Node: GNU Free Documentation License1156295
-Node: Index1181432
+Node: Extension Intro863134
+Node: Plugin License864342
+Node: Extension Design865016
+Node: Old Extension Problems866087
+Ref: Old Extension Problems-Footnote-1867597
+Node: Extension New Mechanism Goals867654
+Ref: Extension New Mechanism Goals-Footnote-1870366
+Node: Extension Other Design Decisions870552
+Node: Extension Mechanism Outline872664
+Ref: load-extension873689
+Ref: load-new-function875167
+Ref: call-new-function876148
+Node: Extension Future Growth878142
+Node: Extension API Description878960
+Node: Extension API Functions Introduction880288
+Node: General Data Types884486
+Ref: General Data Types-Footnote-1890119
+Node: Requesting Values890418
+Ref: table-value-types-returned891149
+Node: Constructor Functions892103
+Node: Registration Functions895099
+Node: Extension Functions895784
+Node: Exit Callback Functions897603
+Node: Extension Version String898846
+Node: Input Parsers899496
+Node: Output Wrappers908075
+Node: Two-way processors912468
+Node: Printing Messages914590
+Ref: Printing Messages-Footnote-1915667
+Node: Updating `ERRNO'915819
+Node: Accessing Parameters916558
+Node: Symbol Table Access917788
+Node: Symbol table by name918300
+Ref: Symbol table by name-Footnote-1920470
+Node: Symbol table by cookie920550
+Ref: Symbol table by cookie-Footnote-1924679
+Node: Cached values924742
+Ref: Cached values-Footnote-1928185
+Node: Array Manipulation928276
+Ref: Array Manipulation-Footnote-1929374
+Node: Array Data Types929413
+Ref: Array Data Types-Footnote-1932116
+Node: Array Functions932208
+Node: Flattening Arrays935974
+Node: Creating Arrays942807
+Node: Extension API Variables947602
+Node: Extension Versioning948238
+Node: Extension API Informational Variables950139
+Node: Extension API Boilerplate951225
+Node: Finding Extensions955059
+Node: Extension Example955606
+Node: Internal File Description956344
+Node: Internal File Ops960032
+Ref: Internal File Ops-Footnote-1971116
+Node: Using Internal File Ops971256
+Ref: Using Internal File Ops-Footnote-1973612
+Node: Extension Samples973878
+Node: Extension Sample File Functions975321
+Node: Extension Sample Fnmatch983690
+Node: Extension Sample Fork985416
+Node: Extension Sample Ord986630
+Node: Extension Sample Readdir987406
+Node: Extension Sample Revout989746
+Node: Extension Sample Rev2way990339
+Node: Extension Sample Read write array991029
+Node: Extension Sample Readfile992912
+Node: Extension Sample API Tests993667
+Node: Extension Sample Time994192
+Node: gawkextlib995499
+Node: Language History997880
+Node: V7/SVR3.1999402
+Node: SVR41001723
+Node: POSIX1003165
+Node: BTL1004173
+Node: POSIX/GNU1004907
+Node: Common Extensions1010442
+Node: Ranges and Locales1011549
+Ref: Ranges and Locales-Footnote-11016167
+Ref: Ranges and Locales-Footnote-21016194
+Ref: Ranges and Locales-Footnote-31016454
+Node: Contributors1016675
+Node: Installation1020971
+Node: Gawk Distribution1021865
+Node: Getting1022349
+Node: Extracting1023175
+Node: Distribution contents1024867
+Node: Unix Installation1030089
+Node: Quick Installation1030706
+Node: Additional Configuration Options1032668
+Node: Configuration Philosophy1034145
+Node: Non-Unix Installation1036487
+Node: PC Installation1036945
+Node: PC Binary Installation1038244
+Node: PC Compiling1040092
+Node: PC Testing1043036
+Node: PC Using1044212
+Node: Cygwin1048397
+Node: MSYS1049397
+Node: VMS Installation1049911
+Node: VMS Compilation1050514
+Ref: VMS Compilation-Footnote-11051521
+Node: VMS Installation Details1051579
+Node: VMS Running1053214
+Node: VMS Old Gawk1054821
+Node: Bugs1055295
+Node: Other Versions1059147
+Node: Notes1064462
+Node: Compatibility Mode1065049
+Node: Additions1065832
+Node: Accessing The Source1066759
+Node: Adding Code1068185
+Node: New Ports1074227
+Node: Derived Files1078362
+Ref: Derived Files-Footnote-11083670
+Ref: Derived Files-Footnote-21083704
+Ref: Derived Files-Footnote-31084304
+Node: Future Extensions1084402
+Node: Basic Concepts1085889
+Node: Basic High Level1086570
+Ref: figure-general-flow1086841
+Ref: figure-process-flow1087440
+Ref: Basic High Level-Footnote-11090669
+Node: Basic Data Typing1090854
+Node: Glossary1094209
+Node: Copying1119520
+Node: GNU Free Documentation License1157077
+Node: Index1182214
End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 8adef64..be04007 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -28242,8 +28242,8 @@ gawk -M 'BEGIN @{ n = 13; print n % 2 @}'
@chapter Writing Extensions for @command{gawk}
It is possible to add new built-in functions to @command{gawk} using
-dynamically loaded libraries. This facility is available on systems (such
-as GNU/Linux) that support the C @code{dlopen()} and @code{dlsym()}
+dynamically loaded libraries. This facility is available on systems
+that support the C @code{dlopen()} and @code{dlsym()}
functions. This @value{CHAPTER} describes how to create extensions
using code written in C or C++.
@@ -28288,7 +28288,7 @@ want to do and can write in C or C++, you can write an
extension to do it!
Extensions are written in C or C++, using the @dfn{Application Programming
Interface} (API) defined for this purpose by the @command{gawk}
developers. The rest of this @value{CHAPTER} explains the design
-decisions behind the API, the facilities it provides and how to use
+decisions behind the API, the facilities that it provides and how to use
them, and presents a small sample extension. In addition, it documents
the sample extensions included in the @command{gawk} distribution,
and describes the @code{gawkextlib} project.
@@ -28456,7 +28456,7 @@ about extensions as well.
@node Extension Other Design Decisions
@subsection Other Design Decisions
-As an ``arbitrary'' design decision, extensions can read the values of
+As an arbitrary design decision, extensions can read the values of
built-in variables and arrays (such as @code{ARGV} and @code{FS}), but cannot
change them, with the exception of @code{PROCINFO}.
@@ -28482,6 +28482,14 @@ being brought out to the API in order to keep things
simple and close to
traditional @command{awk} semantics. (In fact, arrays indexed internally
by integers are so transparent that they aren't even documented!)
+Additionally, all functions in the API check that their pointer
+input parameters are not @code{NULL}. If they are, they return an error.
+(It is a good idea for extension code to verify that
+pointers received from @command{gawk} are not @code{NULL}.
+Such a thing should not happen, but the @command{gawk} developers
+are only human, and they have been known to occasionally make
+mistakes.)
+
With time, the API will undoubtedly evolve; the @command{gawk} developers
expect this to be driven by user needs. For now, the current API seems
to provide a minimal yet powerful set of features for creating extensions.
@@ -28559,10 +28567,10 @@ Convenience macros in the @file{gawkapi.h} header
file make calling
through the function pointers look like regular function calls so that
extension code is quite readable and understandable.
-Although all of this sounds medium complicated, the result is that
-extension code is quite clean and straightforward. This can be seen in
-the sample extensions @file{filefuncs.c} (@pxref{Extension Example})
-and also the @file{testext.c} code for testing the APIs.
+Although all of this sounds somewhat complicated, the result is that
+extension code is quite straightforward to write and to read. You can
+see this in the sample extensions @file{filefuncs.c} (@pxref{Extension
+Example}) and also the @file{testext.c} code for testing the APIs.
Some other bits and pieces:
@@ -28586,16 +28594,22 @@ happen, but we all know how @emph{that} goes.)
@node Extension Future Growth
@subsection Room For Future Growth
-The API provides room for future growth, in two ways.
+The API can later be expanded, in two ways:
-An ``extension id'' is passed into the extension when its loaded. This
-extension id is then passed back to @command{gawk} with each function
-call. This allows @command{gawk} to identify the extension calling into it,
-should it need to know.
address@hidden @bullet
address@hidden
address@hidden passes an ``extension id'' into the extension when it
+first loads the extension. The extension then passes this id back
+to @command{gawk} with each function call. This mechanism allows
address@hidden to identify the extension calling into it, should it need
+to know.
-A ``name space'' is passed into @command{gawk} when an extension function
-is registered. This provides for a future mechanism for grouping
-extension functions and possibly avoiding name conflicts.
address@hidden
+Similarly, the extension passes a ``name space'' into @command{gawk}
+when it registers each extension function. This allows a future
+mechanism for grouping extension functions and possibly avoiding name
+conflicts.
address@hidden itemize
Of course, as of this writing, no decisions have been made with respect
to any of the above.
@@ -28700,6 +28714,10 @@ Finally, to pass reasonable integer values for
@code{ERRNO}, you
will need to include @code{<errno.h>}.
@item
+The @file{gawkapi.h} file may be included more than once without ill effect.
+Doing so, however, is poor coding practice.
+
address@hidden
Although the API only uses ISO C 90 features, there is an exception; the
``constructor'' functions use the @code{inline} keyword. If your compiler
does not support this keyword, you should either place
@@ -28742,8 +28760,8 @@ so that the extension can, e.g., print an error message
While you may call the API functions by using the function pointers
directly, the interface is not so pretty. To make extension code look
-more like regular code, the @file{gawkapi.h} header file defines a number
-of macros which you should use in your code. This @value{SECTION} presents
+more like regular code, the @file{gawkapi.h} header file defines several
+macros that you should use in your code. This @value{SECTION} presents
the macros as if they were functions.
@node General Data Types
@@ -29146,7 +29164,7 @@ of @code{RS} to find the end of the record, and then
uses @code{FS}
(or @code{FIELDWIDTHS}) to split it into fields (@pxref{Reading Files}).
Additionally, it sets the value of @code{RT} (@pxref{Built-in Variables}).
-If you want, you can provide your own, custom, input parser. An input
+If you want, you can provide your own custom input parser. An input
parser's job is to return a record to the @command{gawk} record processing
code, along with indicators for the value and length of the data to be
used for @code{RT}, if any.
@@ -29638,7 +29656,7 @@ if it is not there. Return true if everything worked,
false otherwise.
Changing types (scalar to array or vice versa) of an existing variable
is @emph{not} allowed, nor may this routine be used to update an array.
-This routine cannot be be used to update any of the predefined
+This routine cannot be used to update any of the predefined
variables (such as @code{ARGC} or @code{NF}).
@item awk_bool_t sym_constant(const char *name, awk_value_t *value);
@@ -29649,7 +29667,7 @@ address@hidden (currently) is no @code{awk}-level
feature that
provides this ability.} The extension may change the value of @code{name}'s
variable with subsequent calls to this routine, and may also convert
a variable created by @code{sym_update()} into a constant. However,
-once a variable becomes a constant it cannot later be reverted into a
+once a variable becomes a constant, it cannot later be reverted into a
mutable variable.
@end table
@@ -29679,7 +29697,7 @@ Here too, the built-in variables may not be updated.
@end table
It is not obvious at first glance how to work with scalar cookies or
-what their @i{raison d'etre} really is. In theory, the @code{sym_lookup()}
+what their @i{raison address@hidden really is. In theory, the
@code{sym_lookup()}
and @code{sym_update()} routines are all you really need to work with
variables. For example, you might have code that looked up the value of
a variable, evaluated a condition, and then possibly changed the value
@@ -29853,7 +29871,11 @@ What happens if @command{awk} code assigns a new value
to @code{VAR1},
are all the others be changed too?''
That's a great question. The answer is that no, it's not a problem.
address@hidden is smart enough to avoid such problems.
+Internally, @command{gawk} uses reference-counted strings. This means
+that many variables can share the same string, and @command{gawk}
+keeps track of the usage. When a variable's value changes, @command{gawk}
+simply decrements the reference count on the old value and updates
+the variable to use the new value.
Finally, as part of your clean up action (@pxref{Exit Callback Functions})
you should release any cached values that you created, using
@@ -29916,13 +29938,13 @@ The fields are as follows:
@table @code
@item struct awk_element *next;
This pointer is for the convenience of extension writers. It allows
-an extension to create a linked list of new elements which can then be
+an extension to create a linked list of new elements that can then be
added to an array in a loop that traverses the list.
@item enum @{ @dots{} @} flags;
A set of flag values that convey information between @command{gawk}
-and the extension. Currently there is only one: @code{AWK_ELEMENT_DELETE},
-which the extension can set to cause @command{gawk} to delete the
+and the extension. Currently there is only one: @code{AWK_ELEMENT_DELETE}.
+Setting it causes @command{gawk} to delete the
element from the original array upon release of the flattened array.
@item index
@@ -30041,9 +30063,9 @@ First, the @command{gawk} script that drives the test
extension:
@@load "testext"
BEGIN @{
n = split("blacky rusty sophie raincloud lucky", pets)
- printf "pets has %d elements\n", length(pets)
+ printf("pets has %d elements\n", length(pets))
ret = dump_array_and_delete("pets", "3")
- printf "dump_array_and_delete(pets) returned %d\n", ret
+ printf("dump_array_and_delete(pets) returned %d\n", ret)
if ("3" in pets)
printf("dump_array_and_delete() did NOT remove index \"3\"!\n")
else
@@ -30251,7 +30273,7 @@ you must add the new array to its parent before adding
any elements to it.
Thus, the correct way to build an array is to work ``top down.'' Create
the array, and immediately install it in @command{gawk}'s symbol table
using @code{sym_update()}, or install it as an element in a previously
-existing array using @code{set_element()}. Example code is coming shortly.
+existing array using @code{set_element()}. We show example code shortly.
@item
Due to gawk internals, after using @code{sym_update()} to install an array
@@ -31684,8 +31706,8 @@ file:
On systems without the file type information, calling
@samp{readdir_do_ftype("stat")} causes the extension to use the
address@hidden()} system call to retrieve the appropriate information. This
-is not the default, since @code{lstat()} is a potentially expensive
address@hidden()} system call to retrieve the appropriate information. That
+is not the default, because @code{lstat()} is a potentially expensive
operation. By calling @samp{readdir_do_ftype("never")} one can ensure
that the file type information is never displayed, even when readily
available in the directory entry.
@@ -31853,7 +31875,7 @@ inserting @samp{@@load "time"} in your script.
Return the time in seconds that has elapsed since 1970-01-01 UTC as a
floating point value. If the time is unavailable on this platform, return
@minus{}1 and set @code{ERRNO}. The returned time should have sub-second
-precision, but the actual precision will vary based on the platform.
+precision, but the actual precision may vary based on the platform.
If the standard C @code{gettimeofday()} system call is available on this
platform, then it simply returns the value. Otherwise, if on Windows,
it tries to use @code{GetSystemTimeAsFileTime()}.
diff --git a/extension/ChangeLog b/extension/ChangeLog
index 004168f..12cbfcb 100644
--- a/extension/ChangeLog
+++ b/extension/ChangeLog
@@ -1,3 +1,8 @@
+2012-11-16 Arnold D. Robbins <address@hidden>
+
+ * testext.c: In awk code, use printf(...) instead of the form
+ without parentheses everywhere. This makes Nelson happy.
+
2012-11-14 Andrew J. Schorr <address@hidden>
Bug fix for filesystems without d_type in directory entry.
diff --git a/extension/testext.c b/extension/testext.c
index 06564b1..eef62bf 100644
--- a/extension/testext.c
+++ b/extension/testext.c
@@ -95,9 +95,9 @@ valrep2str(const awk_value_t *value)
@load "testext"
BEGIN {
n = split("blacky rusty sophie raincloud lucky", pets)
- printf "pets has %d elements\n", length(pets)
+ printf("pets has %d elements\n", length(pets))
ret = dump_array_and_delete("pets", "3")
- printf "dump_array_and_delete(pets) returned %d\n", ret
+ printf("dump_array_and_delete(pets) returned %d\n", ret)
if ("3" in pets)
printf("dump_array_and_delete() did NOT remove index \"3\"!\n")
else
@@ -283,7 +283,7 @@ out:
BEGIN {
testvar = "One Adam Twelve"
ret = var_test("testvar")
- printf "var_test() returned %d, test_var = %s\n", ret, testvar
+ printf("var_test() returned %d, test_var = %s\n", ret, testvar)
print ""
}
*/
@@ -345,7 +345,7 @@ out:
BEGIN {
ERRNO = ""
ret = test_errno()
- printf "test_errno() returned %d, ERRNO = %s\n", ret, ERRNO
+ printf("test_errno() returned %d, ERRNO = %s\n", ret, ERRNO)
print ""
}
*/
@@ -372,9 +372,9 @@ BEGIN {
for (i = 1; i <= 10; i++)
test_array[i] = i + 2
- printf ("length of test_array is %d, should be 10\n",
length(test_array))
+ printf("length of test_array is %d, should be 10\n", length(test_array))
ret = test_array_size(test_array);
- printf "test_array_size() returned %d, length is now %d\n", ret,
length(test_array)
+ printf("test_array_size() returned %d, length is now %d\n", ret,
length(test_array))
print ""
}
*/
@@ -422,24 +422,24 @@ out:
BEGIN {
n = split("one two three four five six", test_array2)
ret = test_array_elem(test_array2, "3")
- printf "test_array_elem() returned %d, test_array2[3] = %g\n", ret,
test_array2[3]
+ printf("test_array_elem() returned %d, test_array2[3] = %g\n", ret,
test_array2[3])
if ("5" in test_array2)
- printf "error: test_array_elem() did not remove element \"5\"\n"
+ printf("error: test_array_elem() did not remove element
\"5\"\n")
else
- printf "test_array_elem() did remove element \"5\"\n"
+ printf("test_array_elem() did remove element \"5\"\n")
if ("7" in test_array2)
- printf "test_array_elem() added element \"7\" --> %s\n",
test_array2[7]
+ printf("test_array_elem() added element \"7\" --> %s\n",
test_array2[7])
else
- printf "test_array_elem() did not add element \"7\"\n"
+ printf("test_array_elem() did not add element \"7\"\n")
if ("subarray" in test_array2) {
if (isarray(test_array2["subarray"])) {
for (i in test_array2["subarray"])
printf("test_array2[\"subarray\"][\"%s\"] =
%s\n",
i, test_array2["subarray"][i])
} else
- printf "test_array_elem() added element \"subarray\" as
scalar\n"
+ printf("test_array_elem() added element \"subarray\" as
scalar\n")
} else
- printf "test_array_elem() did not add element \"subarray\"\n"
+ printf("test_array_elem() did not add element \"subarray\"\n")
print ""
}
*/
@@ -516,8 +516,8 @@ out:
/*
BEGIN {
ret = test_array_param(a_new_array)
- printf "test_array_param() returned %d\n", ret
- printf "isarray(a_new_array) = %d\n", isarray(a_new_array)
+ printf("test_array_param() returned %d\n", ret)
+ printf("isarray(a_new_array) = %d\n", isarray(a_new_array))
if (isarray(a_new_array))
for (i in a_new_array)
printf("a_new_array[\"%s\"] = %s\n",
@@ -525,8 +525,8 @@ BEGIN {
a_scalar = 42
ret = test_array_param(a_scalar)
- printf "test_array_param() returned %d\n", ret
- printf "isarray(a_scalar) = %d\n", isarray(a_scalar)
+ printf("test_array_param() returned %d\n", ret)
+ printf("isarray(a_scalar) = %d\n", isarray(a_scalar))
print ""
}
*/
@@ -563,13 +563,13 @@ out:
/*
BEGIN {
- printf "Initial value of LINT is %d\n", LINT
+ printf("Initial value of LINT is %d\n", LINT)
ret = print_do_lint();
- printf "print_do_lint() returned %d\n", ret
+ printf("print_do_lint() returned %d\n", ret)
LINT = ! LINT
- printf "Changed value of LINT is %d\n", LINT
+ printf("Changed value of LINT is %d\n", LINT)
ret = print_do_lint();
- printf "print_do_lint() returned %d\n", ret
+ printf("print_do_lint() returned %d\n", ret)
print ""
}
*/
-----------------------------------------------------------------------
Summary of changes:
doc/ChangeLog | 5 +
doc/gawk.info | 348 ++++++++++++++++++++++++++------------------------
doc/gawk.texi | 86 ++++++++-----
extension/ChangeLog | 5 +
extension/testext.c | 42 +++---
5 files changed, 266 insertions(+), 220 deletions(-)
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gawk-diffs] [SCM] gawk branch, master, updated. adb0a3271736be1b8c9a899d7e42ac9777837688,
Arnold Robbins <=