[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawk-diffs] [SCM] gawk branch, master, updated. b68a7db5669521f4c56dc69
|
From: |
Arnold Robbins |
|
Subject: |
[gawk-diffs] [SCM] gawk branch, master, updated. b68a7db5669521f4c56dc690a12588422548fa53 |
|
Date: |
Sun, 16 Dec 2012 13:35:55 +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 b68a7db5669521f4c56dc690a12588422548fa53 (commit)
from 9f87da605cc746045f1bd6a697e10a766ce26ad5 (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=b68a7db5669521f4c56dc690a12588422548fa53
commit b68a7db5669521f4c56dc690a12588422548fa53
Author: Arnold D. Robbins <address@hidden>
Date: Sun Dec 16 15:35:29 2012 +0200
Move API design decisions to appendix.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 8b3fe26..d599237 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2012-12-16 Arnold D. Robbins <address@hidden>
+
+ * gawk.texi: Move design decisions on new API to appendix C.
+
2012-12-15 Arnold D. Robbins <address@hidden>
* macros: Update to GPL Version 3 and add copyright year.
diff --git a/doc/gawk.info b/doc/gawk.info
index 4a65ec7..b3c7a69 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -513,12 +513,7 @@ texts being (a) (see below), and with the Back-Cover Texts
being (b)
with `gawk'.
* Extension Intro:: What is an extension.
* Plugin License:: A note about licensing.
-* Extension Design:: Design notes about the extension API.
-* Old Extension Problems:: Problems with the old mechanism.
-* Extension New Mechanism Goals:: Goals for the new mechanism.
-* Extension Other Design Decisions:: Some other design decisions.
* Extension Mechanism Outline:: An outline of how it works.
-* Extension Future Growth:: Some room for future growth.
* Extension API Description:: A full description of the API.
* Extension API Functions Introduction:: Introduction to the API functions.
* General Data Types:: The data types.
@@ -636,7 +631,13 @@ texts being (a) (see below), and with the Back-Cover Texts
being (b)
`git' repository.
* Future Extensions:: New features that may be implemented
one day.
-* Implementation Limitations:: Some limitations of the implementation.
+* Implementation Limitations:: Some limitations of the
+ implementation.
+* Extension Design:: Design notes about the extension API.
+* Old Extension Problems:: Problems with the old mechanism.
+* Extension New Mechanism Goals:: Goals for the new mechanism.
+* Extension Other Design Decisions:: Some other design decisions.
+* Extension Future Growth:: Some room for future growth.
* Basic High Level:: The high level view.
* Basic Data Typing:: A very quick intro to data types.
@@ -21368,7 +21369,7 @@ 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
the extensions that come with `gawk' (*note Extension Samples::), and
-the minor node on the `gawkextlib' project (*note gawkextlib::). The
+the information on the `gawkextlib' project (*note gawkextlib::). The
sample extensions are automatically built and installed when `gawk' is.
NOTE: When `--sandbox' is specified, extensions are disabled
@@ -21378,7 +21379,7 @@ sample extensions are automatically built and installed
when `gawk' is.
* Extension Intro:: What is an extension.
* Plugin License:: A note about licensing.
-* Extension Design:: Design notes about the extension API.
+* Extension Mechanism Outline:: An outline of how it works.
* Extension API Description:: A full description of the API.
* Extension Example:: Example C code for an extension.
* Extension Samples:: The sample extensions that ship with
@@ -21412,7 +21413,7 @@ sample extensions included in the `gawk' distribution,
and describes
the `gawkextlib' project.
-File: gawk.info, Node: Plugin License, Next: Extension Design, Prev:
Extension Intro, Up: Dynamic Extensions
+File: gawk.info, Node: Plugin License, Next: Extension Mechanism Outline,
Prev: Extension Intro, Up: Dynamic Extensions
16.2 Extension Licensing
========================
@@ -21429,203 +21430,14 @@ the symbol exists in the global scope. Something
like this is enough:
int plugin_is_GPL_compatible;
-File: gawk.info, Node: Extension Design, Next: Extension API Description,
Prev: Plugin License, Up: Dynamic Extensions
-
-16.3 Extension API Design
-=========================
-
-The first version of extensions for `gawk' was developed in the
-mid-1990s and released with `gawk' 3.1 in the late 1990s. The basic
-mechanisms and design remained unchanged for close to 15 years, until
-2012.
-
- The old extension mechanism used data types and functions from
-`gawk' itself, with a "clever hack" to install extension functions.
-
- `gawk' included some sample extensions, of which a few were really
-useful. However, it was clear from the outset that the extension
-mechanism was bolted onto the side and was not really thought out.
-
-* Menu:
-
-* Old Extension Problems:: Problems with the old mechanism.
-* Extension New Mechanism Goals:: Goals for the new mechanism.
-* Extension Other Design Decisions:: Some other design decisions.
-* Extension Mechanism Outline:: An outline of how it works.
-* Extension Future Growth:: Some room for future growth.
-
-
-File: gawk.info, Node: Old Extension Problems, Next: Extension New Mechanism
Goals, Up: Extension Design
-
-16.3.1 Problems With The Old Mechanism
---------------------------------------
-
-The old extension mechanism had several problems:
-
- * It depended heavily upon `gawk' internals. Any time the `NODE'
- structure(1) changed, an extension would have to be recompiled.
- Furthermore, to really write extensions required understanding
- something about `gawk''s internal functions. There was some
- documentation in this Info file, but it was quite minimal.
-
- * Being able to call into `gawk' from an extension required linker
- facilities that are common on Unix-derived systems but that did
- not work on Windows systems; users wanting extensions on Windows
- had to statically link them into `gawk', even though Windows
- supports dynamic loading of shared objects.
-
- * The API would change occasionally as `gawk' changed; no
- compatibility between versions was ever offered or planned for.
-
- Despite the drawbacks, the `xgawk' project developers forked `gawk'
-and developed several significant extensions. They also enhanced
-`gawk''s facilities relating to file inclusion and shared object access.
-
- A new API was desired for a long time, but only in 2012 did the
-`gawk' maintainer and the `xgawk' developers finally start working on
-it together. More information about the `xgawk' project is provided in
-*note gawkextlib::.
-
- ---------- Footnotes ----------
-
- (1) A critical central data structure inside `gawk'.
-
-
-File: gawk.info, Node: Extension New Mechanism Goals, Next: Extension Other
Design Decisions, Prev: Old Extension Problems, Up: Extension Design
-
-16.3.2 Goals For A New Mechanism
---------------------------------
-
-Some goals for the new API were:
-
- * The API should be independent of `gawk' internals. Changes in
- `gawk' internals should not be visible to the writer of an
- extension function.
-
- * The API should provide _binary_ compatibility across `gawk'
- releases as long as the API itself does not change.
-
- * The API should enable extensions written in C to have roughly the
- same "appearance" to `awk'-level code as `awk' functions do. This
- means that extensions should have:
-
- - The ability to access function parameters.
-
- - The ability to turn an undefined parameter into an array
- (call by reference).
-
- - The ability to create, access and update global variables.
-
- - Easy access to all the elements of an array at once ("array
- flattening") in order to loop over all the element in an easy
- fashion for C code.
-
- - The ability to create arrays (including `gawk''s true
- multi-dimensional arrays).
-
- Some additional important goals were:
-
- * The API should use only features in ISO C 90, so that extensions
- can be written using the widest range of C and C++ compilers. The
- header should include the appropriate `#ifdef __cplusplus' and
- `extern "C"' magic so that a C++ compiler could be used. (If
- using C++, the runtime system has to be smart enough to call any
- constructors and destructors, as `gawk' is a C program. As of this
- writing, this has not been tested.)
-
- * The API mechanism should not require access to `gawk''s symbols(1)
- by the compile-time or dynamic linker, in order to enable creation
- of extensions that also work on Windows.
-
- During development, it became clear that there were other features
-that should be available to extensions, which were also subsequently
-provided:
-
- * Extensions should have the ability to hook into `gawk''s I/O
- redirection mechanism. In particular, the `xgawk' developers
- provided a so-called "open hook" to take over reading records.
- During development, this was generalized to allow extensions to
- hook into input processing, output processing, and two-way I/O.
-
- * An extension should be able to provide a "call back" function to
- perform clean up actions when `gawk' exits.
-
- * An extension should be able to provide a version string so that
- `gawk''s `--version' option can provide information about
- extensions as well.
-
- ---------- Footnotes ----------
-
- (1) The "symbols" are the variables and functions defined inside
-`gawk'. Access to these symbols by code external to `gawk' loaded
-dynamically at runtime is problematic on Windows.
-
-
-File: gawk.info, Node: Extension Other Design Decisions, Next: Extension
Mechanism Outline, Prev: Extension New Mechanism Goals, Up: Extension Design
-
-16.3.3 Other Design Decisions
------------------------------
-
-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'.
+File: gawk.info, Node: Extension Mechanism Outline, Next: Extension API
Description, Prev: Plugin License, Up: Dynamic Extensions
- The reason for this is to prevent an extension function from
-affecting the flow of an `awk' program outside its control. While a
-real `awk' function can do what it likes, that is at the discretion of
-the programmer. An extension function should provide a service or make
-a C API available for use within `awk', and not mess with `FS' or
-`ARGC' and `ARGV'.
-
- In addition, it becomes easy to start down a slippery slope. How
-much access to `gawk' facilities do extensions need? Do they need
-`getline'? What about calling `gsub()' or compiling regular
-expressions? What about calling into `awk' functions? (_That_ would be
-messy.)
-
- In order to avoid these issues, the `gawk' developers chose to start
-with the simplest, most basic features that are still truly useful.
-
- Another decision is that although `gawk' provides nice things like
-MPFR, and arrays indexed internally by integers, these features are not
-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
-extensions.
-
-
-File: gawk.info, Node: Extension Mechanism Outline, Next: Extension Future
Growth, Prev: Extension Other Design Decisions, Up: Extension Design
-
-16.3.4 At A High Level How It Works
------------------------------------
-
-The requirement to avoid access to `gawk''s symbols is, at first
-glance, a difficult one to meet.
-
- One design, apparently used by Perl and Ruby and maybe others, would
-be to make the mainline `gawk' code into a library, with the `gawk'
-utility a small C `main()' function linked against the library.
-
- This seemed like the tail wagging the dog, complicating build and
-installation and making a simple copy of the `gawk' executable from one
-system to another (or one place to another on the same system!) into a
-chancy operation.
+16.3 At A High Level How It Works
+=================================
- Pat Rankin suggested the solution that was adopted. Communication
-between `gawk' and an extension is two-way. First, when an extension
-is loaded, it is passed a pointer to a `struct' whose fields are
-function pointers. This is shown in *note load-extension::.
+Communication between `gawk' and an extension is two-way. First, when
+an extension is loaded, it is passed a pointer to a `struct' whose
+fields are function pointers. This is shown in *note load-extension::.
API
Struct
@@ -21722,28 +21534,7 @@ Example::) and also the `testext.c' code for testing
the APIs.
Versioning::, for details.
-File: gawk.info, Node: Extension Future Growth, Prev: Extension Mechanism
Outline, Up: Extension Design
-
-16.3.5 Room For Future Growth
------------------------------
-
-The API can later be expanded, in two ways:
-
- * `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.
-
- * 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.
-
-
-File: gawk.info, Node: Extension API Description, Next: Extension Example,
Prev: Extension Design, Up: Dynamic Extensions
+File: gawk.info, Node: Extension API Description, Next: Extension Example,
Prev: Extension Mechanism Outline, Up: Dynamic Extensions
16.4 API Description
====================
@@ -23159,12 +22950,12 @@ as a nice example to show how to use the APIs.
}
This code creates an array with `split()' (*note String Functions::)
-and then calls `dump_and_delete()'. That function looks up the array
-whose name is passed as the first argument, and deletes the element at
-the index passed in the second argument. It then prints the return
-value and checks if the element was indeed deleted. Here is the C code
-that implements `dump_array_and_delete()'. It has been edited slightly
-for presentation.
+and then calls `dump_array_and_delete()'. That function looks up the
+array whose name is passed as the first argument, and deletes the
+element at the index passed in the second argument. It then prints the
+return value and checks if the element was indeed deleted. Here is the
+C code that implements `dump_array_and_delete()'. It has been edited
+slightly for presentation.
The first part declares variables, sets up the default return value
in `result', and checks that the function was called with the correct
@@ -26496,6 +26287,7 @@ and maintainers of `gawk'. Everything in it applies
specifically to
* Additions:: Making Additions To `gawk'.
* Future Extensions:: New features that may be implemented one day.
* Implementation Limitations:: Some limitations of the implementation.
+* Extension Design:: Design notes about the extension API.
File: gawk.info, Node: Compatibility Mode, Next: Additions, Up: Notes
@@ -26959,7 +26751,7 @@ Additions::, if you are interested in tackling any of
the projects
listed there.
-File: gawk.info, Node: Implementation Limitations, Prev: Future Extensions,
Up: Notes
+File: gawk.info, Node: Implementation Limitations, Next: Extension Design,
Prev: Future Extensions, Up: Notes
C.4 Some Limitations of the Implementation
==========================================
@@ -26990,6 +26782,220 @@ Size of a literal string `MAX_INT '
Size of a printf string `MAX_INT '
+File: gawk.info, Node: Extension Design, Prev: Implementation Limitations,
Up: Notes
+
+C.5 Extension API Design
+========================
+
+This minor node documents the design of the extension API, including a
+discussion of some of the history and problems that needed to be solved.
+
+ The first version of extensions for `gawk' was developed in the
+mid-1990s and released with `gawk' 3.1 in the late 1990s. The basic
+mechanisms and design remained unchanged for close to 15 years, until
+2012.
+
+ The old extension mechanism used data types and functions from
+`gawk' itself, with a "clever hack" to install extension functions.
+
+ `gawk' included some sample extensions, of which a few were really
+useful. However, it was clear from the outset that the extension
+mechanism was bolted onto the side and was not really thought out.
+
+* Menu:
+
+* Old Extension Problems:: Problems with the old mechanism.
+* Extension New Mechanism Goals:: Goals for the new mechanism.
+* Extension Other Design Decisions:: Some other design decisions.
+* Extension Future Growth:: Some room for future growth.
+
+
+File: gawk.info, Node: Old Extension Problems, Next: Extension New Mechanism
Goals, Up: Extension Design
+
+C.5.1 Problems With The Old Mechanism
+-------------------------------------
+
+The old extension mechanism had several problems:
+
+ * It depended heavily upon `gawk' internals. Any time the `NODE'
+ structure(1) changed, an extension would have to be recompiled.
+ Furthermore, to really write extensions required understanding
+ something about `gawk''s internal functions. There was some
+ documentation in this Info file, but it was quite minimal.
+
+ * Being able to call into `gawk' from an extension required linker
+ facilities that are common on Unix-derived systems but that did
+ not work on Windows systems; users wanting extensions on Windows
+ had to statically link them into `gawk', even though Windows
+ supports dynamic loading of shared objects.
+
+ * The API would change occasionally as `gawk' changed; no
+ compatibility between versions was ever offered or planned for.
+
+ Despite the drawbacks, the `xgawk' project developers forked `gawk'
+and developed several significant extensions. They also enhanced
+`gawk''s facilities relating to file inclusion and shared object access.
+
+ A new API was desired for a long time, but only in 2012 did the
+`gawk' maintainer and the `xgawk' developers finally start working on
+it together. More information about the `xgawk' project is provided in
+*note gawkextlib::.
+
+ ---------- Footnotes ----------
+
+ (1) A critical central data structure inside `gawk'.
+
+
+File: gawk.info, Node: Extension New Mechanism Goals, Next: Extension Other
Design Decisions, Prev: Old Extension Problems, Up: Extension Design
+
+C.5.2 Goals For A New Mechanism
+-------------------------------
+
+Some goals for the new API were:
+
+ * The API should be independent of `gawk' internals. Changes in
+ `gawk' internals should not be visible to the writer of an
+ extension function.
+
+ * The API should provide _binary_ compatibility across `gawk'
+ releases as long as the API itself does not change.
+
+ * The API should enable extensions written in C to have roughly the
+ same "appearance" to `awk'-level code as `awk' functions do. This
+ means that extensions should have:
+
+ - The ability to access function parameters.
+
+ - The ability to turn an undefined parameter into an array
+ (call by reference).
+
+ - The ability to create, access and update global variables.
+
+ - Easy access to all the elements of an array at once ("array
+ flattening") in order to loop over all the element in an easy
+ fashion for C code.
+
+ - The ability to create arrays (including `gawk''s true
+ multi-dimensional arrays).
+
+ Some additional important goals were:
+
+ * The API should use only features in ISO C 90, so that extensions
+ can be written using the widest range of C and C++ compilers. The
+ header should include the appropriate `#ifdef __cplusplus' and
+ `extern "C"' magic so that a C++ compiler could be used. (If
+ using C++, the runtime system has to be smart enough to call any
+ constructors and destructors, as `gawk' is a C program. As of this
+ writing, this has not been tested.)
+
+ * The API mechanism should not require access to `gawk''s symbols(1)
+ by the compile-time or dynamic linker, in order to enable creation
+ of extensions that also work on Windows.
+
+ During development, it became clear that there were other features
+that should be available to extensions, which were also subsequently
+provided:
+
+ * Extensions should have the ability to hook into `gawk''s I/O
+ redirection mechanism. In particular, the `xgawk' developers
+ provided a so-called "open hook" to take over reading records.
+ During development, this was generalized to allow extensions to
+ hook into input processing, output processing, and two-way I/O.
+
+ * An extension should be able to provide a "call back" function to
+ perform clean up actions when `gawk' exits.
+
+ * An extension should be able to provide a version string so that
+ `gawk''s `--version' option can provide information about
+ extensions as well.
+
+ The requirement to avoid access to `gawk''s symbols is, at first
+glance, a difficult one to meet.
+
+ One design, apparently used by Perl and Ruby and maybe others, would
+be to make the mainline `gawk' code into a library, with the `gawk'
+utility a small C `main()' function linked against the library.
+
+ This seemed like the tail wagging the dog, complicating build and
+installation and making a simple copy of the `gawk' executable from one
+system to another (or one place to another on the same system!) into a
+chancy operation.
+
+ Pat Rankin suggested the solution that was adopted. *Note Extension
+Mechanism Outline::, for the details.
+
+ ---------- Footnotes ----------
+
+ (1) The "symbols" are the variables and functions defined inside
+`gawk'. Access to these symbols by code external to `gawk' loaded
+dynamically at runtime is problematic on Windows.
+
+
+File: gawk.info, Node: Extension Other Design Decisions, Next: Extension
Future Growth, Prev: Extension New Mechanism Goals, Up: Extension Design
+
+C.5.3 Other Design Decisions
+----------------------------
+
+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'.
+
+ The reason for this is to prevent an extension function from
+affecting the flow of an `awk' program outside its control. While a
+real `awk' function can do what it likes, that is at the discretion of
+the programmer. An extension function should provide a service or make
+a C API available for use within `awk', and not mess with `FS' or
+`ARGC' and `ARGV'.
+
+ In addition, it becomes easy to start down a slippery slope. How
+much access to `gawk' facilities do extensions need? Do they need
+`getline'? What about calling `gsub()' or compiling regular
+expressions? What about calling into `awk' functions? (_That_ would be
+messy.)
+
+ In order to avoid these issues, the `gawk' developers chose to start
+with the simplest, most basic features that are still truly useful.
+
+ Another decision is that although `gawk' provides nice things like
+MPFR, and arrays indexed internally by integers, these features are not
+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
+extensions.
+
+
+File: gawk.info, Node: Extension Future Growth, Prev: Extension Other Design
Decisions, Up: Extension Design
+
+C.5.4 Room For Future Growth
+----------------------------
+
+The API can later be expanded, in two ways:
+
+ * `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.
+
+ * 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.
+
+
File: gawk.info, Node: Basic Concepts, Next: Glossary, Prev: Notes, Up: Top
Appendix D Basic Programming Concepts
@@ -31779,516 +31785,516 @@ Index
Tag Table:
Node: Top1352
-Node: Foreword40138
-Node: Preface44483
-Ref: Preface-Footnote-147536
-Ref: Preface-Footnote-247642
-Node: History47874
-Node: Names50265
-Ref: Names-Footnote-151742
-Node: This Manual51814
-Ref: This Manual-Footnote-157720
-Node: Conventions57820
-Node: Manual History59954
-Ref: Manual History-Footnote-163224
-Ref: Manual History-Footnote-263265
-Node: How To Contribute63339
-Node: Acknowledgments64483
-Node: Getting Started68979
-Node: Running gawk71358
-Node: One-shot72544
-Node: Read Terminal73769
-Ref: Read Terminal-Footnote-175419
-Ref: Read Terminal-Footnote-275695
-Node: Long75866
-Node: Executable Scripts77242
-Ref: Executable Scripts-Footnote-179111
-Ref: Executable Scripts-Footnote-279213
-Node: Comments79760
-Node: Quoting82227
-Node: DOS Quoting86850
-Node: Sample Data Files87525
-Node: Very Simple90557
-Node: Two Rules95156
-Node: More Complex97303
-Ref: More Complex-Footnote-1100233
-Node: Statements/Lines100318
-Ref: Statements/Lines-Footnote-1104780
-Node: Other Features105045
-Node: When105973
-Node: Invoking Gawk108120
-Node: Command Line109581
-Node: Options110364
-Ref: Options-Footnote-1125762
-Node: Other Arguments125787
-Node: Naming Standard Input128445
-Node: Environment Variables129539
-Node: AWKPATH Variable130097
-Ref: AWKPATH Variable-Footnote-1132855
-Node: AWKLIBPATH Variable133115
-Node: Other Environment Variables133712
-Node: Exit Status136207
-Node: Include Files136882
-Node: Loading Shared Libraries140451
-Node: Obsolete141676
-Node: Undocumented142373
-Node: Regexp142616
-Node: Regexp Usage144005
-Node: Escape Sequences146031
-Node: Regexp Operators151794
-Ref: Regexp Operators-Footnote-1159174
-Ref: Regexp Operators-Footnote-2159321
-Node: Bracket Expressions159419
-Ref: table-char-classes161309
-Node: GNU Regexp Operators163832
-Node: Case-sensitivity167555
-Ref: Case-sensitivity-Footnote-1170523
-Ref: Case-sensitivity-Footnote-2170758
-Node: Leftmost Longest170866
-Node: Computed Regexps172067
-Node: Reading Files175477
-Node: Records177480
-Ref: Records-Footnote-1186404
-Node: Fields186441
-Ref: Fields-Footnote-1189474
-Node: Nonconstant Fields189560
-Node: Changing Fields191762
-Node: Field Separators197743
-Node: Default Field Splitting200372
-Node: Regexp Field Splitting201489
-Node: Single Character Fields204831
-Node: Command Line Field Separator205890
-Node: Field Splitting Summary209331
-Ref: Field Splitting Summary-Footnote-1212523
-Node: Constant Size212624
-Node: Splitting By Content217208
-Ref: Splitting By Content-Footnote-1220934
-Node: Multiple Line220974
-Ref: Multiple Line-Footnote-1226821
-Node: Getline227000
-Node: Plain Getline229216
-Node: Getline/Variable231305
-Node: Getline/File232446
-Node: Getline/Variable/File233768
-Ref: Getline/Variable/File-Footnote-1235367
-Node: Getline/Pipe235454
-Node: Getline/Variable/Pipe238014
-Node: Getline/Coprocess239121
-Node: Getline/Variable/Coprocess240364
-Node: Getline Notes241078
-Node: Getline Summary243865
-Ref: table-getline-variants244273
-Node: Read Timeout245131
-Ref: Read Timeout-Footnote-1248876
-Node: Command line directories248933
-Node: Printing249563
-Node: Print251194
-Node: Print Examples252531
-Node: Output Separators255315
-Node: OFMT257075
-Node: Printf258433
-Node: Basic Printf259339
-Node: Control Letters260878
-Node: Format Modifiers264690
-Node: Printf Examples270699
-Node: Redirection273414
-Node: Special Files280398
-Node: Special FD280931
-Ref: Special FD-Footnote-1284556
-Node: Special Network284630
-Node: Special Caveats285480
-Node: Close Files And Pipes286276
-Ref: Close Files And Pipes-Footnote-1293299
-Ref: Close Files And Pipes-Footnote-2293447
-Node: Expressions293597
-Node: Values294729
-Node: Constants295405
-Node: Scalar Constants296085
-Ref: Scalar Constants-Footnote-1296944
-Node: Nondecimal-numbers297126
-Node: Regexp Constants300185
-Node: Using Constant Regexps300660
-Node: Variables303715
-Node: Using Variables304370
-Node: Assignment Options306094
-Node: Conversion307966
-Ref: table-locale-affects313342
-Ref: Conversion-Footnote-1313966
-Node: All Operators314075
-Node: Arithmetic Ops314705
-Node: Concatenation317210
-Ref: Concatenation-Footnote-1320003
-Node: Assignment Ops320123
-Ref: table-assign-ops325111
-Node: Increment Ops326519
-Node: Truth Values and Conditions329989
-Node: Truth Values331072
-Node: Typing and Comparison332121
-Node: Variable Typing332910
-Ref: Variable Typing-Footnote-1336807
-Node: Comparison Operators336929
-Ref: table-relational-ops337339
-Node: POSIX String Comparison340888
-Ref: POSIX String Comparison-Footnote-1341844
-Node: Boolean Ops341982
-Ref: Boolean Ops-Footnote-1346060
-Node: Conditional Exp346151
-Node: Function Calls347883
-Node: Precedence351477
-Node: Locales355146
-Node: Patterns and Actions356235
-Node: Pattern Overview357289
-Node: Regexp Patterns358958
-Node: Expression Patterns359501
-Node: Ranges363186
-Node: BEGIN/END366152
-Node: Using BEGIN/END366914
-Ref: Using BEGIN/END-Footnote-1369645
-Node: I/O And BEGIN/END369751
-Node: BEGINFILE/ENDFILE372033
-Node: Empty374937
-Node: Using Shell Variables375253
-Node: Action Overview377538
-Node: Statements379895
-Node: If Statement381749
-Node: While Statement383248
-Node: Do Statement385292
-Node: For Statement386448
-Node: Switch Statement389600
-Node: Break Statement391697
-Node: Continue Statement393687
-Node: Next Statement395480
-Node: Nextfile Statement397870
-Node: Exit Statement400511
-Node: Built-in Variables402927
-Node: User-modified404022
-Ref: User-modified-Footnote-1412377
-Node: Auto-set412439
-Ref: Auto-set-Footnote-1424790
-Ref: Auto-set-Footnote-2424995
-Node: ARGC and ARGV425051
-Node: Arrays428902
-Node: Array Basics430407
-Node: Array Intro431233
-Node: Reference to Elements435551
-Node: Assigning Elements437821
-Node: Array Example438312
-Node: Scanning an Array440044
-Node: Controlling Scanning442358
-Ref: Controlling Scanning-Footnote-1447291
-Node: Delete447607
-Ref: Delete-Footnote-1450372
-Node: Numeric Array Subscripts450429
-Node: Uninitialized Subscripts452612
-Node: Multi-dimensional454240
-Node: Multi-scanning457334
-Node: Arrays of Arrays458925
-Node: Functions463570
-Node: Built-in464389
-Node: Calling Built-in465467
-Node: Numeric Functions467455
-Ref: Numeric Functions-Footnote-1471287
-Ref: Numeric Functions-Footnote-2471644
-Ref: Numeric Functions-Footnote-3471692
-Node: String Functions471961
-Ref: String Functions-Footnote-1495458
-Ref: String Functions-Footnote-2495587
-Ref: String Functions-Footnote-3495835
-Node: Gory Details495922
-Ref: table-sub-escapes497601
-Ref: table-sub-posix-92498955
-Ref: table-sub-proposed500306
-Ref: table-posix-sub501660
-Ref: table-gensub-escapes503205
-Ref: Gory Details-Footnote-1504412
-Ref: Gory Details-Footnote-2504463
-Node: I/O Functions504614
-Ref: I/O Functions-Footnote-1511719
-Node: Time Functions511866
-Ref: Time Functions-Footnote-1522758
-Ref: Time Functions-Footnote-2522826
-Ref: Time Functions-Footnote-3522984
-Ref: Time Functions-Footnote-4523095
-Ref: Time Functions-Footnote-5523207
-Ref: Time Functions-Footnote-6523434
-Node: Bitwise Functions523700
-Ref: table-bitwise-ops524258
-Ref: Bitwise Functions-Footnote-1528479
-Node: Type Functions528663
-Node: I18N Functions529133
-Node: User-defined530760
-Node: Definition Syntax531564
-Ref: Definition Syntax-Footnote-1536474
-Node: Function Example536543
-Node: Function Caveats539137
-Node: Calling A Function539558
-Node: Variable Scope540673
-Node: Pass By Value/Reference543636
-Node: Return Statement547076
-Node: Dynamic Typing550057
-Node: Indirect Calls550792
-Node: Library Functions560477
-Ref: Library Functions-Footnote-1563476
-Node: Library Names563647
-Ref: Library Names-Footnote-1567118
-Ref: Library Names-Footnote-2567338
-Node: General Functions567424
-Node: Strtonum Function568377
-Node: Assert Function571307
-Node: Round Function574633
-Node: Cliff Random Function576176
-Node: Ordinal Functions577192
-Ref: Ordinal Functions-Footnote-1580262
-Ref: Ordinal Functions-Footnote-2580514
-Node: Join Function580723
-Ref: Join Function-Footnote-1582494
-Node: Getlocaltime Function582694
-Node: Data File Management586409
-Node: Filetrans Function587041
-Node: Rewind Function591180
-Node: File Checking592567
-Node: Empty Files593661
-Node: Ignoring Assigns595891
-Node: Getopt Function597444
-Ref: Getopt Function-Footnote-1608748
-Node: Passwd Functions608951
-Ref: Passwd Functions-Footnote-1617926
-Node: Group Functions618014
-Node: Walking Arrays626098
-Node: Sample Programs627667
-Node: Running Examples628344
-Node: Clones629072
-Node: Cut Program630296
-Node: Egrep Program640141
-Ref: Egrep Program-Footnote-1647914
-Node: Id Program648024
-Node: Split Program651640
-Ref: Split Program-Footnote-1655159
-Node: Tee Program655287
-Node: Uniq Program658090
-Node: Wc Program665519
-Ref: Wc Program-Footnote-1669785
-Ref: Wc Program-Footnote-2669985
-Node: Miscellaneous Programs670077
-Node: Dupword Program671265
-Node: Alarm Program673296
-Node: Translate Program678045
-Ref: Translate Program-Footnote-1682432
-Ref: Translate Program-Footnote-2682660
-Node: Labels Program682794
-Ref: Labels Program-Footnote-1686165
-Node: Word Sorting686249
-Node: History Sorting690133
-Node: Extract Program691972
-Ref: Extract Program-Footnote-1699455
-Node: Simple Sed699583
-Node: Igawk Program702645
-Ref: Igawk Program-Footnote-1717802
-Ref: Igawk Program-Footnote-2718003
-Node: Anagram Program718141
-Node: Signature Program721209
-Node: Internationalization722309
-Node: I18N and L10N723741
-Node: Explaining gettext724427
-Ref: Explaining gettext-Footnote-1729493
-Ref: Explaining gettext-Footnote-2729677
-Node: Programmer i18n729842
-Node: Translator i18n734042
-Node: String Extraction734835
-Ref: String Extraction-Footnote-1735796
-Node: Printf Ordering735882
-Ref: Printf Ordering-Footnote-1738666
-Node: I18N Portability738730
-Ref: I18N Portability-Footnote-1741179
-Node: I18N Example741242
-Ref: I18N Example-Footnote-1743877
-Node: Gawk I18N743949
-Node: Advanced Features744566
-Node: Nondecimal Data746070
-Node: Array Sorting747653
-Node: Controlling Array Traversal748350
-Node: Array Sorting Functions756588
-Ref: Array Sorting Functions-Footnote-1760262
-Ref: Array Sorting Functions-Footnote-2760355
-Node: Two-way I/O760549
-Ref: Two-way I/O-Footnote-1765981
-Node: TCP/IP Networking766051
-Node: Profiling768895
-Node: Debugger776349
-Node: Debugging777317
-Node: Debugging Concepts777750
-Node: Debugging Terms779606
-Node: Awk Debugging782203
-Node: Sample Debugging Session783095
-Node: Debugger Invocation783615
-Node: Finding The Bug784944
-Node: List of Debugger Commands791432
-Node: Breakpoint Control792766
-Node: Debugger Execution Control796430
-Node: Viewing And Changing Data799790
-Node: Execution Stack803146
-Node: Debugger Info804613
-Node: Miscellaneous Debugger Commands808594
-Node: Readline Support814039
-Node: Limitations814870
-Node: Arbitrary Precision Arithmetic817122
-Ref: Arbitrary Precision Arithmetic-Footnote-1818764
-Node: General Arithmetic818912
-Node: Floating Point Issues820632
-Node: String Conversion Precision821513
-Ref: String Conversion Precision-Footnote-1823219
-Node: Unexpected Results823328
-Node: POSIX Floating Point Problems825481
-Ref: POSIX Floating Point Problems-Footnote-1829306
-Node: Integer Programming829344
-Node: Floating-point Programming831097
-Ref: Floating-point Programming-Footnote-1837406
-Node: Floating-point Representation837670
-Node: Floating-point Context838835
-Ref: table-ieee-formats839677
-Node: Rounding Mode841061
-Ref: table-rounding-modes841540
-Ref: Rounding Mode-Footnote-1844544
-Node: Gawk and MPFR844725
-Node: Arbitrary Precision Floats845967
-Ref: Arbitrary Precision Floats-Footnote-1848396
-Node: Setting Precision848707
-Node: Setting Rounding Mode851440
-Ref: table-gawk-rounding-modes851844
-Node: Floating-point Constants853024
-Node: Changing Precision854448
-Ref: Changing Precision-Footnote-1855848
-Node: Exact Arithmetic856022
-Node: Arbitrary Precision Integers859130
-Ref: Arbitrary Precision Integers-Footnote-1862130
-Node: Dynamic Extensions862277
-Node: Extension Intro863663
-Node: Plugin License864871
-Node: Extension Design865545
-Node: Old Extension Problems866616
-Ref: Old Extension Problems-Footnote-1868126
-Node: Extension New Mechanism Goals868183
-Ref: Extension New Mechanism Goals-Footnote-1870895
-Node: Extension Other Design Decisions871081
-Node: Extension Mechanism Outline873193
-Ref: load-extension874218
-Ref: load-new-function875696
-Ref: call-new-function876677
-Node: Extension Future Growth878671
-Node: Extension API Description879489
-Node: Extension API Functions Introduction880817
-Node: General Data Types885595
-Ref: General Data Types-Footnote-1891197
-Node: Requesting Values891496
-Ref: table-value-types-returned892227
-Node: Constructor Functions893181
-Node: Registration Functions896177
-Node: Extension Functions896862
-Node: Exit Callback Functions899036
-Node: Extension Version String900279
-Node: Input Parsers900929
-Node: Output Wrappers909516
-Node: Two-way processors913932
-Node: Printing Messages916062
-Ref: Printing Messages-Footnote-1917139
-Node: Updating `ERRNO'917291
-Node: Accessing Parameters918030
-Node: Symbol Table Access919260
-Node: Symbol table by name919772
-Ref: Symbol table by name-Footnote-1921942
-Node: Symbol table by cookie922022
-Ref: Symbol table by cookie-Footnote-1926151
-Node: Cached values926214
-Ref: Cached values-Footnote-1929657
-Node: Array Manipulation929748
-Ref: Array Manipulation-Footnote-1930846
-Node: Array Data Types930885
-Ref: Array Data Types-Footnote-1933588
-Node: Array Functions933680
-Node: Flattening Arrays937446
-Node: Creating Arrays944279
-Node: Extension API Variables949074
-Node: Extension Versioning949710
-Node: Extension API Informational Variables951611
-Node: Extension API Boilerplate952697
-Node: Finding Extensions956528
-Node: Extension Example957075
-Node: Internal File Description957813
-Node: Internal File Ops961501
-Ref: Internal File Ops-Footnote-1972948
-Node: Using Internal File Ops973088
-Ref: Using Internal File Ops-Footnote-1975441
-Node: Extension Samples975707
-Node: Extension Sample File Functions977150
-Node: Extension Sample Fnmatch985623
-Node: Extension Sample Fork987349
-Node: Extension Sample Ord988563
-Node: Extension Sample Readdir989339
-Node: Extension Sample Revout990843
-Node: Extension Sample Rev2way991436
-Node: Extension Sample Read write array992126
-Node: Extension Sample Readfile994009
-Node: Extension Sample API Tests994764
-Node: Extension Sample Time995289
-Node: gawkextlib996596
-Node: Language History998977
-Node: V7/SVR3.11000499
-Node: SVR41002820
-Node: POSIX1004262
-Node: BTL1005270
-Node: POSIX/GNU1006075
-Node: Common Extensions1011610
-Node: Ranges and Locales1012669
-Ref: Ranges and Locales-Footnote-11017287
-Ref: Ranges and Locales-Footnote-21017314
-Ref: Ranges and Locales-Footnote-31017574
-Node: Contributors1017795
-Node: Installation1022091
-Node: Gawk Distribution1022985
-Node: Getting1023469
-Node: Extracting1024295
-Node: Distribution contents1025987
-Node: Unix Installation1031248
-Node: Quick Installation1031865
-Node: Additional Configuration Options1033827
-Node: Configuration Philosophy1035304
-Node: Non-Unix Installation1037646
-Node: PC Installation1038104
-Node: PC Binary Installation1039403
-Node: PC Compiling1041251
-Node: PC Testing1044195
-Node: PC Using1045371
-Node: Cygwin1049556
-Node: MSYS1050556
-Node: VMS Installation1051070
-Node: VMS Compilation1051673
-Ref: VMS Compilation-Footnote-11052680
-Node: VMS Installation Details1052738
-Node: VMS Running1054373
-Node: VMS Old Gawk1055980
-Node: Bugs1056454
-Node: Other Versions1060306
-Node: Notes1065621
-Node: Compatibility Mode1066280
-Node: Additions1067063
-Node: Accessing The Source1067990
-Node: Adding Code1069593
-Node: New Ports1075635
-Node: Derived Files1079770
-Ref: Derived Files-Footnote-11085091
-Ref: Derived Files-Footnote-21085125
-Ref: Derived Files-Footnote-31085725
-Node: Future Extensions1085823
-Node: Implementation Limitations1086404
-Node: Basic Concepts1087631
-Node: Basic High Level1088312
-Ref: figure-general-flow1088583
-Ref: figure-process-flow1089182
-Ref: Basic High Level-Footnote-11092411
-Node: Basic Data Typing1092596
-Node: Glossary1095951
-Node: Copying1121262
-Node: GNU Free Documentation License1158819
-Node: Index1183956
+Node: Foreword40178
+Node: Preface44523
+Ref: Preface-Footnote-147576
+Ref: Preface-Footnote-247682
+Node: History47914
+Node: Names50305
+Ref: Names-Footnote-151782
+Node: This Manual51854
+Ref: This Manual-Footnote-157760
+Node: Conventions57860
+Node: Manual History59994
+Ref: Manual History-Footnote-163264
+Ref: Manual History-Footnote-263305
+Node: How To Contribute63379
+Node: Acknowledgments64523
+Node: Getting Started69019
+Node: Running gawk71398
+Node: One-shot72584
+Node: Read Terminal73809
+Ref: Read Terminal-Footnote-175459
+Ref: Read Terminal-Footnote-275735
+Node: Long75906
+Node: Executable Scripts77282
+Ref: Executable Scripts-Footnote-179151
+Ref: Executable Scripts-Footnote-279253
+Node: Comments79800
+Node: Quoting82267
+Node: DOS Quoting86890
+Node: Sample Data Files87565
+Node: Very Simple90597
+Node: Two Rules95196
+Node: More Complex97343
+Ref: More Complex-Footnote-1100273
+Node: Statements/Lines100358
+Ref: Statements/Lines-Footnote-1104820
+Node: Other Features105085
+Node: When106013
+Node: Invoking Gawk108160
+Node: Command Line109621
+Node: Options110404
+Ref: Options-Footnote-1125802
+Node: Other Arguments125827
+Node: Naming Standard Input128485
+Node: Environment Variables129579
+Node: AWKPATH Variable130137
+Ref: AWKPATH Variable-Footnote-1132895
+Node: AWKLIBPATH Variable133155
+Node: Other Environment Variables133752
+Node: Exit Status136247
+Node: Include Files136922
+Node: Loading Shared Libraries140491
+Node: Obsolete141716
+Node: Undocumented142413
+Node: Regexp142656
+Node: Regexp Usage144045
+Node: Escape Sequences146071
+Node: Regexp Operators151834
+Ref: Regexp Operators-Footnote-1159214
+Ref: Regexp Operators-Footnote-2159361
+Node: Bracket Expressions159459
+Ref: table-char-classes161349
+Node: GNU Regexp Operators163872
+Node: Case-sensitivity167595
+Ref: Case-sensitivity-Footnote-1170563
+Ref: Case-sensitivity-Footnote-2170798
+Node: Leftmost Longest170906
+Node: Computed Regexps172107
+Node: Reading Files175517
+Node: Records177520
+Ref: Records-Footnote-1186444
+Node: Fields186481
+Ref: Fields-Footnote-1189514
+Node: Nonconstant Fields189600
+Node: Changing Fields191802
+Node: Field Separators197783
+Node: Default Field Splitting200412
+Node: Regexp Field Splitting201529
+Node: Single Character Fields204871
+Node: Command Line Field Separator205930
+Node: Field Splitting Summary209371
+Ref: Field Splitting Summary-Footnote-1212563
+Node: Constant Size212664
+Node: Splitting By Content217248
+Ref: Splitting By Content-Footnote-1220974
+Node: Multiple Line221014
+Ref: Multiple Line-Footnote-1226861
+Node: Getline227040
+Node: Plain Getline229256
+Node: Getline/Variable231345
+Node: Getline/File232486
+Node: Getline/Variable/File233808
+Ref: Getline/Variable/File-Footnote-1235407
+Node: Getline/Pipe235494
+Node: Getline/Variable/Pipe238054
+Node: Getline/Coprocess239161
+Node: Getline/Variable/Coprocess240404
+Node: Getline Notes241118
+Node: Getline Summary243905
+Ref: table-getline-variants244313
+Node: Read Timeout245171
+Ref: Read Timeout-Footnote-1248916
+Node: Command line directories248973
+Node: Printing249603
+Node: Print251234
+Node: Print Examples252571
+Node: Output Separators255355
+Node: OFMT257115
+Node: Printf258473
+Node: Basic Printf259379
+Node: Control Letters260918
+Node: Format Modifiers264730
+Node: Printf Examples270739
+Node: Redirection273454
+Node: Special Files280438
+Node: Special FD280971
+Ref: Special FD-Footnote-1284596
+Node: Special Network284670
+Node: Special Caveats285520
+Node: Close Files And Pipes286316
+Ref: Close Files And Pipes-Footnote-1293339
+Ref: Close Files And Pipes-Footnote-2293487
+Node: Expressions293637
+Node: Values294769
+Node: Constants295445
+Node: Scalar Constants296125
+Ref: Scalar Constants-Footnote-1296984
+Node: Nondecimal-numbers297166
+Node: Regexp Constants300225
+Node: Using Constant Regexps300700
+Node: Variables303755
+Node: Using Variables304410
+Node: Assignment Options306134
+Node: Conversion308006
+Ref: table-locale-affects313382
+Ref: Conversion-Footnote-1314006
+Node: All Operators314115
+Node: Arithmetic Ops314745
+Node: Concatenation317250
+Ref: Concatenation-Footnote-1320043
+Node: Assignment Ops320163
+Ref: table-assign-ops325151
+Node: Increment Ops326559
+Node: Truth Values and Conditions330029
+Node: Truth Values331112
+Node: Typing and Comparison332161
+Node: Variable Typing332950
+Ref: Variable Typing-Footnote-1336847
+Node: Comparison Operators336969
+Ref: table-relational-ops337379
+Node: POSIX String Comparison340928
+Ref: POSIX String Comparison-Footnote-1341884
+Node: Boolean Ops342022
+Ref: Boolean Ops-Footnote-1346100
+Node: Conditional Exp346191
+Node: Function Calls347923
+Node: Precedence351517
+Node: Locales355186
+Node: Patterns and Actions356275
+Node: Pattern Overview357329
+Node: Regexp Patterns358998
+Node: Expression Patterns359541
+Node: Ranges363226
+Node: BEGIN/END366192
+Node: Using BEGIN/END366954
+Ref: Using BEGIN/END-Footnote-1369685
+Node: I/O And BEGIN/END369791
+Node: BEGINFILE/ENDFILE372073
+Node: Empty374977
+Node: Using Shell Variables375293
+Node: Action Overview377578
+Node: Statements379935
+Node: If Statement381789
+Node: While Statement383288
+Node: Do Statement385332
+Node: For Statement386488
+Node: Switch Statement389640
+Node: Break Statement391737
+Node: Continue Statement393727
+Node: Next Statement395520
+Node: Nextfile Statement397910
+Node: Exit Statement400551
+Node: Built-in Variables402967
+Node: User-modified404062
+Ref: User-modified-Footnote-1412417
+Node: Auto-set412479
+Ref: Auto-set-Footnote-1424830
+Ref: Auto-set-Footnote-2425035
+Node: ARGC and ARGV425091
+Node: Arrays428942
+Node: Array Basics430447
+Node: Array Intro431273
+Node: Reference to Elements435591
+Node: Assigning Elements437861
+Node: Array Example438352
+Node: Scanning an Array440084
+Node: Controlling Scanning442398
+Ref: Controlling Scanning-Footnote-1447331
+Node: Delete447647
+Ref: Delete-Footnote-1450412
+Node: Numeric Array Subscripts450469
+Node: Uninitialized Subscripts452652
+Node: Multi-dimensional454280
+Node: Multi-scanning457374
+Node: Arrays of Arrays458965
+Node: Functions463610
+Node: Built-in464429
+Node: Calling Built-in465507
+Node: Numeric Functions467495
+Ref: Numeric Functions-Footnote-1471327
+Ref: Numeric Functions-Footnote-2471684
+Ref: Numeric Functions-Footnote-3471732
+Node: String Functions472001
+Ref: String Functions-Footnote-1495498
+Ref: String Functions-Footnote-2495627
+Ref: String Functions-Footnote-3495875
+Node: Gory Details495962
+Ref: table-sub-escapes497641
+Ref: table-sub-posix-92498995
+Ref: table-sub-proposed500346
+Ref: table-posix-sub501700
+Ref: table-gensub-escapes503245
+Ref: Gory Details-Footnote-1504452
+Ref: Gory Details-Footnote-2504503
+Node: I/O Functions504654
+Ref: I/O Functions-Footnote-1511759
+Node: Time Functions511906
+Ref: Time Functions-Footnote-1522798
+Ref: Time Functions-Footnote-2522866
+Ref: Time Functions-Footnote-3523024
+Ref: Time Functions-Footnote-4523135
+Ref: Time Functions-Footnote-5523247
+Ref: Time Functions-Footnote-6523474
+Node: Bitwise Functions523740
+Ref: table-bitwise-ops524298
+Ref: Bitwise Functions-Footnote-1528519
+Node: Type Functions528703
+Node: I18N Functions529173
+Node: User-defined530800
+Node: Definition Syntax531604
+Ref: Definition Syntax-Footnote-1536514
+Node: Function Example536583
+Node: Function Caveats539177
+Node: Calling A Function539598
+Node: Variable Scope540713
+Node: Pass By Value/Reference543676
+Node: Return Statement547116
+Node: Dynamic Typing550097
+Node: Indirect Calls550832
+Node: Library Functions560517
+Ref: Library Functions-Footnote-1563516
+Node: Library Names563687
+Ref: Library Names-Footnote-1567158
+Ref: Library Names-Footnote-2567378
+Node: General Functions567464
+Node: Strtonum Function568417
+Node: Assert Function571347
+Node: Round Function574673
+Node: Cliff Random Function576216
+Node: Ordinal Functions577232
+Ref: Ordinal Functions-Footnote-1580302
+Ref: Ordinal Functions-Footnote-2580554
+Node: Join Function580763
+Ref: Join Function-Footnote-1582534
+Node: Getlocaltime Function582734
+Node: Data File Management586449
+Node: Filetrans Function587081
+Node: Rewind Function591220
+Node: File Checking592607
+Node: Empty Files593701
+Node: Ignoring Assigns595931
+Node: Getopt Function597484
+Ref: Getopt Function-Footnote-1608788
+Node: Passwd Functions608991
+Ref: Passwd Functions-Footnote-1617966
+Node: Group Functions618054
+Node: Walking Arrays626138
+Node: Sample Programs627707
+Node: Running Examples628384
+Node: Clones629112
+Node: Cut Program630336
+Node: Egrep Program640181
+Ref: Egrep Program-Footnote-1647954
+Node: Id Program648064
+Node: Split Program651680
+Ref: Split Program-Footnote-1655199
+Node: Tee Program655327
+Node: Uniq Program658130
+Node: Wc Program665559
+Ref: Wc Program-Footnote-1669825
+Ref: Wc Program-Footnote-2670025
+Node: Miscellaneous Programs670117
+Node: Dupword Program671305
+Node: Alarm Program673336
+Node: Translate Program678085
+Ref: Translate Program-Footnote-1682472
+Ref: Translate Program-Footnote-2682700
+Node: Labels Program682834
+Ref: Labels Program-Footnote-1686205
+Node: Word Sorting686289
+Node: History Sorting690173
+Node: Extract Program692012
+Ref: Extract Program-Footnote-1699495
+Node: Simple Sed699623
+Node: Igawk Program702685
+Ref: Igawk Program-Footnote-1717842
+Ref: Igawk Program-Footnote-2718043
+Node: Anagram Program718181
+Node: Signature Program721249
+Node: Internationalization722349
+Node: I18N and L10N723781
+Node: Explaining gettext724467
+Ref: Explaining gettext-Footnote-1729533
+Ref: Explaining gettext-Footnote-2729717
+Node: Programmer i18n729882
+Node: Translator i18n734082
+Node: String Extraction734875
+Ref: String Extraction-Footnote-1735836
+Node: Printf Ordering735922
+Ref: Printf Ordering-Footnote-1738706
+Node: I18N Portability738770
+Ref: I18N Portability-Footnote-1741219
+Node: I18N Example741282
+Ref: I18N Example-Footnote-1743917
+Node: Gawk I18N743989
+Node: Advanced Features744606
+Node: Nondecimal Data746110
+Node: Array Sorting747693
+Node: Controlling Array Traversal748390
+Node: Array Sorting Functions756628
+Ref: Array Sorting Functions-Footnote-1760302
+Ref: Array Sorting Functions-Footnote-2760395
+Node: Two-way I/O760589
+Ref: Two-way I/O-Footnote-1766021
+Node: TCP/IP Networking766091
+Node: Profiling768935
+Node: Debugger776389
+Node: Debugging777357
+Node: Debugging Concepts777790
+Node: Debugging Terms779646
+Node: Awk Debugging782243
+Node: Sample Debugging Session783135
+Node: Debugger Invocation783655
+Node: Finding The Bug784984
+Node: List of Debugger Commands791472
+Node: Breakpoint Control792806
+Node: Debugger Execution Control796470
+Node: Viewing And Changing Data799830
+Node: Execution Stack803186
+Node: Debugger Info804653
+Node: Miscellaneous Debugger Commands808634
+Node: Readline Support814079
+Node: Limitations814910
+Node: Arbitrary Precision Arithmetic817162
+Ref: Arbitrary Precision Arithmetic-Footnote-1818804
+Node: General Arithmetic818952
+Node: Floating Point Issues820672
+Node: String Conversion Precision821553
+Ref: String Conversion Precision-Footnote-1823259
+Node: Unexpected Results823368
+Node: POSIX Floating Point Problems825521
+Ref: POSIX Floating Point Problems-Footnote-1829346
+Node: Integer Programming829384
+Node: Floating-point Programming831137
+Ref: Floating-point Programming-Footnote-1837446
+Node: Floating-point Representation837710
+Node: Floating-point Context838875
+Ref: table-ieee-formats839717
+Node: Rounding Mode841101
+Ref: table-rounding-modes841580
+Ref: Rounding Mode-Footnote-1844584
+Node: Gawk and MPFR844765
+Node: Arbitrary Precision Floats846007
+Ref: Arbitrary Precision Floats-Footnote-1848436
+Node: Setting Precision848747
+Node: Setting Rounding Mode851480
+Ref: table-gawk-rounding-modes851884
+Node: Floating-point Constants853064
+Node: Changing Precision854488
+Ref: Changing Precision-Footnote-1855888
+Node: Exact Arithmetic856062
+Node: Arbitrary Precision Integers859170
+Ref: Arbitrary Precision Integers-Footnote-1862170
+Node: Dynamic Extensions862317
+Node: Extension Intro863694
+Node: Plugin License864902
+Node: Extension Mechanism Outline865587
+Ref: load-extension866004
+Ref: load-new-function867482
+Ref: call-new-function868463
+Node: Extension API Description870457
+Node: Extension API Functions Introduction871796
+Node: General Data Types876574
+Ref: General Data Types-Footnote-1882176
+Node: Requesting Values882475
+Ref: table-value-types-returned883206
+Node: Constructor Functions884160
+Node: Registration Functions887156
+Node: Extension Functions887841
+Node: Exit Callback Functions890015
+Node: Extension Version String891258
+Node: Input Parsers891908
+Node: Output Wrappers900495
+Node: Two-way processors904911
+Node: Printing Messages907041
+Ref: Printing Messages-Footnote-1908118
+Node: Updating `ERRNO'908270
+Node: Accessing Parameters909009
+Node: Symbol Table Access910239
+Node: Symbol table by name910751
+Ref: Symbol table by name-Footnote-1912921
+Node: Symbol table by cookie913001
+Ref: Symbol table by cookie-Footnote-1917130
+Node: Cached values917193
+Ref: Cached values-Footnote-1920636
+Node: Array Manipulation920727
+Ref: Array Manipulation-Footnote-1921825
+Node: Array Data Types921864
+Ref: Array Data Types-Footnote-1924567
+Node: Array Functions924659
+Node: Flattening Arrays928425
+Node: Creating Arrays935264
+Node: Extension API Variables940059
+Node: Extension Versioning940695
+Node: Extension API Informational Variables942596
+Node: Extension API Boilerplate943682
+Node: Finding Extensions947513
+Node: Extension Example948060
+Node: Internal File Description948798
+Node: Internal File Ops952486
+Ref: Internal File Ops-Footnote-1963933
+Node: Using Internal File Ops964073
+Ref: Using Internal File Ops-Footnote-1966426
+Node: Extension Samples966692
+Node: Extension Sample File Functions968135
+Node: Extension Sample Fnmatch976608
+Node: Extension Sample Fork978334
+Node: Extension Sample Ord979548
+Node: Extension Sample Readdir980324
+Node: Extension Sample Revout981828
+Node: Extension Sample Rev2way982421
+Node: Extension Sample Read write array983111
+Node: Extension Sample Readfile984994
+Node: Extension Sample API Tests985749
+Node: Extension Sample Time986274
+Node: gawkextlib987581
+Node: Language History989962
+Node: V7/SVR3.1991484
+Node: SVR4993805
+Node: POSIX995247
+Node: BTL996255
+Node: POSIX/GNU997060
+Node: Common Extensions1002595
+Node: Ranges and Locales1003654
+Ref: Ranges and Locales-Footnote-11008272
+Ref: Ranges and Locales-Footnote-21008299
+Ref: Ranges and Locales-Footnote-31008559
+Node: Contributors1008780
+Node: Installation1013076
+Node: Gawk Distribution1013970
+Node: Getting1014454
+Node: Extracting1015280
+Node: Distribution contents1016972
+Node: Unix Installation1022233
+Node: Quick Installation1022850
+Node: Additional Configuration Options1024812
+Node: Configuration Philosophy1026289
+Node: Non-Unix Installation1028631
+Node: PC Installation1029089
+Node: PC Binary Installation1030388
+Node: PC Compiling1032236
+Node: PC Testing1035180
+Node: PC Using1036356
+Node: Cygwin1040541
+Node: MSYS1041541
+Node: VMS Installation1042055
+Node: VMS Compilation1042658
+Ref: VMS Compilation-Footnote-11043665
+Node: VMS Installation Details1043723
+Node: VMS Running1045358
+Node: VMS Old Gawk1046965
+Node: Bugs1047439
+Node: Other Versions1051291
+Node: Notes1056606
+Node: Compatibility Mode1057335
+Node: Additions1058118
+Node: Accessing The Source1059045
+Node: Adding Code1060648
+Node: New Ports1066690
+Node: Derived Files1070825
+Ref: Derived Files-Footnote-11076146
+Ref: Derived Files-Footnote-21076180
+Ref: Derived Files-Footnote-31076780
+Node: Future Extensions1076878
+Node: Implementation Limitations1077459
+Node: Extension Design1078711
+Node: Old Extension Problems1079828
+Ref: Old Extension Problems-Footnote-11081336
+Node: Extension New Mechanism Goals1081393
+Ref: Extension New Mechanism Goals-Footnote-11084752
+Node: Extension Other Design Decisions1084938
+Node: Extension Future Growth1087044
+Node: Basic Concepts1087865
+Node: Basic High Level1088546
+Ref: figure-general-flow1088817
+Ref: figure-process-flow1089416
+Ref: Basic High Level-Footnote-11092645
+Node: Basic Data Typing1092830
+Node: Glossary1096185
+Node: Copying1121496
+Node: GNU Free Documentation License1159053
+Node: Index1184190
End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 647d3b7..60fb794 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -721,12 +721,7 @@ particular records in a file and perform operations upon
them.
with @command{gawk}.
* Extension Intro:: What is an extension.
* Plugin License:: A note about licensing.
-* Extension Design:: Design notes about the extension API.
-* Old Extension Problems:: Problems with the old mechanism.
-* Extension New Mechanism Goals:: Goals for the new mechanism.
-* Extension Other Design Decisions:: Some other design decisions.
* Extension Mechanism Outline:: An outline of how it works.
-* Extension Future Growth:: Some room for future growth.
* Extension API Description:: A full description of the API.
* Extension API Functions Introduction:: Introduction to the API functions.
* General Data Types:: The data types.
@@ -844,7 +839,13 @@ particular records in a file and perform operations upon
them.
@command{git} repository.
* Future Extensions:: New features that may be implemented
one day.
-* Implementation Limitations:: Some limitations of the implementation.
+* Implementation Limitations:: Some limitations of the
+ implementation.
+* Extension Design:: Design notes about the extension API.
+* Old Extension Problems:: Problems with the old mechanism.
+* Extension New Mechanism Goals:: Goals for the new mechanism.
+* Extension Other Design Decisions:: Some other design decisions.
+* Extension Future Growth:: Some room for future growth.
* Basic High Level:: The high level view.
* Basic Data Typing:: A very quick intro to data types.
@end detailmenu
@@ -28262,7 +28263,7 @@ using code written in C or C++.
If you don't know anything about C programming, you can safely skip this
@value{CHAPTER}, although you may wish to review the documentation on the
extensions that come with @command{gawk} (@pxref{Extension Samples}),
-and the @value{SECTION} on the @code{gawkextlib} project (@pxref{gawkextlib}).
+and the information on the @code{gawkextlib} project (@pxref{gawkextlib}).
The sample extensions are automatically built and installed when
@command{gawk} is.
@@ -28274,7 +28275,7 @@ When @option{--sandbox} is specified, extensions are
disabled
@menu
* Extension Intro:: What is an extension.
* Plugin License:: A note about licensing.
-* Extension Design:: Design notes about the extension API.
+* Extension Mechanism Outline:: An outline of how it works.
* Extension API Description:: A full description of the API.
* Extension Example:: Example C code for an extension.
* Extension Samples:: The sample extensions that ship with
@@ -28321,208 +28322,10 @@ the symbol exists in the global scope. Something
like this is enough:
int plugin_is_GPL_compatible;
@end example
address@hidden Extension Design
address@hidden Extension API Design
-
-The first version of extensions for @command{gawk} was developed in
-the mid-1990s and released with @command{gawk} 3.1 in the late 1990s.
-The basic mechanisms and design remained unchanged for close to 15 years,
-until 2012.
-
-The old extension mechanism used data types and functions from
address@hidden itself, with a ``clever hack'' to install extension
-functions.
-
address@hidden included some sample extensions, of which a few were
-really useful. However, it was clear from the outset that the extension
-mechanism was bolted onto the side and was not really thought out.
-
address@hidden
-* Old Extension Problems:: Problems with the old mechanism.
-* Extension New Mechanism Goals:: Goals for the new mechanism.
-* Extension Other Design Decisions:: Some other design decisions.
-* Extension Mechanism Outline:: An outline of how it works.
-* Extension Future Growth:: Some room for future growth.
address@hidden menu
-
address@hidden Old Extension Problems
address@hidden Problems With The Old Mechanism
-
-The old extension mechanism had several problems:
-
address@hidden @bullet
address@hidden
-It depended heavily upon @command{gawk} internals. Any time the
address@hidden address@hidden critical central data structure
-inside @command{gawk}.} changed, an extension would have to be
-recompiled. Furthermore, to really write extensions required understanding
-something about @command{gawk}'s internal functions. There was some
-documentation in this @value{DOCUMENT}, but it was quite minimal.
-
address@hidden
-Being able to call into @command{gawk} from an extension required linker
-facilities that are common on Unix-derived systems but that did
-not work on Windows systems; users wanting extensions on Windows
-had to statically link them into @command{gawk}, even though Windows supports
-dynamic loading of shared objects.
-
address@hidden
-The API would change occasionally as @command{gawk} changed; no compatibility
-between versions was ever offered or planned for.
address@hidden itemize
-
-Despite the drawbacks, the @command{xgawk} project developers forked
address@hidden and developed several significant extensions. They also
-enhanced @command{gawk}'s facilities relating to file inclusion and
-shared object access.
-
-A new API was desired for a long time, but only in 2012 did the
address@hidden maintainer and the @command{xgawk} developers finally
-start working on it together. More information about the @command{xgawk}
-project is provided in @ref{gawkextlib}.
-
address@hidden Extension New Mechanism Goals
address@hidden Goals For A New Mechanism
-
-Some goals for the new API were:
-
address@hidden @bullet
address@hidden
-The API should be independent of @command{gawk} internals. Changes in
address@hidden internals should not be visible to the writer of an
-extension function.
-
address@hidden
-The API should provide @emph{binary} compatibility across @command{gawk}
-releases as long as the API itself does not change.
-
address@hidden
-The API should enable extensions written in C to have roughly the
-same ``appearance'' to @command{awk}-level code as @command{awk}
-functions do. This means that extensions should have:
-
address@hidden @minus
address@hidden
-The ability to access function parameters.
-
address@hidden
-The ability to turn an undefined parameter into an array (call by reference).
-
address@hidden
-The ability to create, access and update global variables.
-
address@hidden
-Easy access to all the elements of an array at once (``array flattening'')
-in order to loop over all the element in an easy fashion for C code.
-
address@hidden
-The ability to create arrays (including @command{gawk}'s true
-multi-dimensional arrays).
address@hidden itemize
address@hidden itemize
-
-Some additional important goals were:
-
address@hidden @bullet
address@hidden
-The API should use only features in ISO C 90, so that extensions
-can be written using the widest range of C and C++ compilers. The header
-should include the appropriate @samp{#ifdef __cplusplus} and @samp{extern "C"}
-magic so that a C++ compiler could be used. (If using C++, the runtime
-system has to be smart enough to call any constructors and destructors,
-as @command{gawk} is a C program. As of this writing, this has not been
-tested.)
-
address@hidden
-The API mechanism should not require access to @command{gawk}'s
address@hidden @dfn{symbols} are the variables and functions
-defined inside @command{gawk}. Access to these symbols by code
-external to @command{gawk} loaded dynamically at runtime is
-problematic on Windows.} by the compile-time or dynamic linker,
-in order to enable creation of extensions that also work on Windows.
address@hidden itemize
-
-During development, it became clear that there were other features
-that should be available to extensions, which were also subsequently
-provided:
-
address@hidden @bullet
address@hidden
-Extensions should have the ability to hook into @command{gawk}'s
-I/O redirection mechanism. In particular, the @command{xgawk}
-developers provided a so-called ``open hook'' to take over reading
-records. During development, this was generalized to allow
-extensions to hook into input processing, output processing, and
-two-way I/O.
-
address@hidden
-An extension should be able to provide a ``call back'' function
-to perform clean up actions when @command{gawk} exits.
-
address@hidden
-An extension should be able to provide a version string so that
address@hidden's @option{--version} option can provide information
-about extensions as well.
address@hidden itemize
-
address@hidden Extension Other Design Decisions
address@hidden Other Design Decisions
-
-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}.
-
-The reason for this is to prevent an extension function from affecting
-the flow of an @command{awk} program outside its control. While a real
address@hidden function can do what it likes, that is at the discretion
-of the programmer. An extension function should provide a service or
-make a C API available for use within @command{awk}, and not mess with
address@hidden or @code{ARGC} and @code{ARGV}.
-
-In addition, it becomes easy to start down a slippery slope. How
-much access to @command{gawk} facilities do extensions need?
-Do they need @code{getline}? What about calling @code{gsub()} or
-compiling regular expressions? What about calling into @command{awk}
-functions? (@emph{That} would be messy.)
-
-In order to avoid these issues, the @command{gawk} developers chose
-to start with the simplest, most basic features that are still truly useful.
-
-Another decision is that although @command{gawk} provides nice things like
-MPFR, and arrays indexed internally by integers, these features are not
-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.
-
@node Extension Mechanism Outline
address@hidden At A High Level How It Works
address@hidden At A High Level How It Works
-The requirement to avoid access to @command{gawk}'s symbols is, at first
-glance, a difficult one to meet.
-
-One design, apparently used by Perl and Ruby and maybe others, would
-be to make the mainline @command{gawk} code into a library, with the
address@hidden utility a small C @code{main()} function linked against
-the library.
-
-This seemed like the tail wagging the dog, complicating build and
-installation and making a simple copy of the @command{gawk} executable
-from one system to another (or one place to another on the same
-system!) into a chancy operation.
-
-Pat Rankin suggested the solution that was adopted. Communication between
+Communication between
@command{gawk} and an extension is two-way. First, when an extension
is loaded, it is passed a pointer to a @code{struct} whose fields are
function pointers.
@@ -28603,28 +28406,6 @@ happen, but we all know how @emph{that} goes.)
@xref{Extension Versioning}, for details.
@end itemize
address@hidden Extension Future Growth
address@hidden Room For Future Growth
-
-The API can later be expanded, in two ways:
-
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.
-
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.
@node Extension API Description
@section API Description
@@ -30113,7 +29894,7 @@ BEGIN @{
@noindent
This code creates an array with @code{split()} (@pxref{String Functions})
-and then calls @code{dump_and_delete()}. That function looks up
+and then calls @code{dump_array_and_delete()}. That function looks up
the array whose name is passed as the first argument, and
deletes the element at the index passed in the second argument.
It then prints the return value and checks if the element
@@ -34303,6 +34084,7 @@ maintainers of @command{gawk}. Everything in it
applies specifically to
* Additions:: Making Additions To @command{gawk}.
* Future Extensions:: New features that may be implemented one day.
* Implementation Limitations:: Some limitations of the implementation.
+* Extension Design:: Design notes about the extension API.
@end menu
@node Compatibility Mode
@@ -34916,7 +34698,6 @@ This following table describes limits of @command{gawk}
on a Unix-like
system (although it is variable even then). Other systems may have
different limits.
address@hidden @multitable {Number of file redirections} {min(number of
processes per user, number of open files)}
@multitable @columnfractions .40 .60
@headitem Item @tab Limit
@item Characters in a character class @tab 2^(number of bits per byte)
@@ -34934,6 +34715,234 @@ different limits.
@item Size of a printf string @tab @code{MAX_INT }
@end multitable
address@hidden Extension Design
address@hidden Extension API Design
+
+This @value{SECTION} documents the design of the extension API,
+including a discussion of some of the history and problems that needed
+to be solved.
+
+The first version of extensions for @command{gawk} was developed in
+the mid-1990s and released with @command{gawk} 3.1 in the late 1990s.
+The basic mechanisms and design remained unchanged for close to 15 years,
+until 2012.
+
+The old extension mechanism used data types and functions from
address@hidden itself, with a ``clever hack'' to install extension
+functions.
+
address@hidden included some sample extensions, of which a few were
+really useful. However, it was clear from the outset that the extension
+mechanism was bolted onto the side and was not really thought out.
+
address@hidden
+* Old Extension Problems:: Problems with the old mechanism.
+* Extension New Mechanism Goals:: Goals for the new mechanism.
+* Extension Other Design Decisions:: Some other design decisions.
+* Extension Future Growth:: Some room for future growth.
address@hidden menu
+
address@hidden Old Extension Problems
address@hidden Problems With The Old Mechanism
+
+The old extension mechanism had several problems:
+
address@hidden @bullet
address@hidden
+It depended heavily upon @command{gawk} internals. Any time the
address@hidden address@hidden critical central data structure
+inside @command{gawk}.} changed, an extension would have to be
+recompiled. Furthermore, to really write extensions required understanding
+something about @command{gawk}'s internal functions. There was some
+documentation in this @value{DOCUMENT}, but it was quite minimal.
+
address@hidden
+Being able to call into @command{gawk} from an extension required linker
+facilities that are common on Unix-derived systems but that did
+not work on Windows systems; users wanting extensions on Windows
+had to statically link them into @command{gawk}, even though Windows supports
+dynamic loading of shared objects.
+
address@hidden
+The API would change occasionally as @command{gawk} changed; no compatibility
+between versions was ever offered or planned for.
address@hidden itemize
+
+Despite the drawbacks, the @command{xgawk} project developers forked
address@hidden and developed several significant extensions. They also
+enhanced @command{gawk}'s facilities relating to file inclusion and
+shared object access.
+
+A new API was desired for a long time, but only in 2012 did the
address@hidden maintainer and the @command{xgawk} developers finally
+start working on it together. More information about the @command{xgawk}
+project is provided in @ref{gawkextlib}.
+
address@hidden Extension New Mechanism Goals
address@hidden Goals For A New Mechanism
+
+Some goals for the new API were:
+
address@hidden @bullet
address@hidden
+The API should be independent of @command{gawk} internals. Changes in
address@hidden internals should not be visible to the writer of an
+extension function.
+
address@hidden
+The API should provide @emph{binary} compatibility across @command{gawk}
+releases as long as the API itself does not change.
+
address@hidden
+The API should enable extensions written in C to have roughly the
+same ``appearance'' to @command{awk}-level code as @command{awk}
+functions do. This means that extensions should have:
+
address@hidden @minus
address@hidden
+The ability to access function parameters.
+
address@hidden
+The ability to turn an undefined parameter into an array (call by reference).
+
address@hidden
+The ability to create, access and update global variables.
+
address@hidden
+Easy access to all the elements of an array at once (``array flattening'')
+in order to loop over all the element in an easy fashion for C code.
+
address@hidden
+The ability to create arrays (including @command{gawk}'s true
+multi-dimensional arrays).
address@hidden itemize
address@hidden itemize
+
+Some additional important goals were:
+
address@hidden @bullet
address@hidden
+The API should use only features in ISO C 90, so that extensions
+can be written using the widest range of C and C++ compilers. The header
+should include the appropriate @samp{#ifdef __cplusplus} and @samp{extern "C"}
+magic so that a C++ compiler could be used. (If using C++, the runtime
+system has to be smart enough to call any constructors and destructors,
+as @command{gawk} is a C program. As of this writing, this has not been
+tested.)
+
address@hidden
+The API mechanism should not require access to @command{gawk}'s
address@hidden @dfn{symbols} are the variables and functions
+defined inside @command{gawk}. Access to these symbols by code
+external to @command{gawk} loaded dynamically at runtime is
+problematic on Windows.} by the compile-time or dynamic linker,
+in order to enable creation of extensions that also work on Windows.
address@hidden itemize
+
+During development, it became clear that there were other features
+that should be available to extensions, which were also subsequently
+provided:
+
address@hidden @bullet
address@hidden
+Extensions should have the ability to hook into @command{gawk}'s
+I/O redirection mechanism. In particular, the @command{xgawk}
+developers provided a so-called ``open hook'' to take over reading
+records. During development, this was generalized to allow
+extensions to hook into input processing, output processing, and
+two-way I/O.
+
address@hidden
+An extension should be able to provide a ``call back'' function
+to perform clean up actions when @command{gawk} exits.
+
address@hidden
+An extension should be able to provide a version string so that
address@hidden's @option{--version} option can provide information
+about extensions as well.
address@hidden itemize
+
+The requirement to avoid access to @command{gawk}'s symbols is, at first
+glance, a difficult one to meet.
+
+One design, apparently used by Perl and Ruby and maybe others, would
+be to make the mainline @command{gawk} code into a library, with the
address@hidden utility a small C @code{main()} function linked against
+the library.
+
+This seemed like the tail wagging the dog, complicating build and
+installation and making a simple copy of the @command{gawk} executable
+from one system to another (or one place to another on the same
+system!) into a chancy operation.
+
+Pat Rankin suggested the solution that was adopted.
address@hidden Mechanism Outline}, for the details.
+
address@hidden Extension Other Design Decisions
address@hidden Other Design Decisions
+
+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}.
+
+The reason for this is to prevent an extension function from affecting
+the flow of an @command{awk} program outside its control. While a real
address@hidden function can do what it likes, that is at the discretion
+of the programmer. An extension function should provide a service or
+make a C API available for use within @command{awk}, and not mess with
address@hidden or @code{ARGC} and @code{ARGV}.
+
+In addition, it becomes easy to start down a slippery slope. How
+much access to @command{gawk} facilities do extensions need?
+Do they need @code{getline}? What about calling @code{gsub()} or
+compiling regular expressions? What about calling into @command{awk}
+functions? (@emph{That} would be messy.)
+
+In order to avoid these issues, the @command{gawk} developers chose
+to start with the simplest, most basic features that are still truly useful.
+
+Another decision is that although @command{gawk} provides nice things like
+MPFR, and arrays indexed internally by integers, these features are not
+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.
+
address@hidden Extension Future Growth
address@hidden Room For Future Growth
+
+The API can later be expanded, in two ways:
+
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.
+
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.
+
+
@c ENDOFRANGE impis
@c ENDOFRANGE gawii
-----------------------------------------------------------------------
Summary of changes:
doc/ChangeLog | 4 +
doc/gawk.info | 1494 +++++++++++++++++++++++++++++----------------------------
doc/gawk.texi | 473 ++++++++++---------
3 files changed, 995 insertions(+), 976 deletions(-)
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gawk-diffs] [SCM] gawk branch, master, updated. b68a7db5669521f4c56dc690a12588422548fa53,
Arnold Robbins <=