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