[gawk-diffs] [SCM] gawk branch, master, updated. eb2698f49247c94c84e1e2c2304ba94d96c89bc9

[Arnold Robbins]

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  eb2698f49247c94c84e1e2c2304ba94d96c89bc9 (commit)
      from  07e825ba195cc9778bcdb75a831d11f26f99ef5a (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=eb2698f49247c94c84e1e2c2304ba94d96c89bc9

commit eb2698f49247c94c84e1e2c2304ba94d96c89bc9
Author: Arnold D. Robbins <address@hidden>
Date:   Tue Sep 25 12:33:06 2012 +0200

    Minor updates to api.texi.

diff --git a/doc/api.texi b/doc/api.texi
index 77982ce..2b8f186 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -277,7 +277,8 @@ It depended heavily upon @command{gawk} internals.
 Any time the @code{NODE} structure 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 but it was quite minimal.
+internal functions.  There was some documentation in this @value{DOCUMENT},
+but it was quite minimal.
 
 @item
 Being able to call into @command{gawk} from an extension required linker
@@ -298,7 +299,9 @@ shared object access.
 
 A new API was desired for a long time, but only in 2012 did the
 @command{gawk} maintainer and the @command{xgawk} developers finally
-start working on it together (FIXME: need more about @command{xgawk}).
+start working on it together.
+More information about the @command{xgawk} project is provided
+in @ref{gawkextlib}.
 
 @node Extension New Mechansim Goals
 @subsection Goals For A New Mechansim
@@ -351,18 +354,37 @@ as @command{gawk} is a C program.)
 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 run-time, is
+external to @command{gawk} loaded dynamically at run-time is
 problematic on Windows.} by the compile-time or dynamic linker,
 in order to enable creation of extensions that will also work on Windows.
 @end 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 the 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 itemize
+
+strong{FIXME:} Review the header for other things to list here.
+
 @node Extension Other Design Decisions
 @subsection Other Design Decisions
 
-As an ``arbitrary'' design decision, extensions cannot access or change
-built-in variables and arrays (such as @code{ARGV}, @code{FS}), with
-the exception of @code{PROCINFO}.  (Read-only access could in theory be
-allowed but wasn't.)
+As an ``arbitrary'' design decision, extensions read the values of
+built-in variables and arrays (such as @code{ARGV}, @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
@@ -385,7 +407,8 @@ Another decision is that
 although @command{gawk} provides nice things like MPFR, and arrays indexed
 internally by integers, we are not bringing these features
 out to the API in order to keep things simple and close to traditional
address@hidden semantics.
address@hidden semantics.  (In fact, arrays indexed internally by integers
+are so transparent that they aren't even documented!)
 
 @node Extension Mechanism Outline
 @subsection At A High Level How It Works
@@ -395,8 +418,8 @@ 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 @command{gawk} program a small @code{main()}
-linked against the library.
+into a library, with the @command{gawk} program 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
@@ -467,6 +490,9 @@ A ``name space'' is passed into @command{gawk} when an 
extension
 is registered.  This allows for some 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.
+
 @node Extension Versioning
 @subsection API Versioning
 
@@ -484,7 +510,7 @@ The minor version of the API.
 The minor version increases when new functions are added to the API. Such
 new functions are always added to the end of the API @code{struct}.
 
-The major version increases (and minor version is reset to zero) if any
+The major version increases (and the minor version is reset to zero) if any
 of the data types change size or member order, or if any of the existing
 functions change signature.
 
@@ -538,12 +564,6 @@ query routines return an @code{awk_bool_t}, with ``true'' 
meaning success and
 Access to facilities within @command{gawk} are made available
 by calling through function pointers passed into your extension.
 
-While you may call through these 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 section presents the macros as if they were functions.
-
 API function pointers are provided for the following kinds of operations:
 
 @itemize @bullet
@@ -564,7 +584,7 @@ Updating @code{ERRNO}, or unsetting it
 Registering an extension function
 
 @item
-Registering exit handler functions to be called with @command{gawk} exits
+Registering exit handler functions to be called when @command{gawk} exits
 
 @item
 Accessing and creating global variables
@@ -598,11 +618,17 @@ can be a big performance win.
 Registering an informational version string.
 @end itemize
 
+While you may call through these 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 section presents the macros as if they were functions.
+
 Points about using the API:
 
 @c @item
 
-In general, all pointers filled in by @command{gawk} are to memory
+All pointers filled in by @command{gawk} are to memory
 managed by @command{gawk} and should be treated by the extension as
 read-only.  Memory for @emph{all} strings passed into @command{gawk}
 from the extension @emph{must} come from @code{malloc()} and is managed
@@ -792,7 +818,9 @@ the file. If it does so, it shold set the @code{fd} field to
 @code{INVALID_HANDLE}.
 
 Having a ``tear down'' function is optional. If your input parser does
-not need it, do not set this field.
+not need it, do not set this field.  In that case, @command{gawk}
+will close the regular @code{close()} system call on the
+file descriptor, so it should be valid.
 @end table
 
 The @address@hidden()} function does the work of creating
@@ -802,7 +830,7 @@ input records.  The parameters are as follows:
 @item char **out
 This is a pointer to a @code{char *} variable which is set to point
 to the record.  @command{gawk} will make its own copy of the data, so
-it is the responsibility of the extension to manage this storage.
+the extension must manage this storage.
 
 @item struct iobuf_public *iobuf
 This is the @code{IOBUF_PUBLIC} for the file.  The fields should be

-----------------------------------------------------------------------

Summary of changes:
 doc/api.texi |   70 ++++++++++++++++++++++++++++++++++++++++-----------------
 1 files changed, 49 insertions(+), 21 deletions(-)


hooks/post-receive
-- 
gawk