gawk: Extension New Mechanism Goals
1
1 C.5.2 Goals For A New Mechanism
1 -------------------------------
1
1 Some goals for the new API were:
1
1 * The API should be independent of 'gawk' internals. Changes in
1 'gawk' internals should not be visible to the writer of an
1 extension function.
1
1 * The API should provide _binary_ compatibility across 'gawk'
1 releases as long as the API itself does not change.
1
1 * The API should enable extensions written in C or C++ to have
1 roughly the same "appearance" to 'awk'-level code as 'awk'
1 functions do. This means that extensions should have:
1
1 - The ability to access function parameters.
1
1 - The ability to turn an undefined parameter into an array (call
1 by reference).
1
1 - The ability to create, access and update global variables.
1
1 - Easy access to all the elements of an array at once ("array
1 flattening") in order to loop over all the element in an easy
1 fashion for C code.
1
1 - The ability to create arrays (including 'gawk''s true arrays
1 of arrays).
1
1 Some additional important goals were:
1
1 * The API should use only features in ISO C 90, so that extensions
1 can be written using the widest range of C and C++ compilers. The
1 header should include the appropriate '#ifdef __cplusplus' and
1 'extern "C"' magic so that a C++ compiler could be used. (If using
1 C++, the runtime system has to be smart enough to call any
1 constructors and destructors, as 'gawk' is a C program. As of this
1 writing, this has not been tested.)
1
1 * The API mechanism should not require access to 'gawk''s symbols(1)
1 by the compile-time or dynamic linker, in order to enable creation
1 of extensions that also work on MS-Windows.
1
1 During development, it became clear that there were other features
1 that should be available to extensions, which were also subsequently
1 provided:
1
1 * Extensions should have the ability to hook into 'gawk''s I/O
1 redirection mechanism. In particular, the 'xgawk' developers
1 provided a so-called "open hook" to take over reading records.
1 During development, this was generalized to allow extensions to
1 hook into input processing, output processing, and two-way I/O.
1
1 * An extension should be able to provide a "call back" function to
1 perform cleanup actions when 'gawk' exits.
1
1 * An extension should be able to provide a version string so that
1 'gawk''s '--version' option can provide information about
1 extensions as well.
1
1 The requirement to avoid access to 'gawk''s symbols is, at first
1 glance, a difficult one to meet.
1
1 One design, apparently used by Perl and Ruby and maybe others, would
1 be to make the mainline 'gawk' code into a library, with the 'gawk'
1 utility a small C 'main()' function linked against the library.
1
1 This seemed like the tail wagging the dog, complicating build and
1 installation and making a simple copy of the 'gawk' executable from one
1 system to another (or one place to another on the same system!) into a
1 chancy operation.
1
11 Pat Rankin suggested the solution that was adopted. ⇒Extension
Mechanism Outline, for the details.
1
1 ---------- Footnotes ----------
1
1 (1) The "symbols" are the variables and functions defined inside
1 'gawk'. Access to these symbols by code external to 'gawk' loaded
1 dynamically at runtime is problematic on MS-Windows.
1