[gawk-diffs] [SCM] gawk branch, master, updated. gawk-4.1.0-2591-g8e8326d

[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  8e8326d91e40166e25921b323ad468399c11d60d (commit)
      from  f22661b0de5c0e5c46bec9d066d23a03d9b783c3 (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=8e8326d91e40166e25921b323ad468399c11d60d

commit 8e8326d91e40166e25921b323ad468399c11d60d
Author: Arnold D. Robbins <address@hidden>
Date:   Fri Jul 7 11:54:16 2017 +0300

    Misc edits in io.c and gawkapi.h.

diff --git a/ChangeLog b/ChangeLog
index 0f8c12f..b199e73 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2017-07-07         Arnold D. Robbins     <address@hidden>
+
+       * gawapi.h: Bring descriptive comments up to date, minor edits.
+       * io.c: Add some initial comments to functions where they were missing.
+
 2017-07-03         Arnold D. Robbins     <address@hidden>
 
        * gawkapi.h, gawkapi.c: Typo fixes in comments.
diff --git a/gawkapi.h b/gawkapi.h
index 08af418..b8e8a26 100644
--- a/gawkapi.h
+++ b/gawkapi.h
@@ -3,7 +3,7 @@
  */
 
 /*
- * Copyright (C) 2012-2016 the Free Software Foundation, Inc.
+ * Copyright (C) 2012-2017 the Free Software Foundation, Inc.
  *
  * This file is part of GAWK, the GNU implementation of the
  * AWK Programming Language.
@@ -118,7 +118,7 @@ typedef enum awk_bool {
 } awk_bool_t;  /* we don't use <stdbool.h> on purpose */
 
 /*
- * If the input parser would like to specify the field positions in the input
+ * If an input parser would like to specify the field positions in the input
  * record, it may populate an awk_fieldwidth_info_t structure to indicate
  * the location of each field. The use_chars boolean controls whether the
  * field lengths are specified in terms of bytes or potentially multi-byte
@@ -208,7 +208,7 @@ typedef struct awk_input_parser {
        const char *name;       /* name of parser */
 
        /*
-        * The can_take_file function should return non-zero if the parser
+        * The can_take_file function should return true if the parser
         * would like to parse this file.  It should not change any gawk
         * state!
         */
@@ -219,7 +219,7 @@ typedef struct awk_input_parser {
         * It can assume that a previous call to can_take_file was successful,
         * and no gawk state has changed since that call.  It should populate
         * the awk_input_buf_t's get_record, close_func, and opaque values as 
needed.
-        * It should return non-zero if successful.
+        * It should return true if successful.
         */
        awk_bool_t (*take_control_of)(awk_input_buf_t *iobuf);
 
@@ -254,7 +254,7 @@ typedef struct awk_output_wrapper {
        const char *name;       /* name of the wrapper */
 
        /*
-        * The can_take_file function should return non-zero if the wrapper
+        * The can_take_file function should return true if the wrapper
         * would like to process this file.  It should not change any gawk
         * state!
         */
@@ -265,7 +265,7 @@ typedef struct awk_output_wrapper {
         * It can assume that a previous call to can_take_file was successful,
         * and no gawk state has changed since that call.  It should populate
         * the awk_output_buf_t function pointers and opaque pointer as needed.
-        * It should return non-zero if successful.
+        * It should return true if successful.
         */
        awk_bool_t (*take_control_of)(awk_output_buf_t *outbuf);
 
@@ -277,7 +277,7 @@ typedef struct awk_two_way_processor {
        const char *name;       /* name of the two-way processor */
 
        /*
-        * The can_take_file function should return non-zero if the two-way
+        * The can_take_file function should return true if the two-way
         * processor would like to parse this file.  It should not change
         * any gawk state!
         */
@@ -288,7 +288,7 @@ typedef struct awk_two_way_processor {
         * It can assume that a previous call to can_take_file was successful,
         * and no gawk state has changed since that call.  It should populate
         * the awk_input_buf_t and awk_otuput_buf_t structures as needed.
-        * It should return non-zero if successful.
+        * It should return true if successful.
         */
        awk_bool_t (*take_control_of)(const char *name, awk_input_buf_t *inbuf,
                                        awk_output_buf_t *outbuf);
@@ -315,7 +315,8 @@ enum {
  * be multibyte encoded in the current locale's encoding and character
  * set. Gawk will convert internally to wide characters if necessary.
  *
- * Note that the string will always be terminated with a '\0' character.
+ * Note that a string provided by gawk will always be terminated
+ * with a '\0' character.
  */
 typedef struct awk_string {
        char *str;      /* data */
@@ -407,8 +408,8 @@ typedef struct awk_flat_array {
  * loaded, the extension should pass in one of these to gawk for
  * each C function.
  *
- * Each called function must fill in the result with either a number
- * or string. Gawk takes ownership of any string memory.
+ * Each called function must fill in the result with either a scalar
+ * (number, string, or regex). Gawk takes ownership of any string memory.
  *
  * The called function must return the value of `result'.
  * This is for the convenience of the calling code inside gawk.
@@ -522,13 +523,13 @@ typedef struct gawk_api {
         * behave in the same way.
         *
         * For a function parameter, the return is false if the argument
-        * count is out of range, or if actual paramater does not match
+        * count is out of range, or if the actual paramater does not match
         * what is specified in wanted. In that case,  result->val_type
         * will hold the actual type of what was passed.
         *
         * Similarly for symbol table access to variables and array elements,
         * the return is false if the actual variable or array element does
-        * not match what was requested, and the result->val_type will hold
+        * not match what was requested, and result->val_type will hold
         * the actual type.
 
        Table entry is type returned:
@@ -652,7 +653,7 @@ typedef struct gawk_api {
         *              use the scalar cookie
         *
         * Return will be false if the new value is not one of
-        * AWK_STRING or AWK_NUMBER.
+        * AWK_STRING, AWK_NUMBER, AWK_REGEX.
         *
         * Here too, the built-in variables may not be updated.
         */
@@ -662,12 +663,12 @@ typedef struct gawk_api {
        /* Cached values */
 
        /*
-        * Create a cached string or numeric value for efficient later
+        * Create a cached string,regex, or numeric value for efficient later
         * assignment. This improves performance when you want to assign
         * the same value to one or more variables repeatedly.  Only
-        * AWK_NUMBER and AWK_STRING values are allowed.  Any other type
-        * is rejected.  We disallow AWK_UNDEFINED since that case would
-        * result in inferior performance.
+        * AWK_NUMBER, AWK_STRING, AWK_REGEX and AWK_STRNUM values are allowed.
+        * Any other type is rejected.  We disallow AWK_UNDEFINED since that
+        * case would result in inferior performance.
         */
        awk_bool_t (*api_create_value)(awk_ext_id_t id, awk_value_t *value,
                    awk_value_cookie_t *result);
@@ -711,21 +712,22 @@ typedef struct gawk_api {
 
        /*
         * Remove the element with the given index.
-        * Returns success if removed or false if element did not exist.
+        * Returns true if removed or false if element did not exist.
         */
        awk_bool_t (*api_del_array_element)(awk_ext_id_t id,
                        awk_array_t a_cookie, const awk_value_t* const index);
 
-       /* Create a new array cookie to which elements may be added */
+       /* Create a new array cookie to which elements may be added. */
        awk_array_t (*api_create_array)(awk_ext_id_t id);
 
-       /* Clear out an array */
+       /* Clear out an array. */
        awk_bool_t (*api_clear_array)(awk_ext_id_t id, awk_array_t a_cookie);
 
        /*
         * Flatten out an array with type conversions as requested.
-        * This supersedes the api_flatten_array function that did not allow
-        * the caller to specify the requested types.
+        * This supersedes the earlier api_flatten_array function that
+        * did not allow the caller to specify the requested types.
+        * (That API is still available as a macro, defined below.)
         */
        awk_bool_t (*api_flatten_array_typed)(awk_ext_id_t id,
                        awk_array_t a_cookie,
@@ -752,21 +754,34 @@ typedef struct gawk_api {
         * data for the currently open input file corresponding to FILENAME
         * (and it will not access the filetype argument, so that may be
         * undefined).
-        * If the file is not already open, it tries to open it.
+        *
+        * If the file is not already open, try to open it.
+        *
         * The "filetype" argument should be one of:
+        *
         *    ">", ">>", "<", "|>", "|<", and "|&"
+        *
         * If the file is not already open, and the fd argument is non-negative,
         * gawk will use that file descriptor instead of opening the file
-        * in the usual way.  If the fd is non-negative, but the file exists
-        * already, gawk ignores the fd and returns the existing file.  It is
-        * the caller's responsibility to notice that the fd in the returned
-        * awk_input_buf_t does not match the requested value.  Note that
-        * supplying a file descriptor is currently NOT supported for pipes.
-        * It should work for input, output, append, and two-way (coprocess)
-        * sockets.  If the filetype is two-way, we assume that it is a socket!
+        * in the usual way.
+        *
+        * If the fd is non-negative, but the file exists already, gawk
+        * ignores the fd and returns the existing file.  It is the caller's
+        * responsibility to notice that the fd in the returned
+        * awk_input_buf_t does not match the requested value.
+        *
+        * Note that supplying a file descriptor is currently NOT supported
+        * for pipes. It should work for input, output, append, and two-way
+        * (coprocess) sockets.  If the filetype is two-way, we assume that
+        * it is a socket!
+        *
         * Note that in the two-way case, the input and output file descriptors
         * may differ.  To check for success, one must check that either of
         * them matches.
+        *
+        * ibufp and obufp point at gawk's internal copies of the
+        * awk_input_buf_t and awk_output_t associated with the open
+        * file.  Treat these data structures as read-only!
         */
        awk_bool_t (*api_get_file)(awk_ext_id_t id,
                        const char *name,
@@ -942,9 +957,9 @@ r_make_string(const gawk_api_t *api,        /* needed for 
emalloc */
 #define make_malloced_regex(str, len, result)  r_make_string_type(api, ext_id, 
str, len, 0, result, AWK_REGEX)
 
 /*
- * Note: The caller may not create a Strnum, but it can create a string that is
- * flagged as user input that MAY be a Strnum. Gawk will decide whether it's a
- * Strnum or a String by checking whether the string is numeric.
+ * Note: The caller may not create a STRNUM, but it can create a string that is
+ * flagged as user input that MAY be a STRNUM. Gawk will decide whether it's a
+ * STRNUM or a string by checking whether the string is numeric.
  */
 #define make_const_user_input(str, len, result)        r_make_string_type(api, 
ext_id, str, len, 1, result, AWK_STRNUM)
 #define make_malloced_user_input(str, len, result)     r_make_string_type(api, 
ext_id, str, len, 0, result, AWK_STRNUM)
diff --git a/io.c b/io.c
index 5d79e17..0227855 100644
--- a/io.c
+++ b/io.c
@@ -3,7 +3,7 @@
  */
 
 /*
- * Copyright (C) 1986, 1988, 1989, 1991-2016,
+ * Copyright (C) 1986, 1988, 1989, 1991-2017,
  * the Free Software Foundation, Inc.
  *
  * This file is part of GAWK, the GNU implementation of the
@@ -3334,8 +3334,6 @@ grow_iop_buffer(IOBUF *iop)
        iop->end = iop->buf + iop->size;
 }
 
-/* Here are the routines. */
-
 /* rs1scan --- scan for a single character record terminator */
 
 static RECVALUE
@@ -4270,6 +4268,8 @@ gawk_fwrite(const void *buf, size_t size, size_t count, 
FILE *fp, void *opaque)
        return fwrite(buf, size, count, fp);
 }
 
+/* gawk_fflush --- like fflush */
+
 static int
 gawk_fflush(FILE *fp, void *opaque)
 {
@@ -4278,6 +4278,8 @@ gawk_fflush(FILE *fp, void *opaque)
        return fflush(fp);
 }
 
+/* gawk_ferror --- like ferror */
+
 static int
 gawk_ferror(FILE *fp, void *opaque)
 {
@@ -4286,6 +4288,8 @@ gawk_ferror(FILE *fp, void *opaque)
        return ferror(fp);
 }
 
+/* gawk_fclose --- like fclose */
+
 static int
 gawk_fclose(FILE *fp, void *opaque)
 {
@@ -4303,7 +4307,6 @@ gawk_fclose(FILE *fp, void *opaque)
        return result;
 }
 
-
 /* init_output_wrapper --- initialize the output wrapper */
 
 static void

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

Summary of changes:
 ChangeLog |  5 ++++
 gawkapi.h | 83 +++++++++++++++++++++++++++++++++++++--------------------------
 io.c      | 11 ++++++---
 3 files changed, 61 insertions(+), 38 deletions(-)


hooks/post-receive
-- 
gawk