diff options
| -rw-r--r-- | README.git | 25 | ||||
| -rw-r--r-- | TODO | 4 | ||||
| -rw-r--r-- | doc/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/gawk.info | 261 | ||||
| -rw-r--r-- | doc/gawk.texi | 36 |
5 files changed, 182 insertions, 148 deletions
@@ -1,4 +1,4 @@ -Sun Aug 5 16:25:58 IDT 2012 +Sat Dec 1 21:53:02 IST 2012 ============================ If you are reading this, you have retrieved the gawk code base via @@ -327,3 +327,26 @@ turn, followed by "bzr pull" to sync the branch. It depends upon if you have pushed the commit or not. Lots of good info is at http://stackoverflow.com/questions/927358/git-undo-last-commit . + +- What is the difference between using `git rebase' and `git merge' ? + +Both of these can be used to bring one branch up to date with respect +to another. For example, if you are working on a feature branch based +off master, and master has since progressed, you can use + + git checkout feature + git merge master + +or + + git checkout feature + git rebase master + +In the end, you will have your changes on top of the current version of +master in the feature branch. + +So which to use? The answer depends on whether your feature branch +has been pushed up to the Savannah repo or not. + +If your branch is completely local to your machine, use `git rebase'. +Otherwise, use `git merge'. @@ -19,12 +19,12 @@ Minor Cleanups and Code Improvements Make GAWKDEBUG pass the test suite. API: - awk_true and awk_false ??? + DONE: awk_true and awk_false DONE: Update doc to use gcc -o filefuncs.so -shared filefuncs.o instead of ld ... ??? #if !defined(GAWK) && !defined(GAWK_OMIT_CONVENIENCE_MACROS) - Make fflush() and fflush("") both flush all files, as in BWK awk. + DONE: Make fflush() and fflush("") both flush all files, as in BWK awk. ?? Add debugger commands to reference card diff --git a/doc/ChangeLog b/doc/ChangeLog index 21a1c976..1d4a9e32 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2012-12-01 Arnold D. Robbins <arnold@skeeve.com> + + * gawk.texi: API chapter. Sync with gawkapi.h + 2012-11-27 Arnold D. Robbins <arnold@skeeve.com> * gawk.texi: API chapter. Change command for making shared libs diff --git a/doc/gawk.info b/doc/gawk.info index ca986467..724ae201 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -21920,11 +21920,16 @@ that use them. in the API data structures unwritable from extension code, while allowing `gawk' to use them as it needs to. -`typedef int awk_bool_t;' - A simple boolean type. At the moment, the API does not define - special "true" and "false" values, although perhaps it should. +`typedef enum awk_bool {' -`typedef struct {' +` awk_false = 0,' + +` awk_true' + +`} awk_bool_t;' + A simple boolean type. + +`typedef struct awk_string {' ` char *str; /* data */' ` size_t len; /* length thereof, in chars */' `} awk_string_t;' @@ -21946,7 +21951,7 @@ that use them. This `enum' indicates the type of a value. It is used in the following `struct'. -`typedef struct {' +`typedef struct awk_value {' ` awk_valtype_t val_type;' ` union {' ` awk_string_t s;' @@ -22166,7 +22171,7 @@ File: gawk.info, Node: Extension Functions, Next: Exit Callback Functions, Up Extension functions are described by the following record: - typedef struct { + typedef struct awk_ext_func { const char *name; awk_value_t *(*function)(int num_actual_args, awk_value_t *result); size_t num_expected_args; @@ -22285,11 +22290,11 @@ used for `RT', if any. Your extension should package these functions inside an `awk_input_parser_t', which looks like this: - typedef struct input_parser { + typedef struct awk_input_parser { const char *name; /* name of parser */ awk_bool_t (*can_take_file)(const awk_input_buf_t *iobuf); awk_bool_t (*take_control_of)(awk_input_buf_t *iobuf); - awk_const struct input_parser *awk_const next; /* for use by gawk */ + awk_const struct awk_input_parser *awk_const next; /* for use by gawk */ } awk_input_parser_t; The fields are: @@ -22456,11 +22461,11 @@ an extension to take over the output to a file opened with the `>' or The output wrapper is very similar to the input parser structure: - typedef struct output_wrapper { + typedef struct awk_output_wrapper { const char *name; /* name of the wrapper */ awk_bool_t (*can_take_file)(const awk_output_buf_t *outbuf); awk_bool_t (*take_control_of)(awk_output_buf_t *outbuf); - awk_const struct output_wrapper *awk_const next; /* for use by gawk */ + awk_const struct awk_output_wrapper *awk_const next; /* for use by gawk */ } awk_output_wrapper_t; The members are as follows: @@ -22487,7 +22492,7 @@ an extension to take over the output to a file opened with the `>' or The `awk_output_buf_t' structure looks like this: - typedef struct { + typedef struct awk_output_buf { const char *name; /* name of output file */ const char *mode; /* mode argument to fopen */ FILE *fp; /* stdio file pointer */ @@ -22563,13 +22568,13 @@ structures as described earlier. A two-way processor is represented by the following structure: - typedef struct two_way_processor { + typedef struct awk_two_way_processor { const char *name; /* name of the two-way processor */ awk_bool_t (*can_take_two_way)(const char *name); awk_bool_t (*take_control_of)(const char *name, awk_input_buf_t *inbuf, awk_output_buf_t *outbuf); - awk_const struct two_way_processor *awk_const next; /* for use by gawk */ + awk_const struct awk_two_way_processor *awk_const next; /* for use by gawk */ } awk_two_way_processor_t; The fields are as follows: @@ -23612,8 +23617,8 @@ in the `gawkapi.h' header file: If you need to do some initialization work, you should define a function that does it (creates variables, opens files, etc.) and then define the `init_func' pointer to point to your function. - The function should return zero (false) upon failure, non-zero - (success) if everything goes well. + The function should return `awk_false' upon failure, or `awk_true' + if everything goes well. If you don't need to do any initialization, define the pointer and initialize it to `NULL'. @@ -23634,7 +23639,7 @@ standard work. It does the following: to load, it prints a warning message but continues on. 3. If the `init_func' pointer is not `NULL', call the function it - points to. If it returns non-zero, print a warning message. + points to. If it returns `awk_false', print a warning message. 4. If `ext_version' is not `NULL', register the version string with `gawk'. @@ -32167,117 +32172,117 @@ Node: Extension Future Growth878591 Node: Extension API Description879409 Node: Extension API Functions Introduction880737 Node: General Data Types885437 -Ref: General Data Types-Footnote-1891070 -Node: Requesting Values891369 -Ref: table-value-types-returned892100 -Node: Constructor Functions893054 -Node: Registration Functions896050 -Node: Extension Functions896735 -Node: Exit Callback Functions898554 -Node: Extension Version String899797 -Node: Input Parsers900447 -Node: Output Wrappers909026 -Node: Two-way processors913419 -Node: Printing Messages915541 -Ref: Printing Messages-Footnote-1916618 -Node: Updating `ERRNO'916770 -Node: Accessing Parameters917509 -Node: Symbol Table Access918739 -Node: Symbol table by name919251 -Ref: Symbol table by name-Footnote-1921421 -Node: Symbol table by cookie921501 -Ref: Symbol table by cookie-Footnote-1925630 -Node: Cached values925693 -Ref: Cached values-Footnote-1929136 -Node: Array Manipulation929227 -Ref: Array Manipulation-Footnote-1930325 -Node: Array Data Types930364 -Ref: Array Data Types-Footnote-1933067 -Node: Array Functions933159 -Node: Flattening Arrays936925 -Node: Creating Arrays943758 -Node: Extension API Variables948553 -Node: Extension Versioning949189 -Node: Extension API Informational Variables951090 -Node: Extension API Boilerplate952176 -Node: Finding Extensions956010 -Node: Extension Example956557 -Node: Internal File Description957295 -Node: Internal File Ops960983 -Ref: Internal File Ops-Footnote-1972430 -Node: Using Internal File Ops972570 -Ref: Using Internal File Ops-Footnote-1974923 -Node: Extension Samples975189 -Node: Extension Sample File Functions976632 -Node: Extension Sample Fnmatch985105 -Node: Extension Sample Fork986831 -Node: Extension Sample Ord988045 -Node: Extension Sample Readdir988821 -Node: Extension Sample Revout990325 -Node: Extension Sample Rev2way990918 -Node: Extension Sample Read write array991608 -Node: Extension Sample Readfile993491 -Node: Extension Sample API Tests994246 -Node: Extension Sample Time994771 -Node: gawkextlib996078 -Node: Language History998459 -Node: V7/SVR3.1999981 -Node: SVR41002302 -Node: POSIX1003744 -Node: BTL1004752 -Node: POSIX/GNU1005486 -Node: Common Extensions1011021 -Node: Ranges and Locales1012128 -Ref: Ranges and Locales-Footnote-11016746 -Ref: Ranges and Locales-Footnote-21016773 -Ref: Ranges and Locales-Footnote-31017033 -Node: Contributors1017254 -Node: Installation1021550 -Node: Gawk Distribution1022444 -Node: Getting1022928 -Node: Extracting1023754 -Node: Distribution contents1025446 -Node: Unix Installation1030668 -Node: Quick Installation1031285 -Node: Additional Configuration Options1033247 -Node: Configuration Philosophy1034724 -Node: Non-Unix Installation1037066 -Node: PC Installation1037524 -Node: PC Binary Installation1038823 -Node: PC Compiling1040671 -Node: PC Testing1043615 -Node: PC Using1044791 -Node: Cygwin1048976 -Node: MSYS1049976 -Node: VMS Installation1050490 -Node: VMS Compilation1051093 -Ref: VMS Compilation-Footnote-11052100 -Node: VMS Installation Details1052158 -Node: VMS Running1053793 -Node: VMS Old Gawk1055400 -Node: Bugs1055874 -Node: Other Versions1059726 -Node: Notes1065041 -Node: Compatibility Mode1065700 -Node: Additions1066483 -Node: Accessing The Source1067410 -Node: Adding Code1069013 -Node: New Ports1075055 -Node: Derived Files1079190 -Ref: Derived Files-Footnote-11084498 -Ref: Derived Files-Footnote-21084532 -Ref: Derived Files-Footnote-31085132 -Node: Future Extensions1085230 -Node: Implementation Limitations1085811 -Node: Basic Concepts1087038 -Node: Basic High Level1087719 -Ref: figure-general-flow1087990 -Ref: figure-process-flow1088589 -Ref: Basic High Level-Footnote-11091818 -Node: Basic Data Typing1092003 -Node: Glossary1095358 -Node: Copying1120669 -Node: GNU Free Documentation License1158226 -Node: Index1183363 +Ref: General Data Types-Footnote-1891039 +Node: Requesting Values891338 +Ref: table-value-types-returned892069 +Node: Constructor Functions893023 +Node: Registration Functions896019 +Node: Extension Functions896704 +Node: Exit Callback Functions898536 +Node: Extension Version String899779 +Node: Input Parsers900429 +Node: Output Wrappers909016 +Node: Two-way processors913432 +Node: Printing Messages915562 +Ref: Printing Messages-Footnote-1916639 +Node: Updating `ERRNO'916791 +Node: Accessing Parameters917530 +Node: Symbol Table Access918760 +Node: Symbol table by name919272 +Ref: Symbol table by name-Footnote-1921442 +Node: Symbol table by cookie921522 +Ref: Symbol table by cookie-Footnote-1925651 +Node: Cached values925714 +Ref: Cached values-Footnote-1929157 +Node: Array Manipulation929248 +Ref: Array Manipulation-Footnote-1930346 +Node: Array Data Types930385 +Ref: Array Data Types-Footnote-1933088 +Node: Array Functions933180 +Node: Flattening Arrays936946 +Node: Creating Arrays943779 +Node: Extension API Variables948574 +Node: Extension Versioning949210 +Node: Extension API Informational Variables951111 +Node: Extension API Boilerplate952197 +Node: Finding Extensions956028 +Node: Extension Example956575 +Node: Internal File Description957313 +Node: Internal File Ops961001 +Ref: Internal File Ops-Footnote-1972448 +Node: Using Internal File Ops972588 +Ref: Using Internal File Ops-Footnote-1974941 +Node: Extension Samples975207 +Node: Extension Sample File Functions976650 +Node: Extension Sample Fnmatch985123 +Node: Extension Sample Fork986849 +Node: Extension Sample Ord988063 +Node: Extension Sample Readdir988839 +Node: Extension Sample Revout990343 +Node: Extension Sample Rev2way990936 +Node: Extension Sample Read write array991626 +Node: Extension Sample Readfile993509 +Node: Extension Sample API Tests994264 +Node: Extension Sample Time994789 +Node: gawkextlib996096 +Node: Language History998477 +Node: V7/SVR3.1999999 +Node: SVR41002320 +Node: POSIX1003762 +Node: BTL1004770 +Node: POSIX/GNU1005504 +Node: Common Extensions1011039 +Node: Ranges and Locales1012146 +Ref: Ranges and Locales-Footnote-11016764 +Ref: Ranges and Locales-Footnote-21016791 +Ref: Ranges and Locales-Footnote-31017051 +Node: Contributors1017272 +Node: Installation1021568 +Node: Gawk Distribution1022462 +Node: Getting1022946 +Node: Extracting1023772 +Node: Distribution contents1025464 +Node: Unix Installation1030686 +Node: Quick Installation1031303 +Node: Additional Configuration Options1033265 +Node: Configuration Philosophy1034742 +Node: Non-Unix Installation1037084 +Node: PC Installation1037542 +Node: PC Binary Installation1038841 +Node: PC Compiling1040689 +Node: PC Testing1043633 +Node: PC Using1044809 +Node: Cygwin1048994 +Node: MSYS1049994 +Node: VMS Installation1050508 +Node: VMS Compilation1051111 +Ref: VMS Compilation-Footnote-11052118 +Node: VMS Installation Details1052176 +Node: VMS Running1053811 +Node: VMS Old Gawk1055418 +Node: Bugs1055892 +Node: Other Versions1059744 +Node: Notes1065059 +Node: Compatibility Mode1065718 +Node: Additions1066501 +Node: Accessing The Source1067428 +Node: Adding Code1069031 +Node: New Ports1075073 +Node: Derived Files1079208 +Ref: Derived Files-Footnote-11084516 +Ref: Derived Files-Footnote-21084550 +Ref: Derived Files-Footnote-31085150 +Node: Future Extensions1085248 +Node: Implementation Limitations1085829 +Node: Basic Concepts1087056 +Node: Basic High Level1087737 +Ref: figure-general-flow1088008 +Ref: figure-process-flow1088607 +Ref: Basic High Level-Footnote-11091836 +Node: Basic Data Typing1092021 +Node: Glossary1095376 +Node: Copying1120687 +Node: GNU Free Documentation License1158244 +Node: Index1183381 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 6abc337f..02b7623b 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -28818,11 +28818,13 @@ and to nothing when compiling @command{gawk} itself. This makes certain fields in the API data structures unwritable from extension code, while allowing @command{gawk} to use them as it needs to. -@item typedef int awk_bool_t; -A simple boolean type. At the moment, the API does not define special -``true'' and ``false'' values, although perhaps it should. +@item typedef enum awk_bool @{ +@item @ @ @ @ awk_false = 0, +@item @ @ @ @ awk_true +@item @} awk_bool_t; +A simple boolean type. -@item typedef struct @{ +@item typedef struct awk_string @{ @itemx @ @ @ @ char *str;@ @ @ @ @ @ /* data */ @itemx @ @ @ @ size_t len;@ @ @ @ @ /* length thereof, in chars */ @itemx @} awk_string_t; @@ -28845,7 +28847,7 @@ multibyte encoding. This @code{enum} indicates the type of a value. It is used in the following @code{struct}. -@item typedef struct @{ +@item typedef struct awk_value @{ @itemx @ @ @ @ awk_valtype_t val_type; @itemx @ @ @ @ union @{ @itemx @ @ @ @ @ @ @ @ awk_string_t@ @ @ @ @ @ @ s; @@ -29091,7 +29093,7 @@ registering parts of your extension with @command{gawk}. Extension functions are described by the following record: @example -typedef struct @{ +typedef struct awk_ext_func @{ @ @ @ @ const char *name; @ @ @ @ awk_value_t *(*function)(int num_actual_args, awk_value_t *result); @ @ @ @ size_t num_expected_args; @@ -29220,11 +29222,11 @@ Your extension should package these functions inside an @code{awk_input_parser_t}, which looks like this: @example -typedef struct input_parser @{ +typedef struct awk_input_parser @{ const char *name; /* name of parser */ awk_bool_t (*can_take_file)(const awk_input_buf_t *iobuf); awk_bool_t (*take_control_of)(awk_input_buf_t *iobuf); - awk_const struct input_parser *awk_const next; /* for use by gawk */ + awk_const struct awk_input_parser *awk_const next; /* for use by gawk */ @} awk_input_parser_t; @end example @@ -29413,11 +29415,11 @@ with the @samp{>} or @samp{>>} operators (@pxref{Redirection}). The output wrapper is very similar to the input parser structure: @example -typedef struct output_wrapper @{ +typedef struct awk_output_wrapper @{ const char *name; /* name of the wrapper */ awk_bool_t (*can_take_file)(const awk_output_buf_t *outbuf); awk_bool_t (*take_control_of)(awk_output_buf_t *outbuf); - awk_const struct output_wrapper *awk_const next; /* for use by gawk */ + awk_const struct awk_output_wrapper *awk_const next; /* for use by gawk */ @} awk_output_wrapper_t; @end example @@ -29447,7 +29449,7 @@ This is for use by @command{gawk}. The @code{awk_output_buf_t} structure looks like this: @example -typedef struct @{ +typedef struct awk_output_buf @{ const char *name; /* name of output file */ const char *mode; /* mode argument to fopen */ FILE *fp; /* stdio file pointer */ @@ -29526,13 +29528,13 @@ as described earlier. A two-way processor is represented by the following structure: @example -typedef struct two_way_processor @{ +typedef struct awk_two_way_processor @{ const char *name; /* name of the two-way processor */ awk_bool_t (*can_take_two_way)(const char *name); awk_bool_t (*take_control_of)(const char *name, awk_input_buf_t *inbuf, awk_output_buf_t *outbuf); - awk_const struct two_way_processor *awk_const next; /* for use by gawk */ + awk_const struct awk_two_way_processor *awk_const next; /* for use by gawk */ @} awk_two_way_processor_t; @end example @@ -30432,7 +30434,7 @@ static awk_bool_t init_testarray(void) @{ create_new_array(); - return 1; + return awk_true; @} static awk_bool_t (*init_func)(void) = init_testarray; @@ -30650,8 +30652,8 @@ If you need to do some initialization work, you should define a function that does it (creates variables, opens files, etc.) and then define the @code{init_func} pointer to point to your function. -The function should return zero (false) upon failure, non-zero -(success) if everything goes well. +The function should return @code{awk_false} upon failure, or @code{awk_true} +if everything goes well. If you don't need to do any initialization, define the pointer and initialize it to @code{NULL}. @@ -30678,7 +30680,7 @@ continues on. @item If the @code{init_func} pointer is not @code{NULL}, call the -function it points to. If it returns non-zero, print a +function it points to. If it returns @code{awk_false}, print a warning message. @item |